# WhatsApp connections

Register your customer's business, then connect their WhatsApp Business account and numbers.

## Register a client business (the future owner of a WhatsApp Business account)

`POST /connected-businesses`

Authentication: API key, or console session with X-Environment-Id · scope: connections:manage

Body (JSON):

| Field | Type | | Description |
|---|---|---|---|
| `name` | string | required | Name of your customer's business (2 to 120 characters). |
| `externalRef` | string | optional | Your own identifier for this customer |

```bash
curl -X POST "$INBOX_API/connected-businesses" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cabinet Dentaire Zokem",
    "externalRef": "client-42"
  }'
```

Response 201:

```json
{
  "id": "39e2803f-79e7-4e99-8da0-1c15991f5985",
  "name": "Cabinet Dentaire Zokem",
  "externalRef": "client-42",
  "createdAt": "2026-11-12T08:33:45.469Z"
}
```

## List the businesses in the key's environment

`GET /connected-businesses`

Authentication: API key, or console session with X-Environment-Id · scope: connections:read

```bash
curl "$INBOX_API/connected-businesses" \
  -H "Authorization: Bearer $INBOX_KEY"
```

Response 200:

```json
[
  {
    "id": "39e2803f-79e7-4e99-8da0-1c15991f5985",
    "name": "Cabinet Dentaire Zokem",
    "externalRef": "client-42",
    "createdAt": "2026-11-12T08:33:45.469Z"
  }
]
```

## Complete Embedded Signup: connect the WhatsApp Business account and number

`POST /connected-businesses/{businessId}/waba-connections`

Authentication: API key, or console session with X-Environment-Id · scope: connections:manage

Parameters:

| Name | Location | Type | Description |
|---|---|---|---|
| `businessId` | path | string |  |

Body (JSON):

| Field | Type | | Description |
|---|---|---|---|
| `code` | string | required | Code returned by Embedded Signup (single-use, short-lived) |
| `wabaId` | string | required | ID of the WhatsApp Business account (WABA) returned by Embedded Signup. Digits only. |
| `phoneNumberId` | string | required | ID of the WhatsApp number returned by Embedded Signup. Digits only. |
| `mode` | string | optional | `cloud_api` (default), or `coexistence` if the customer keeps the WhatsApp Business app on their phone. |

```bash
curl -X POST "$INBOX_API/connected-businesses/BUSINESS_ID/waba-connections" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AQBx7…",
    "wabaId": "102290129340398",
    "phoneNumberId": "106540352242922",
    "mode": "cloud_api"
  }'
```

Response 201:

```json
{
  "id": "b76a1f98-53d6-4078-8d28-6406482daabb",
  "wabaId": "102290129340398",
  "status": "active",
  "mode": "cloud_api",
  "phoneNumber": {
    "id": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "phoneNumberId": "106540352242922",
    "displayNumber": "+237 6 52242922",
    "verifiedName": "Cabinet Test",
    "qualityRating": "GREEN"
  }
}
```

## A business's connected accounts and numbers

`GET /connected-businesses/{businessId}/phone-numbers`

Authentication: API key, or console session with X-Environment-Id · scope: connections:read

Parameters:

| Name | Location | Type | Description |
|---|---|---|---|
| `businessId` | path | string |  |

```bash
curl "$INBOX_API/connected-businesses/BUSINESS_ID/phone-numbers" \
  -H "Authorization: Bearer $INBOX_KEY"
```

Response 200:

```json
[
  {
    "id": "b76a1f98-53d6-4078-8d28-6406482daabb",
    "wabaId": "102290129340398",
    "status": "active",
    "mode": "cloud_api",
    "phoneNumbers": [
      {
        "id": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
        "phoneNumberId": "106540352242922",
        "displayNumber": "+237 6 52242922",
        "verifiedName": "Cabinet Test",
        "qualityRating": "GREEN"
      }
    ]
  }
]
```