> ## 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 setup

> Connect the WhatsApp Business Account and phone number of a tenant, and switch an agent on.

Each tenant connects its own WhatsApp Business Account and phone number. The tenant signs in to Meta and allows
ImpelLabs to use the number. The account and the number stay with the tenant, and its payment method for WhatsApp is on its
own Meta account. Reading needs `channels:read`. Connecting needs `channels:write`.

You can connect in two ways. The hosted sign-up needs the least work from you.

## Hosted sign-up

ImpelLabs hosts a page that runs Meta's sign-up for the tenant. You send the tenant a link.

**1. Set the return address once**

In the [partner console](https://docs.impellabs.tech/partners/console.md), set the WhatsApp return address under Brand and domain. It must start with
`https://`. A request without it answers 409 with the code `no_return_url`. A request cannot set the address.

**2. Make a sign-up link**

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/channels/whatsapp/signup-session/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{ "state": "order-77" }'
```

The answer is 201:

```json theme={null}
{ "url": "https://impellabs.tech/connect/TOKEN", "expires_at": "2026-01-15T09:45:00+00:00", "session_id": "1a2b3c4d-0000-4000-8000-000000000000" }
```

The link works once and expires after 15 minutes. It is for one tenant. `state` is optional text, 512 characters at
most. It comes back to you on the return address. If WhatsApp sign-up is not set up on the server, the call answers 503.

**3. Send the tenant to the link**

The page asks the tenant to choose one of two things. The tenant can use the number that is on its WhatsApp Business
app, and the app keeps working on its phone. Or the tenant can connect a new number, which needs a code by text or
call. A tenant who needs a PIN for the number types it on the page. The PIN is used once and is not kept.

**4. Receive the result**

The page sends the tenant to your return address with `status` (`connected`, `cancelled` or `failed`), your `state`, and
a `reason` when it failed. ImpelLabs also sends the event `channel.connected` to your
[webhook endpoint](https://docs.impellabs.tech/partners/webhooks.md), also when the tenant closes the page before the redirect. Do not depend on the
redirect alone.

`channel.connected` carries `phone_number_id`, `waba_id`, `display_phone_number`, `verified_name`, `activated` and
`coexistence`.

## Sign-up in your own page

You can open Meta's sign-up in your own page instead. First read the settings:

```bash theme={null}
curl https://api.impellabs.tech/api/v1/partner/whatsapp/signup-config/ \
  -H "Authorization: Bearer implpk_..."
```

The answer has `app_id`, `config_id`, `graph_version` and `server_ready`. If `server_ready` is `false`, sign-up is not set
up on this server. Use the values to open the Meta window. When it ends, send the `code` from your server:

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/channels/whatsapp/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "CODE_FROM_META", "waba_id": "200000000000001", "phone_number_id": "100000000000001" }'
```

`code` and `waba_id` are required. `phone_number_id` is the number to connect. Without it, the first number of the
account is used. The code works once, so do not repeat this call blindly. If you lose the answer, read the channel with
`GET` on the same path. A number that needs a PIN answers 409 with `field` set to `pin`. This route cannot finish that
step, so use the hosted sign-up for such a number.

The answer of both `GET` and `POST` holds `configured` and the `numbers` that are connected.

## A connected number does not answer yet

A new number has the status `pending`. Switch an agent on:

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/channels/whatsapp/numbers/100000000000001/activate/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{ "assistant_id": "AGENT_ID" }'
```

`assistant_id` is the id of an agent in the workspace of the tenant. See [Get an agent id](https://docs.impellabs.tech/partners/channels/overview.md#get-an-agent-id). The number
becomes `active`. Send `{ "on": false }` to pause it. A paused number keeps its connection.

When the tenant has more than one number and no agent answers on this one, the call answers 400 `no_binding`. Send
`"force": true` to switch it on anyway. An archived agent answers 400 `assistant_archived`. A number whose connection
failed answers 409. Reconnect it first.

## Next

See [Numbers](https://docs.impellabs.tech/partners/channels/whatsapp/numbers.md) to manage the numbers of a tenant, and
[Syncing](https://docs.impellabs.tech/partners/channels/whatsapp/syncing.md) for the chats that come from the WhatsApp Business app.


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