API Reference (v1)

Send WhatsApp messages programmatically. All endpoints are under https://app.wazvox.com/api/v1 and require an API key (create one under Developers).

Authentication

Pass your key in the Authorization header:

Authorization: Bearer wbsp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Send a text message

POST /api/v1/messages

curl -X POST https://app.wazvox.com/api/v1/messages \
  -H "Authorization: Bearer $WBSP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "from": "15551234567",       // your connected number or phone_number_id
    "to": "15557654321",         // recipient (E.164, no +)
    "text": "Hello from the API!"
  }'

Response 201:

{
  "id": "ckv...",
  "waMessageId": "wamid.HBg...",
  "status": "accepted",
  "to": "15557654321",
  "from": "+1 555 123 4567"
}

Note: free-form text is only deliverable inside the 24-hour customer service window. Outside it, use a template.

Send a template message

curl -X POST https://app.wazvox.com/api/v1/messages \
  -H "Authorization: Bearer $WBSP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "template",
    "from": "15551234567",
    "to": "15557654321",
    "template": {
      "name": "order_confirmation",
      "language": "en_US",
      "components": [
        { "type": "body", "parameters": [ { "type": "text", "text": "1234" } ] }
      ]
    }
  }'

Get message status

GET /api/v1/messages/:id

curl https://app.wazvox.com/api/v1/messages/wamid.HBg... \
  -H "Authorization: Bearer $WBSP_KEY"

List numbers / templates

curl https://app.wazvox.com/api/v1/numbers   -H "Authorization: Bearer $WBSP_KEY"
curl https://app.wazvox.com/api/v1/templates -H "Authorization: Bearer $WBSP_KEY"

Receiving events (your webhook)

Configure a webhook URL under Developers. We POST inbound messages and delivery statuses to it. Verify authenticity:

X-BSP-Signature: sha256=<hmac>
X-BSP-Event: message.received | message.status

// signature = HMAC_SHA256(your_signing_secret, rawRequestBody)
// Example payload:
{
  "type": "message.received",
  "wabaId": "1234...",
  "phoneNumberId": "5678...",
  "data": {
    "from": "15557654321",
    "contactName": "Jane",
    "message": { "id": "wamid...", "type": "text", "text": { "body": "Hi!" } }
  },
  "timestamp": "2026-06-30T12:00:00.000Z"
}

Errors

{ "error": { "code": "invalid_api_key", "message": "The API key is invalid or revoked." } }

Codes: missing_api_key, invalid_api_key, invalid_request, number_not_found, waba_not_found, whatsapp_error, internal_error.