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 calls its End Chat tool, which sends a closing message and closes the chat. See End the chat.
The customer goes quiet	After the agent’s idle timeout (3 hours by default) 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 length	A chat lasts at most the agent’s maximum length (24 hours by default), however active it is. The next message after that opens a new chat.
Nobody writes again	A chat that goes quiet and gets no further message is closed automatically shortly after its idle timeout.

A new chat starts without the previous chat’s messages, so choose timeouts that fit how long your customers take to reply. See Set the session timeouts. 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, in seconds) apply to text chat in the web widget. WhatsApp chats use the session timeouts below instead.

Set the session timeouts

Each WhatsApp agent sets its own idle timeout and maximum chat length:

Setting	What it does	Default	Allowed
`idle_timeout_minutes`	Ends the chat after this many minutes with no message from the customer. Each customer message restarts the clock.	180 (3 hours)	5 to 1440 (1 day)
`max_duration_minutes`	Starts a new chat once the chat is this many minutes old.	1440 (24 hours)	60 to 10080 (7 days)

The maximum length must be at least the idle timeout. Set both with Edit Assistant and operation: "edit_chat_settings":

curl --request PATCH "https://prod-api.ringg.ai/ca/api/v0/agent/v1" \
  --header "X-API-KEY: your-api-key" \
  --header "Content-Type: application/json" \
  --data '{
    "operation": "edit_chat_settings",
    "agent_id": "your-agent-id",
    "chat_settings": {
      "whatsapp_session": { "idle_timeout_minutes": 1440, "max_duration_minutes": 4320 }
    }
  }'

A chat keeps the timeouts it started with, so a change applies to chats that open after it.

End the chat

WhatsApp agents have an End Chat tool, the chat counterpart of End Call. The assistant uses it to send a closing message and close the chat, which runs post-call tools and analysis straight away instead of waiting for the idle timeout. Mention it in your prompt as @||end_chat|| at the point where the conversation should end.

Use @||end_chat|| in a WhatsApp agent’s prompt, not @||end_call||. End Call and the other call tools (call transfer, DTMF, stay on line) only work on voice calls and are not offered to the assistant during a chat.

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.

Say when the conversation is over and mention @||end_chat|| there.

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.
- When the customer says they're done, thank them and end the chat with
  @||end_chat||.

Send a template during a chat

A WhatsApp agent can send an approved message template in the middle of a chat, for example a brochure, a payment link or a quick-reply menu. Pick the templates the assistant may send, then tag them in the prompt.

Select the templates

In the editor sidebar, open WhatsApp Templates and click Select Template. The list shows the approved templates for the attached number. Tick each one the assistant may send. To add or edit templates, use Manage templates, which opens Message templates.

Fill in the variables

If a template has variables or a media header, a setup dialog opens. For each variable, choose where its value comes from:

Static: fixed text, sent as written.
Variable: a custom variable such as {{name}}, filled when the chat starts.
Dynamic: the assistant fills it from the conversation, for example the plan the customer chose.

For an image, video or document header, paste an https:// link to the file. Edit these later with the pencil next to the template.

Tag the template in the prompt

Type @ in the prompt and pick the template. Each one appears under its own tool name, send_ followed by the template name, for example @||send_renewal_reminder||. Mention it at the point where it should be sent.

- When the customer asks for the renewal link, send it with
  @||send_renewal_reminder||.

The template is the assistant’s whole reply for that turn, so it won’t send a separate text message as well. If a Variable isn’t available in a chat, the assistant fills it in from the conversation instead. Each send appears in the chat under Logs → WhatsApp.

Replies to earlier messages

When a customer swipes to reply to an earlier message, or taps a quick-reply button on a template, the assistant sees which message they’re answering. Their reply reaches the assistant with a short quote of that message, so an answer like “yes, this one” is understood in context. You don’t need to handle this in the prompt.

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

Set the session timeouts

End the chat

Write a prompt for WhatsApp

Send a template during a chat

Replies to earlier messages

Test from your phone

​Create the agent

​Attach a WhatsApp number

​What’s different in the editor

​When a chat opens and closes

​Set the session timeouts

​End the chat

​Write a prompt for WhatsApp

​Send a template during a chat

​Replies to earlier messages

​Test from your phone

Create the agent

Attach a WhatsApp number

What’s different in the editor

When a chat opens and closes

Set the session timeouts

End the chat

Write a prompt for WhatsApp

Send a template during a chat

Replies to earlier messages

Test from your phone