Put your AI agent on WhatsApp

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:

Connect your number in the console under WhatsApp, at voice.wixzel.com/whatsapp.
Pick the agent that answers it.
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 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:

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.

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:

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

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

Getting started

Guides

Carriers

Concepts

API reference

Put your AI agent on WhatsApp

Connect a number

With your own Meta app

Pick the agent that answers

WhatsApp tools on an agent

Templates and the 24-hour window

Files the agent can send

Send from your own code

What it costs

Limits

MCP tools

​Connect a number

​With your own Meta app

​Pick the agent that answers

​WhatsApp tools on an agent

​Templates and the 24-hour window

​Files the agent can send

​Send from your own code

​What it costs

​Limits

​MCP tools

Connect a number

With your own Meta app

Pick the agent that answers

WhatsApp tools on an agent

Templates and the 24-hour window

Files the agent can send

Send from your own code

What it costs

Limits

MCP tools