Numbers

The WhatsApp phone numbers connected to your organization. Read them to pick a sending number and watch its health.

EndpointsKey permission

GET/v1/numbersList connected numbersnumbers:read
GET/v1/numbers/{id}numbers:read
GET/v1/numbers/{id}/profileWhatsApp business profilenumbers:read
GET/v1/numbers/{id}/conversationalIce breakers, commands and welcome messagenumbers:read
GET/v1/numbers/{id}/qr-codesClick-to-chat QR codesnumbers:read

Connecting numbers

Numbers are connected through Meta's Embedded Signup in Settings → WhatsApp numbers. Registering, renaming, editing the profile and removing numbers are done there too — they aren't available to API keys.

The number object

Use the Engage id as phone_number_id when sending messages and creating campaigns. GET /v1/numbers returns { "data": [...] }; keys with messages:send can list numbers too.

JSON

{
  "id": "1c2d3e4f-…",
  "phone_number_id": "100000000000001",
  "waba_id": "1000000000000002",
  "messaging_account_id": "5b8e…",
  "display_phone": "+1 415 555 0100",
  "verified_name": "Example Store",
  "name_status": "APPROVED",
  "new_name_status": null,
  "quality_rating": "GREEN",
  "status": "CONNECTED",
  "code_verification_status": "VERIFIED",
  "messaging_limit": "TIER_10K",
  "payment_method_status": "VALID",
  "mps": 80,
  "throughput_level": "STANDARD",
  "is_coexistence": false,
  "is_official": false,
  "label": "Support line",
  "is_default": true,
  "registered_at": "2026-11-02T09:12:00Z",
  "last_webhook_at": "2026-11-11T10:45:11Z",
  "synced_at": "2026-11-11T06:00:00Z",
  "profile": { "about": "…", "description": "…", "websites": ["https://example.com"] },
  "conversational": { "prompts": ["Track my order"], "enable_welcome_message": true }
}

Field	Meaning
`phone_number_id`	Meta's id for the number (not the Engage id)
`quality_rating`	`GREEN`, `YELLOW` or `RED` — WhatsApp's view of recent customer feedback
`messaging_limit`	How many unique people the business can start conversations with per 24 hours, e.g. `TIER_1K`, `TIER_10K`
`mps`	Messages per second Engage paces this number to
`is_coexistence`	The number is also used in the WhatsApp Business app
`is_default`	Used when a send doesn't name a `phone_number_id`

Subscribe to the number.quality webhook to hear when quality, throughput or the messaging limit changes.

Something unclear or missing on this page? Tell us at contact@swastik.ai