Skip to content

Connect WhatsApp

Start a QR session

Starts the QR-linked session for the workspace. If the number is not linked yet, a QR code becomes available from GET /api/whatsapp/qr. If it is already linked, the session reconnects. Returns the session state. Linking a device is channel administration, so only owners and admins signed in to the app can call it; API keys get 403.

POST/api/whatsapp/connect
  • Console only: owner or admin
  • Workspace: X-Tenant-ID

Headers

  • Cookiestringrequired

    The whatsappx_session cookie the app sets when you sign in. Browsers send it automatically; API keys are not accepted on this endpoint.

    Example
    whatsappx_session=…
  • X-Tenant-IDuuidrequired

    Workspace id. Required for session requests. You can pass ?tenant=<id> instead.

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

Response

200 OKapplication/json

  • connectedboolean

    The linked session is connected to WhatsApp.

  • logged_inboolean

    The number is linked (paired) to this workspace.

  • qr_pendingboolean

    A QR code is waiting to be scanned.

  • jidstringmay be absent

    WhatsApp id of the linked number, once linked.

Status codes

  • 200OK. The session state after starting.
  • 401Unauthorized. 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. API keys can never call this endpoint (API keys cannot administer workspaces). A signed-in user who is not an owner or admin gets admin required; a user who is not a member of the workspace gets forbidden.
  • 500Server error. The session could not be started. The error carries the reason.

How is a number linked?

  1. Start the session

    An owner or admin clicks Connect in the app (this calls POST /api/whatsapp/connect with their session).

  2. Show the QR code

    The app shows it. With an API key you can also poll GET /api/whatsapp/qr every few seconds and display image while pending is true.

  3. Scan it

    On the phone: WhatsApp → Settings → Linked devices → Link a device.

  4. Wait for the link

    Poll GET /api/whatsapp/status until logged_in and connected are true. Chats then sync in the background; the live event stream reports sync.progress.