whatsapp-numbers

Get a WhatsApp number

Returns a WhatsApp number connected to the workspace and its state as of meta_synced_at. Poll this after completing embedded signup to follow the connection. The reported status can lag send availability by up to one hour.

pending is WhatsApp's own token for a number it does not hold as registered, and is also what a number with no stored WhatsApp status reads, including after setup completes. Other WhatsApp states include connected, disconnected, and flagged. A failed status means connection setup ended permanently, and error says why; a failure still being retried leaves the number pending and sets no error.

get/v1/whatsapp/numbers/{number_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/whatsapp/numbers/{number_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

number_idstring required
Example:wan_01krdgeqcxet5s7t44vh8rt9mg

ID of the WhatsApp number (wan_ prefix), as returned by the number list.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The WhatsApp number.

idstring required
wabastring

The WhatsApp Business Account this number is connected under. Present only for a number your workspace connected itself.

phone_numberstring nullable required

The number in E.164 format. Null only while the number itself is not yet known: a number your workspace holds carries its E.164 from the moment setup starts, so a value here does not mean the number can send. status is what says that.

number_idstring

Identifier of a number allocated to your workspace, as returned in the id field of GET /v1/numbers.

namestring required

Your workspace's own label for this number, given when it was connected and changeable afterwards. It has no bearing on what WhatsApp displays to people the number messages; GET /v1/whatsapp/numbers/{number_id}/profile returns that as display_name. For a number we operate on your behalf, this is our own label instead and cannot be changed.

scope'system' | 'workspace' required
data_localization_region'AU' | 'ID' | 'IN' | 'JP' | 'SG' | 'KR' | 'DE' | 'CH' | 'GB' | 'BR' | 'BH' | 'ZA' | 'AE' | 'CA'

A country where WhatsApp can store a business phone number's message content at rest, as its two-letter ISO 3166 code.

statusstring required

Operational state of a business phone number. The preparing status means the service is verifying a managed number. The awaiting_signup status means verification finished and you must complete signup. The pending status is WhatsApp's own token for a number it does not hold as registered, and is also returned when no WhatsApp status has been stored, including after setup completes. It does not by itself establish whether setup is complete. The connected status means registration completed. The failed status means connection was refused permanently. Other values are WhatsApp's own operational states for a number already connected. This is an open enum. Accept unrecognized values.

finish_setup_urlstring uri

Where a person finishes connecting this number, present only while status is awaiting_signup. Finishing means completing WhatsApp's embedded signup, which is a browser flow behind an OAuth screen: it cannot be done over the API, so open this link and have someone with access to the workspace complete it. The number is offered to them already verified. Once they finish, status moves on and this link is no longer returned.

quality_ratingstring

WhatsApp quality rating for a business phone number, based on recipient feedback. green, yellow, and red indicate decreasing quality; sustained red can restrict the number. unknown is itself a reported rating. This is separate from a template-language quality score. Accept unrecognized values.

messaging_limitstring

How many unique WhatsApp users can be messaged outside a customer service window in a rolling 24 hours, as WhatsApp's own tier token. WhatsApp calculates this for the business portfolio, and every number in that portfolio shares it; it is not this number's private capacity, and one number can consume all of it. Values are WhatsApp's own tokens, lower-cased. Open enum: WhatsApp documents a 2,000 limit its published tier vocabulary has no token for, so treat an unrecognized value as a tier WhatsApp added.

throughput_levelstring

How fast WhatsApp lets this number send, as WhatsApp's own level token. standard is 80 messages per second; WhatsApp upgrades an eligible number to 1,000 per second automatically. Values are WhatsApp's own tokens, lower-cased. This enum is open because WhatsApp publishes no vocabulary for the field. The standard value is the only value Bird has measured. The upgraded level's token remains unknown until a number returns it.

is_official_business_accountboolean

Whether WhatsApp grants this number Official Business Account status as of meta_synced_at. Absent until WhatsApp has reported it, and always absent for a number we operate on your behalf. WhatsApp grants the status per number, so two numbers on one WhatsApp Business Account can differ. The status also decides whether a rename is possible here: a number that has it cannot be renamed through PATCH /v1/whatsapp/numbers/{number_id}/profile at all, and has to be renamed through WhatsApp support instead.

is_on_business_appboolean

Whether this number is also in use on the WhatsApp Business app, so the business keeps sending one-to-one messages from the app while you send through the API. Absent until WhatsApp has reported it, and always absent for a number we operate on your behalf.

meta_synced_atstring date-time

When this number's state was last read from WhatsApp. status, quality_rating, messaging_limit, throughput_level, and is_official_business_account all belong to that reading rather than representing live values. We re-read roughly hourly, so a change at WhatsApp can be up to an hour old here. Absent for a number we have never read back and for a number we operate on your behalf.

pre_verification_requested_atstring date-time

When we last asked WhatsApp to send this number a verification code, which we do only for a number your workspace connected itself from a number you hold with us. Absent for a number we operate on your behalf, and for one you connected through Embedded Signup with a code you read yourself. Wait a few hours after this before repairing a number whose verification failed: WhatsApp rotates the routes it verifies over during that period, and throttles a number asked repeatedly in a short window. Distinct from updated_at, which any change to the number moves.

created_atstring date-time required

When this number was submitted for connection.

updated_atstring date-time required

When this number was last changed.

Example response

{
  "id": "wan_01krdgeqcxet5s7t44vh8rt9mg",
  "waba": "102290129340398",
  "phone_number": "+15550001234",
  "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg",
  "name": "Sales EU",
  "scope": "workspace",
  "data_localization_region": "DE",
  "status": "connected",
  "error": {
    "code": "registration_pin_rejected",
    "description": "Cannot Create Certificate: Please ensure two-factor authentication is disabled.",
    "meta_error_code": "2388001"
  },
  "finish_setup_url": "https://bird.com/dashboard/w/ws_01krdgeqcxet5s7t44vh8rt9mg/whatsapp/numbers?finish_setup_number=wan_01krdgeqcxet5s7t44vh8rt9mg",
  "quality_rating": "green",
  "messaging_limit": "tier_250",
  "throughput_level": "standard"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.