WASync · Developers
API ReferenceConnections

Get connection status

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.

GET
/connections/{id}

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.

AuthorizationBearer <token>

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

Path Parameters

id*string

Connection id (from POST /connections or GET /connections).

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/connections/string"
{  "connection": {    "id": "conn_8f3a21",    "status": "connected",    "phoneNumber": "40700000000",    "label": "Support line",    "provider": "qr",    "licenseStatus": "active",    "licenseExpires": "2019-08-24T14:15:22Z",    "qr": "string",    "phone": "40700000000",    "license_status": "active",    "license_expires": "2019-08-24T14:15:22Z"  }}

Create a new connection POST

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.

Delete a connection DELETE

Permanently removes the connection and its adapter session. This cannot be undone — the user will need to create a new connection and go through QR pairing again.