WhatsApp inbox and handoff

WhatsApp chats appear in the chat inbox next to web chats, marked with the WhatsApp badge and the business number the customer wrote to (to +91 …) - with several live numbers, every reply goes from that same number. Replying needs the agents: write permission; other teammates can read.

When a customer came from a click-to-WhatsApp ad (or a boosted post), the person panel shows Came from an ad with the ad’s headline and text, its ad ID (to match Meta Ads Manager) and a link to it.

Take over and hand back

When the agent hands off (or the customer asks for a person), the chat shows as Waiting in WhatsApp → Inbox → Live. You can also take over any chat the AI is handling.

• Take over - you handle the chat; the AI stops replying.
• Hand back to agent - the AI continues, and it sees what you said.
• Release - put it back in the queue for a teammate.
• Close - end the chat.

If someone else acted first (a teammate took it, or the chat ended), you’re told in plain words and the conversation refreshes. A chat a teammate is handling says A teammate is replying; a chat your helpdesk took over through the API says Your helpdesk is handling this conversation.

Assign conversations to teammates

Assign in a conversation’s header gives it to a teammate who can reply (or to you): they handle it, and the AI stops replying, as with Take over. A conversation a teammate holds can be moved by a workspace admin (or anyone with agents: admin); one your helpdesk holds through the API can’t. The list shows who holds each conversation, and the Assigned to me and Not assigned filters narrow it.

Assign handoffs in turn (the settings button at the top of the inbox, for admins; off by default): when the AI hands a conversation to a person, it goes straight to the next teammate who can reply, in turn, instead of waiting for someone to take it. Your systems can assign too, with Assign a conversation; every assignment sends a chat.assigned webhook.

Saved replies and labels

• Saved replies - answers your team sends often. In the reply box, type / (then part of the shortcut, like /thanks): pick one with the arrow keys and Enter (or click), and edit it before sending. Ctrl/Cmd + Enter sends.
• Labels - tag conversations (VIP, Refund, Lead…). Labels in a conversation’s header adds or removes them; they show on the list, and both Live (Any label) and History (Label) filter by them. The API’s conversation reads include each conversation’s labels.

Workspace admins (or anyone with agents: admin) manage both under the inbox’s settings button → Saved replies and labels. Everyone who can open the inbox can use them; applying labels needs edit access to agents.

The 24-hour reply window

WhatsApp lets you reply freely for 24 hours after the customer’s last message. The header shows how long is left (“Free replies for 3h 12m more”). After that, the composer switches to a picker of your approved templates - the only thing WhatsApp allows until the customer writes again. Each template value shows the words around it so you know what you’re filling.

Your reply goes out on WhatsApp first and appears in the conversation once WhatsApp accepts it, with delivery ticks (sent, delivered, read). A failed message says why and what to do (see Troubleshooting). You can attach an image, video or PDF.

Customer photos show as thumbnails (click for full size) and documents as a Download button; voice notes play in place with their transcript.

Unassigned

The Unassigned tab lists customers no chat is handling - messages to a number with no agent, or that arrived while the agent couldn’t answer. Reply yourself, Mark read, or press Let the agent reply to have the number’s agent pick up from the last few messages. A number with no agent says so, with a link to choose one.

If the agent can’t run when a message arrives (the flow isn’t published, the wallet is empty, or WhatsApp agents are off), the message still reaches the inbox and the customer gets your offline note at most once a day.

Customers who hide their number (WhatsApp usernames)

WhatsApp lets people chat with a username instead of their phone number. When someone with a username writes to you for the first time in 30 days and isn’t in your contacts, WhatsApp doesn’t share their number - only a private id for your business.

• The chat still works: it shows their WhatsApp name, or @username · number hidden. Each customer gets their own conversation and contact, and the AI agent replies normally.
• Their number appears on its own once WhatsApp shares it (usually from their next message). The conversation and contact stay the same.
• STOP, START and erasing the contact work the same way.
• Campaigns send to phone numbers, so a contact with only a username is skipped (No phone number). To reach them later, ask for their number in the chat.
• A few messages can’t go to a hidden number (one-tap, zero-tap and copy-code login templates). The chat then moves to Waiting so a teammate can take over.
• When a customer changes their number, the conversation moves with them and shows Customer changed their number. Their WhatsApp opt-out moves too.

Before usernames were supported, the messages of several username customers could land in one shared conversation. We moved every message we could to its own customer. What is left stays in the inbox as a quarantined conversation: you can read it, but nothing can be sent from it. After you’ve looked at it, a workspace owner or admin can remove it for good with Delete conversation - this permanently deletes its messages and files and can’t be undone. Other conversations can’t be deleted this way; to remove a customer’s data, erase their contact.

Your own helpdesk (Zendesk, Freshdesk, your own inbox)

If your team works in another helpdesk, connect it with the API instead of the console:

• Take over a conversation - the AI stops replying; your helpdesk replies with Send a message.
• Hand it back - pass the replies your helpdesk sent (and an optional note for the agent) so the agent knows what was said.
• Handing a conversation to the agent from your helpdesk? Start a conversation with priorMessages (up to 200 earlier messages) and a handoverNote: the agent reads them as background.
• The chat.taken_over and chat.handed_back webhooks tell your systems when either happens.
• Every reply your helpdesk sends through the API keeps the conversation open; a held conversation nobody touches for a few hours is closed as abandoned.
• While your helpdesk holds a conversation, a teammate can’t take it over in the console. If your helpdesk integration stops working, hand the conversation back through the API, or close it with End in the inbox.
• priorMessages and a handoverNote only seed a new conversation, so a request that combines them with onActiveSession: "send_in_session" is refused.

When a conversation needs a person

When the agent hands a conversation to your team (it asked for a person, or it could not answer - for example its replies kept failing three times in a row), the conversation moves to the inbox as waiting, and:

• the workspace owners and admins get an email (at most one every 15 minutes, however many conversations are waiting), and
• your systems get a chat.handoff_requested webhook for each one.

With round-robin on, the conversation goes straight to the next teammate instead of waiting; the email and the webhook still go out, the email also reaches that teammate and says who has it.

History, the message log and export

• WhatsApp → Inbox → History filters by agent, number, how the chat ended, test chats and dates, and searches the transcript text or a customer’s number. Export CSV downloads up to 200,000 chats, with or without the analysis. (Export is in the console; the API reads conversations one page at a time.)
• WhatsApp → Messages lists every WhatsApp message sent or received. Filter by date, direction, status, source, number, template or failure reason; the filters stay in the page address so you can share a view. Open a row for its timeline, the reason it failed with the next step, and the Meta fee (free inside the 24-hour window, or the category Meta billed). Message ids and Meta’s raw codes are under Technical details. Customer numbers are masked and times are in your workspace time zone.

When the AI pauses a chat

The AI stops answering a chat and hands it to your team, with a one-line reason at the top of the conversation, when:

• WhatsApp could not deliver a message the AI sent - the message shows a failed tick, and the AI never assumes the customer read it.
• WhatsApp refused two replies in a row to this customer - they blocked your number, are not on WhatsApp, or cannot be reached.
• Meta is limiting the number (error 131048) - AI replies on that number pause for one hour; owners and admins get an email (and a whatsapp.number_ai_paused webhook). Customer messages still reach the inbox. New chats get the AI back after the hour; chats already handed to your team stay with you.

A customer who comes back within 24 hours of a chat that closed for inactivity (or ran too long) in the middle of a flow continues where they left off - no new greeting, nothing asked again, and a document step first checks the files they already sent.

Opt-outs (STOP / START)

When a customer replies with only an opt-out keyword (default: STOP, STOP ALL, STOP PROMOTIONS, UNSUBSCRIBE, OPT OUT, OPTOUT, बंद, रोकें), they’re opted out of WhatsApp only - no templates, campaigns or follow-ups from then on, and any open chat ends. Calls keep following your do-not-call list. They get one confirmation (only within 24 hours of their message), and a contact.opted_out webhook is sent with channel: "whatsapp". START or SUBSCRIBE opts them back in. “Don’t stop my order” is not an opt-out.

Phrases like “stop messaging me”, “message mat bhejo”, “बंद करो”, “மெசேஜ் அனுப்ப வேண்டாம்” and their equivalents in Hinglish, Hindi, Bengali, Tamil, Telugu, Marathi, Gujarati, Kannada, Malayalam and Punjabi always work, whatever your keyword list says. When a customer asks in other words (“please don’t send me these anymore”), the agent never opts them out on a guess: it asks “Do you want to stop receiving messages from us on WhatsApp?” with Yes, stop / No, continue buttons, in the chat’s language. Yes, stop opts them out exactly like STOP; anything else continues the chat. The question and the opted-out note below come in 11 languages - English, Hindi, Bengali, Gujarati, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil and Telugu (the chat’s language, else English); Odia has no built-in stop phrases yet, so an Odia request to stop always gets the Yes / No question.

An opted-out customer who writes again gets one short note (at most once a day): “You’ve unsubscribed from our messages. Reply START to receive messages again. A team member can still see this chat.” Their message lands in the inbox.

Edit the keywords and the confirmation on the Opt-out keywords card (admins only). Opt-in keywords must be at least 4 letters and can’t be everyday replies such as HI, OK or YES - a customer who said STOP would otherwise be signed up again by a greeting. Such a word saved before this rule is ignored. STOP, UNSUBSCRIBE and STOP PROMOTIONS always work.

A customer can also turn off marketing messages from you inside WhatsApp itself (WhatsApp’s “Stop promotions” option). We record that on the contact (their timeline shows it): they get no marketing templates or marketing campaigns until they turn it back on in WhatsApp, but your service replies and utility templates still reach them. The same happens if WhatsApp refuses a marketing message because the person stopped marketing from you. Matching ignores case, surrounding punctuation, emoji and WhatsApp formatting.

Erasing a contact

Erasing a contact (DPDP) also erases their WhatsApp message content, their number and profile name from the message log, and the raw webhook data we hold, in that workspace. Delivery history (sent, delivered, read, failed) is kept without the content. Messages already delivered to the customer’s phone can’t be deleted at Meta.

---

Next: Campaigns and follow-ups →