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:
- Summarize conversations: allow reading conversations and messages.
- Prepare replies for review: keep the connection read-only and ask for a draft in your assistant.
- Send replies to visitors: add
send_repliesand check the selected Send Replies as agent. - Organize conversations: add only the note, tag, assignment, or resolution permissions you need.
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.