> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding overview

> Embed the WhatsApp QR connection page in your own product, with default or fully custom UI

The `qr_link` returned by [Generate QR code for user](https://timelines.ai/docs/partner-api-reference/qr/generate-qr-code-for-user.md) opens a TimelinesAI-hosted page that walks the end user through connecting their WhatsApp account. Partners building white-label experiences typically embed this page in an iframe so the user never leaves the partner's product.

This section covers everything that controls how that embedded experience looks and behaves: the URL parameter that styles the page for embedding, and a `postMessage`-based API for partners who want to drive the flow with their own UI.

## Two integration modes

> [card] Default UI in an iframe
>
> Embed the QR connection page in an iframe and let TimelinesAI render the QR code, phone-pairing fallback, and instructions. Minimal partner-side code. Use the `display_mode=embedding` URL parameter for iframe-friendly styling — see [Partner API Overview → QR code embedding](https://timelines.ai/docs/partner-api-reference/overview.md#qr-code-embedding).

> [card] Fully custom UI
>
> Hide the iframe entirely and drive the connection flow through the [postMessage API](https://timelines.ai/docs/partner-api-reference/qr/embedding-postmessage-api.md). Receive the raw QR payload and pairing code as events, render them in your own design system, and listen for connection and error events.

Both modes use the same `qr_link` URL — the difference is purely partner-side.

## Prerequisite: register your embedding domain

Embedding the QR page in your application requires your partner record to have one or more **embedding domains** registered. This is the allowlist of parent-window origins to which TimelinesAI will dispatch outbound `postMessage` events and from which it will accept inbound `postMessage` commands.

This applies in both integration modes — even a partner using the default UI inside an iframe receives the `TIMELINES_QR_CONNECTED` outbound event on successful connection, which requires the allowlist to be configured.

**1. Contact TimelinesAI**

Email [support@timelines.ai](mailto:support@timelines.ai) with the list of origins where you will embed the iframe (e.g. `https://app.your-product.com`, `https://staging.your-product.com`). Include exact scheme, host, and port for each.

**2. Confirmation**

The TimelinesAI team registers the origins on your partner record. Multiple origins are supported.

**3. Verify**

Once registered, embed the iframe from one of the allowed origins and confirm a postMessage round-trip succeeds. Messages from any other origin are silently ignored by the iframe.

> [!WARNING]
>
> Origin matching is exact: scheme, host, and port must all match. `https://app.example.com` is **not** the same as `https://www.app.example.com` or `http://app.example.com`. If you embed from redirects, rewrites, or a non-standard port, list every variant.

## Next

> [card] [postMessage API](https://timelines.ai/docs/partner-api-reference/qr/embedding-postmessage-api.md)
>
> Inbound and outbound message catalog for driving the flow programmatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.