A role is a named bundle of permissions. Every organization gets its own copy of the four built-in roles, and an owner can add custom ones on top. The list shows each role's type, how many members hold it, and how many permissions it grants.
The four built-in roles #
These are marked System and cannot be edited or deleted. Their permissions come from a fixed matrix in the application, not from the database, so they behave the same in every workspace.
| Field | What it does |
|---|---|
| Owner | Everything. The permission check is short-circuited for owners, so no individual key can be withheld from them. Owners are the only people who can create, edit or delete roles. |
| Admin | Everything except adding or removing WhatsApp accounts, changing billing, and mutating roles. An admin can view accounts, update them, set a default and register a number, and can manage the whole team; billing and roles are read-only. |
| Agent | The day-to-day operator. Full inbox access; contacts they can view, create, update, bulk-upload and assign; contact lists they can build and populate. Campaigns and templates are view-only, and there is no delete on contacts. |
| Viewer | Read-only. The view permission for WhatsApp accounts, contacts, contact lists, campaigns, templates and the inbox, and nothing else. |
Rank matters as well as permissions. Owner, Admin, Agent and Viewer are ranked in that order, and some abilities — reaching the team screen, managing another member, editing roles — are gated on rank rather than on a permission key. That is why a custom role cannot be used to hand out team management.
Custom roles #
Press New Role to compose one. You give it a name, an optional description, and tick the permissions it grants. Members assigned to that role get exactly those capabilities — nothing is inherited from Agent or from anywhere else.
-
Start from the job, not the screen
Write down what the person has to do — "answer the inbox and nothing else", "run campaigns but never touch contacts" — then tick the keys that allow exactly that. -
Tick the view key too
A create or update permission is not much use on its own if the person cannot open the list. Grant the matching.viewkey alongside it. -
Assign it on the team screen
A new role appears in the role picker on Team members for anyone senior enough to assign it.
Deleting a role is blocked while anyone still holds it: move those members to another role first. System roles have no Delete at all.
How permissions compose #
Every permission is a key in the form group.action — contacts.create, inbox.send, billing.manage. When the application asks whether you may do something, it asks for one of these keys by name.
Three things can answer yes: the exact key is granted, the group wildcard contacts.* is granted, or you are an owner. That is the whole rule. Permissions do not stack across roles, because a user holds exactly one role.
The permission groups #
The catalog is fixed by the application — these are the groups you will see on the editor, in this order.
| Field | What it does |
|---|---|
| WhatsApp Accounts | view, create, update, delete, set_default, register. |
| Contacts | view, create, update, delete, bulk_upload, block, opt_out, assign. |
| Contact Lists | view, create, update, delete, manage_members. |
| Campaigns | view, create, launch, cancel. Launch is separate from create, so you can let someone build a broadcast that another person sends. |
| Templates & Commerce | templates view, create, update, delete, plus products view and manage. |
| Inbox | view, send, assign, archive. |
| AI Agents | view and manage. |
| Team & Roles | team view, invite, update, delete, plus roles view, create, update, delete. |
| Billing | view and manage. |
| Developer / API | api_keys view, create, delete, and webhooks manage. |