Skip to main content
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 under WhatsApp settings.

​
Registering a Phone Number

Register a WhatsApp phone number with your organization:
Register 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

ParameterTypeRequiredDescription
displayPhoneNumberstringYesPhone number in E.164 format
metaPhoneNumberIdstringYesPhone Number ID from Meta Business Manager
metaBusinessAccountIdstringYesBusiness Account ID from Meta
appIdsarrayNoApplication IDs to assign the number to

​
Response

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

ParameterTypeDescription
limitnumberMaximum results (1-100, default 20)
offsetnumberResults offset for pagination
isTestNumberbooleanFilter by test number status

​
Response

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.

​
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:
RatingDescription
GREENHigh quality - no issues
YELLOWMedium quality - some users marked messages as spam
REDLow 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:
  1. Log in to Meta Business Manager
  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
Keep your Meta IDs secure. The Phone Number ID is required for API operations, but should not be shared publicly.