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

# Managing WhatsApp Phone Numbers

> Register and manage WhatsApp Business phone numbers

WhatsApp Business phone numbers must be registered with Chirp and assigned to applications before you can send or receive messages.

## Prerequisites

Before registering a phone number with Chirp, you need:

1. A WhatsApp Business account with Meta
2. A verified phone number in your WhatsApp Business account
3. The Meta Phone Number ID for your number
4. The Meta Business Account ID

You can find these IDs in the [Meta Business Manager](https://business.facebook.com) under WhatsApp settings.

## Registering a Phone Number

Register a WhatsApp phone number with your organization:

```bash icon="terminal" title="Register Phone Number" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/organization/whatsapp/phone-numbers \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayPhoneNumber": "+15551234567",
    "metaPhoneNumberId": "123456789012345",
    "metaBusinessAccountId": "987654321098765",
    "appIds": ["app_abc123"]
  }'
```

### Request Parameters

| Parameter               | Type   | Required | Description                                |
| ----------------------- | ------ | -------- | ------------------------------------------ |
| `displayPhoneNumber`    | string | Yes      | Phone number in E.164 format               |
| `metaPhoneNumberId`     | string | Yes      | Phone Number ID from Meta Business Manager |
| `metaBusinessAccountId` | string | Yes      | Business Account ID from Meta              |
| `appIds`                | array  | No       | Application IDs to assign the number to    |

### Response

```json icon="code" title="Response" theme={null}
{
  "id": "wap_2DbBs7GWhGvVNJGrDXr5RG0",
  "displayPhoneNumber": "+15551234567",
  "metaPhoneNumberId": "123456789012345",
  "metaBusinessAccountId": "987654321098765",
  "verified": false,
  "qualityRating": null,
  "isTestNumber": false,
  "apps": [
    {
      "appId": "app_abc123",
      "appName": "My App",
      "appSlug": "my-app"
    }
  ],
  "createdAt": "2024-01-15T12:00:00.000Z",
  "updatedAt": "2024-01-15T12:00:00.000Z"
}
```

## Listing Phone Numbers

List all WhatsApp phone numbers in your organization:

```bash icon="terminal" title="List Phone Numbers" theme={null}
curl https://api.buildwithchirp.com/v1/organization/whatsapp/phone-numbers \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"
```

### Query Parameters

| Parameter      | Type    | Description                         |
| -------------- | ------- | ----------------------------------- |
| `limit`        | number  | Maximum results (1-100, default 20) |
| `offset`       | number  | Results offset for pagination       |
| `isTestNumber` | boolean | Filter by test number status        |

### Response

```json icon="code" title="Response" theme={null}
{
  "phoneNumbers": [
    {
      "id": "wap_2DbBs7GWhGvVNJGrDXr5RG0",
      "displayPhoneNumber": "+15551234567",
      "metaPhoneNumberId": "123456789012345",
      "metaBusinessAccountId": "987654321098765",
      "verified": true,
      "qualityRating": "GREEN",
      "isTestNumber": false,
      "apps": [
        {
          "appId": "app_abc123",
          "appName": "My App",
          "appSlug": "my-app"
        }
      ],
      "createdAt": "2024-01-15T12:00:00.000Z",
      "updatedAt": "2024-01-15T12:00:00.000Z"
    }
  ],
  "totalCount": 1
}
```

## Assigning Numbers to Applications

Update which applications a phone number is assigned to:

```bash icon="terminal" title="Update App Assignments" theme={null}
curl -X PUT https://api.buildwithchirp.com/v1/organization/whatsapp/phone-numbers/{phoneNumberId}/apps \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appIds": ["app_abc123", "app_def456"]
  }'
```

This replaces all current assignments with the new list of apps.

## Sharing Numbers Across Applications

You can assign the same WhatsApp number to multiple applications:

* Each app uses its own API keys
* Each app can have its own webhook configuration
* Messages are routed based on the app context

This allows you to:

* Use one number for multiple projects
* Separate test and production environments
* Route messages to different webhook endpoints

## Quality Rating

WhatsApp assigns quality ratings to phone numbers based on user feedback:

| Rating   | Description                                               |
| -------- | --------------------------------------------------------- |
| `GREEN`  | High quality - no issues                                  |
| `YELLOW` | Medium quality - some users marked messages as spam       |
| `RED`    | Low quality - high spam reports, messaging may be limited |

<Warning>
  If your quality rating drops to RED, WhatsApp may limit or suspend your ability to send messages. Monitor your quality rating and respond to user feedback.
</Warning>

## Test Phone Numbers

For development and testing, you can register test phone numbers:

* Test numbers are marked with `isTestNumber: true`
* Use test numbers with test API keys
* Test numbers don't affect production quality ratings

## Finding Meta IDs

To find your Meta Phone Number ID and Business Account ID:

1. Log in to [Meta Business Manager](https://business.facebook.com)
2. Navigate to **WhatsApp Manager**
3. Select your WhatsApp Business Account
4. Click on **Phone Numbers**
5. Your Phone Number ID is displayed for each number
6. Your Business Account ID is in the URL or account settings

<Tip>
  Keep your Meta IDs secure. The Phone Number ID is required for API operations, but should not be shared publicly.
</Tip>