WhatsApp numbers

A tenant can have several numbers on one WhatsApp Business Account. In every path, {pnid} is the phone_number_id. Reading needs channels:read. Changing needs channels:write.

List the numbers

GET /api/v1/partner/tenants/{external_ref}/channels/whatsapp/numbers/ answers { "data": [...] }.

{
  "data": [
    {
      "phone_number_id": "100000000000001",
      "display_phone_number": "+1 555 010 0100",
      "verified_name": "Acme Dental",
      "quality_rating": "GREEN",
      "waba_id": "200000000000001",
      "status": "pending",
      "connected": true,
      "problem": "",
      "payment_method_linked": null,
      "can_send_message": null,
      "problems": []
    }
  ]
}

Field	Meaning
`status`	`active` when an agent answers, else `pending`.
`connected`	`false` when the connection failed. `problem` says why.
`payment_method_linked`	Whether the Meta account has a payment method. `null` until a health check or a send tells.
`can_send_message`, `problems`	The result of the last health check. `problems` lists what blocks sending, with the fix.

Add a number from the same account

Do not sign up again for a second number of the same account. List the numbers that Meta has under the account:

curl https://api.impellabs.tech/api/v1/partner/tenants/acme-001/channels/whatsapp/available-numbers/ \
  -H "Authorization: Bearer implpk_..."

Each row has connected. Connect one:

curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/channels/whatsapp/numbers/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "100000000000002" }'

The answer is 201 with the number. A number that is not under the account answers 400. A number that another workspace holds answers 409 with code set to number_claimed. The same call also works at .../numbers/adopt/.

Switch on, pause

POST .../numbers/{pnid}/activate/ with assistant_id, or { "on": false }. See Setup. The number object has is_primary (the first number that was connected), activated, activated_at and settings.

Check a number

GET .../numbers/{pnid}/health/ checks the access token, the webhook subscription, the registration, the payment method and whether the number can send. The result is kept for 10 minutes and has cached set to true when it is a kept result. Add ?refresh=true to ask Meta again. If the number needs registration, needs_registration is true. Register it with its two-step PIN:

curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/channels/whatsapp/numbers/100000000000001/register/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{ "pin": "123456" }'

The PIN is used for this call only and is not kept. The answer has platform_type and needs_registration. A PIN that Meta refuses answers 400. In payment, method_linked can be null with reason not_permitted. Meta lets only a Business Solution Provider read the payment method. In that case the tenant checks it in Meta’s Billing hub, and billing_url points to it.

Settings

GET and PATCH .../numbers/{pnid}/settings/ read and change four settings. Send only the ones that change.

Setting	Use
`read_receipts`	Mark customer messages as read when the agent answers.
`typing_indicator`	Show a typing indicator with the read receipt. It works only when `read_receipts` is on.
`rich_blocks`	Allow buttons and lists in the agent’s messages.
`reply_wait_seconds`	Seconds that the agent waits for more lines before it answers. From 0 to 120.

Business profile

GET .../numbers/{pnid}/profile/ returns what customers see in the details of the number: about, address, description, email, websites, vertical and profile_picture_url. PATCH changes only the fields you send. Send JSON, or multipart form data with a photo file (JPEG or PNG, 5 MB at most). A PATCH with no field and no photo answers 400. A refusal by Meta answers 400, or 502 when Meta asks you to try again.

Disconnect

DELETE .../numbers/{pnid}/ disconnects the number. It is archived, not deleted. A number that is not connected answers 404.

Get started

Customers

Channels

Events

Partner API reference