Developer docs

Three things: connect a number, receive its messages at your webhook, send messages with your API key.

1. Connect a number

In the dashboard press Connect a number. Meta's Embedded Signup opens in a window; choose Use my existing WhatsApp Business app number for coexistence (the number stays on the phone) or Register a new number for API-only. The connection appears with its phone number id.

2. Receive messages

Set your webhook URL in Webhook. Every event is posted as JSON with the header X-NumberBridge-Signature = HMAC-SHA256 of the raw body with your webhook secret.

POST https://yourapp.com/hooks/whatsapp Content-Type: application/json X-NumberBridge-Signature: 2f0c… {"event":"message","connection":{"phone_number_id":"1493089310546632","display_phone":"+91 95917 24716"}, "message":{"id":"wamid.HBg…","from":"919716019716","timestamp":1760412000,"type":"text","text":{"body":"ledger bhej do"}}}

Statuses arrive the same way with "event":"status" and status in sent / delivered / read / failed. Reply 2xx within 10 seconds; anything else is retried three times with backoff and shown in your delivery log.

3. Send a message

curl -X POST https://numberbridge.io/api/v1/messages \ -H "Authorization: Bearer nb_live_…" -H "Content-Type: application/json" \ -d '{"to":"919716019716","text":"Namaskar Mahavir ji, ledger attached hai."}' # an approved template (required outside the 24-hour window) -d '{"to":"919716019716","template":{"name":"payment_reminder_gentle_gp","language":"en","body_params":["Mahavir ji","GP/26-27/0160","Rs 13,31,795"]}}' # a document by public link -d '{"to":"919716019716","document":{"link":"https://…/ledger.pdf","filename":"ledger.pdf","caption":"Statement"}}'

Response: {"ok":true,"message_id":"wamid.…"}. With more than one connection, pass "from":"<phone_number_id>".

Other endpoints

  • GET /api/v1/connections: your connections and their status.
  • GET /api/v1/messages?wa_id=…&limit=50: the stored thread.
  • GET /api/v1/templates: approved templates.

Rules worth knowing

  • Free text only inside 24 hours of the customer's last message; otherwise an approved template.
  • Two numbers that are both on the WhatsApp Business Platform cannot message each other; test from an ordinary phone.
  • Coexistence needs a number that has been on the WhatsApp Business app for a few days and a phone that stays online for the first sync.