Canonical page: https://docs.teloring.com/docs/product/roles/overview Last modified: 2026-08-20T20:49:57.000Z # Roles and Permissions A **role** is a named bundle of permissions. You decide once what a role may reach, then give that role to as many agents as you like. Change the role later and **everyone on it follows immediately** — you never edit permissions person by person. Open **Admin → Agents, Teams & Roles → Roles & Permissions** in the sidebar.  Every account defines its own roles. There is no fixed list of role names in Teloring — *Owner*, *Team Leader*, *Marketing*, *Agent* and *Viewer* are five starting points that ship with your account, and you can rename, re-scope, duplicate or delete any of them except **Owner**. :::info Account isolation Roles belong only to the current Teloring account. A role created here is never visible in another account, and an agent can only be given a role that exists in their own account. ::: ## What a role controls A role answers two separate questions, and they work differently. Each has its own tab in the role editor. | Tab | The question it answers | How it is expressed | | --- | --- | --- | | **System permissions** | *May this agent reach this feature?* | Every feature is split into up to four actions: **Read**, **Create**, **Update**, **Delete**. | | **Channel permissions** | *Which inboxes does this agent work in, and what may they do there?* | 18 on/off abilities, set separately for each inbox. | The split exists because the two are genuinely different problems. "Can this person open Analytics?" is a yes/no about a page. "Can this person see the WhatsApp waiting line but not the Email one?" is a question about *places*, and no amount of read/create/update/delete describes it. - **[System permissions reference →](./system-permissions.md)** every feature and what each action unlocks - **[Channel permissions reference →](./channel-permissions.md)** all 18 inbox abilities, and the Future inbox rule - **[Example roles and recipes →](./examples.md)** ready-made setups to copy ## Key facts | Fact | Meaning | | --- | --- | | A role is a bundle of permissions | Not a job title, not a team. | | An agent has exactly one role | There is no stacking or combining of roles. | | Roles are account-wide | Everyone works from the same role list. | | Editing a role affects everyone on it | Immediately, on their very next click. No re-login needed. | | Owner cannot be edited or deleted | Deliberately — see [The Owner role](#the-owner-role). | | A team is not a permission | [Team](../teams.md) membership affects conversation *routing* only. It grants and restricts nothing. | | Department is not a permission | The **Department** field on an agent is a free-text label for display and search. | | Enforced on the server | Hiding a button is a courtesy. The rule is applied again on every request. | | Up to 50 roles per account | Enough for any real structure; if you need more, you are probably describing people, not roles. | :::warning Permissions are enforced twice, on purpose Teloring hides what an agent cannot use — menu items disappear, buttons vanish, queues come back empty. That is only to keep the workspace honest and uncluttered. The real protection is on the server. Every action checks the role again before it runs, so an agent who reaches a restricted feature another way — a saved link, a browser console, the public API — is refused with a *permission denied* error. You never have to rely on the interface hiding something. ::: --- ## The Roles page ### Role cards The page opens on a gallery with one card per role.  | Element | What it shows | | --- | --- | | **Role name** | The name agents and admins see when assigning. | | **Badge** | **Fixed**, **Default** or **Custom** — see the table below. | | **Description** | Your own note about what this role is for. It appears again under the role picker on the Agents page, so write it for the person choosing. | | **agents** | How many **active** agents currently hold this role. Deactivated agents are not counted. | | **permissions** | How many individual permissions are granted. A rough measure of how broad the role is — useful for spotting a role that has quietly grown. Owner shows `∞`. | | **Edit** / **View** | Opens the role editor. It reads **View** for the Owner role and for anyone without permission to change roles. | | **Duplicate** | Creates an unsaved copy — *Agent* becomes `Agent (copy)` — with the same permissions, ready to adjust. The fastest way to build a new role. | | **Delete** | Removes the role. See [Delete a role](#delete-a-role). | ### Badges | Badge | Meaning | | --- | --- | | **Fixed** | The Owner role. Full access, permanently. Cannot be changed or deleted by anyone. | | **Default** | One of the five roles created with your account. Fully editable and deletable — the badge only tells you Teloring made it, not you. | | **Custom** | A role somebody in your account created. | ### Buttons and states | Element | What it does | | --- | --- | | **+ New role** | Opens an empty role editor. Hidden if you do not have permission to create roles. | | **No roles yet** | The empty state, with a shortcut to create the first role. You should not normally see this — every account is created with five. | --- ## Create a role 1. Open **Admin → Agents, Teams & Roles → Roles & Permissions**. 2. Click **+ New role** — or click **Duplicate** on the role closest to what you want, which is usually faster. 3. Enter a **Role name**. This is what appears in the role picker on the Agents page, so make it obvious: *Night shift supervisor*, not *Role 4*. 4. Optionally write a **Description** — what this role is for. It is shown under the picker when somebody assigns it. 5. On the **System permissions** tab, tick what this role may reach. 6. On the **Channel permissions** tab, set the **Future inbox** defaults first, then adjust individual inboxes that differ. 7. Click **Save**.  ### Field reference | Field | Required | Limit | Notes | | --- | --- | --- | --- | | **Role name** | Yes | 60 characters | Must be at least 2 characters and unique in the account. Names are compared ignoring case, so `Agent` and `agent` collide. | | **Description** | No | 400 characters | Free text. Shown on the role card and under the role picker on the Agents page. | :::tip Start from Duplicate Building a role from an empty grid means ticking dozens of boxes and remembering what a support agent actually needs. Duplicating **Agent** or **Team Leader** and changing five things is faster and much less error-prone. ::: --- ## Edit a role Click **Edit** on the card, change what you need, and click **Save**. **The change is immediate.** Everyone on that role gets the new permissions on their next click — nobody has to sign out and back in. If you remove a permission from somebody who is using that feature right now, their next action there is refused. :::warning Editing your own role If you edit the role you yourself hold, you are changing your own access. Removing **Roles & permissions → Update** from your own role means you can no longer open this page to put it back. Teloring does not stop you: an account can have several roles that manage roles, and second-guessing you would be worse. If it happens, an Owner can restore it — which is the reason Owner cannot be edited. ::: --- ## Delete a role Click **Delete** on the card. **If nobody holds the role**, it is removed straight away. **If agents still hold it**, Teloring will not orphan them. The dialog tells you how many there are and asks which role they should move to.  | Element | What it does | | --- | --- | | **Move those agents to** | The role every affected agent receives. Every other role in the account is listed. | | **Delete** | Moves the agents, then deletes the role. | | **Cancel** | Nothing changes. | Deleting a role does **not** delete agents, conversations, customers or anything else. The affected agents keep working immediately — with their new role's permissions. :::note You cannot delete the Owner role The **Delete** button does not appear on the Owner card, and the API refuses the request. See below. ::: --- ## The Owner role **Owner** is the one role Teloring treats as special. It has full access to everything, permanently, and it **cannot be edited or deleted by anyone — including an Owner**. That is not an oversight. Every other role can be narrowed until it can no longer reach the Roles page, so without one role that is guaranteed to work, an account could lock itself out of its own workspace with a single mistaken save. Owner is that guarantee. | Question | Answer | | --- | --- | | Can I change what Owner may do? | No. Its card opens read-only, fully ticked, with no **Save** button. | | Can I delete it? | No. | | Can I rename it? | No. | | Can I give Owner to more people? | **Yes** — as many as you like. It is an ordinary assignment on the Agents page. | | Who has it at the start? | The person who created the account. | | Can I take Owner away from someone? | Yes, as long as somebody else still has it. | ### The last Owner is protected Teloring refuses any change that would leave the account with **no active Owner**: - moving the last Owner to another role; - deactivating the last Owner; - deleting the last Owner's profile. All three are blocked with *"This is the account's last Owner. Give Owner to another agent first."* — from the Agents page and from Teloring support tooling alike. Two things never count as cover: a **deactivated** agent, and an **AI Agent**. Software cannot administer an account. :::tip Give Owner to two people One Owner is a single point of failure — somebody on holiday, somebody who left. Two Owners means the protection above never gets in your way, and somebody can always reach billing and settings. ::: --- ## Assign a role to an agent Roles are assigned on the **Agents** page, not here. 1. Open **Admin → Agents, Teams & Roles → Agents**. 2. Click ✏️ on the agent's row — or **Add Agent** for somebody new. 3. Pick a **Role**. The list contains every role in your account, and the description appears underneath so you can confirm you picked the right one. 4. Save.  The agent's new permissions apply immediately, on their next click. | Situation | What happens | | --- | --- | | New agent created without choosing a role | Gets the account's **Agent** role — the least-privilege sensible default, never "no access". | | Agent's role is deleted | Moved to the role chosen in the delete dialog. | | Agent is the last Owner | Cannot be moved to another role until somebody else is an Owner. | The **Role** column in the agents table shows each person's role name, so you can scan the directory and see who has what. See [Agents and AI Agents](../agents.md). :::note AI Agents do not have roles An AI Agent has no login, so a role would mean nothing to it. What an AI Agent may do is configured in its own profile — see [Agents and AI Agents](../agents.md). ::: --- ## The five default roles Every new account is created with these five. They are a starting point, not a fixed structure: rename them, re-scope them, or delete the ones you do not need. | Role | Built for | Shape | | --- | --- | --- | | **Owner** | The person who owns the workspace | Everything, permanently. Fixed. | | **Team Leader** | A support manager who is not the account owner | Runs the floor: every inbox, every conversation, teams, Studio, knowledge base, full analytics, business hours. **No billing, no agent management, no API keys, no workspace deletion.** | | **Marketing** | Campaigns, automations and reporting | Analytics, Studio, forms, knowledge base, customers. Handles its own conversations but **sees none of the shared support queues**. | | **Agent** | Front-line support | Full conversation handling in every inbox except the Studio Bot and AI Agent queues. Customers read/create/update. No account administration. | | **Viewer** | A read-only visitor — an accountant, a consultant, a stakeholder | Reads analytics, customers and configuration. **No conversation access at all.** | For the exact grants, see the comparison tables in [System permissions](./system-permissions.md#what-the-default-roles-grant) and [Channel permissions](./channel-permissions.md#what-the-default-roles-grant). :::info Default role names follow your language The five names and descriptions above are shown in each agent's own interface language — a Hebrew console shows *בעלים* rather than *Owner*, without anything being renamed in the account. The moment you edit a default role's **name** or **description**, it becomes your text and Teloring stops translating that field. Rename *Agent* to *Support Rep* and every agent sees *Support Rep*, whatever language they use. Roles you create yourself are never translated, for the same reason. ::: :::info An existing account that has never seen this page Accounts created before Roles & Permissions existed are given the same five roles the first time the page is opened, and their existing agents are matched to the closest one — the account's administrator becomes **Owner**, everybody else becomes **Agent**. Nothing is lost and no migration is needed. Review the assignments on the Agents page afterwards. ::: --- ## What is never restricted Some parts of Teloring are available to every signed-in agent, whatever their role. They are not in the permission grid because switching them off would produce a broken workspace rather than a restricted one. | Always available | Why | | --- | --- | | **Dashboard** (home) | The landing page after sign-in. Its content already reflects what the agent may see. | | The **Conversations** menu and its queues | The menu never disappears. What appears *inside* each queue is controlled by [Channel permissions](./channel-permissions.md). | | **Mine** | Conversations assigned to the agent are always reachable, in any inbox. See [Why "Mine" is never filtered](./channel-permissions.md#why-mine-is-never-filtered). | | **Docs** | This documentation site. | | **Their own profile** | Name, photo, language, timezone, their own password and email. | | **Notifications** and the bell | An agent must be able to see what they were alerted about. | | **Team Chat** | Internal agent-to-agent chat. | | **The voice softphone** | Making and receiving calls. Voice *inbox configuration* is still under **My Ring**, and per-agent voice access is still switched on by somebody with agent permissions. | --- ## Where roles are enforced Useful to know when you are testing a role, or explaining to an agent why something disappeared. | Layer | What it does | | --- | --- | | **Sidebar and menus** | Entries the role cannot reach are not rendered. A whole section disappears when the role reaches none of it — no empty *Admin* heading. | | **Buttons and controls** | Create, edit and delete controls are hidden. Some controls — a priority or label picker inside a conversation — are shown greyed out instead, so the agent can still *read* the current value. | | **Lists and counts** | Conversation queues and their sidebar badge numbers only include inboxes the role may see. A badge never says 12 over a list of 3. | | **Search** | Conversation and message search is scoped to the same inboxes as the queue being searched, so search can never surface something a list would hide. | | **Pages** | Opening a restricted page by URL redirects to the Dashboard with *"You do not have permission to do that"*. | | **Every API request** | The final check. Refused with HTTP 403 and the exact missing permission, whether the request came from the workspace, a script, or the public API. | | **Audit log** | `role.created`, `role.updated` and `role.deleted` are recorded, with who did it and what changed. See **Admin → Audit Log**. | ### What an API key can do An account **API key** is a machine credential and does not carry a role. It can reach the operational API — conversations, messages, contacts, customers, CRM records, views, Studio, forms, knowledge base — and it cannot reach agents, teams, roles, billing, settings, inbox configuration or the CRM object designer. That is fixed and not configurable. Manage keys under **Settings → API**, which requires the **Settings → API** permission. --- ## Limitations and what to watch for These are real product limits today, not mistakes on your side. | Item | What actually happens | Do this instead | | --- | --- | --- | | **One role per agent** | An agent cannot hold two roles. There is no combining or stacking. | Duplicate the closest role and adjust it. | | **No role inheritance** | Roles are flat. Editing *Agent* does not affect a role you duplicated from it. | Re-apply the change to each role, or keep fewer roles. | | **Managing roles is powerful** | Anybody with **Roles & permissions → Create** or **Update** can grant themselves anything, because that is what editing a role means. | Give it to as few people as possible — usually only Owners. | | **You can lock yourself out of a page** | Removing a permission from your own role takes effect immediately, including the Roles page itself. | Keep two Owners. Test restrictive roles on a spare agent, not on yourself. | | **No per-role working hours** | A role has no schedule. It cannot grant access only during a shift. | Use [business hours](../settings.md) in Studio, or deactivate the agent. | | **No per-record permissions** | Permissions are per feature and per inbox, never per individual customer, view or report. An agent who can read customers can read all of them. | Separate the data by inbox where it matters. | | **Team ≠ permission** | Being in a [team](../teams.md) does not restrict what an agent can open. Teams affect routing only. | Use channel permissions for visibility. | | **A role with nothing ticked** | Saves fine. Its agents can sign in, see the Dashboard, and reach nothing else. | Only useful for a suspended account. Deactivate the agent instead. | | **Deleting an inbox** | Its per-inbox settings stay stored in each role, harmlessly, and vanish from the editor. | Nothing to do. | --- ## Troubleshooting ### An agent says a menu item disappeared Their role does not grant **Read** on that feature. Open **Admin → Agents, Teams & Roles → Roles & Permissions**, edit their role, and tick **Read** for it. The item reappears on their next page load. ### An agent can open a page but every button is missing **Read** is granted, **Create**, **Update** and **Delete** are not. That is the intended behaviour of a read-only role — the agent can look, not change. ### A queue is empty for one agent and full for another Different roles, or the same role with different inboxes ticked. Open the role's **Channel permissions** tab and check the capability for that queue — `See the waiting line` for **Waiting in line**, `See All Open conversations` for **All Open**, and so on. See [Channel permissions](./channel-permissions.md). ### "Get next in line" says nothing is waiting, but the queue shows conversations `Get Next in Line` is a separate permission from `See the waiting line`, per inbox. A role can watch a queue without being handed work from it. Tick **Get Next in Line** for that inbox. Also check [Teams](../teams.md): an agent can only be handed a conversation with no team, or one from a team they belong to. ### I cannot untick "Read" Because **Create**, **Update** or **Delete** is ticked on that row, and none of them can work without Read. Untick the write actions first and Read is released. See [How the four actions work](./system-permissions.md#how-the-four-actions-work). ### "A role with this name already exists" Names are unique per account and compared ignoring case, so `Agent` and `agent` collide. Pick a different name or edit the existing role. ### "This is the account's last Owner" You are trying to move, deactivate or delete the only agent with the Owner role. Give Owner to somebody else first, then repeat the change. ### I removed my own access to the Roles page Ask an Owner to restore it. Owner always can, because Owner cannot be narrowed. If nobody in the account has Owner — which Teloring's last-Owner protection is designed to prevent — contact Teloring support. ### An agent still has old permissions Permissions refresh on the agent's next request; there is nothing to clear and no need to sign out. If it persists for more than a minute, confirm you saved the role and that the agent actually holds the role you edited — check the **Role** column on the Agents page. --- ## Related guides - [System permissions reference](./system-permissions.md) — every feature and what each action unlocks. - [Channel permissions reference](./channel-permissions.md) — the 18 inbox abilities and the Future inbox rule. - [Example roles and recipes](./examples.md) — setups to copy. - [Agents and AI Agents](../agents.md) — where a role is assigned to a person. - [Teams](../teams.md) — routing, which is a separate concern from permissions. - [Conversations](../../getting-started/conversations.md) — the queues that channel permissions control. - [Account settings](../settings.md) — the settings pages the permission grid refers to.