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:

With domain, the result for that website is also returned at the top level. Chatway checks in this order:

  1. Recent conversations on that domain in the last 7 days: widget_operational.
  2. A connected Chatway store app for the domain: script_detected with detected_by: marketplace.
  3. The page HTML. Chatway loads the domain's home page and looks for this account's script: script_detected with detected_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