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

# Put your AI agent on WhatsApp

> Connect a WhatsApp business number through Meta, let an agent answer its chats and voice notes, and let agents send WhatsApp messages, files, booking confirmations and reminders during and after phone calls.

A Wixzel Voice agent can work on WhatsApp as well as on the phone:

* **Answer chats.** Messages to your business number are answered by the agent you pick, with its prompt, knowledge base, tools and appointment booking.
* **Reply to voice notes.** A voice note is transcribed, and the agent answers with a voice note in its own voice.
* **Send during and after calls.** On a phone call, the agent can send the caller a template, a file from its knowledge base, or schedule a reminder, all on WhatsApp.
* **Confirm and remind.** When an agent books an appointment, a confirmation and a reminder go out on WhatsApp by themselves.

Three steps:

1. Connect your number in the console under **WhatsApp**, at [voice.wixzel.com/whatsapp](https://voice.wixzel.com/whatsapp).
2. Pick the agent that answers it.
3. In the agent, turn on the WhatsApp tools you want it to have.

## Connect a number

**Connect WhatsApp** in the console opens Meta's own sign-up. Sign in with the
Facebook account that manages your business, pick or create a WhatsApp
Business Account, and add the phone number. That is all: Wixzel Voice is
registered as a technology provider on the account, and messages start
arriving at once.

You need:

* a Meta business account you can administer;
* a phone number that is not already registered with another WhatsApp provider;
* a payment method in [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/) to send templates. Meta bills its fees to it directly.

A number you use in the **WhatsApp Business app** can stay there. Choose that
option in the sign-up, and the agent answers alongside you. When you reply from
the app yourself, the agent steps back for a while (30 minutes by default) so
the two of you do not talk over each other.

### With your own Meta app

If you already run the number from a Meta app of your own, connect it with
`POST /v1/whatsapp/accounts` or **Use my own Meta app** in the console:

```bash theme={null}
curl https://api.voice.wixzel.com/v1/whatsapp/accounts \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "106540352242922",
    "waba_id": "102290129340398",
    "access_token": "EAAG…",
    "app_secret": "…",
    "inbound_agent_id": "6650c0ffee0000000000a001"
  }'
```

The response carries `webhook.url` and a `verify_token`, shown once. In your
Meta app, open **WhatsApp > Configuration**, set the callback URL and verify
token, and subscribe to the `messages` field. The number's `webhook.status`
turns `ok` when the first message arrives.

## Pick the agent that answers

Set `inbound_agent_id` on the number, in the console or with
`PATCH /v1/whatsapp/accounts/{id}`. With no agent, messages are kept and not
answered.

How it behaves is in the number's `settings`:

| Setting | Default | What it does |
| - | - | - |
| `messaging_enabled` | `true` | Off keeps the number for sending only. |
| `voice_note_replies` | `true` | Answer a voice note with a voice note, on the `classic` and `sarvam` engines. Other engines reply in text. |
| `typing_indicator` | `true` | Mark the message read and show "typing…" while the agent works. |
| `inactivity_minutes` | `15` | A conversation with no message for this long closes; the next message starts a new one. |
| `offline_reply` | empty | Sent once per conversation, at no charge, when your balance is too low for the agent to answer. |
| `human_pause_minutes` | `30` | On a number shared with the WhatsApp Business app, how long the agent waits after you reply. |

The agent chats with its own text model when it runs on the `classic` engine,
and with `whatsapp.chat_model` (or the default) on realtime engines, which only
speak. It can book appointments, search its knowledge base, use your tools and
connected apps, and offer tappable buttons and lists.

People who send **STOP** get one confirmation and nothing more until they send
**START**.

## WhatsApp tools on an agent

Each agent has a `whatsapp` object. Every tool is off until you turn it on, and
the agent can only ever message the person it is talking to: the caller on a
phone call, or the person in the chat. It never chooses a number.

```bash theme={null}
curl -X PATCH https://api.voice.wixzel.com/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp": {
      "account_id": "6650c0ffee0000000000b001",
      "tools": { "templates": true, "media": true, "schedule": true },
      "templates": {
        "booking_confirmation": { "name": "booking_confirmed", "language": "en_US" },
        "reminder": { "name": "visit_reminder", "language": "en_US" }
      },
      "auto_booking_confirmation": true,
      "auto_reminder_minutes": 120
    }
  }'
```

| Tool | Where | What it does |
| - | - | - |
| `templates` | calls and chats | Send an approved template from the purpose templates or `allowed_templates`. |
| `messages` | calls | Send the caller free text, if they messaged the number in the last 24 hours. |
| `media` | calls and chats | Send a file from the agent's knowledge base. |
| `schedule` | calls and chats | Schedule the reminder or follow-up template for later, up to 30 days ahead. |
| `interactive` | chats | Offer up to three reply buttons, or a list of up to ten options. |

`account_id` is the number the agent sends from during phone calls. In a
WhatsApp chat it always replies from the number the chat is on. One call or
chat turn sends at most `max_sends_per_call` messages (3 by default), and
marketing templates are refused unless `allow_marketing` is on.

With `auto_booking_confirmation`, the booking confirmation template goes out
when the agent books an appointment. With `auto_reminder_minutes`, the reminder
template goes out that many minutes before it. A template's values are filled
from the appointment by how many it takes: three are the name, date and time;
two are the date and time; one is "date at time".

## Templates and the 24-hour window

WhatsApp allows free-form messages, files and buttons only within 24 hours of
the person's last message to your number. Outside that window, only a
**template** can be sent: a message you write in WhatsApp Manager and Meta
approves, usually within minutes. Reminders, confirmations and follow-ups are
templates for this reason.

Write a template with **New template** on the number's Templates tab, or with
`POST /v1/whatsapp/templates`. Number its values `{{1}}`, `{{2}}`, … and give an
example for each, which Meta needs for its review:

```bash theme={null}
curl https://api.voice.wixzel.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "6650c0ffee0000000000b001",
    "name": "visit_reminder",
    "category": "UTILITY",
    "body": "Hi {{1}}, a reminder of your visit on {{2}}.",
    "examples": ["Asha", "Thursday at 4 pm"]
  }'
```

It starts `PENDING`, and Meta's approval or rejection arrives by itself. A
template made in WhatsApp Manager shows up after **Sync**, or
`POST /v1/whatsapp/templates/sync`. `DELETE /v1/whatsapp/templates/{id}`
removes one from both.

## Files the agent can send

Documents in a knowledge base (PDF, Word, text) can be sent once they are
uploaded. Images (JPEG or PNG, up to 5 MB) and videos (MP4, up to 16 MB) can be
added too, with a `description` saying what they show; the agent finds them by
it. A file's `sendable` field says whether it can be sent. Files added before
WhatsApp sending was available cannot be; upload them again.

## Send from your own code

```bash theme={null}
curl https://api.voice.wixzel.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "6650c0ffee0000000000b001",
    "to": "+919812345678",
    "template": { "name": "visit_reminder", "language": "en_US", "parameters": ["Thursday at 4 pm"] }
  }'
```

Send exactly one of `text`, `template` or `knowledge_file_id`. Add `send_at` to
schedule it. A refusal by WhatsApp's rules is a `400` whose `code` says which:
`window_closed`, `opted_out`, `template_not_found`, `template_not_approved` or
`template_params`.

Conversations, with their messages, voice-note transcripts and what they cost,
are at `GET /v1/whatsapp/conversations`.

## What it costs

Two parties bill separately.

* **Wixzel Voice**, from your balance: \$0.002 per message the agent sends or
  receives, plus the agent's usage at the same rates as calls: the text model's
  tokens, transcribing voice notes, and speaking voice-note replies. The
  [model prices](/composing.md) apply.
* **Meta**, to the payment method in WhatsApp Manager: its own fee for
  templates, and for service messages beyond the free monthly allowance, at
  [Meta's rates](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
  for each country. Each message shows Meta's estimated fee in
  `meta_cost_micros`, and each conversation a total.

When your balance is too low for a reply, the agent stays quiet (sending your
`offline_reply`, if you set one) until you top up.

## Limits

* One Wixzel Voice account per WhatsApp number.
* WhatsApp voice calls are not answered yet; messages and voice notes are.
* Video and sticker messages people send are stored and shown, but the agent only sees that one arrived.
* A number registered with another WhatsApp provider cannot be connected until it leaves that provider.

## MCP tools

`list_whatsapp_accounts` `get_whatsapp_account` `create_whatsapp_account`
`update_whatsapp_account` `delete_whatsapp_account` `refresh_whatsapp_account`
`list_whatsapp_templates` `sync_whatsapp_templates` `create_whatsapp_template` `delete_whatsapp_template` `send_whatsapp_message`
`list_whatsapp_conversations` `get_whatsapp_conversation`
`list_whatsapp_scheduled_messages` `cancel_whatsapp_scheduled_message`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.