Create a new connection
Provisions a new WhatsApp connection inside this grant. The core starts a QR pairing session and returns an initial QR code. Render `qr` (a data-URI PNG) and poll `GET /connections/{id}` every 3–5 s until `status` is `"connected"`, re-rendering the `qr` from every response. **WhatsApp rotates the pairing code roughly every 20 seconds**, so the `qr` in this create response is stale within seconds: a QR left on screen simply never pairs, and nothing surfaces an error to explain why. Do not cache it, and do not treat the create response as the pairing code. **With an API key there is no bootstrap step:** a key is issued against your workspace directly, so this endpoint creates the FIRST connection as readily as the tenth — nothing has to be clicked in a portal UI first. (An OAuth grant, by contrast, can only be issued over connections that already exist, so an OAuth-only integration still needs one connection to exist before it can create more. That is the reason to start with a key.) Standalone workspaces only — a Bitrix24-owned portal is rejected with 403 `forbidden_portal_kind`. Check `GET /account` first: creating past your slot quota leaves the new connection without an active licence. Connections created here are QR/WAPP (`provider: qr`); WABA numbers are onboarded through Meta embedded signup, not this endpoint. **Idempotency (optional).** Creating a connection provisions a WhatsApp session and consumes a paid SLOT at pairing time, so an HTTP client that times out and retries would otherwise create a SECOND connection — and you would silently pay for two slots for one customer. Send an optional `Idempotency-Key` header to make the retry safe: within 24 h the same key + the same body returns the SAME connection with **200** and `Idempotency-Replayed: true` instead of provisioning again; the same key with a DIFFERENT body is rejected with 400 `idempotency_key_reuse`; and while the first request is still in flight the retry gets 409 `idempotency_in_progress` with `Retry-After: 1`. Generate ONE key per customer-onboarding ATTEMPT (a fresh UUID minted right before the call, reused only by that call's retries) — never one per process, per API key, per day, or a constant. Omit the header and behaviour is exactly as before. This is the only endpoint that supports it.
Provisions a new WhatsApp connection inside this grant. The core starts a QR pairing session and returns an initial QR code. Render qr (a data-URI PNG) and poll GET /connections/{id} every 3–5 s until status is "connected", re-rendering the qr from every response. WhatsApp rotates the pairing code roughly every 20 seconds, so the qr in this create response is stale within seconds: a QR left on screen simply never pairs, and nothing surfaces an error to explain why. Do not cache it, and do not treat the create response as the pairing code.
With an API key there is no bootstrap step: a key is issued against your workspace directly, so this endpoint creates the FIRST connection as readily as the tenth — nothing has to be clicked in a portal UI first. (An OAuth grant, by contrast, can only be issued over connections that already exist, so an OAuth-only integration still needs one connection to exist before it can create more. That is the reason to start with a key.) Standalone workspaces only — a Bitrix24-owned portal is rejected with 403 forbidden_portal_kind. Check GET /account first: creating past your slot quota leaves the new connection without an active licence. Connections created here are QR/WAPP (provider: qr); WABA numbers are onboarded through Meta embedded signup, not this endpoint.
Idempotency (optional). Creating a connection provisions a WhatsApp session and consumes a paid SLOT at pairing time, so an HTTP client that times out and retries would otherwise create a SECOND connection — and you would silently pay for two slots for one customer. Send an optional Idempotency-Key header to make the retry safe: within 24 h the same key + the same body returns the SAME connection with 200 and Idempotency-Replayed: true instead of provisioning again; the same key with a DIFFERENT body is rejected with 400 idempotency_key_reuse; and while the first request is still in flight the retry gets 409 idempotency_in_progress with Retry-After: 1. Generate ONE key per customer-onboarding ATTEMPT (a fresh UUID minted right before the call, reused only by that call's retries) — never one per process, per API key, per day, or a constant. Omit the header and behaviour is exactly as before. This is the only endpoint that supports it.
The default way to authenticate. Create a key at https://developers.wasync.app/keys and send it as Authorization: Bearer wsk_live_….
The key is shown once at creation and stored only as a hash — lose it and you revoke it and create another. Each key carries its own scopes (whatsapp.read, whatsapp.send, whatsapp.events, whatsapp.manage) and an optional IP allowlist.
Errors: an unknown or revoked key returns 401 invalid_key; a key whose IP allowlist does not cover the calling address returns 403 ip_not_allowed (a distinct code on purpose — the key is fine, the address is not). Both carry a WWW-Authenticate: Bearer challenge. Scopes and the connection list are resolved live on every request, so revoking a key or narrowing it takes effect on the next call.
In: header
Header Parameters
Optional. Makes a retried create safe: a connection consumes a paid slot, so a timed-out retry without this header creates a second connection you pay for twice.
Four cases, all scoped to 24 h from the first request that used the key:
- New key → the connection is provisioned as normal → 201 Created.
- Same key, same request body → the SAME connection is returned, nothing is provisioned again, 200 OK plus the response header
Idempotency-Replayed: true. Theqrin that response is FRESHLY fetched, not the code stored at first creation — WhatsApp rotates pairing codes roughly every 20 seconds, so a replayed stale QR would simply fail to scan. - Same key, DIFFERENT request body → 400
idempotency_key_reuse. - Same key while the first request is still in flight → 409
idempotency_in_progresswithRetry-After: 1. Honour it and retry.
The body comparison is over a hash of the CANONICAL request body, so JSON key order does not matter. Keys are namespaced per WORKSPACE — two partners using the same literal key string never collide, and a key from one workspace is invisible to another. After 24 h the key is free to be reused for a different request.
Any opaque string up to 255 characters; longer is rejected with 400 idempotency_key_invalid (never truncated), and a blank/whitespace-only header is treated as absent.
Generate ONE key per customer-onboarding ATTEMPT — a fresh UUID (e.g. crypto.randomUUID()) minted right before the call and reused only by that call's retries. Do NOT use one key per process, per API key, per day, or a constant: a key that is too coarse means the second customer you onboard gets handed the FIRST customer's connection back instead of his own.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/connections" \ -H "Idempotency-Key: 3f2a9c14-8d5e-4b7a-9f01-2c6d8e4a7b13" \ -H "Content-Type: application/json" \ -d '{ "label": "Support line" }'{ "connection": { "id": "conn_8f3a21", "status": "connecting", "qr": "data:image/png;base64,…" }}List authorized connections GET
Returns the WhatsApp connections this access token may use. Only connections with an active API add-on appear; an expired add-on hides the connection. Call this first to discover which `id` to send from or read.
Get connection status GET
Returns the current status and metadata of a single connection. Poll every 3–5 s during QR pairing — `status` becomes `"connected"` once the user scans the code. The `qr` field carries a NEW pairing code on each poll — re-render it every time. WhatsApp rotates the code roughly every 20 s, so a QR displayed for longer than that will not scan.