Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Get a WhatsApp number

GET
/v1/whatsapp/numbers/{number_id}
const number = await bird.whatsapp.numbers.get("wan_01krdgeqcxet5s7t44vh8rt9mg");
console.log(number.status, number.quality_rating, number.messaging_limit);
Response200
{
  "id": "wan_01krdgeqcxet5s7t44vh8rt9mg",
  "waba": "102290129340398",
  "phone_number": "+15550001234",
  "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg",
  "name": "Sales EU",
  "scope": "workspace",
  "data_localization_region": "DE",
  "status": "connected",
  "next": [
    {
      "kind": "operation"
    }
  ],
  "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"
}

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.

Parameters

number_idstring

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

Response Payload

id
string
required

Unique identifier for the connected number.

waba
string

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

phone_number
nullable string
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_id
string

The number you hold with us that this WhatsApp number was connected from, as its id in GET /v1/numbers. Absent for a number you brought yourself.

name
string
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
string
required

Whether the number sends under a WhatsApp Business Account we operate on your behalf (system) or one your workspace connected itself (workspace).

data_localization_region
string

The country this number's message content is stored at rest in, as its two-letter ISO 3166 code. Absent when it uses WhatsApp's default storage. It can differ from the region requested at connection when WhatsApp requires a particular country for the number.

status
string
required

WhatsApp's own state for this number as of meta_synced_at, except for the three states we answer ourselves because WhatsApp holds nothing to report. A connection we are still verifying reads preparing, one waiting for someone to finish signup reads awaiting_signup, and a permanently refused one reads failed, with error saying why. 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, so it does not by itself establish whether setup is complete. A number we operate on your behalf reads connected as our own assertion rather than a reading from WhatsApp for every number we ship today; that tier carries no meta_synced_at.

next
array of object

What to do next about this number, given the state it is in. Each entry names one action and says why it is worth taking, so you can act on this response without working out the order yourself. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.

While status is awaiting_signup this carries the browser step that finishes the connection, because embedded signup sits behind an OAuth screen no API call can stand in for.

Show child attributes
next.kind
string
required

What you do about this step.

  • operation: call the operation named in operation, then read again.
  • external: act somewhere this API does not reach, then read again.
  • wait: nothing is asked of you, so read again later.
  • terminal: nothing you do resolves this, so stop retrying.

Tolerate a value you do not recognize: show the description and offer no action.

Possible values (may grow over time): operation, external, wait, terminal

next.description
string
required

A short, human-readable label for the step, suitable for display.

next.operation
string

The operationId to call. Present only when kind is operation. The operation's own schema says how to call it; this says only which one, and what to address it with.

next.params
object

The parameters that address the operation, by name: {"sender_id": "…"} for an operation on /v1/sms/senders/{sender_id}/requirements. A parameter the operation takes in its query string is given the same way, so an operation addressed as ?subject_id= carries {"subject_id": "…"}. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when kind is operation and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.

next.url
string

A URL to open. Present only when kind is external, and only when the step has one. An external step whose description says to go and do something with no URL to open is normal.

error
object

Why this number's connection was refused for good. Present only while status is failed. A retryable step records its cause on a still-pending number without setting this field, because that cause is not a refusal yet, so a connection you are still waiting on reports no error here.

Show child attributes
error.code
string
required

Standardized failure reason.

error.description
string

Why the connection failed: WhatsApp's own words, in the language of the account it refused, when WhatsApp answered; our own explanation when the number was refused before WhatsApp was asked; a generic sentence when WhatsApp refused without giving a reason. Absent when the attempt failed without ever reaching WhatsApp, which leaves code as the only account of the failure. Show it to the person who owns the number; never match on its text.

error.meta_error_code
nullable string

WhatsApp's most specific code for the refusal: its error subcode where it sent one, otherwise its top-level code. Null when WhatsApp did not provide a code. Treat it as an opaque string.

finish_setup_url
string

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_rating
string

WhatsApp's quality rating for this number as of meta_synced_at. Absent until WhatsApp has reported one, and always absent for a number we operate on your behalf.

messaging_limit
string

The messaging limit WhatsApp applied to this number's business portfolio as of meta_synced_at. Absent until WhatsApp has reported one, and always absent for a number we operate on your behalf.

throughput_level
string

The send rate WhatsApp allowed this number as of meta_synced_at. Absent until WhatsApp has reported one, and always absent for a number we operate on your behalf.

is_official_business_account
boolean

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.

meta_synced_at
string

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_at
string

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_at
string
required

When this number was submitted for connection.

updated_at
string
required

When this number was last changed.

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief