Don’t confuse it with the AI in your bot
These are two different things that both involve conversations, so it’s worth separating them clearly.- The Conversations Agent (this page) talks to you, in the Paige sidebar, while you read your inbox. It helps you find contacts, understand context, and draft replies.
- The AI in your bot talks to your customers, on WhatsApp, as part of the bot you deploy.
The Conversations Agent works on conversations that already exist in your inbox. It doesn’t change how your bot behaves — for that, use the Code Agent.
Open the Conversations Agent
Open the Conversations tab in the dashboard. The chat sidebar switches to the Conversations Agent automatically, ready to answer questions about your contacts and messages.“Show me contacts waiting in handover.”
“What did the customer on +2782… last say?”
“Draft a reply letting them know their order ships tomorrow.”
What it can do
Find contacts
List and search your contacts by name, phone, or conversation state — and see at a glance who’s still inside the 24-hour messaging window.
Read history
Pull the recent messages for a contact so it has the context it needs before suggesting or drafting a reply.
Change states
Move a single conversation — or a batch at once — into a different state, such as handing a conversation over to a human.
Draft replies
Compose a reply for you to review, copy, and send yourself. It never sends on its own.
Propose a template send
When the 24-hour window has closed, it can put an approved template in front of you, filled in and ready — you press the button.
Propose a new template
If no template fits, it can draft one and hand it to you to submit to Meta.
The tools it uses
The agent has nine built-in tools it uses behind the scenes to complete your requests.list_contacts
Lists contacts with optional filters (state, search, pagination). Each contact is tagged with a computed
in_24h_window field so you can see instantly who you can still message freely.get_contact_messages
Fetches recent messages for a contact, so the agent can read the conversation before drafting a reply.
list_conversation_states
Returns every unique conversation state currently in use across your inbox.
update_conversation_state
Changes the state of a single conversation. Can’t update conversations that have ended.
bulk_update_state
Changes the state for many conversations in one call — capped at 100 per call.
draft_message
Returns a draft reply for a contact. It never sends — you copy the draft and send it from the conversation view.
propose_template_send
Puts an approved template, with its placeholders filled in, into an approval card in the chat. Nothing is sent until you press the button on that card.
propose_template_create
Drafts a new template — name, category, body, example values — into an approval card. Submitting it to Meta is your click, not the agent’s.
tag_contacts
Adds or removes tags on one contact, and writes the change immediately — no card. Tagging a whole group is the Broadcasting agent’s job.
Tagging someone mid-conversation
With a conversation open, just ask: “tag them as vip”, “mark this person as a lead”, “take the trial tag off them”. The tags in the thread header update as it writes. There’s no approval card here, unlike a template send. One contact is a small, obvious change you can undo with a tap in the tag editor, so a card would be ceremony rather than safety. The limit is structural, not a matter of the agent behaving well: this tool takes one contact, never a list, so there is no way for it to tag your whole address book. Tagging a group means going to the Broadcasts tab, where the Broadcasting agent works out who matches, tells you how many people that is, and waits for you to approve.It tags people who already exist. If the contact isn’t in your list, you get told so — the agent never creates a contact as a side effect of tagging one.
Proposals are cards, not actions
The twopropose_* tools don’t do anything by themselves. They render a card in the chat, and your browser performs the send or the submission when you press its button — under your own session, with your own permissions.
That’s a structural guarantee rather than a promise about the agent’s behaviour: there is no tool that sends a template or creates one, so a confused or misled agent has nothing to call. The worst it can do is put a card in front of you that you decline.
The 24-hour window and handover
Two rules gate what the agent can do, and both exist to keep you on the right side of WhatsApp’s messaging policy.Drafting is gated by both the window and handover
Before it will draft a message,draft_message checks two conditions — and both must be true:
- The contact is inside the open 24-hour window. WhatsApp only lets you send a free-form message within 24 hours of the customer’s last inbound message. Outside that window you need a pre-approved template, so the agent won’t draft a free-form reply.
- The conversation is in a handover state. Handover means the bot has stepped back so a human can reply. If the conversation isn’t in handover, the agent tells you to enable handover first.
Moving a conversation into handover is checked too
When you ask the agent to move a conversation into handover, that change runs an eligibility check first: the contact has to be inside the open 24-hour window. If they’re outside it, the move is refused with a clear reason, because there’d be no way to reply to them free-form once handed over.Bulk changes re-check every conversation individually.
bulk_update_state handles up to 100 conversations per call, and when you’re moving them into handover it runs the same eligibility check on each one. Some may succeed while others are refused — the agent reports back which conversations it updated and which it couldn’t, with the reason for each.What it can’t do
The Conversations Agent works only with your existing conversation data. It can’t send a message, submit a template to Meta, delete a contact or conversation, change your bot’s code, or reach any system outside your inbox. It can propose a template send or a new template, but you are the one who presses the button. Ask it to write or fix bot behavior and it’ll point you to the Code Agent.