Managing WhatsApp numbers
Open Numbers to see your WhatsApp numbers, their connection status, and their business accounts. To add a number, follow Connect your number.
Check connection status
| Status | What to do |
|---|---|
| Preparing | Wait while Bird verifies a number your workspace holds. |
| Pre-verified | Select Finish setting up to connect it through Meta. |
| Pending | Wait while Bird registers the number with Meta. |
| Connected | Your number is ready to send. |
| Failed | Open the number to check the failure reason. |
For verification_code_not_received or verification_rate_limited, select Try again on the number's page. See pre-verification failures for retry timing. For other setup failures, disconnect the failed number before connecting it again.
Review a connected number
Open a number to see its Quality rating, Messaging limit, and Send rate. These values come from Meta. Not rated means Meta does not yet have enough history to score the number.
Use Business profile to update the display name, description, address, and profile picture recipients see. The Activity section shows sending activity.
Review the business account
Select the account in the WABA column to review the WhatsApp Business Account that owns the number.
- Business verification affects access to features such as your own authentication templates.
- Marketing Messages API shows whether Meta has accepted the account for its marketing delivery optimizations. Marketing messages can send before onboarding, but GIF headers require it.
- Last read from WhatsApp shows when Bird last refreshed these details.
A workspace can have several business accounts. Check the account linked to the number you plan to send from.
Read your numbers from the API
Use an API key with whatsapp_management read access. List numbers returns a cursor page of your numbers:
for await (const number of bird.whatsapp.numbers.list({ limit: 25 })) {
console.log(number.id, number.phone_number, number.status);
}for number in client.whatsapp.numbers.list(limit=25):
print(number.id, number.phone_number, number.status)for number, err := range client.Whatsapp.Numbers.List(ctx, bird.WhatsappNumbersListParams{Limit: 25}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(number.Id, number.PhoneNumber, number.Status)
}foreach ($bird->whatsapp->numbers->list() as $number) {
echo $number->getId(), ' ', $number->getPhoneNumber(), ' ', $number->getStatus(), PHP_EOL;
}curl -sS "https://us1.platform.bird.com/v1/whatsapp/numbers?limit=25" \
-H "Authorization: Bearer $BIRD_API_KEY"Read a number for its status, quality rating, and sending limits. Related reads include:
| Endpoint | Returns |
|---|---|
| Number profile | Description, address, and websites. |
| Number events | Setup, status, quality, limit, and display-name changes, newest first. |
| Business accounts | The workspace's WhatsApp Business Accounts. |
| Business account details | Account review, business verification, marketing onboarding, and Meta health status. |
meta_synced_at dates the values last read from Meta. It is absent on default numbers. meta_health_status is absent until Bird has read the account. A number's waba contains Meta's account ID.
During setup, status can be preparing or awaiting_signup. The next field describes the next action, and finish_setup_url opens the browser step. Event type is an open enum, so handle unfamiliar values without failing.
Use the dashboard or CLI to connect, rename, or disconnect a number; these actions are not part of the public API or SDKs. The CLI commands are bird whatsapp numbers create|update|delete and bird whatsapp numbers profile update. Creating a connection returns finish_setup_url because Meta's consent step requires a browser.
Receive messages
Messages to your connected numbers appear in the WhatsApp log. The Inbound metrics show received volume by number. Each inbound message opens the 24-hour customer service window for free-form replies.
Number options
For a number your workspace holds at Bird, Connect your number shows automatic verification and Meta setup. For a number held elsewhere, choose I have my own number and receive Meta's SMS or voice code yourself. Use the supported migration or eligible Business app coexistence path for an existing registration. Enter a Phone registration PIN only if the number already has one on WhatsApp.
Default numbers send supported templates without connecting your own number.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideConnecting WhatsApp to Bird: from buying a number to a live channelUnderstand the conceptWhat is the 24-hour customer service window on WhatsApp?Use the toolWhatsApp message builderExplore the capabilityWhatsApp
Try the practice and get an implementation brief