Managing WhatsApp 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:

A WhatsApp Business account with Meta
A verified phone number in your WhatsApp Business account
The Meta Phone Number ID for your number
The Meta Business Account ID

You can find these IDs in the Meta Business Manager under WhatsApp settings.

Registering a Phone Number

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

{
  "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:

List Phone Numbers

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

{
  "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:

Update App Assignments

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. 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

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.

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:

Log in to Meta Business Manager
Navigate to WhatsApp Manager
Select your WhatsApp Business Account
Click on Phone Numbers
Your Phone Number ID is displayed for each number
Your Business Account ID is in the URL or account settings

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

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Managing WhatsApp Phone Numbers

Prerequisites

Registering a Phone Number

Request Parameters

Response

Listing Phone Numbers

Query Parameters

Response

Assigning Numbers to Applications

Quality Rating

Test Phone Numbers

Finding Meta IDs

​Prerequisites

​Registering a Phone Number

​Request Parameters

​Response

​Listing Phone Numbers

​Query Parameters

​Response

​Assigning Numbers to Applications

​Sharing Numbers Across Applications

​Quality Rating

​Test Phone Numbers

​Finding Meta IDs

Prerequisites

Registering a Phone Number

Request Parameters

Response

Listing Phone Numbers

Query Parameters

Response

Assigning Numbers to Applications

Sharing Numbers Across Applications

Quality Rating

Test Phone Numbers

Finding Meta IDs