Permissions & access

Every MCP request passes three independent checks. All three must pass, so a permission on its own is never enough to reach data you did not share.

Layer Question
Widgets & channels Is this conversation in an inbox the connection can access?
Permissions Was this specific capability granted to the connection?
Role Does the authorizing user's Chatway role allow it at all?

Tools whose permission was not granted are not offered to the assistant, and return an error if called anyway. The Tool reference documents what each tool takes and returns.

Widgets & channels

A connection is scoped to the widgets and channels you picked when authorizing it. All of them are selected by default, and you can narrow the list at any time.

Channels cover email, WhatsApp, Messenger, and Instagram, so you can give an assistant your website widget without also giving it your WhatsApp inbox.

Anything outside the selection is invisible: conversations from other widgets are not listed, not searchable, and cannot be fetched by ID. Team boundaries are enforced separately and cannot be widened by any permission — a connection never reaches another team's data.

You must keep at least one widget or channel selected.

This selection only controls which conversations the assistant can access. It is not used to install Chatway: the installation code identifies your account, not a widget.

Installation code

Any connected assistant can retrieve your account's installation code with get-installation-code and check an installation with get-installation-status. These tools are always available to a connected assistant: they need no permission and are not listed on the consent screen or in Manage access. The code is the same script that appears in your website's HTML and contains no secret. Only owners and admins can connect an assistant, so only they can authorize this.

Read permissions

Permission Grants Unlocks
read_conversations View conversations and conversation lists. list-conversations, get-conversation, search-conversations
read_conversation_messages View conversations and all messages. list-conversation-messages
read_visitor_details View visitor contact and profile details. get-visitor
search_contacts Search and view contact information. search-contacts
search_knowledge_base Search FAQs and Help Center content. search-knowledge-base
view_tags View tags and their details. list-tags
view_custom_fields View custom-field names and IDs. list-custom-fields

At least one of read_conversations or read_conversation_messages is always required — an assistant that cannot read anything has nothing to act on.

Write permissions

Permission Grants Unlocks
send_replies Send messages as an agent. send-message
resolve_conversations Mark conversations as resolved. resolve-conversation
unresolve_conversations Reopen conversations. unresolve-conversation
assign_conversations Assign conversations to agents. list-agents, assign-conversation
add_notes Add private notes to conversations. add-note
add_tags Add tags to conversations or contacts. add-tag
remove_tags Remove tags from conversations or contacts. remove-tag
add_custom_data Add custom field values. add-custom-data
update_custom_data Update custom field values. update-custom-data
remove_custom_data Remove custom field values. remove-custom-data
request_human_handoff Trigger handover to a human agent on conversations handled by a Chatway AI assistant. handoff-to-human

Roles

Only owners and admins may connect or reconnect an External AI assistant (the MCP OAuth flow). Members do not see AI → External AI in Settings — they cannot view connections, authorize from an MCP client, or change External AI settings.

When an owner or admin authorizes, they may grant read and write permissions according to their role:

Role Can connect (OAuth) Can grant
Owner Yes Read and write
Admin Yes Read and write
Member No —

Connections are shared per team: one row per assistant client (Claude, Cursor, and so on) in AI → External AI, visible only to owners and admins. Only they can rename, change access, or disconnect from the dashboard.

Who actions are attributed to

Every write action from External AI is attributed to the Send Replies as agent on the connection — not the person who authorized OAuth. That covers send-message, notes, resolve, unresolve, assign ("by …"), and related system messages.

You choose the agent when authorizing, and it defaults to whoever created the connection. Your team sees that agent's name in the inbox, and visitor-facing replies appear like any other agent reply. Change it any time under Manage access if you would rather actions come from a dedicated "AI assistant" teammate.

Messages are limited to 10,000 characters.

Confirmation policy

Writes run as soon as they are called, so an authorized agent, including one running unattended or server to server, can do routine work without stopping for approval. Every call still needs the right permission, stays within the connection's widgets and channels, counts toward the rate limits, and is recorded in the connection's activity log.

Bulk actions are the exception. When resolve-conversation, unresolve-conversation or assign-conversation targets more than one conversation, the tool returns a challenge instead of acting, and the assistant must ask you before continuing:

This action will resolve 30 conversations. Are you sure?

The assistant then repeats the call with the confirmation_token from the challenge. Tokens expire after 5 minutes and are tied to that exact call, so one cannot be reused to approve a different action.

Tool Needs confirmation
resolve-conversation More than one conversation
unresolve-conversation More than one conversation
assign-conversation More than one conversation
Every other write tool Never

A single conversation never gets a challenge, even when the assistant changes several conversations one call at a time. Those calls are still limited to 30 conversations per minute per action for your account.

Conversation messages, visitor names, profile fields and custom data are written by your customers, and the assistant reads them. Chatway tells assistants to treat that content as data and never follow instructions in it, but a write that needs no challenge, such as remove-tag or remove-custom-data, has no Chatway check in front of it. Grant write permissions, especially the remove permissions, only to connections you trust to act on their own.

send-message replies to customers without a Chatway challenge. Grant send_replies only to connections that may reply on their own; leave it off when replies must be written or approved by a person.

Chatway's confirmation challenge and your AI client's approval prompt are separate. Your client may still ask you to approve a tool call even when Chatway does not, and an action without a Chatway challenge still changes your inbox or sends a message. Review your client's approval settings before enabling write permissions.

Bulk conversation actions are capped at 30 conversations per call. When more than one conversation is targeted, each runs in its own background job after confirmation. See the Tool reference for the confirmation payload and each tool's exact limits.

Choosing a permission set

Choose permissions for the job you want the assistant to do:

A permission makes an action available. It is not an instruction to perform that action.

Start read-only. Grant read_conversations and read_conversation_messages, confirm the assistant behaves the way you expect, then add write permissions one group at a time.

If you only want an assistant to help you triage, read permissions plus add_notes and add_tags are usually enough — it can summarise and organise without ever messaging a visitor.

Changing permissions later

Nothing is fixed at connect time. Edit a connection to add or remove permissions, change its widgets and channels, or switch the replying agent — the client does not need to reconnect or re-authorize. Changes apply to the assistant's next request, and removing a permission takes effect immediately.

See Manage connections.