Roles & Permissions

Every action in whatbot belongs to a permission — contacts.export, settings.manage, and so on. A role is just a named bundle of permissions. You can see the table for your workspace, and who holds which role, under Settings → Role Based Access.

The table below is how roles are designed to work, and the dashboard already follows it: the sidebar and buttons a person sees depend on their role. On the server, enforcement is being switched on in stages:

Enforced today, for viewing and changing: the team (viewing it, invites, roles, deactivation, label restrictions, availability and shifts), API keys, webhooks, the AI-assistant (MCP) page, the audit log, sharing a chat with a colleague, the analytics downloads, and the workspace analytics (an agent gets only “My work”).
Enforced today for changes only: automation rules and business hours, flow secrets, contact fields, auto-assignment settings, the ticket emoji and privacy settings. Only the roles the table allows can create, edit or delete these, but any signed-in member can still view them — for example the list of rules, or the names of flow secrets (secret values are never shown to anyone).
In both lists, anyone the table does not allow is refused for the actions named.
Not yet enforced: everything else in the table, including the own scope on conversations, calls and tickets. Today an agent can open every conversation and ticket in the workspace, not only their own, and other settings pages — your WhatsApp numbers, quick replies, chat properties — are not yet refused on the server for non-admins. These checks are recorded while they are reviewed, and become binding once enforcement is switched on.

The four roles

Role	In one line
Admin (`org_admin`)	Everything: settings, team, API keys, webhooks, flows, PII policy, audit.
Supervisor (`supervisor`)	All conversations and contacts org-wide, assign, broadcast, export. No settings, team changes, API keys, rules, or flow authoring.
Agent (`agent`)	Designed to see the conversations assigned to them plus unassigned ones (see the note above). Send, note, close. No exports.
Viewer (`viewer`)	Read-only org-wide, including analytics. No sends, no exports.

Super admins are separate. It is not a role but a flag on the account, and it bypasses every role check below (though not the privacy setting: a super admin cannot uncover a number either). No role — and nothing arriving from the CRM — can grant it.

What each role can do

✓ = allowed for every record in the workspace. own = only conversations assigned to them or unassigned; for tickets and tasks, only those assigned to them or created by them; for analytics, their own figures (“My work”). — = denied. Remember the note above: only the areas listed there are enforced by the server today.

Permission	Admin	Supervisor	Agent	Viewer
`conversations.read`	✓	✓	own	✓
`conversations.send`	✓	✓	✓	—
`conversations.claim`	✓	✓	✓	—
`conversations.assign`	✓	✓	—	—
`conversations.close`	✓	✓	✓	—
`conversations.note`	✓	✓	✓	—
`conversations.ai_assist`	✓	✓	✓	—
`contacts.read`	✓	✓	✓	✓
`contacts.write`	✓	✓	✓	—
`contacts.import`	✓	✓	—	—
`contacts.export`	✓	✓	—	—
`contacts.reveal_pii`	✓	✓	—	—
`broadcasts.read`	✓	✓	✓	✓
`broadcasts.send`	✓	✓	—	—
`broadcasts.manage`	✓	✓	—	—
`segments.read`	✓	✓	✓	✓
`segments.manage`	✓	✓	—	—
`flows.read`	✓	✓	✓	✓
`flows.manage`	✓	—	—	—
`forms.read`	✓	✓	✓	✓
`forms.manage`	✓	✓	—	—
`forms.export`	✓	✓	—	—
`ai_agents.read`	✓	✓	✓	✓
`ai_agents.manage`	✓	—	—	—
`catalog.read`	✓	✓	✓	✓
`catalog.manage`	✓	✓	—	—
`calls.read`	✓	✓	own	✓
`calls.initiate`	✓	✓	✓	—
`templates.read`	✓	✓	✓	✓
`templates.manage`	✓	✓	—	—
`analytics.read`	✓	✓	own	✓
`analytics.export`	✓	✓	—	—
`exports.read`	✓	✓	—	—
`tickets.read`	✓	✓	own	✓
`tickets.write`	✓	✓	✓	—
`tickets.export`	✓	✓	—	—
`automations.read`	✓	✓	—	✓
`automations.manage`	✓	—	—	—
`assistant.use`	✓	✓	✓	✓
`settings.manage`	✓	—	—	—
`team.read`	✓	✓	—	—
`team.manage`	✓	—	—	—
`apikeys.manage`	✓	—	—	—
`webhooks.manage`	✓	—	—	—
`audit.read`	✓	—	—	✓

Some rows read differently in practice. The audit log page is open to admins only, even though the table lists audit.read for viewers. And contacts.reveal_pii grants nothing today: nobody, in any role, can uncover a customer’s full number — see Phone number masking.

Two that surprise people

A viewer cannot export. They can read a contact on screen but not download the CSV. A one-record-at-a-time read by a named user and a bulk extract of every customer’s phone number are different actions, and “they could see it anyway” does not make the second one safe.

A supervisor cannot author flows or AI agents. Those decide how the workspace answers its customers automatically — org-wide behaviour, so it is designed to stay with admins. (Automation rules already do: only an admin can create or change one.)

Where a role comes from

Standalone (whatbot.in). An admin sets it in Settings → Team & Agents. An admin can give any role below their own — supervisor, agent or viewer — and cannot change their own role. Changes are recorded in the audit log as role.changed, with who changed it and what it was before.

A role change takes effect when that person’s session next refreshes — they are not signed out. If you need someone’s access gone immediately, deactivate the account rather than demoting it.

Embedded (inside the CRM). The role comes from the CRM and is translated on sign-in and on the hourly team sync:

CRM role	whatbot role
`super_admin`	`org_admin`
`org_admin`	`org_admin`
`fls_manager`	`supervisor`
`land_manager`	`supervisor`
`team_lead`	`supervisor`
`auditor`	`viewer`
`trainer`	`agent`
`agent`	`agent`
`fls`	`agent`
`land_assignee`	`agent`

Anything unrecognised — a new CRM role, a missing value — becomes an agent. It never resolves upward.

The Team page is read-only in an embedded workspace. The CRM owns the roster there, and the hourly sync would overwrite anything changed here. Change the role in the CRM; it arrives within the hour.

A workspace can override any row of that table (for example, if trainer genuinely supervises in your organisation). Ask support to set it.

If someone is missing something

Check their role on Settings → Team & Agents first. If it looks right and an action is still refused, quote the error message to support (it often names the permission required), along with the workspace name.