# Connect a WhatsApp number

> POST https://api.nabrah.ai/api/ext/omni_v2/whatsapp/inboxes

Group: WhatsApp. Page: https://www.nabrah.ai/en/docs/api-reference/whatsapp/connect-a-whatsapp-number

Connect a new WhatsApp number to the project by creating a WhatsApp inbox. Provide the WhatsApp Cloud API credentials and phone details so Nabrah can send and receive messages on that number. The response returns the created inbox summary including its generated `id`; `chatbot_agent_id` and `chatbot_agent_name` are null, since a new number has no agent yet.

## Required connection details

These come from your Meta WhatsApp Cloud API setup.

- **name**: Display name for the inbox. Fields: `name`.
- **WhatsApp Cloud API credentials**: `phone_number` (human-readable), `phone_number_id` (Cloud API id), `business_account_id` (WABA id), and `api_key` (Meta access token). Fields: `phone_number`, `phone_number_id`, `business_account_id`, `api_key`.
- **enable_auto_assignment**: Set true to automatically assign new conversations on this inbox to agents. Fields: `enable_auto_assignment`.

The created inbox's `id` becomes the `inbox_id` used by other endpoints. Re-list with GET /api/ext/omni_v2/whatsapp/inboxes. Numbers can also be connected through Meta sign-in in the app, without entering these details; that flow is not available through the API.

## Limits

- **Number limit**: A project can connect up to `max_inboxes` WhatsApp numbers (GET /api/ext/omni_v2/whatsapp/inboxes). Connecting one more returns 409; contact support to raise the limit.
- **Already connected**: Connecting a number whose `phone_number_id` or `phone_number` is already connected to the project returns 409. Fields: `phone_number_id`, `phone_number`.

## Authorization

- `X-API-Key` (string, header, required): your workspace API key.

## Body (application/json)

### Example: Create inbox

```json
{
  "name": "Support WhatsApp",
  "phone_number": "+966512345678",
  "phone_number_id": "109876543210987",
  "business_account_id": "104958611234567",
  "api_key": "EAAGm0PX4ZCpsBA...",
  "enable_auto_assignment": true
}
```

## Response

### 200 Successful Response

Content type: `application/json`

```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "inbox_type": "whatsapp",
  "project_id": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "config": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "inbox_id": 0,
  "chatbot_agent_id": "00000000-0000-4000-8000-000000000000",
  "chatbot_agent_name": "string"
}
```

### 422 Validation Error

Content type: `application/json`

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```

## Request examples

### cURL

```bash
curl --request POST \
  --url 'https://api.nabrah.ai/api/ext/omni_v2/whatsapp/inboxes' \
  --header 'X-API-Key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support WhatsApp",
  "phone_number": "+966512345678",
  "phone_number_id": "109876543210987",
  "business_account_id": "104958611234567",
  "api_key": "EAAGm0PX4ZCpsBA...",
  "enable_auto_assignment": true
}'
```

### Python

```python
import requests

url = "https://api.nabrah.ai/api/ext/omni_v2/whatsapp/inboxes"
headers = {
    "X-API-Key": "<your-api-key>",
}
payload = {
    "name": "Support WhatsApp",
    "phone_number": "+966512345678",
    "phone_number_id": "109876543210987",
    "business_account_id": "104958611234567",
    "api_key": "EAAGm0PX4ZCpsBA...",
    "enable_auto_assignment": True
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.nabrah.ai/api/ext/omni_v2/whatsapp/inboxes", {
  method: "POST",
  headers: {
    "X-API-Key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Support WhatsApp",
    "phone_number": "+966512345678",
    "phone_number_id": "109876543210987",
    "business_account_id": "104958611234567",
    "api_key": "EAAGm0PX4ZCpsBA...",
    "enable_auto_assignment": true
  }),
});

const data = await response.json();
console.log(data);
```

### Go

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
  "name": "Support WhatsApp",
  "phone_number": "+966512345678",
  "phone_number_id": "109876543210987",
  "business_account_id": "104958611234567",
  "api_key": "EAAGm0PX4ZCpsBA...",
  "enable_auto_assignment": true
}`)

	req, _ := http.NewRequest("POST", "https://api.nabrah.ai/api/ext/omni_v2/whatsapp/inboxes", payload)
	req.Header.Set("X-API-Key", "<your-api-key>")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```