whatsapp-numbers

List WhatsApp numbers

Returns a paginated list of the WhatsApp numbers your workspace can send from. The list includes both platform-managed numbers and numbers on a WhatsApp Business Account you connected. Each item reports its WhatsApp status, quality rating, business portfolio messaging limit, allowed send rate, and Official Business Account status.

Page through the full set with the response cursors. A cursor naming a platform-managed number is rejected once the active filters would exclude it, including a scope=system cursor for a number that is not platform-managed. Start again without starting_after or ending_before whenever you change phone_number, waba, status, or scope.

get/v1/whatsapp/numbers

Request

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

Query parameters

wabastring
Example:102290129340398

Filter to a single WhatsApp Business Account by its Meta-assigned ID. Use the waba of a connected WhatsApp Business Account, or the waba on a number this list returns. A platform-managed number belongs to no WhatsApp Business Account and is never returned when this is set, so pairing it with scope=system always returns an empty page. An account this workspace does not hold returns an empty page.

phone_numberstring
Example:+31612340001

Filter to a single number, given in E.164 format. The value is normalized before matching, so +31612340001 and +31 6 1234 0001 are the same filter. A value that cannot be normalized is matched exactly as given. A number this workspace cannot send from returns an empty page, rather than being rejected.

statusWhatsAppNumberStatus[]

Filter by the number's WhatsApp state: the status a number in this list carries. Every value matches that status exactly, so repeat the parameter for each state you want. pending covers both a number WhatsApp reports as not registered and one it has reported no state for at all, while the two states before that keep their own values: a number we are still verifying carries preparing, and one waiting for someone to finish signup carries awaiting_signup. Asking for all three reaches every connection that has not finished, plus any finished one WhatsApp has not reported on yet. failed matches a connection refused permanently. A value this vocabulary does not recognize matches nothing, rather than being rejected. Omit to return numbers in every state.

[
  "connected"
]
scope'system' | 'workspace'
Example:workspace

Filter by ownership tier: system for platform-managed numbers and workspace for numbers your workspace connected. Omit to return both. A system number belongs to no WhatsApp Business Account, so pairing this with waba always returns an empty page.

sort'created_at'

Sortable fields for a WhatsApp number list.

Field to sort by.

order'asc' | 'desc'

Sort direction, ascending or descending.

Sort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

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

A page of the WhatsApp numbers your workspace can send from.

next_cursorstring nullable required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursorstring nullable required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursorstring nullable required

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Example response

{
  "data": [
    {
      "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"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Changes

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