> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# WhatsApp

> Send WhatsApp messages and templates through the Voicebip API.

> **Note**
>
> 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

```bash
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:

```bash
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

| Type          | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `text`        | Plain text message                                             |
| `image`       | Image with optional caption (`media_url`, `media_caption`)     |
| `audio`       | Audio file (`media_url`)                                       |
| `document`    | PDF, DOCX, etc. (`media_url`, `media_caption`)                 |
| `video`       | Video file (`media_url`)                                       |
| `interactive` | Interactive message (quick reply buttons or scrollable list)   |
| `template`    | Pre-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:

```json
{
  "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.