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:

{
  "event_id": "evt_xxx",
  "event_type": "message.received",
  "channel": "whatsapp",
  "agent_id": "agt_xxx",
  "number": "+2348031000001",
  "from": "+2348031234567",
  "timestamp": "2026-04-09T12:05:00Z",
  "payload": {
    "message_id": "msg_xxx",
    "conversation_id": "conv_xxx",
    "message_type": "text",
    "inbound_message": {
      "message_id": "msg_xxx",
      "body": "I need help with my order",
      "type": "text",
      "received_at": "2026-04-09T12:05:00Z"
    }
  }
}

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.