API reference

Numbers

Connect and manage WhatsApp Business numbers. A number is connected only after the WABA is subscribed to WhaBuzz, the number is registered, and a webhook endpoint has passed its verify ping.

Connect and manage WhatsApp Business numbers. A number is connected only after the WABA is subscribed to WhaBuzz, the number is registered, and a webhook endpoint has passed its verify ping.

Base URL https://api.whabuzz.com. Every request needs Authorization: Bearer <key> unless the operation says otherwise; see Authentication. Errors follow the two-source contract.

Operations on this page:

GET /v1/numbers: List numbers
GET /v1/numbers/{phone_number_id}: Get a number
POST /v1/numbers/embedded-signup: Finish Embedded Signup with the code from Meta's popup
POST /v1/numbers/connect: Connect an existing WABA with a business system-user token
POST /v1/numbers/migrate: Start migrating a number into one of your WABAs
POST /v1/numbers/{phone_number_id}/register: Register the number with Cloud API
POST /v1/numbers/{phone_number_id}/deregister: Deregister the number
POST /v1/numbers/{phone_number_id}/request-code: Request an SMS or voice verification code
POST /v1/numbers/{phone_number_id}/verify-code: Verify the code
POST /v1/numbers/{phone_number_id}/two-step: Set or change the two-step verification PIN
POST /v1/numbers/{phone_number_id}/subscribe: Re-subscribe the number's WABA to WhaBuzz (repair)
GET /v1/numbers/{phone_number_id}/business-profile: Get the WhatsApp business profile
POST /v1/numbers/{phone_number_id}/business-profile: Update the WhatsApp business profile

#List numbers

GET/v1/numbers

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: listNumbers.

cURL:

curl -X GET "https://api.whabuzz.com/v1/numbers" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Numbers

{
  "data": [
    {
      "phone_number_id": "1013622581841046",
      "display_phone_number": "+1 469-231-1132",
      "verified_name": "WhaBuzz Demo",
      "waba_id": "26059971920328384",
      "connection_state": "connected",
      "connection_detail": null,
      "quality_rating": "GREEN",
      "messaging_limit_tier": "TIER_250",
      "throughput_level": "STANDARD"
    }
  ]
}

json

#Get a number

GET/v1/numbers/{phone_number_id}

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: getNumber.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes
`refresh`	query	boolean	no	Re-read the number from Meta first (stored as `meta_snapshot`).

cURL:

curl -X GET "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Number

connected:

{
  "phone_number_id": "1013622581841046",
  "display_phone_number": "+1 469-231-1132",
  "verified_name": "WhaBuzz Demo",
  "waba_id": "26059971920328384",
  "connection_state": "connected",
  "connection_detail": null,
  "quality_rating": "GREEN",
  "messaging_limit_tier": "TIER_250",
  "throughput_level": "STANDARD",
  "name_status": "APPROVED",
  "registered_at": "2026-10-02T06:00:00Z",
  "last_event_at": "2026-10-16T05:12:03Z"
}

json

pending:

{
  "phone_number_id": "1013622581841046",
  "display_phone_number": "+1 469-231-1132",
  "waba_id": "26059971920328384",
  "connection_state": "pending",
  "connection_detail": "no_verified_endpoint"
}

json

Common errors. Shape and meanings are on the Errors page.

HTTP	WhaBuzz code	Meaning
404	`not_found`	Not found

#Finish Embedded Signup with the code from Meta's popup

POST/v1/numbers/embedded-signup

Exchanges the code, checks the token, subscribes the WABA to WhaBuzz, registers the number and stores Meta's view of it.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: completeEmbeddedSignup.

Request body (application/json, required)

Field	Type	Required	Description
`code`	string	yes
`waba_id`	string	yes
`phone_number_id`	string	yes
`pin`	string	no	Two-step PIN to register with. Generated when omitted. Pattern `^[0-9]{6}$`.

Request example:

{
  "code": "AQBx…",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/embedded-signup" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "AQBx…",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046"
}'

bash

Responses

200 Number stored. connection_state tells you what is left.

{
  "phone_number_id": "1013622581841046",
  "display_phone_number": "+1 469-231-1132",
  "waba_id": "26059971920328384",
  "connection_state": "pending",
  "connection_detail": "no_verified_endpoint"
}

json

Common errors. Shape and meanings are on the Errors page.

HTTP	WhaBuzz code	Meaning
400	`131030`	Meta's error, passed through with Meta's HTTP status

#Connect an existing WABA with a business system-user token

POST/v1/numbers/connect

For businesses that already have a WABA. The token must belong to WhaBuzz's Meta app (debug_token app id), carry whatsapp_business_management and whatsapp_business_messaging, and list waba_id in its granular scopes. WhaBuzz subscribes the WABA and imports its numbers.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: connectExisting.

Request body (application/json, required)

Field	Type	Required	Description
`waba_id`	string	yes
`access_token`	string	no
`code`	string	no	Alternative to access_token: an Embedded Signup code.

Request example:

{
  "waba_id": "1496378315413646",
  "access_token": "EAAG…"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/connect" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "waba_id": "1496378315413646",
  "access_token": "EAAG…"
}'

bash

Responses

200 Imported numbers

{
  "waba_id": "1496378315413646",
  "numbers": [
    {
      "phone_number_id": "301234567890123",
      "display_phone_number": "+91 95158 47444",
      "connection_state": "pending",
      "connection_detail": "not_registered"
    }
  ]
}

json

400 Token checks failed, or Meta error

whabuzz:

{
  "source": "whabuzz",
  "error": {
    "code": "invalid_request",
    "message": "Token is not scoped to WABA 1496378315413646",
    "details": {
      "granular_scopes": [
        "whatsapp_business_messaging"
      ]
    }
  },
  "request_id": "req_01JAB3M0P4Q7R2S5T8V1W4X7Y0"
}

json

Meta 190 passed through (HTTP 401 from Meta becomes 401 here):

{
  "source": "meta",
  "error": {
    "message": "Error validating access token: Session has expired.",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 463,
    "fbtrace_id": "C3d4E5f6G7h8I9j0"
  }
}

json

#Start migrating a number into one of your WABAs

POST/v1/numbers/migrate

Wraps POST /{waba_id}/phone_numbers with migrate_phone_number=true. Follow with request-code, verify-code and register.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: migrateNumber.

Request body (application/json, required)

Field	Type	Required
`waba_id`	string	yes
`cc`	string	yes
`phone_number`	string	yes

Request example:

{
  "waba_id": "1496378315413646",
  "cc": "91",
  "phone_number": "9515847444"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/migrate" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "waba_id": "1496378315413646",
  "cc": "91",
  "phone_number": "9515847444"
}'

bash

Responses

200 Meta's response verbatim

{
  "id": "301234567890123"
}

json

Common errors. Shape and meanings are on the Errors page.

HTTP	WhaBuzz code	Meaning
400	`131030`	Meta's error, passed through with Meta's HTTP status

#Register the number with Cloud API

POST/v1/numbers/{phone_number_id}/register

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: registerNumber.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

Request body (application/json)

Field	Type	Required	Description
`pin`	string	no	Pattern `^[0-9]{6}$`.

Request example:

{
  "pin": "482913"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pin": "482913"
}'

bash

Responses

200 Meta's response verbatim

{
  "success": true
}

json

Common errors. Shape and meanings are on the Errors page.

HTTP	WhaBuzz code	Meaning
400	`131030`	Meta's error, passed through with Meta's HTTP status

#Deregister the number

POST/v1/numbers/{phone_number_id}/deregister

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: deregisterNumber.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/deregister" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Meta's response verbatim

{
  "success": true
}

json

#Request an SMS or voice verification code

POST/v1/numbers/{phone_number_id}/request-code

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: requestVerificationCode.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Description
`code_method`	`SMS` or `VOICE`	yes
`language`	string	yes

Request example:

{
  "code_method": "SMS",
  "language": "en_US"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/request-code" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code_method": "SMS",
  "language": "en_US"
}'

bash

Responses

200 Meta's response verbatim

{
  "success": true
}

json

#Verify the code

POST/v1/numbers/{phone_number_id}/verify-code

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: verifyCode.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Description
`code`	string	yes

Request example:

{
  "code": "123456"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/verify-code" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "123456"
}'

bash

Responses

200 Meta's response verbatim

{
  "success": true
}

json

Common errors. Shape and meanings are on the Errors page.

HTTP	WhaBuzz code	Meaning
400	`131030`	Meta's error, passed through with Meta's HTTP status

#Set or change the two-step verification PIN

POST/v1/numbers/{phone_number_id}/two-step

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: setTwoStepPin.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

Request body (application/json, required)

Field	Type	Required	Description
`pin`	string	yes	Pattern `^[0-9]{6}$`.

Request example:

{
  "pin": "482913"
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/two-step" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pin": "482913"
}'

bash

Responses

200 Meta's response verbatim

{
  "success": true
}

json

#Re-subscribe the number's WABA to WhaBuzz (repair)

POST/v1/numbers/{phone_number_id}/subscribe

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: resubscribeWaba.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/subscribe" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Subscribed; connection state recomputed

{
  "phone_number_id": "1013622581841046",
  "connection_state": "connected",
  "connection_detail": null
}

json

#Get the WhatsApp business profile

GET/v1/numbers/{phone_number_id}/business-profile

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: getBusinessProfile.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

cURL:

curl -X GET "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/business-profile" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Meta's response verbatim

{
  "data": [
    {
      "about": "Strength coaching in Kokapet",
      "address": "Kokapet, Hyderabad",
      "description": "Personal training studio",
      "email": "hello@example.com",
      "messaging_product": "whatsapp",
      "profile_picture_url": "https://pps.whatsapp.net/v/t61/…",
      "websites": [
        "https://example.com"
      ],
      "vertical": "HEALTH"
    }
  ]
}

json

#Update the WhatsApp business profile

POST/v1/numbers/{phone_number_id}/business-profile

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: updateBusinessProfile.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	string	yes

Request body (application/json, required)

Request example:

{
  "messaging_product": "whatsapp",
  "about": "Strength coaching in Kokapet",
  "websites": [
    "https://example.com"
  ]
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/numbers/$PHONE_NUMBER_ID/business-profile" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "about": "Strength coaching in Kokapet",
  "websites": [
    "https://example.com"
  ]
}'

bash

Responses

200 Meta's response verbatim

{
  "success": true
}

json

This page as Markdown: /api/numbers.md. All docs in one file: /llms-full.txt.

Start

Guides

API reference

Webhook events

Reference

Numbers

#List numbers

#Get a number

#Finish Embedded Signup with the code from Meta's popup

#Connect an existing WABA with a business system-user token

#Start migrating a number into one of your WABAs

#Register the number with Cloud API

#Deregister the number

#Request an SMS or voice verification code

#Verify the code

#Set or change the two-step verification PIN

#Re-subscribe the number's WABA to WhaBuzz (repair)

#Get the WhatsApp business profile

#Update the WhatsApp business profile