Skip to main content

WhatsApp conversations

When a contact writes to one of your WhatsApp numbers, or replies to a template you sent, the agent assigned to that number answers. Fonema groups those messages into sessions: a session starts with the first message and ends when the conversation closes. This page explains when a conversation closes, what happens at that moment, and how to read your conversations in Messages.

Before you start​

  • A connected WhatsApp number with an agent answering it. See WhatsApp Business to connect the number and assign the agent in Telephones → Assign agents to telephones.
  • Optional: success criteria, a call summary prompt and output variables in the agent's Instructions tab. The same settings you use for calls are used to review each WhatsApp conversation when it closes.

When a conversation closes​

What happensWhen the conversation closes
Nobody writes for a while1 hour after the last message. Every new message starts the wait again.
The agent ends the chatAbout 5 minutes after the agent's goodbye.
You sent a template and the contact never replies1 hour after the template was sent. The conversation closes with No reply.

The 1-hour wait is the default. The Calls and WhatsApp sequence editor shows the wait for the agent that answers the number (see Calls and WhatsApp sequence).

When the agent ends the chat​

Every WhatsApp agent can close the conversation on its own. It does so when the contact says goodbye, is not interested, asks not to be contacted, or has what they needed. The agent says goodbye and the conversation closes about 5 minutes later.

Those 5 minutes catch a late "thanks" or "bye":

  • If the contact only thanks the agent or says goodbye, the agent ends the chat again and the 5 minutes start over.
  • If the contact brings up something new, the agent keeps the conversation going and the 1-hour wait applies again.

In Messages, the agent's decision shows as a Tool: end_session card above its goodbye.

Testing your agent

To close a conversation right away while you test, send fonema.endSession from your phone. The agent replies Done, the conversation closes immediately and its card says Closed manually.

When the contact writes again​

A message after the conversation closed starts a new session with the same contact. It appears in the same thread in Messages, below the card of the previous session.

In a new session the agent does not see the earlier messages. To let it remember previous conversations, add {{sessionSummaries}} to the agent's prompt: Fonema fills it with the summaries of the contact's last 3 sessions, each with its date.

What happens when a conversation closes​

  1. Fonema reviews the conversation. It writes a summary (using the agent's call summary prompt), fills the agent's output variables and, if the agent has success criteria, marks the conversation Successful or Unsuccessful. A conversation in which the contact never wrote is not reviewed: it is marked No reply and counts as unsuccessful.
  2. A session card is added at the end of the conversation in Messages (see The session card).
  3. The calls and WhatsApp sequence moves on, when the conversation is part of one. An unsuccessful conversation, or one with no reply, leads to the next turn of the sequence; a successful one ends it. See Calls and WhatsApp sequence.
  4. Your webhook is called, when the agent has an end-of-call webhook. See For developers.

The Messages inbox​

Messages in the sidebar shows every WhatsApp conversation of your company. It appears once your company has a connected WhatsApp Business account. Admins and operators both see it.

The list of contacts​

Each row is one contact, with the contact who wrote most recently at the top. More contacts load as you scroll down.

PartWhat it shows
NameThe contact's name from the data you sent with the call or the campaign: a name, nombre or nombreCliente variable, or a first name and last name. When there is none, it shows --. The name the contact uses on WhatsApp is not shown.
NumberThe contact's WhatsApp number.
LabelA label the agent put on the contact, such as Interested, when your agent is set up to label contacts. A contact has one label at a time: a new one replaces the previous one.

Use the search box above the list to find a contact by phone number. Type any part of the number. The search does not look at names.

The list does not refresh on its own. Reload the page to see contacts who wrote after you opened it.

A conversation​

Click a contact to open the conversation.

  • The contact's messages are on the left, in white. The agent's messages, including the templates you sent, are on the right, in green. Each message shows its time, and the messages are grouped by day.
  • When the agent used one of its tools (for example to check a calendar or to end the chat), a Tool card with the tool's name appears above its reply. Click the arrow to see what the agent sent and the Response it got.
  • The newest messages are at the bottom. Scroll up to load older ones.
  • While the conversation is open, new messages appear on their own every few seconds.
  • Images, documents and voice notes appear as text: the description, the document's text or the transcription that the agent read, not the file itself. See Images and PDFs.

The session card​

Each time a conversation closes, a card closes that session:

PartWhat it shows
Session endedThe time the conversation closed.
Closed after inactivityNobody wrote for the wait time, or a template got no reply.
Closed by agentThe agent ended the chat.
Closed manuallySomeone sent fonema.endSession.
N messagesMessages in the session, from the contact and from the agent.
No replyThe contact never wrote in this session.
Successful / UnsuccessfulThe result against the agent's success criteria. It does not appear when the agent has none.
Webhook failedThe agent has an end-of-call webhook and Fonema could not deliver it.
SummaryThe summary of the conversation.
Extracted dataClick it to see the output variables the agent captured, each with its value.

You can't reply from Messages​

Messages is for reading. There is no box to write to the contact and you cannot take over the conversation: the agent answers every message.

Messages are kept after a conversation closes, so you always see the full history of each contact.

Download your messages​

  1. Click the download icon next to the search box.
  2. Pick a start date and an end date (both days are included).
  3. Click Download.

You get an Excel file with the messages of all your WhatsApp conversations in those dates.

Images and PDFs​

By default, the agent reads what contacts send on WhatsApp:

  • Images: the agent gets a description of the image, including any text it shows.
  • Documents up to 20 MB in PDF, Word (.docx, .doc), .odt, .rtf, Excel (.xlsx, .xls), .html, .txt or .md: the agent reads the text. Very long documents are cut.
  • Voice notes: the agent reads a transcription.
  • Videos, stickers, locations and other files: the agent says it can't open them and asks the contact to write instead.

Turn off images and PDFs​

For privacy you can stop the agent from receiving images and PDFs, for example when contacts might send photos of IDs.

  1. Open the agent and click Edit Agent.
  2. Open the Medium tab.
  3. Turn off Receive images and PDFs on WhatsApp.
  4. Click Update.

The setting appears only on agents that answer a WhatsApp number.

When it is off:

  • Images (also when sent as a file) and PDFs are not downloaded or processed.
  • The agent tells the contact it can't receive them and asks them to write the information instead.
  • In Messages you see a short note in place of the file.
  • Other documents and voice notes keep working.

For developers​

To receive each WhatsApp conversation in your own system when it closes, paste your HTTPS endpoint in the agent's end-of-call webhook field. Fonema sends the messages, the summary, the output variables and the success result there. See WhatsApp End of Session for the payload and how it is delivered.

Troubleshooting​

IssueWhat to check
Messages is missing from the sidebarYour company needs a connected WhatsApp Business account. See WhatsApp Business.
A contact shows -- as nameThe contact has no name, nombre or nombreCliente in its data, for example because they wrote first.
A conversation hasn't closed yetIt closes 1 hour after the last message, or about 5 minutes after the agent ends the chat.
The agent doesn't remember an earlier chatAdd {{sessionSummaries}} to the agent's prompt.
The image setting is missing in the Medium tabAssign a WhatsApp number to the agent in Telephones → Assign agents to telephones.

Need help? Contact us.