Numbers and Embedded Signup

Connect WhatsApp numbers with Embedded Signup, an existing WABA token, or a hosted link; connection states and what makes a number connected.

A number is a WhatsApp Business phone number registered on a WhatsApp Business Account (WABA). Its id is the Meta phone_number_id, which you pass as from when sending. The resource is read with GET /v1/numbers and GET /v1/numbers/{phone_number_id}.

There are three ways to connect one. All end in the same state.

#Embedded Signup

Meta's Embedded Signup is a popup run in a browser. The person logs in with Facebook, picks or creates a WABA, adds a number, and verifies it by SMS or voice. When it closes, the page receives a one-time code and the ids of the WABA and phone number.

Send those to POST /v1/numbers/embedded-signup:

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

WhaBuzz exchanges the code for a business token, checks it (the token must belong to our Meta app, carry whatsapp_business_management and whatsapp_business_messaging, and cover this WABA), stores the token encrypted, subscribes the WABA to our webhooks, and registers the number. The token never reaches your server.

#Connect an existing WABA

POST /v1/numbers/connect takes the waba_id and either a system-user access_token, or an Embedded Signup code. WhaBuzz runs the same token checks, then connects the numbers on that WABA.

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

A token rejected by those checks answers 422 invalid_request with the failing check in details.

#Hosted link for your customers

Platforms should not run Meta's popup in their own app. Create a session:

curl -X POST https://api.whabuzz.com/v1/connect-sessions \
  -H "Authorization: Bearer $WHABUZZ_APP_KEY" -H "X-WhaBuzz-Tenant: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://yourapp.example/whatsapp/done"}'

The response carries url (https://app.whabuzz.com/connect/<token>), valid for one hour. Send your customer there. After the popup, they are redirected to return_url?session_id=…&status=connected (or failed). Poll GET /v1/connect-sessions/{session_id} or wait for the number.connection event (WhaBuzz events).

#Connection state

A number is connected only when all of these hold:

1. The WABA is subscribed to WhaBuzz's webhooks.
2. The number is registered with Meta.
3. At least one of your webhook endpoints is active and subscribed to message.inbound or *.
4. The business token is not invalid.
5. The tenant is active.

Otherwise the state is pending (never completed) or disconnected, and connection_detail says why: waba_not_subscribed, not_registered, no_verified_endpoint, token_invalid or tenant_inactive. Sending from a number that is not connected answers 409 number_not_connected with that detail. Fix the detail, and the state recovers by itself; each change emits a number.connection event.

#Maintenance calls

These pass through to Meta with the number's stored token:

• register and deregister
• request-code and verify-code (SMS or voice)
• two-step sets the six-digit PIN
• subscribe re-subscribes the WABA if the state shows waba_not_subscribed
• business-profile read and update
• migrate moves a number between WABAs you control

Because they are Meta calls, their errors come back as "source":"meta".

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