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.
The tools it uses
The agent has six 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.
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, delete a contact or conversation, change your bot’s code, or reach any system outside your inbox. Ask it to write or fix bot behavior and it’ll point you to the Code Agent.