Skip to content

Connect WhatsApp

Get the QR code

Returns the QR code to scan in WhatsApp (Settings → Linked devices → Link a device). The session must be started first (POST /api/whatsapp/connect, Console only). WhatsApp rotates the code regularly, so poll this endpoint while pending is true and re-render the image.

GET/api/whatsapp/qr
  • Bearer API key
  • Scope: read or write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Response

200 OKapplication/json

  • codestringmay be absent

    Raw QR payload, if you want to render the code yourself.

  • imagestring

    The QR code as a 256 px PNG data URL (data:image/png;base64,…). Empty when there is no code.

  • pendingboolean

    true while a code is waiting to be scanned.

  • errorstringmay be absent

    Only when there is no code.

  • messagestringmay be absent

    Only when there is no code; same text as error.

Status codes

  • 200OK. The current QR code. When there is none (not started, already linked or expired), the response is still 200 with pending: false, an empty image, and an explanation in both error and message.
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The X-Tenant-ID header or tenant query does not match the API key’s workspace (API key belongs to a different workspace), or a signed-in user is not a member of the workspace (forbidden).

Response when there is no QR code

{
  "pending": false,
  "image": "",
  "error": "no QR code available; call POST /api/whatsapp/connect first, or the previous QR expired",
  "message": "no QR code available; call POST /api/whatsapp/connect first, or the previous QR expired"
}