WhatsApp authorization

WhatsApp QR pairing: call /auth/qr/start to begin the device session. The QR token is delivered to your webhook as an account.auth.required event, and is also exposed synchronously via /auth/qr/check for polling.

1. 1. POST /v1/accounts with provider=whatsapp, auth_mode=qrcode. Optionally set provider_data.device_os / device_platform for the device fingerprint, and use the top-level proxy field for persistent routing.
2. 2. POST /v1/accounts/{account_id}/auth/qr/start to boot the device. Status returns awaiting_qr_scan; the actual QR string is delivered asynchronously.
3. 3. Listen for the account.auth.required event on your webhook — auth_payload.qr_code is the raw token your UI must render as a scannable QR image. Alternatively poll /auth/qr/check.
4. 4. After scanning, an account.auth.succeeded event lands on your webhook with provider_account_ref filled in, normally followed by account.started. Confirm runtime_status before deciding whether POST /v1/accounts/{account_id}/runtime/start is needed.

• provider_data.device_os — Optional device label shown during pairing. Leave unset unless you need a custom display name.
• provider_data.device_platform — Numeric device platform code (1=CHROME, 2=FIREFOX, 5=SAFARI, 14=IOS_PHONE, 16=ANDROID_PHONE, ...). Must be set together with device_os to take effect.
• proxy — Optional top-level account proxy used for persistent network routing. This is not provider_data.proxy_config.

WhatsApp phone-number pairing: save the phone number on the account at creation time, then enter the 8-character verify_code on the phone (Linked Devices → Link with phone number).

1. 1. POST /v1/accounts with provider=whatsapp, auth_mode=code, and provider_data.phone set to the E.164 number (digits only). The phone is persisted on the account and replayed automatically by later authentication actions.
2. 2. POST /v1/accounts/{account_id}/auth/start with an empty body. The saved phone is reused; the response carries the 8-character verify_code under auth_payload.
3. 3. Show verify_code to the user. The phone accepts it for ~3 minutes — after that, restart the flow.
4. 4. Once paired, account.auth.succeeded and account.started arrive on your webhook just like the QR flow.

• provider_data.phone — E.164 phone number (digits only, e.g. 15551234567). Set this under provider_data.phone when creating the account; later authentication actions reuse it automatically.

WhatsApp QR authorization may require a Passkey. Continue through the hosted authorization page, or handle WebAuthn directly with the public Account Auth endpoints.

1. 1. Start and poll the normal WhatsApp QR flow until GET /auth or /auth/qr/check returns status=passkey_required and auth_payload.public_key.
2. 2. Hosted path: POST /v1/accounts/{account_id}/auth-sessions, then open the short-lived authorize_url in the user’s browser. The hosted page completes the browser interaction.
3. 3. Direct path: call the browser WebAuthn API with auth_payload.public_key, serialize the complete credential response, and POST it as webauthn_response to /auth/passkey-response.
4. 4. If the state becomes passkey_confirmation, obtain the user’s confirmation and POST /auth/passkey-confirm. Otherwise keep polling while the state is passkey_pending.
5. 5. Poll GET /auth until status becomes authorized or failed. Authorization success normally starts the runtime automatically.

• auth_payload.public_key — WebAuthn request options returned for the current Passkey challenge.
• authorize_url — Short-lived hosted authorization URL. Treat the complete URL as a sensitive credential.
• webauthn_response — Complete browser-generated WebAuthn credential response serialized as a JSON string.