---
title: "Connect a WhatsApp number"
method: POST
path: "/whatsapp/connect/"
tags: ["WhatsApp numbers"]
---

# Connect a WhatsApp number

`POST /whatsapp/connect/`

## Request

- Base URL: `https://wbiztool.com/api/v1`
- URL: `https://wbiztool.com/api/v1/whatsapp/connect/`
- Auth: none required

Start linking a WhatsApp number (Advanced and Enterprise plans). The call only starts it: the QR code (`login_method=qr`, default) or an 8-character pairing code (`login_method=phone`) arrives at `webhook_url` (see the `whatsappConnect` webhook), followed by `connected` or `not_connected`. A request not picked up within 10 minutes expires. The JSON body is served with `Content-Type: text/html`; parse it as JSON whatever the header says.

## Request body

- ConnectWhatsappRequest: Your API credentials, sent in the request body (JSON or form fields) of every request that uses them. Both come from Settings → API keys in the dashboard. The API key decides which workspace the request acts on.
  - `client_id` integer, required: Your API Client ID from Settings → API keys.
  - `api_key` string, required: One of your API keys from the same page. Keep it secret.
  - `webhook_url` string, uri: Receives the QR code or phone code and the result (see the `whatsappConnect` webhook). Without it you cannot get the QR code through the API.
  - `login_method` 'qr' | 'phone': `qr` sends a QR code to the webhook; `phone` an 8-character pairing code.
  - `whatsapp_number` string: Required with `login_method=phone`: full international number, country code first, no leading `0`. Ignored for `qr`.
  - `whatsapp_client_id` integer: Reconnect this existing, disconnected number (keeps its ID). Leave out to add a new number.

## Response `200`

Connection request created (`status: 1`) or refused (`status: 0`): `Auth Error` (also for an invalid JSON body), `Higher Subscription Required`, `WhatsApp Account Limit Reached. Upgrade your account to get more whatsapp limit`, `Already Connected With Given Number`; a non-POST request returns `{}`.

- union
  - WhatsappConnectStarted
    - `status` 1, required
    - `message` 'Whatsapp Client Created', required
    - `whatsapp_client_id` integer, required
    - `login_method` 'qr' | 'phone', required
  - ApiError: A failed request. `status` is `0` and `message` says why. (`Account Disabled` has no `status` field.)
    - `status` 0
    - `message` string, required

## Other responses

- `400`: `login_method must be 'qr' or 'phone'`, the phone-number format error for `login_method=phone`, `Auth Error: invalid api key` or `Invalid WhatsApp client`.
- `403`: `client_id` is not a whole number.
- `500`: `webhook_url` longer than 250 characters.

---

[API](https://skmtc.dev/wbiztool/apis/wbiztool-api.md) · [All operations](https://skmtc.dev/wbiztool/apis/wbiztool-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wbiztool/apis/wbiztool-api/revisions/bc7380bb5684?raw)