API referenceWhatsApp

POST /api/v1/whatsapp/connect

Connect a number with an existing token (system user or test token) instead of Embedded Signup: reads the number and the WABA with it, subscribes the app to the WABA and registers the number (failures are reported in onboarding, not as errors). The token is stored encrypted. Emits account.connected

POST
/api/v1/whatsapp/connect

Authorization

BearerAuth
headerAuthorizationBearer <token>

API key sk_...

Request Body

application/json
  1. body
accessToken*string

Token with whatsapp_business_management and whatsapp_business_messaging

phoneNumberId*string

Cloud API phone number id

wabaId*string

WhatsApp Business Account id

pin?string

6-digit two-step verification PIN (default: random)

Match^\d{6}$
register?boolean
Defaulttrue
subscribe?boolean
Defaulttrue
externalId?string
Lengthlength <= 200

Response Body

{account, whatsapp}

application/json
  1. response
account?
whatsapp?
Example Request
curl -X POST 'https://example.com/api/v1/whatsapp/connect' \  -H 'Content-Type: application/json' \  -d '{  "accessToken": "string",  "phoneNumberId": "string",  "wabaId": "string"}'
Example Response
{  "account": {    "id": "string",    "platform": "string",    "accountName": "string",    "platformAccountId": "string",    "externalId": "string"  },  "whatsapp": {    "accountId": "string",    "platform": "whatsapp",    "accountName": "string",    "phoneNumberId": "string",    "wabaId": "string",    "businessId": "string",    "externalId": "string",    "status": "string",    "phoneNumber": {      "displayPhoneNumber": "string",      "verifiedName": "string",      "qualityRating": "string",      "messagingLimitTier": "string",      "nameStatus": "string",      "platformType": "string",      "codeVerificationStatus": "string",      "status": "string",      "checkedAt": "2019-08-24T14:15:22Z",      "throughput": null    },    "onboarding": {      "connection": "embedded_signup",      "onboarding": "cloud_api",      "subscribed": true,      "subscribeError": "string",      "registered": true,      "registerError": "string",      "registerSkipped": "string",      "onboardedAt": "2019-08-24T14:15:22Z"    }  }}

POST /api/v1/whatsapp/numbers/{id}/retry POST

Retry a failed number from the step that failed

GET /api/v1/whatsapp/accounts/{id}/phone-number GET

The number: display number, verified name, quality rating, messaging limit tier, name status, status and onboarding state; refresh=true reads it from Meta and saves it