Getting started

From sign-up to your first received webhook event in seven steps.

Seven steps, in order. The console steps can also be done through the API; each step links to the endpoint.

You will need: a business email address (free-mail domains are refused), a GSTIN or PAN, a WhatsApp number that is not already in use on a personal WhatsApp account, and an HTTPS URL on your server that can receive webhooks.

#1. Sign up

Create an account at app.whabuzz.com with your business email, website and tax id (GSTIN or PAN). Confirm the email link. Your account is created in pending_approval.

#2. Wait for approval

A person at WhaBuzz reviews every sign-up. Until then you can sign in and read these docs, but every /v1 call except GET /v1/tenant answers 403 tenant_not_approved. You get an email when the account is approved. If it is rejected, the email carries the reason.

#3. Connect a number

In the console open Numbers and run Embedded Signup, which walks you through Meta's popup: log in with Facebook, pick or create your WhatsApp Business Account, add the number, verify it with the code Meta sends. WhaBuzz then subscribes the account to its webhooks and registers the number.

Already have a WABA and a system-user token? Use POST /v1/numbers/connect instead. Both paths are in Numbers and Embedded Signup.

The number shows pending until step 5 is done. A number is connected only after the WABA is subscribed, the number is registered, and one of your webhook endpoints has passed its verify ping.

#4. Create an API key

Console, API keys, or POST /v1/api-keys from a console session. The full key (wb_live_…) is shown once. Store it as a secret.

export WHABUZZ_KEY="wb_live_7Hq2Xc9LmN4pR8sT1vW6yZ0aB3dE5fG7hJ2kM4nP6"   # your key
curl https://api.whabuzz.com/v1/tenant -H "Authorization: Bearer $WHABUZZ_KEY"

#5. Add a webhook endpoint

Console, Webhooks, or POST /v1/webhooks.

curl -X POST https://api.whabuzz.com/v1/webhooks \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/whatsapp/events","event_types":["*"]}'

WhaBuzz immediately POSTs a signed verify ping with a challenge. Your endpoint must answer 2xx with the challenge as plain text or JSON {"challenge":"…"}. The response carries your signing secret (whsec_…), shown once. Handler code is in Webhooks.

When the endpoint is active and the number is registered, the number turns connected.

#6. Send a template

To start a conversation WhatsApp requires an approved template. Create one with POST /v1/templates (Meta's own template body) and wait for the template.status event with event: "APPROVED", or use a template already approved on your WABA (POST /v1/templates/sync imports them).

curl -X POST https://api.whabuzz.com/v1/messages \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "1013622581841046",
    "messaging_product": "whatsapp",
    "to": "16505551234",
    "type": "template",
    "template": {
      "name": "renewal_reminder",
      "language": { "code": "en" },
      "components": [
        { "type": "body", "parameters": [
          { "type": "text", "text": "Kerry" },
          { "type": "text", "text": "31 Oct" } ] }
      ]
    }
  }'

from is the phone_number_id of one of your numbers (or its E.164 number). Everything else is Meta's body. A success answer is Meta's:

{"messaging_product":"whatsapp","contacts":[{"input":"16505551234","wa_id":"16505551234"}],"messages":[{"id":"wamid.HBgL…","message_status":"accepted"}]}

If Meta refuses, you get Meta's HTTP status and Meta's error, labelled "source":"meta". While your WhatsApp Business account is in test mode, Meta answers 131030 for recipients outside the allowed list; see Errors.

#7. Receive the first event

Seconds later your endpoint receives a message.status event for the message you just sent (sent, then delivered, then read), and a message.outbound event recording the send itself. When the customer replies, you receive message.inbound.

Verify the signature, answer 2xx quickly, and dedupe on dedupe_key. The payloads are in the event catalogue; a status event looks like this one.

The console's Getting started checklist ticks off the same four things: number connected, API key created, webhook verified, test message sent.

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