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.
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 profile and activity. | 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. | view-tags |
view_custom_fields |
View custom fields and values. | view-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. | 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 on bulk and destructive actions
High-risk actions are safe by default. Rather than acting immediately, the tool returns a challenge and the assistant must ask you before continuing:
This action will resolve 100 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 |
Always |
unresolve-conversation |
Always |
assign-conversation |
Always |
remove-tag |
Always |
remove-custom-data |
Always |
Bulk conversation actions are capped at 100 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
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.