Phone numbers
A phone number is a registered WhatsApp Business line. It’s the single most important identifier in the API — every message you send specifies a phone_number_id.
WABA business_id=123
├── PhoneNumber phone_number_id=555123456789 +54 11 5555 1234 (quality: green)
└── PhoneNumber phone_number_id=555987654321 +54 11 5555 5678 (quality: yellow)phone_number_id is the key
Meta gives each registered phone a unique numeric ID (phone_number_id). This is what you pass to send/receive operations — not the human-readable phone string.
# ✓ Correct
POST /v1/messages
{
"phone_number_id": "555123456789",
"to": "5491140123456",
...
}
# ✗ Wrong — using display phone instead of ID
POST /v1/messages
{
"phone_number_id": "+5491155551234",
...
}The phone_number_id is stable across number ports, display name changes, etc. It’s the only safe identifier to persist in your DB.
Properties
| Field | Type | Description |
|---|---|---|
id | bigint | Internal numeric ID |
waba_id | bigint | Internal WABA ID |
phone_number_id | string | Meta’s identifier — use this in all API calls |
display_phone_number | string | Human-readable: +54 11 5555 1234 |
display_phone_number_normalized | string | E164 without spaces: 5491155551234 |
display_name | string | What contacts see on top of the chat |
verified_name | string | If business verified, the legal name |
quality_rating | enum | green / yellow / red / unknown |
throughput_tier | string | Standard / High (msg/sec capacity) |
connection_type | enum | dedicated / coexistence |
is_coexistence | boolean | true if the number ALSO runs the consumer WhatsApp Business app |
is_official_business_account | boolean | Green checkmark from Meta |
inbound_processing_enabled | boolean | If false, we ignore inbound webhooks |
calls_enabled | boolean | WhatsApp Calls API enabled (beta) |
status | string | Lifecycle status (active/disconnected/pending) |
Quality rating
Meta assigns a quality rating based on contact feedback (block rate, complaint rate, etc.):
| Rating | Meaning | Effect |
|---|---|---|
🟢 green | Healthy | Higher messaging limits, recommended |
🟡 yellow | Some complaints, watch out | Lower throughput, monitor your content |
🔴 red | High complaints — can be downgraded | Lowest tier, risk of suspension |
⚪ unknown | Brand new number, not enough data yet | Treated as green initially |
If quality drops to red, the next escalation is WABA suspension. Pause marketing sends and double-check your opt-in flow immediately.
GoSendAPI emits a whatsapp.phone_number.quality_update webhook event when the rating changes, so you can react in real-time.
Connection types
| Type | When |
|---|---|
dedicated | The number is only for Cloud API. Recommended. Highest reliability. |
coexistence | The number is also registered in the WhatsApp Business consumer app. The customer can use both. Meta beta — not always stable. |
Throughput tiers
Meta limits how many messages/second a number can send:
| Tier | Limit | How to upgrade |
|---|---|---|
| Standard | 80 msg/s | Default for new numbers |
| Medium | 200 msg/s | Sustained volume + green quality |
| High | 1000 msg/s | Apply to Meta, requires consistent traffic + green |
| Unlimited | No limit | Enterprise customers, Meta approval |
The dashboard shows the current tier and you can apply for upgrades from there.
Phone number lifecycle
provisioning (during Embedded Signup)
│
▼
pending (WABA created, waiting for PIN verification)
│
▼
active (can send/receive)
│
├──> disconnected (token expired or revoked)
│ │
│ └──> active (after reconnect)
│
└──> deleted (customer removed it)Webhooks for phone events
| Event | When it fires |
|---|---|
whatsapp.phone_number.created | New phone registered to a WABA |
whatsapp.phone_number.quality_update | Quality rating changed |
whatsapp.phone_number.deleted | Phone removed from WABA |
Configure these in Webhooks to keep your system in sync.