Create a WhatsApp Agent

A WhatsApp agent is an assistant whose type is WhatsApp. It answers the messages that arrive on its attached WhatsApp number. Create one after you’ve connected WhatsApp Business and registered at least one number.

Create the agent

Start a new assistant

Go to Assistants and select Create agent. In Create Assistant, choose the WhatsApp tab.

Pick Single Prompt

Under Create from scratch, choose Single Prompt, described as “Create a WhatsApp assistant from scratch for simple workflows”. This template’s prompt already carries the WhatsApp formatting rules.

Fill in the basics

Enter the Agent Name and the Primary Language, with an optional Secondary Language. The form also asks you to pick a voice, since every assistant carries one. A WhatsApp agent never speaks, so any voice will do. Select Next.

Describe the business and the goal

Enter Company and Call Details: what the business is and what the agent should achieve in the chat. These are used to generate the first version of the prompt. Add any Custom variables and Knowledge Base the agent needs.

Select the WhatsApp number

Under Select WhatsApp Number, pick the registered number this assistant answers on. Only registered numbers that no other assistant uses are listed. You can also leave it empty and attach a number later.

Create

Select Create Assistant. The agent editor opens, with a WhatsApp badge next to the agent name.

Assistants → Create agent → WhatsApp → Single Prompt, through to selecting the WhatsApp number.

To find your WhatsApp agents later, set the Channels filter on the Assistants page to WhatsApp. Each card shows its channel, for example “WhatsApp • Activity: 3”.

Attach a WhatsApp number

A WhatsApp agent answers on exactly one WhatsApp Business number, and each number serves one assistant at a time. Messages to a number with no assistant attached get no reply. A number is offered only when all of these are true:

It belongs to the WhatsApp Business account connected to this workspace.

It is registered, meaning it shows Ready on the account’s Phone numbers tab. See Connect WhatsApp Business.

No other assistant uses it, or this assistant already does.

You can pick the number while creating the agent, as in the steps above. To attach or change it later:

Open Attach Number

In the agent editor, select Attach Number in the left menu.

Choose the number

Open the WhatsApp Number field and choose a number. The current number is marked with a check. The field saves as soon as you choose.

Need another number?

The last option, + Connect WhatsApp Number, opens Numbers → WhatsApp, where you can add and register a new number.

Attach Number lists the WhatsApp numbers this agent can use. Test assistant then opens a chat with it.

To move a number to another agent, first clear the WhatsApp Number field on the agent that has it, or pick a different number there. Then attach it on the new agent. Numbers → WhatsApp shows which assistant uses each number in its Used By column. WhatsApp numbers are only offered to WhatsApp assistants, and phone numbers only to voice assistants.

De-registering a number, or archiving it, detaches it from its assistant. That assistant stops answering until you attach another number.

What’s different in the editor

The editor is the same one used for voice assistants, with a few changes for chat:

Section	For a WhatsApp agent
Prompt	The first message is sent as a WhatsApp message at the start of the conversation.
Attach Number	Sits in the main menu and offers only WhatsApp numbers. See above.
Chat → Settings	Session limits for the chat, covered below.
Tools	Pre-call, on-call and post-call tools as usual, plus the WhatsApp send tools (on-call, post-call). Pre-call tools run when a chat opens, on the customer’s first message. They never hold up the reply, and a field a tool didn’t return resolves to “not available”.
Event Subscription	Offers chat events instead of call events. See Events.
Not shown	Embed & Widgets, Convert to multi-prompt, and version A/B testing.

When a chat opens and closes

A WhatsApp conversation is one chat. The customer’s first message opens it, and it stays open while messages keep flowing. It closes when any of these happens:

Trigger	When
The agent ends it	The assistant decides the conversation is over and closes the chat.
The customer goes quiet	After 3 hours with no messages, the session expires. The customer’s next message then closes the old chat and opens a new one.
It reaches the maximum age	A chat lasts at most 24 hours. The next message after that opens a new chat.
Nobody writes again	Chats still open about 25 hours after they started are closed automatically.

Closing the chat is what runs post-call tools and analysis and fires the chat_completed webhook. So if a customer simply stops replying, those results can arrive hours later.

The timeouts under Chat → Settings (maximum length and idle warning/end) apply to text chat in the web widget. WhatsApp chats follow the rules above instead.

Write a prompt for WhatsApp

Keep replies short, one to three small paragraphs. WhatsApp hides long messages behind “Read more”.

Use WhatsApp formatting only: *bold*, _italic_, ~strike~, and lines starting with - or 1. for lists.

Never use Markdown headings, tables or [label](url) links. Send the bare URL and WhatsApp turns it into a link.

Don’t mention calls, audio, holding or keypad input. The customer is typing.

Mention every on-call tool with @ at the point in the prompt where it should be used.

You are Neha, a WhatsApp assistant for Acme Insurance. You help customers renew
their health policy.

- Greet the customer by name if {{name}} is available, and ask how you can help.
- Answer plan questions from the knowledge base. Keep each reply under 80 words.
- When the customer is ready to renew, send the renewal link with
  @||WhatsApp_send_template_message|| and tell them it has been sent.
- Use *bold* for plan names and prices. Never use headings or tables.

Test from your phone

Select Test assistant in the editor’s top bar. A QR code for the attached number appears with Scan to start a WhatsApp chat. Scan it with your phone’s camera, or use Open in WhatsApp, and send a message. Your conversation appears under Logs → WhatsApp like any other. The recording under Attach a WhatsApp number ends on this QR code. If no number is attached you’ll see No number attached. Attach one, then reopen Test assistant.

Get Started

WhatsApp

API Reference

Webhooks Setup

Telephony Integration

MCP Server

Parrot STT

External Integrations

Privacy and Compliance

Create the agent

Attach a WhatsApp number

What’s different in the editor

When a chat opens and closes

Write a prompt for WhatsApp

Test from your phone

​Create the agent

​Attach a WhatsApp number

​What’s different in the editor

​When a chat opens and closes

​Write a prompt for WhatsApp

​Test from your phone

Create the agent

Attach a WhatsApp number

What’s different in the editor

When a chat opens and closes

Write a prompt for WhatsApp

Test from your phone