> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zexa.ao/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Messaging with Zexa: Business API Setup Guide

> Use Zexa to send WhatsApp messages to your customers. Connect your WhatsApp Business account, register templates, and send at scale.

WhatsApp lets you send rich messages — text, images, and documents — to customers who have opted in to hear from your business. Zexa integrates directly with the WhatsApp Business API, so you can send transactional alerts, appointment reminders, and support replies at scale without managing the underlying infrastructure.

## Requirements

Before sending WhatsApp messages through Zexa, ensure the following are in place:

* **WhatsApp Business account** linked to Zexa via the dashboard under **Channels > WhatsApp**.
* **Approved message templates** for any outbound marketing or notification messages sent outside an active customer conversation window.
* **Recipient opt-in** — contacts must have explicitly agreed to receive WhatsApp messages from your business.

<Warning>
  Sending messages to users who have not opted in violates WhatsApp's policies and Zexa's Terms of Use. Repeated violations may result in your WhatsApp Business account being permanently banned.
</Warning>

## Message types

WhatsApp distinguishes between two categories of messages, each with different rules:

**Session messages**

A session message is any free-form message sent within a **24-hour window** that opens when a customer messages your business first. During this window you can send text, images, documents, and other rich content without using a pre-approved template.

**Template messages**

A template message is a pre-approved message format used to initiate or continue a conversation **outside the 24-hour session window**. Templates are required for outbound notifications such as order updates, appointment reminders, and delivery alerts. See [Message Templates](/messaging/templates) for instructions on creating and submitting templates for approval.

<Note>
  WhatsApp template approval typically takes 1–2 business days. Submit your templates in advance to avoid delays.
</Note>

## Send a WhatsApp message via API

Send a `POST` request to `/messages` with `"channel": "whatsapp"` to deliver a message via WhatsApp.

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.zexa.ao/v1/messages \
    --header 'Authorization: Bearer <api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "channel": "whatsapp",
      "to": "+244912345678",
      "from": "MYSENDER",
      "body": "Hello! Your appointment is confirmed for tomorrow at 10am."
    }'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.zexa.ao/v1/messages"

  payload = {
      "channel": "whatsapp",
      "to": "+244912345678",
      "from": "MYSENDER",
      "body": "Hello! Your appointment is confirmed for tomorrow at 10am."
  }

  headers = {
      "Authorization": "Bearer <api_key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

A successful request returns a `201` response with the message object:

```json theme={null}
{
  "id": "msg_wa4521",
  "status": "queued",
  "channel": "whatsapp",
  "to": "+244912345678",
  "created_at": "2026-06-24T10:05:00Z"
}
```

## Template messages

If you need to send a message to a customer who has not contacted you in the last 24 hours — for example, a shipping notification or a payment reminder — you must use an approved template. Attempting to send a free-form message outside the session window will result in an error.

To use a template, include the `template_id` and any variable values in your request body alongside the `channel` field. Full details are available in the [Message Templates](/messaging/templates) guide.

## Next steps

<CardGroup cols={2}>
  <Card title="Message Templates" icon="file-lines" href="/messaging/templates">
    Create, submit, and manage WhatsApp message templates for outbound notifications.
  </Card>

  <Card title="Sender IDs" icon="id-card" href="/messaging/sender-ids">
    Register the WhatsApp Sender ID associated with your Business account.
  </Card>
</CardGroup>