Tool reference
Chatway exposes 21 MCP tools. This page documents every one: its parameters, what it returns, the permission it needs, and when it asks for confirmation.
You do not normally call these yourself — your assistant does. Use this page when you are building an integration, debugging a failed call, or writing instructions that steer an assistant toward the right tool.
Tool index
| Tool | What it does | Permission | Confirmation |
|---|---|---|---|
list-conversations |
Browse conversations by status and find the next threads to review. | read_conversations |
— |
get-conversation |
Open one conversation to see its contact, status, and assigned agents. | read_conversations |
— |
list-conversation-messages |
Read a conversation's messages before summarizing it or preparing a reply. | read_conversation_messages |
— |
search-conversations |
Find candidate conversations, then open a match to review its details and messages. | read_conversations |
— |
get-visitor |
Read one visitor's contact details and profile. | read_visitor_details |
— |
search-contacts |
Find matching contacts before choosing the person you want to work with. | search_contacts |
— |
search-knowledge-base |
Find relevant FAQ or Help Center answers to help prepare a reply. | search_knowledge_base |
— |
list-tags |
See available tags and their names before organizing a contact. | view_tags |
— |
list-custom-fields |
See custom-field names before adding or changing visitor data. | view_custom_fields |
— |
list-agents |
Find the teammate to assign a conversation to, using their name or email. | assign_conversations |
— |
send-message |
Send a visitor-facing reply as the connection's selected agent. | send_replies |
— |
resolve-conversation |
Mark selected conversations as resolved. | resolve_conversations |
Bulk only |
unresolve-conversation |
Reopen selected conversations. | unresolve_conversations |
Bulk only |
assign-conversation |
Assign selected conversations to a teammate. | assign_conversations |
Bulk only |
add-note |
Add an internal note that the visitor cannot see. | add_notes |
— |
add-tag |
Tag the contact linked to a conversation; create the tag if it does not exist. | add_tags |
— |
remove-tag |
Remove a named tag from the conversation's contact. | remove_tags |
— |
add-custom-data |
Set a named custom-field value on a visitor. | add_custom_data |
— |
update-custom-data |
Change an existing named custom-field value on a visitor. | update_custom_data |
— |
remove-custom-data |
Remove a named custom-field value from a visitor. | remove_custom_data |
— |
handoff-to-human |
Request human help for a conversation handled by a Chatway AI assistant and stop further External AI replies while the handoff remains active. | request_human_handoff |
— |
get-installation-code |
Get the account's script for installing Chatway on a website. | None | — |
get-installation-status |
List the account's websites and messaging channels, or check one website. | None | — |
Conventions
These rules apply to every tool.
| Identifiers | Use the identifier returned for the resource you are targeting. A conversation_id identifies a conversation; a visitor_id identifies a visitor. Follow each parameter's format and do not substitute one resource's ID for another. |
| Scope | Results are always limited to the widgets and channels the connection was granted. A conversation outside that set behaves as if it does not exist. |
| Permissions | A tool is only published to the assistant if its permission was granted. Calling one without permission returns an error. |
| Rate limit | 120 requests per minute per connection, then 429. resolve-conversation, unresolve-conversation and assign-conversation also allow 30 conversations per minute for each action, per account, shared with the REST API. |
| Visibility | Inbox tools only appear once a live connection exists. A disconnected connection publishes none. The MCP server may still expose internal diagnostic tools to assistants only — these are not configurable in Chatway. |
Every tool sets all four MCP hints, so clients that surface them can warn you before a tool runs:
| Hint | Tools | Why |
|---|---|---|
| Read-only and idempotent | All read and search tools | They only return data and change nothing. |
| Destructive | send-message, resolve-conversation, unresolve-conversation, assign-conversation, add-tag, remove-tag, add-custom-data, update-custom-data, remove-custom-data |
They overwrite or remove existing data or state (a status, an assignment, a tag color, a field value), or, for send-message, deliver a reply that cannot be unsent. |
| Open world | send-message |
Its result reaches the customer outside your Chatway workspace. Every other tool stays inside your workspace. |
| Not idempotent | All write tools | Calling one twice does the work twice. |
add-note and handoff-to-human only add internal records, so they are neither destructive nor
open world. Do not automatically repeat a write after a timeout. First check whether it succeeded, especially when sending messages or adding notes, so a retry does not create a duplicate.
The confirmation flow
Chatway asks for confirmation only on bulk actions: resolve-conversation,
unresolve-conversation and assign-conversation called with more than one conversation. Instead
of doing the work they return confirmation_required: true with a confirmation_token, an
affected_count, a plain-language message, and expires_in_seconds. The assistant shows you
the message, then repeats the call with the token to proceed.
Every other write runs as soon as it is called, including these three tools on a single
conversation. This lets an authorized agent, including one running unattended, do routine work
without stopping for approval. Permissions, source scope, rate limits and the activity log still
apply to every call. send-message runs only when the connection was granted send_replies;
leave that permission off if replies must be written by a person.
Your AI client may still ask you to approve a tool before calling it, based on the hints above or its own settings. That prompt comes from the client, not from Chatway, and is configured in the client.
Tokens last 300 seconds and are bound to the exact arguments they were issued for, so an approval cannot be replayed against a different call.
| Tool | Asks when |
|---|---|
resolve-conversation |
More than one conversation — show the user the message, then retry with confirmation_token |
unresolve-conversation |
More than one conversation |
assign-conversation |
More than one conversation |
Read tools
list-conversations
Lists conversations newest first, with a preview of the last message. Call this before reading messages so newly created conversations are picked up.
Permission: read_conversations
| Parameter | Type | Required | Notes |
|---|---|---|---|
status |
string | No | all, unresolved, or resolved. Defaults to all. |
page |
integer | No | 1–10000. Defaults to 1. |
per_page |
integer | No | 1–100. Defaults to 25. |
Returns conversations and pagination.
Each conversation carries id, contact (id, name, email), last_message (id,
content, type, origin, sender_type, created_at), widget_id, origin, origin_url,
email_subject, is_resolved, resolved_at, ended_at, created_at, and updated_at.
pagination carries page, per_page, has_more, and next_page.
get-conversation
Gets one conversation with contact and assigned-agent detail.
Permission: read_conversations
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
Returns a single conversation object with everything list-conversations provides plus
contact.phone, contact.country, contact.language, contact.timezone, assigned_agents
(each id, name, email), message_count, social_account_identifier,
external_identifier, resolved_by, and reopened_at.
Errors: no permission; Conversation not found for the configured team.
list-conversation-messages
Lists the messages in one conversation, newest first, using cursor pagination.
Permission: read_conversation_messages
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
limit |
integer | No | 1–100. Defaults to 50. |
before_sort_number |
string | No | Cursor. Pass next_before_sort_number from the previous response. |
include_system_messages |
boolean | No | Defaults to false. |
include_internal_messages |
boolean | No | Defaults to false. |
Returns conversation_id, messages, and pagination.
Each message carries id, conversation_id, sort_number, sender (type, id, name,
email), origin, type, content, urls, parent_id, is_system_message, edited_at,
created_at, and updated_at. pagination carries limit, has_more, and
next_before_sort_number.
Note that system and internal notes are hidden unless you ask for them, so an assistant summarising a thread sees what the visitor saw by default.
search-conversations
Permission: read_conversations
| Parameter | Type | Required | Notes |
|---|---|---|---|
query |
string | Yes | 1–255 characters. |
limit |
integer | No | 1–50. Defaults to 20. |
Returns conversations, each with id, email_subject, origin, is_resolved, and
contact (id, name, email). This is a lighter shape than list-conversations — follow up
with get-conversation for full detail.
get-visitor
Permission: read_visitor_details
| Parameter | Type | Required | Notes |
|---|---|---|---|
visitor_id |
string | Yes | UUID. |
Returns visitor with id, name, email, phone, country, language, timezone,
widget_id, and created_at.
Errors: no permission; Visitor not found for the authorized sources.
search-contacts
Permission: search_contacts
| Parameter | Type | Required | Notes |
|---|---|---|---|
query |
string | Yes | 1–255 characters. |
limit |
integer | No | 1–50. Defaults to 20. |
Returns contacts, each with id, name, email, phone, and widget_id.
search-knowledge-base
Searches your FAQ and Help Center content — useful for grounding a reply in your own material instead of letting the model improvise.
Permission: search_knowledge_base
| Parameter | Type | Required | Notes |
|---|---|---|---|
query |
string | Yes | 1–255 characters. |
limit |
integer | No | 1–50. Defaults to 20. |
Returns results, each with id, question, and answer.
list-tags
Permission: view_tags
Takes no parameters. Returns tags, each with id, name, and color.
list-custom-fields
Permission: view_custom_fields
Takes no parameters. Returns custom_fields, each with id and name.
list-agents
Lists teammates so the assistant can resolve a name like "Nibir" to an agent UUID before assigning. Deactivated agents are omitted.
Permission: assign_conversations
| Parameter | Type | Required | Notes |
|---|---|---|---|
query |
string | No | Filter by name or email (partial match). |
limit |
integer | No | Max results (default 50, max 100). |
Returns agents, each with id, name, email, status, and online_status.
get-installation-code
Returns the JavaScript snippet that installs Chatway on a website. The installation_id in it
identifies your Chatway account. It is not a widget ID: no widget needs to be chosen or created,
and the widget and channel selection on the connection does not affect it.
Permission: none. Any connected account can retrieve its own installation code.
Takes no parameters. Returns installation_id, script_url, script_html (the ready-to-paste
<script> tag), placement, and duplicate_check. The snippet contains no API key or other
secret.
This tool does not change any website. When you ask for the code, the assistant shows it under
Your Chatway installation code with the placement instructions. The code goes once in a shared
layout that loads across the website, inside <head> or <body>, preferably just before
</body>. On Shopify, Wix, WordPress and other supported platforms you can use Chatway's native
app or plugin instead. When you ask the assistant to install Chatway, it first searches the site for
an existing <script id="chatway"> or widget.js?id= script, so the script is never added twice,
and asks before replacing another account's script.
If the assistant is not connected yet, it should ask you to connect Chatway first. If you do not have a Chatway account, sign up at chatway.app, then connect the assistant and approve access.
The same code is available over the REST API with Get Account Installation Code.
get-installation-status
Returns the account's website installations and messaging-channel connections, and optionally checks one website.
Permission: none.
| Parameter | Type | Required | Notes |
|---|---|---|---|
domain |
string | No | Domain such as example.com to check. A full URL is also accepted; only its host is used. Must be a public website. |
Always returns:
websites: the domains where Chatway is installed, most recent first (up to 50). A domain appears when visitors started conversations there in the last 7 days (widget_operational) or when a connected Chatway store app such as WordPress or Shopify is installed for it (script_detectedwithdetected_by: marketplaceandplatform), even with no conversations. A direct JavaScript installation without recent conversations is only found by checking its domain.channels: one entry each for WhatsApp, Facebook Messenger, Instagram and email, withstatusconnected,disabled(connected but turned off, for example after a plan change) ornot_connected, and the names of the connected accounts. This comes from the account's integrations and is separate from website installation.
With domain, the result for that website is also returned at the top level. Chatway checks in
this order:
- Recent conversations on that domain in the last 7 days:
widget_operational. - A connected Chatway store app for the domain:
script_detectedwithdetected_by: marketplace. - The page HTML. Chatway loads the domain's home page and looks for this account's script:
script_detectedwithdetected_by: html.
Each website result has domain, status, script_detected, widget_operational, detected_by
(conversations, marketplace, html, or null), platform, last_conversation_date, and a
user-facing message:
status |
message |
|---|---|
widget_operational |
Chatway was recently active on example.com. The last visitor conversation was on [date]. |
script_detected (html) |
Your Chatway code was found on example.com. Widget visibility hasn't been verified. |
script_detected (marketplace) |
The Chatway Shopify app is installed on example.com. Widget visibility hasn't been verified. |
different_account_script |
Chatway was detected on example.com under a different account. Confirm which account you want to use before changing the installation. |
unverified_spa |
We couldn't confirm the installation on example.com from the page HTML. The site may load Chatway dynamically. |
not_detected |
We didn't detect Chatway on example.com. |
check_failed |
We couldn't check example.com. Try again. |
invalid_domain |
Enter a valid website domain or URL, such as example.com. |
Only widget_operational and script_detected confirm an installation, and neither guarantees the
widget is enabled or visible. A recent conversation confirms past activity, a visible widget
confirms it loads, and a test message received in the inbox confirms visitors can send messages.
The HTML check reads the home page only (up to 2 MB, following up to 3 redirects). Each account can
run 10 website fetches per minute; results answered from conversations or a store app do not count.
The same check is available over the REST API with Get Installation Status.
Write tools
send-message
Sends a reply into a conversation. The message is posted as the connection's Send Replies as agent, so it appears to the visitor like any other agent reply.
Permission: send_replies
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
content |
string | Yes | 1–10,000 characters. |
Returns message with id, conversation_id, content, type, and created_at.
Errors: no permission; conversation not found; No agent is configured for this connection.;
human handoff already requested for this conversation. Chatway also rejects sends that are not
allowed for the conversation's current state, passing through its own explanation.
After handoff-to-human (or Chatway AI's own handoff) has been requested, External AI cannot
send further replies on that conversation until the handoff is cleared.
resolve-conversation
Permission: resolve_conversations · Confirmation: when more than one conversation · Bulk queue: when more than one conversation
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_ids |
array of string | Yes | 1–30 UUIDs. Pass all targets in one call — do not loop single resolves. |
confirmation_token |
string | No | Only for more than one conversation: required on the second call after the user approves the challenge. |
Returns resolved_conversation_ids for a single conversation. For two or more, returns
queued: true, queued_conversation_ids, and skipped_conversation_ids — each conversation is
processed in its own background job.
A single conversation is resolved straight away. With two or more, the first call returns
confirmation_required: true with a plain-language message, for example:
This action will resolve 30 conversations. Are you sure?
Show that message to the user. After they approve, call again with the same arguments plus
confirmation_token.
Conversation limit: each conversation in the call counts toward the account's
30 resolves per minute. If the call would go over, it returns an error with the number of
seconds to wait, no confirmation is issued and no conversation is queued. Wait that long, then
call again. unresolve-conversation and assign-conversation work the same way, each with its
own budget.
Resolving a conversation that is already resolved, or reopening one that is already open, succeeds without changing anything or sending events again.
unresolve-conversation
Permission: unresolve_conversations · Confirmation: when more than one conversation · Bulk queue: when more than one conversation
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_ids |
array of string | Yes | 1–30 UUIDs. |
confirmation_token |
string | No | Only for more than one conversation: required on the second call after the user approves the challenge. |
Returns unresolved_conversation_ids for a single conversation. For two or more, returns
queued: true with queued_conversation_ids and skipped_conversation_ids (one background job
per conversation).
assign-conversation
Assigns or unassigns a teammate. Prefer agent_query when the user names someone ("assign
Nibir"); use list-agents first if you need to browse the roster or the match is ambiguous.
By default the tool assigns the agent. Set unassign: true to remove them instead. A conversation
that is already in the requested state is left unchanged, so repeating a call never undoes it.
Permission: assign_conversations · Confirmation: when more than one conversation · Bulk queue: when more than one conversation
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_ids |
array of string | Yes | 1–30 UUIDs. |
agent_id |
string | One of | UUID of an agent on your team. Required unless agent_query is set. |
agent_query |
string | One of | Name or email to resolve (e.g. Nibir). Required unless agent_id is set. |
unassign |
boolean | No | true removes the agent. Defaults to false, which assigns them. |
confirmation_token |
string | No | Only for more than one conversation: required on the second call after the user approves the challenge. |
Returns agent_id, agent (id, name, email), and for a single conversation one of
assigned_conversation_ids, unassigned_conversation_ids or unchanged_conversation_ids (with a
message) when the agent was already in the requested state. For two or more, returns queued: true with queued_conversation_ids and
skipped_conversation_ids (one background job per conversation).
When several teammates match agent_query, the tool returns ambiguous: true with a
candidates list instead of assigning — call again with the chosen agent_id.
Errors: no permission; Agent not found for this team.; no match for agent_query.
add-note
Adds a private internal note. Notes are never shown to the visitor.
Permission: add_notes
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
content |
string | Yes | 1–10,000 characters. |
Returns note with id, conversation_id, content, and created_at.
Errors: no permission; conversation not found; The authenticated user does not have an agent profile.
add-tag
Tags the visitor on a conversation. Creates the tag if it does not exist yet.
Permission: add_tags
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
name |
string | Yes | Up to 100 characters. |
color |
string | No | Up to 50 characters. |
Returns conversation_id, chat_contact_id, and tag.
Errors: no permission; conversation not found; This conversation has no visitor/contact to tag.
remove-tag
Permission: remove_tags
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
name |
string | Yes | Up to 100 characters. |
Returns conversation_id, chat_contact_id, and removed_tag.
add-custom-data
Sets a custom field value on a visitor. Note this targets a visitor, not a conversation.
Permission: add_custom_data
| Parameter | Type | Required | Notes |
|---|---|---|---|
visitor_id |
string | Yes | UUID. |
name |
string | Yes | Up to 100 characters. |
value |
string | Yes | Up to 1,000 characters. |
Returns visitor_id, name, and value.
update-custom-data
Same parameters and return shape as add-custom-data, for changing a value that already exists.
Permission: update_custom_data
| Parameter | Type | Required | Notes |
|---|---|---|---|
visitor_id |
string | Yes | UUID. |
name |
string | Yes | Up to 100 characters. |
value |
string | Yes | Up to 1,000 characters. |
Returns visitor_id, name, and value.
remove-custom-data
Permission: remove_custom_data
| Parameter | Type | Required | Notes |
|---|---|---|---|
visitor_id |
string | Yes | UUID. |
name |
string | Yes | Up to 100 characters. |
Returns visitor_id and removed_field.
handoff-to-human
Escalates a conversation to a human using the same handover flow as Chatway's built-in AI agent, so your team gets the notifications and inbox state they already expect.
Works only on conversations currently handled by a Chatway AI assistant. If no AI assistant is
assigned, the tool returns AI assistant is not assigned to this conversation. and changes
nothing. To bring in a teammate on any other conversation, use assign-conversation or
add-note.
Permission: request_human_handoff
| Parameter | Type | Required | Notes |
|---|---|---|---|
conversation_id |
string | Yes | UUID. |
Returns conversation_id and status, where status is handoff_requested.
Common workflows
For a draft-only workflow, read the conversation and relevant knowledge-base answers, then show the draft in your assistant. Do not call send-message until you want it delivered to the visitor. If a bulk action returns queued: true, it has been accepted for background processing; check the resulting conversations before reporting that every change is complete.
Triage the unresolved queue. list-conversations with status: unresolved, then
list-conversation-messages on each interesting one, then add-tag or assign-conversation
(use list-agents or agent_query when assigning by name).
Answer from your own docs. list-conversation-messages to read the question,
search-knowledge-base to find the answer, send-message to reply.
Find a customer's history. search-contacts to get the visitor, get-visitor for their
profile, search-conversations for their past threads.
Close out a batch. search-conversations to gather candidates, resolve-conversation with
all the IDs, then confirm when asked.
Related pages
- Permissions & access — which permission unlocks which tool.
- MCP overview — how MCP compares to webhooks and the REST API.