> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp numbers

> List, add, check, set up and disconnect the WhatsApp numbers of a tenant.

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": [...] }`.

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](https://docs.impellabs.tech/partners/channels/whatsapp/setup.md).
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:

```bash theme={null}
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\.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.