Conversation Tools
What an AI can do in your inbox from Yaplet or a connected AI app: search and read conversations, assign, leave and resolve them, add private notes for your team, reply to or email visitors, send a rating request, form or workflow, edit a visitor and their memory, and ban or unban them.
Overview
From Yaplet, the assistant inside your dashboard, or a connected AI app, an AI can search your conversations, read their messages, hand a conversation to a team member, leave it or resolve it, put it in the queue for a person, leave a private note for your team, and reply to the visitor. It can also act on the visitor from a conversation: email them the transcript, ask for a rating, send a form or a workflow, edit their details and memory, and ban or unban them. The AI looks these actions up with find_actions and runs each one with the run tool for its kind — see MCP Server.
In Yaplet, every change and every send to a visitor waits for your Confirm first; the ones that cannot be taken back — a reply, an email, a rating request, a form, a workflow start or a ban — get a red card. Each one is recorded in the Audit Log as AI change or AI delete or send. Reading is not recorded.
Actions
Conversations
| Action | Level | What it does |
|---|---|---|
conversations.search | Read | Finds conversations by message text, by visitor (name, email, phone), by assigned team member, or by the start of a conversation ID, optionally narrowed by agent, rating and date. |
conversations.read_messages | Read | Reads the latest messages of one conversation, and older ones page by page. For an email conversation, the first page also explains how each incoming email was handled. |
conversations.assign | Change | Assigns or transfers up to 100 conversations at once to a team member and posts a transfer notice in each. The member who receives them then gets a short private AI summary in each moved conversation. Uses AI credits. |
conversations.leave | Change | Leaves up to 100 conversations assigned to you: nobody is assigned, the AI agent answers the visitor's next message, and an "X left" line is posted. |
conversations.resolve | Change | Resolves up to 100 conversations that are waiting for a person — the inbox's Resolve, and the way to mark them all as read. |
conversations.request_human | Change | Puts up to 100 conversations nobody is assigned to in the queue for a person, as if the visitor had asked for one. |
conversations.add_private_note | Change | Adds an internal note that only your team sees. Not available to apps connected by browser login. |
conversations.send_reply | Delete or send | Sends a message to the visitor, and can also email it to them, at their own saved address only. |
conversations.email_transcript | Delete or send | Emails the visitor a transcript of the conversation, at their own saved address only. |
conversations.ask_rating | Delete or send | Asks the visitor to rate the person handling the conversation. |
conversations.start_form | Delete or send | Opens one of your ticket forms in the visitor's chat widget. |
conversations.start_workflow | Delete or send | Starts a chat workflow that is already switched on in the conversation. |
Visitors
| Action | Level | What it does |
|---|---|---|
visitors.update | Change | Edits the conversation's visitor: name, plan, country or external ID. The email address cannot be changed. |
visitors.update_memory | Change | Replaces or deletes the visitor's memory — the short notes the AI agent reads about them in later chats. |
visitors.regenerate_memory | Change | Has the AI rewrite the visitor's memory from their latest conversation and saves it. Uses AI credits. |
visitors.ban | Delete or send | Bans the conversation's visitor, completely or from people only, for a set time. |
visitors.unban | Change | Lifts the visitor's manual ban and any connection block made with it. |
How These Actions Behave
Searching
You don't have to pick the right kind of search. Text that looks like the start of a conversation ID is matched as an ID, and if that finds nothing, it is searched as message text. Results are whole conversations (not single messages), most recently updated first, with the total number of matches. The empty records the widget opens for every new visitor are never returned.
Filtering by agent, rating and date
Searches — and conversation lists read with list_records on chats, which take the same filters without a search text — can be narrowed to:
- the team member assigned now
- a last-activity window (updated after / before a date)
- ratings: one or several star scores, the team member who was rated, and a window for when the rating was given. These describe one rating together, so "1 or 2 stars given to Anna in October" finds exactly that, not a 1-star rating plus some other rating for Anna.
Every conversation carries all its ratings, each with the score, the visitor's comment and the rated team member. When a rating filter is set, each rating also says whether it is one the filter matched — the total counts conversations, so this is how the AI answers "how many 1-star ratings did Anna get". If your organization masks visitor text for AI, the rating comments are masked too.
Reading messages, and why an email was handled the way it was
conversations.read_messages returns the latest messages of one conversation, and older ones page by page. For an email conversation, the first page also explains how each incoming email was handled, oldest first, in plain sentences:
- The sender check — whether the sender was verified. The AI agent never answers an email whose sender could not be proven.
- Whether the AI agent was allowed to answer it, and if not, why — for example the sender could not be verified, the email looked automatic, a team member already had the conversation, the AI agent's email answers are switched off, or a safety limit was reached.
- The AI answer filter's verdict, when the brand uses the filter.
- What came of each AI attempt — it answered, answered and handed the conversation to your team, handed it over, found no answer, was skipped by the filter, was taken over by a workflow, or failed.
Email addresses are left out. For conversations from before this was added, you get only what was recorded at the time — the sender check, the filter verdict and the AI's attempts — but not the reason the AI was or was not allowed to answer.
Assigning
An AI can assign or transfer up to 100 conversations to a team member in one call. The team member must be allowed to work in each conversation's brand: a conversation of a brand they may not work in, and a conversation whose visitor is blocked, is skipped. The answer lists every conversation that was assigned and every one that was skipped, with the reason.
After the conversations are moved, the member who receives them gets a short private AI summary in each of them a few seconds later, the same as after a Transfer in the inbox. The summary uses AI credits, and it is written only when your plan includes the inbox AI tools and someone can pay for it (free AI credits first, then bought credit, then the plan's usage billing); otherwise no summary is written and nothing is shown as an error. Very short conversations (3 messages or fewer) get none, and assigning a conversation to yourself makes no summary.
Leaving, resolving and queuing
- Leaving works on your own conversations, up to 100 per call. Afterwards nobody is assigned, the AI agent answers the visitor's next message, and an "X left" line is posted in the conversation. The visitor is asked for a rating when the Ask for a rating switch on the widget's Chat tab is on. This is the same as Leave in the inbox. A conversation assigned to someone else is skipped with the reason "Not assigned to you".
- Resolving is the same as Resolve in the inbox. It works only on conversations that are waiting for a person: they stop waiting and leave the Unassigned list for your whole team, and where nobody is assigned, the AI agent answers the visitor's next message again. A private "marked as seen" line is posted. Up to 100 per call; conversations that are not waiting are skipped, and so, when several are given at once, are those assigned to a colleague. One conversation named on its own may be a colleague's.
- Queuing for a person is the same as Mark as waiting in the inbox. It takes conversations that nobody is assigned to and puts them in the queue for a person, as if the visitor had asked: the AI agent stops answering, an "Agent requested" line is posted and your team is notified. The visitor gets no message. The AI can add a reason of up to 1,000 characters; it is written into the conversation as a private note from the person the connection acts as, right under the "Agent requested" line, for whoever picks the conversation up; only your team sees it. Up to 100 per call; conversations that are assigned, already waiting, or whose visitor is blocked from people are skipped.
Replying
- A reply needs the top access level, Read, change, delete and send.
- The reply is sent as the person the connection runs as — you, in Yaplet or an app you connected by browser login; for an API key, the person who switched its AI access on. The visitor sees it at once.
- When the AI asks for it, the reply is also emailed to the visitor — the same as the inbox's Also send by email switch. It goes only to the visitor's own saved email address; a visitor with none gets the chat message only. The email carries your brand's name and logo, is written in the visitor's language, and the visitor can answer it by email into the same conversation. The answer tells the AI whether the email went out, and why not when it was refused — for example, because a sending limit was reached or your plan does not include email sending.
- Facebook and Instagram conversations are refused. A reply from an AI connection cannot be delivered to those channels yet, so the AI gets a clear message that nothing was sent.
- Phone-call conversations are refused too. Nobody on a phone call reads text, so a written reply could never reach the caller — the Inbox refuses these as well.
Emailing the visitor
- Emailing needs the top access level, Read, change, delete and send — a reply's email copy and a transcript alike. The visitor receives the email at once and it cannot be taken back.
- Emails go only to the visitor's own saved email address. There is no way to name another address. For a visitor with no saved address, a reply goes out as a chat message only, and a transcript is refused.
conversations.email_transcriptis the inbox's Send transcript. It emails every message the visitor could see, never private notes, and a "transcript sent" line appears in the conversation, which the visitor sees too. The sender is one of your organization's sending addresses (the conversation's brand address when none is named), with your organization's name unless another is given; with no sending address of your own it uses Yaplet's own sender. Sending limits apply, and a transcript above them is refused.
Asking for a rating, sending a form, starting a workflow
All three reach the visitor at once and need the top access level, Read, change, delete and send.
- Rating request — the same as Ask for rating in the inbox: a rating card in the chat widget, or a message with five tappable star buttons on Facebook and Instagram. Only the person the conversation is assigned to can ask (for an API key, the person who switched its AI access on), because the rating is about them. It is refused when the visitor already rated them in this conversation in the last 7 days, for blocked visitors, and for email and phone conversations. Your team sees a private "rating requested" line.
- Form — the same as the inbox's Forms picker. The AI names one of your ticket forms or gives its ID; an unknown name is refused with the list of forms it can send. The form opens in the visitor's chat widget, and what they submit becomes a ticket on the form's board. Only forms on boards you may see can be sent. It works for chat widget conversations only — not Facebook, Instagram, email or phone — not for blocked visitors, and only when your plan includes forms.
- Workflow — the same as the inbox's Workflows button. It starts a chat workflow that is already switched on; it does not switch one on. The workflow must be a chat workflow of the conversation's own brand, and your plan must include workflows. Its steps run at once: the visitor sees its messages, questions and buttons, and steps that send emails or call your own API run too. It replaces another workflow's run that was still waiting for the visitor's answer. It is refused for blocked visitors and when the workflow cannot run on the conversation's channel. The answer says whether the workflow is now waiting for the visitor.
Editing a visitor and their memory
visitors.updateis Edit visitor in the inbox sidebar. It changes the visitor's name, plan (a free label), country (a two-letter code such as US or HU) and External ID (their ID in your own system, up to 200 characters). Only the fields sent change; an empty value clears one. Each change is written into the conversation as a private line for your team, and the visitor does not see it. The email address cannot be changed from an AI connection, because the email actions send only to that address; change it in the inbox sidebar.- Memory is the short notes the AI agent reads about a visitor in their later chats; the visitor never sees it.
visitors.update_memoryreplaces it with plain text of up to 1,500 characters; an empty text deletes it, and it rebuilds itself from the visitor's recent history at their next conversation.visitors.regenerate_memoryhas the AI rewrite it from the latest conversation and saves it; it uses AI credits, and saves nothing when the rewrite comes out the same.
Banning
visitors.ban is the inbox's Ban visitor dialog and needs the top access level, Read, change, delete and send.
- A reason is required (1–1000 characters). Your team sees it next to the ban.
- The level is Block completely (the default: the visitor cannot chat at all) or Block from agents only: people can no longer answer them, the conversation is released from its assignee and handed to the AI agent. On a brand with no AI agent switched on, this becomes a complete block.
- The duration is 1 hour, 24 hours (the default), 3 days, 7 days, 30 days or forever. To change the level of an existing ban without moving its end, the AI keeps the current end. The visitor is never shown the duration.
- A new ban replaces any manual ban the visitor already has.
- The connection: with a complete block, the AI can also use Also block their connection, which stops the visitor from coming back as a new visitor from the same internet connection for the length of the ban, at most 24 hours. It works only when the visitor was seen on that connection in the last 24 hours. It can also ban every other visitor seen on that connection in the last 24 hours, with the same reason and length.
visitors.unban lifts the manual ban, so the visitor can chat again and people can answer them. A connection block made with the ban is released with it. A block set by Yaplet's visitor security system is not lifted this way: the answer says the visitor is still blocked, and you clear it under Team → Security.
What an AI Cannot Do Here
- Reply in a Facebook or Instagram conversation. Answer those visitors from the Inbox.
- Reply in a phone-call conversation. A written reply cannot reach a caller, from an AI or from the Inbox.
- Read or add private notes when connected by browser login. Use Yaplet, an API key, or the Inbox.
- Email an address the AI chose. Emails go only to the visitor's own saved address, from the Inbox too.
- Change a visitor's email address or erase a visitor's data. Nobody can change the address the visitor gave, so emails reach only them; the organization owner erases a visitor with Delete visitor data in the Inbox sidebar.
- Ask for a rating on someone else's conversation. Only the person the conversation is assigned to can ask.
Example Prompts
- "Show me the unassigned conversations and summarize what each visitor wants."
- "Find every conversation with [email protected]."
- "Why didn't the AI answer this email?"
- "Assign this conversation to Sarah and add a private note that the customer is on the enterprise plan."
- "Reply to the visitor that their refund has been processed, and send it by email too."
- "Leave the conversations I have open about billing so the AI agent takes them back."
- "Mark every conversation that is waiting for a person as read."
- "Email the transcript of this conversation to the visitor."
- "Ban this visitor for 7 days because they keep posting spam links."