Overview
The native Roles & Access module controls what each person can open, read, and change in an account. In addition to the default Administrator and Agent profiles, an Administrator can create roles with granular permissions, operational team/inbox scope, and personal-data visibility rules.
This module belongs to the Conversa Labs installation and does not depend on Chatwoot Enterprise's premium Custom Roles feature. When a native role is assigned to an Agent, it becomes authoritative: a missing permission is a denial even when the generic Agent profile would normally access that surface.
Prerequisites
- The Administrator profile to create, edit, delete, or assign roles.
- Granular permissions, Field-level permissions, and Platform governance enabled on the account to use permissions/scope, field rules, and the template gallery respectively.
- A native role can only be assigned to an Agent in the same account. Administrators retain full access and cannot receive a native role.
Step by step
- Open Settings → Roles & Access.
- Select New role or Create from template.
- Enter a name and description, then select only the required permissions.
- Under Scope, choose Entire account, Specific teams, or Specific inboxes. A scoped role must contain at least one team/inbox from its own account.
- Under Fields, set Contact and Organization data to Visible, Masked, or Hidden.
- Save. In Settings → Agents, edit an Agent and assign the role.
- Validate with a test account using that role: navigation, direct URLs, reads, creates, updates, deletes, exports, and real-time events must all follow the role.
How the three layers work
- Permissions (L1): each area has its own read or management key. Sensitive operations have separate keys, including contact export/deletion, report export, audit, governance, data-subject requests, and administrative contract actions. Navigation hides unavailable actions, while the backend always makes the final authorization decision.
- Operational scope (L2): for conversations and people, Specific teams and Specific inboxes constrain lists, search, counters, direct-ID access, bulk actions, exports, and real-time delivery. Resources linked to a conversation, contact, team, or inbox follow the available relationship. Global records/settings with no such relationship remain controlled by L1; scope does not invent a relationship that does not exist.
- Field visibility (L3): Contact rules cover name, email, phone, identifier, tax ID, address, and custom/additional attributes. Organization rules cover tax ID, email, phone, and address. Rules are applied to API responses, CSV exports, and real-time events. Masked or hidden fields are also blocked from editing so a client cannot replace the real value with a mask.
Important rules
- An assignment can never reference a role from another account.
- Assigning a native role clears any Enterprise custom role on the same membership; the two authorization models are never silently combined.
- An assigned role cannot be deleted. Remove or replace all assignments first.
- Disabling Granular permissions disables native-role effects and restores the account's standard Administrator/Agent behavior.
- Administrator always remains outside native-role restrictions. Use an Agent to test least privilege.
Use cases
- An outsourced support team limited to one inbox with phone/email masked.
- A DPO who handles data-subject requests and audit without operational administration.
- A supervisor with team conversations, reports, and team management but no integrations or billing.
- Finance staff with payments and exportable reports but no access to unrelated messages.
Troubleshooting
- The role does not seem to restrict anything: verify that it is assigned to an Agent in the same account and that Granular permissions is enabled.
- The person can open a route but an action is unavailable: check the action-specific key; page access does not automatically grant delete, export, or administrative operations.
- The person sees unexpected data: review the scope type, selected teams/inboxes, and the conversation or contact relationships. Global settings without a relationship use L1 only.
- The phone is masked but the call button still works: also intentional. The call is placed by the system from the contact record, without the number ever being shown to the agent — the rule exists to stop the data being read and copied, not to stop the work.
- A field somebody could edit yesterday is now read-only: the rule is now enforced in the interface too. Before, the field looked editable and the save was refused by the server; now it shows as locked from the start. If that person genuinely needs to edit it, change the field rule to Visible.
- A masked value cannot be edited: this is intentional. Change the rule to Visible, update the value, and restore the rule.
- I cannot delete a role: it is still assigned. Replace those assignments first.