Guides

WhatsApp

WhatsApp send/receive is live on the API. The underlying infrastructure may be updated in the future — your integration will not change.

Send a Message

$curl -X POST "https://api.voicebip.com/v1/messages" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "channel": "whatsapp",
>    "agent_id": "agt_PAEZ_njcfm2kycpjs",
>    "from_number": "+2348031000001",
>    "to_number": "+2348031234567",
>    "message_type": "text",
>    "body": "Your order has been confirmed."
>  }'

Send a Template Message

Pre-approved WhatsApp template messages bypass the 24-hour conversation window restriction:

$curl -X POST "https://api.voicebip.com/v1/messages/template" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "agent_id": "agt_PAEZ_njcfm2kycpjs",
>    "from_number": "+2348031000001",
>    "to_number": "+2348031234567",
>    "template_name": "order_confirmation",
>    "language_code": "en",
>    "parameters": ["ORDER-9182"]
>  }'

Message Types

TypeDescription
textPlain text message
imageImage with optional caption (media_url, media_caption)
audioAudio file (media_url)
documentPDF, DOCX, etc. (media_url, media_caption)
videoVideo file (media_url)
interactiveInteractive message (quick reply buttons or scrollable list)
templatePre-approved template message via POST /v1/messages/template

Inbound Messages

Inbound WhatsApp messages are delivered to your agent’s webhook URL in the same format as SMS:

1{
2  "event_id": "evt_xxx",
3  "event_type": "message.received",
4  "channel": "whatsapp",
5  "agent_id": "agt_xxx",
6  "number": "+2348031000001",
7  "from": "+2348031234567",
8  "timestamp": "2026-04-09T12:05:00Z",
9  "payload": {
10    "message_id": "msg_xxx",
11    "conversation_id": "conv_xxx",
12    "message_type": "text",
13    "inbound_message": {
14      "message_id": "msg_xxx",
15      "body": "I need help with my order",
16      "type": "text",
17      "received_at": "2026-04-09T12:05:00Z"
18    }
19  }
20}

One webhook handler processes Voice, SMS, and WhatsApp events.

24-Hour Conversation Window

WhatsApp only allows outbound messages within 24 hours of the last inbound message from the user (the “conversation window”). Voicebip fires a window.closing webhook event 60 minutes before a window expires so you can act before you lose the ability to reply.

Template messages can be sent any time regardless of the window.

Provider Architecture

WhatsApp is abstracted behind a WhatsAppProvider Go interface:

  • Current: KapsoProvider (Kapso.ai as interim WhatsApp infrastructure)
  • Post-WABA approval: MetaCloudAPIProvider (direct Meta Cloud API)
  • Migration: Config swap in voicebip-msg service. Zero developer-facing API changes.