Connect widget · WaConnect Docs

The connect widget is the hosted page behind every connectUrl. It shows a number's live QR code, step-by-step instructions and the result — designed to sit inside your own modal. See Connect a number for the full flow.

Embedding#

<iframe
  src="https://waconnect.ai/connect/TOKEN"
  title="Connect WhatsApp"
  style="width: 400px; height: 600px; border: 0"
></iframe>

The widget is responsive: 400 × 600 fits it comfortably, and it adapts to smaller frames on phones.

URL options#

Parameter	Values	Default
`theme`	`light`, `dark`	`light`

Example: https://waconnect.ai/connect/TOKEN?theme=dark

Browser events#

The widget tells the page that embeds it (iframe) or opened it (pop-up window) what happened, with postMessage. Always check the sender:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://waconnect.ai") return
 
  switch (event.data.type) {
    case "waconnect.ready":
      // The widget loaded and the link is valid.
      break
    case "waconnect.connected":
      // The number is linked. event.data.phoneNumber is e.g. "+12125550147".
      break
    case "waconnect.link_invalid":
      // The link was already used, replaced, or the number was removed.
      break
  }
})

Event	Data	When
`waconnect.ready`	—	The widget loaded with a valid link.
`waconnect.connected`	`phoneNumber`	The number connected. Close your modal and refresh your UI.
`waconnect.link_invalid`	—	The link can't be used. Ask your server for a new one with `POST /v1/numbers/:id/connect-link`.

What the user sees#

Preparing — a spinner for a few seconds while WhatsApp issues the first code.
Scan — the QR code and instructions: open WhatsApp → Linked devices → Link a device.
Expired — if nobody scans in about a minute, a Get a new code button.
Connected — a confirmation with the linked phone number.

The footer shows "Secured by WaConnect".