# Teloring Complete Documentation Generated: 2026-08-20T20:54:44.769Z Canonical documentation: https://docs.teloring.com/docs/ Documentation index: https://docs.teloring.com/llms.txt > This file is generated from every public Docusaurus documentation source during the production build. Do not edit it manually. --- # Teloring User Guides Source: https://docs.teloring.com/docs/ Markdown: https://docs.teloring.com/markdown/docs/index.md Section: Overview Last modified: 2026-08-20T20:49:57.000Z Teloring is an omni-channel customer communication platform and mini CRM. It brings conversations, customer records, agents, AI tools, automation, files, and reporting into one workspace so teams can manage customer communication without switching between channels. These guides are written for daily platform users, team managers, and account admins. They focus on how to use the product. API documentation will come later. ## Who should read this | Role | Start here | Main areas | | --- | --- | --- | | Agents | [Workspace tour](./getting-started/workspace-tour.md) | Conversations, queues, customer panel, quick replies, profile | | Team managers | [The Ring — inboxes](./product/ring/overview.md) | Conversation queues, assignments, CRM, analytics, Studio | | Admins | [First login checklist](./getting-started/first-login.md) | My Ring, [human and AI Agents](./product/agents.md), settings, knowledge base, audit log, billing | ## What you see after login After signing in, most users land in the Teloring workspace. The left sidebar is the main navigation. The top header contains workspace actions such as language switching, theme controls, account indicators, and profile access. The main content area changes based on the selected page. The main sections are: | Section | What it is for | | --- | --- | | Dashboard | A quick overview of open conversations, waiting conversations, resolved conversations, online agents, and recent activity. | | Conversations | The main agent workspace for reading, replying, assigning, labeling, prioritizing, and resolving customer conversations. | | Customers | The CRM area for customer profiles, lifecycle stages, linked contacts, journey history, conversations, calls, documents, and custom objects. | | My Ring | The inbox/channel setup area. This is where admins connect WhatsApp, email, SMS, Telegram, LINE, live chat, voice, TikTok Messenger, and Meta inboxes. | | AI World and Knowledge Base | AI feature configuration and the source material used by AI Copilot and RAG-based answers. | | Forms | The form builder for collecting structured customer data, publishing form links, reviewing submissions, and triggering Studio flows. | | Studio | The visual automation builder for triggers, conditions, replies, HTTP requests, CRM updates, and other workflow actions. | | Quick Replies | Reusable message snippets that agents can insert while replying to customers. | | Analytics | Reports and dashboards for measuring conversations, agents, and operational performance. | | Settings, Agents, Audit Log, Billing | Administration: account configuration, [human and AI team management](./product/agents.md), security review, and usage/credits. | | Roles & Permissions | [Decide what each role may reach](./product/roles/overview.md) across the workspace and inside every inbox. | :::note The exact menu varies by **[role](./product/roles/overview.md)** and by which features your plan enables. Anything your role cannot reach is not shown at all — so two people in the same account can see quite different sidebars. ::: ## Recommended reading order 1. [Workspace tour](./getting-started/workspace-tour.md) - understand the navigation and main screens. 2. [First login checklist](./getting-started/first-login.md) - prepare a new account for real use. 3. [The Ring — inboxes](./product/ring/overview.md) - connect the channels customers will use. 4. [Conversations](./getting-started/conversations.md) - learn the agent workflow. 5. [CRM and Customers](./product/crm.md) - organize customer records and history. 6. [Conversation Attributes](./product/conversation-attributes.md) - record why each conversation happened and how it ended, so you can report on it. 7. [Agents and AI Agents](./product/agents.md) - invite people and configure autonomous conversation profiles. 8. [Forms Builder](./product/forms.md) - collect structured data from customers. 9. [Studio](./product/studio.md) - automate common customer journeys. 10. [Analytics](./product/analytics.md) - build dashboards and reports from your data. --- # Workspace Tour Source: https://docs.teloring.com/docs/getting-started/workspace-tour Markdown: https://docs.teloring.com/markdown/docs/getting-started/workspace-tour.md Section: Getting Started Last modified: 2026-08-20T20:49:57.000Z The Teloring workspace is built around one idea: every customer channel should be handled from one place, while the CRM and automation context stay close to the conversation. ## Main layout The application has three main areas: | Area | What to look for | | --- | --- | | Sidebar | The main navigation: Dashboard, Conversations, Customers, My Ring, AI tools, Studio, Analytics, and admin pages. | | Header | Account-level controls such as language, theme, credit indicators, notifications, and profile access. | | Page content | The active workspace, such as the conversation desk, customer list, Studio canvas, or inbox setup page. | ![Teloring workspace overview](/img/screenshots/getting-started/workspace-overview.png) ## Dashboard The Dashboard gives a quick operational view before an agent opens the conversation desk. You can use it to see: | Card or panel | Meaning | | --- | --- | | Open conversations | Conversations currently open and assigned to you or visible to your role. | | Waiting in line | Conversations waiting for an agent to take them. | | Resolved today | Conversations closed during the current day. | | Agents online | Current online presence from the realtime service. | | Recent conversations | A fast entry point into the latest customer activity. | Clicking a dashboard card opens the relevant conversation queue. ![Teloring dashboard overview](/img/screenshots/getting-started/dashboard-overview.png) ## Sidebar sections The sidebar is grouped by work type. | Sidebar section | Pages | | --- | --- | | Main | Dashboard, Conversations, Customers | | My Ring | Channel and inbox setup | | Tools | AI World, Achievements, Knowledge Base, Files Warehouse, Documents Signature, Studio, Quick Replies | | Analytics | Analytics dashboards and reports | | Admin | Settings, Agents, Audit Log, Billing | The sidebar can be collapsed. Teloring remembers the collapsed state per agent and per account. ## Conversations queues The Conversations menu includes common queues: | Queue | Use it when | | --- | --- | | Mine | You want to continue conversations assigned to you. | | Waiting | You want to take the next unassigned customer conversation. | | Chatbot | You want to review conversations currently handled by a bot flow. | | AI Agent | You want to review conversations owned by an AI agent. | | All Open | You want a wider operational view across open conversations. | | Resolved | You want to search or review completed conversations. | ## Language and direction Teloring supports English and Hebrew. Hebrew pages use right-to-left layout. Each agent can have a default language, and language can also be changed from the workspace header. --- # First Login Checklist Source: https://docs.teloring.com/docs/getting-started/first-login Markdown: https://docs.teloring.com/markdown/docs/getting-started/first-login.md Section: Getting Started Last modified: 2026-08-20T20:49:57.000Z Use this checklist when a new account or new team starts using Teloring. ## 1. Sign in Open the Teloring app URL provided by your account admin and sign in with your email and password. If two-factor authentication is enabled, complete the verification step before entering the workspace. After login, confirm that you can see the correct account name and your own agent profile in the sidebar footer. ## 2. Review your profile Open your profile from the sidebar footer. Check: | Field | Why it matters | | --- | --- | | Name | This is shown in internal views and can appear in customer-facing contexts depending on the channel. | | Email | Used for login and account identification. | | Phone | Used by some notification and verification workflows. | | Language | Controls your default workspace language. | | Personal API token | For advanced users who need API access tied to their own permissions. | ## 3. Confirm your role Your **[role](../product/roles/overview.md)** controls which pages and actions are available. Every account defines its own roles, and yours starts with five: | Role | Typical access | | --- | --- | | **Owner** | Everything, including billing and account settings. | | **Team Leader** | Every conversation and inbox, teams, Studio, knowledge base and analytics — but no billing or agent management. | | **Marketing** | Analytics, Studio, forms and customers. Works its own conversations, not the shared queues. | | **Agent** | Conversations, customers, profile and the daily support tools. | | **Viewer** | Read-only. Analytics and customers, no conversations. | Your role name is shown next to you on **Admin → Agents, Teams & Roles → Agents**. If a page is missing from your sidebar, your role does not include it, or the feature is not enabled for the account. Ask whoever administers your workspace — they can widen the role from **Admin → Agents, Teams & Roles → Roles & Permissions**. ## 4. Connect at least one inbox Whoever holds **My Ring → Create** — normally an Owner — should open [My Ring](../product/ring/overview.md) and connect the first customer channel before agents begin work. Recommended first setup: | Team need | Start with | | --- | --- | | Fast support launch | Live Chat or Email | | WhatsApp-first support | WhatsApp inbox | | Social support | Messenger, Instagram DM, Facebook Page, or Instagram Posts | | Phone support | Voice inbox | | Developer-led integration | API inbox | ## 5. Add agents Admins should open Agents and add the team members who will handle conversations. For each agent, confirm the email, role, active state, and language. ## 6. Prepare common replies Open Quick Replies and create reusable snippets for common answers, such as opening hours, shipping policy, appointment instructions, or escalation text. ## 7. Optional: enable AI and Knowledge Base If your account uses AI Copilot or RAG answers, open AI World and Knowledge Base. Prepare: | Item | Purpose | | --- | --- | | AI feature toggles | Control which AI features are available to agents. | | Knowledge bases | Store approved source material for AI answers. | | Copilot selection | Let agents choose the right knowledge base for a conversation. | ## 8. Optional: create the first Studio flow Open Studio when you are ready to automate part of the customer journey. Start with a small flow, such as: 1. Incoming message trigger. 2. Reply message action. 3. Condition that checks the customer's answer. 4. Assign conversation or end session action. Publish only after testing the flow with a demo conversation. --- # Conversations Source: https://docs.teloring.com/docs/getting-started/conversations Markdown: https://docs.teloring.com/markdown/docs/getting-started/conversations.md Section: Getting Started Last modified: 2026-08-20T20:49:57.000Z Conversations are the main agent workspace. This is where messages from connected inboxes become one organized customer service desk. ## Conversation screen layout The conversation screen has three working areas: | Area | What it contains | | --- | --- | | Left panel | Search, new conversation, get next in line, sorting, filters, bulk actions, and the conversation list. | | Center panel | The selected conversation, messages, email thread view when relevant, and reply composer. | | Right panel | Contact fields, linked customer record, labels, notes/context, and AI Copilot tools. | ![Teloring conversation workspace](/img/screenshots/getting-started/conversation-layout.png) ## Right sidebar The right sidebar keeps the customer context next to the live conversation. Agents can answer faster because they do not need to leave the conversation page to check basic contact details, customer history, previous conversations, or AI support. The right sidebar is split into sections: | Section | What it shows | Common actions | | --- | --- | --- | | Contact Info | The individual person in the conversation, such as name, phone, email, company, status, and custom contact fields. | Edit contact details and save updates directly from the conversation. | | Customers | The CRM customer linked to this conversation. This is usually the company, account, household, or main customer record behind the contact. | View the linked customer, change the customer link, search for an existing customer, or create a new customer from the conversation. | | Previous Conversations | Other conversations connected to the same contact or customer. | Review history before replying, open older conversations, and understand whether this issue is new or a continuation. | | Conversation Attributes | Custom fields your account defined for a conversation — such as reason for contact, outcome, or order number. | Record what this conversation was about and how it ended, then save. Shown only when your account has defined attributes. | | AI Copilot | AI assistance for the current conversation. | Ask questions, use a selected knowledge base, review AI notes, and insert useful AI answers into the reply composer when appropriate. | ![Teloring conversation right sidebar](/img/screenshots/getting-started/conversation-right-sidebar.png) ### Contact Info Contact Info is about the person who sent the message. It is useful when the same customer has several people contacting your team, or when one person contacts you from several channels. Use it to check or update: | Field | Example | | --- | --- | | Name | The person's name as agents should see it. | | Phone | The contact's phone number. | | Email | The contact's email address. | | Company | The organization or business name connected to the person. | | Status | The contact status used by your team. | | Custom fields | Any additional fields your account uses for contacts. | When an agent changes a contact field, the updated information is saved for future conversations with the same contact. ### Customers The Customers section connects the conversation to the CRM. This is important because one customer can have many contacts, many conversations, calls, documents, and custom records. If a customer is already linked, agents can open the customer profile from the right sidebar. If the conversation is not linked yet, agents can search for an existing customer or create a new one from the conversation. Use customer linking when: | Situation | What to do | | --- | --- | | The contact belongs to an existing customer | Link the conversation/contact to that customer. | | The contact is a new business or customer | Create a new customer from the conversation. | | The conversation was linked to the wrong customer | Change the linked customer. | | You need the complete customer history | Open the customer profile. | ### Previous Conversations Previous Conversations helps agents understand the history before replying. It is especially useful when a customer comes back through a different channel, or when a new agent takes over an issue. Use it to answer questions like: | Question | Why it matters | | --- | --- | | Has this customer contacted us before? | Prevents repeated questions and improves continuity. | | Was the last issue resolved? | Helps avoid reopening old problems without context. | | Which channel did they use before? | Helps understand customer preference and history. | | Which agent handled the last case? | Makes follow-up and escalation easier. | ### Conversation Attributes Conversation Attributes are custom fields that belong to **this conversation**, not to the person. Your account designs them once — typically *Reason for contact*, *Outcome*, or *Order number* — and agents fill them in while they work. The difference from Contact Info matters: | | Contact Info | Conversation Attributes | | --- | --- | --- | | Describes | The person | This one conversation | | Next conversation with the same person | Keeps the same values | Starts empty | | Good for | Their phone, email, company, department | Why they wrote today, what you did, which order | Fill the fields in and click **Save**. Values stay with this conversation and follow it into the resolved archive, where they become read-only. Because the answers are structured, they are the fields you report on later — *"what do people contact us about, and how long does each type take?"*. See [Conversation Attributes](../product/conversation-attributes.md) for the full guide, including how to design them and how [Studio](../product/studio.md) can fill them in automatically. :::note The section only appears when your account has defined attributes and your [role](../product/roles/system-permissions.md#workspace) allows it. With **Read** but no **Update**, the fields are visible but locked. ::: ### AI Copilot AI Copilot is designed to support the agent, not replace the agent. Agents can ask Copilot questions about the conversation, use a selected knowledge base, or review AI-generated insights. Depending on enabled AI features, Copilot can help with: | Use case | How it helps | | --- | --- | | Summarizing context | Gives a quick overview of long conversations. | | Answer drafting | Suggests wording agents can use or edit before sending. | | Knowledge base answers | Searches approved knowledge base content and returns an answer based on that source. | | Conversation insights | Shows items such as urgency, labels, churn risk, upsell opportunity, or detected subject when enabled. | | Language help | Helps rewrite or translate replies when account features allow it. | Agents should review AI answers before sending them to customers, especially when the answer includes pricing, legal, billing, medical, technical, or policy-sensitive information. ## Find the right conversation Use the queue links in the sidebar to choose the work list: | Queue | Best for | | --- | --- | | Mine | Conversations assigned to you. | | Waiting | Unassigned conversations waiting for handling. | | Chatbot | Conversations currently handled by Studio bot mode. | | AI Agent | Conversations currently handled by an AI agent. | | On Hold | Conversations parked until a chosen time. See [On Hold](../product/on-hold.md). | | All Open | Open conversations across the account. | | Resolved | Closed conversations and historical review. | Inside a queue, use search, sort, and filters to narrow the list by channel type, inbox name, labels, **assigned agent**, **assigned team**, priority, flag, and time period. The **Assigned agent** filter includes an explicit **Unassigned** chip, and the **Assigned team** filter includes a **No team** chip, so you can isolate work nobody has picked up or routed yet. Both are multi-select. :::note There is no separate "team" queue A conversation assigned to a team but not yet to a person stays in **Waiting**. To see only your team's share of the queue, filter **Waiting** by **Assigned team**. See [Teams](../product/teams.md). ::: ### Get next conversation **Get next** takes the decision out of your hands: Teloring picks the conversation you should handle now, by **priority first**, then **oldest first** among equal priorities. If your account uses [Teams](../product/teams.md), it only offers conversations you are allowed to take — ones with **no team**, or with a team **you belong to**. A conversation belonging to another team is left for that team. When everything waiting belongs to other teams you will see *No conversations waiting in line for your teams*. ## Right-click quick actions In open conversation queues, agents can right-click a conversation in the left list to open quick actions. This is useful when you need to organize work without opening the conversation first. Quick actions can include: | Action | Use it to | | --- | --- | | Mark as read / unread | Control whether the conversation appears as needing attention. | | Mark as resolved | Close the conversation when the work is complete. | | Assign | Assign the conversation to yourself, another agent, an AI agent where available, or send it back in line. | | Assign team | Route the conversation to a whole [team](../product/teams.md), or clear the team. Only shown when the account has teams. | | Priority | Change the priority to low, medium, high, or urgent. | | Assign label | Add or remove conversation labels. | | Pin / unpin | Keep important conversations at the top of the list. | | Flag | Add a colored flag for quick visual follow-up. | | Show customer | Open the linked customer profile, when the conversation is connected to a customer. | Quick actions update the same conversation fields as the controls inside the conversation. For example, changing priority from the right-click menu is the same as changing priority in the conversation top bar. ![Teloring conversation right-click quick actions](/img/screenshots/getting-started/conversation-right-click-menu.png) :::note Right-click actions are available for open conversation lists. Resolved conversation views are used mainly for review and history. ::: ## Handle a conversation A normal agent workflow looks like this: 1. Open a queue. 2. Select a conversation. 3. Review the latest messages and customer context. 4. Assign the conversation if needed. 5. Set priority, flag, or labels when useful. 6. Reply to the customer or add an internal/private note. 7. Use quick replies or AI Copilot when appropriate. 8. Fill in the [Conversation Attributes](../product/conversation-attributes.md) your team uses, such as reason and outcome. 9. Mark the conversation as resolved when the issue is complete — or put it [On Hold](../product/on-hold.md) when you are waiting for a time, a delivery, or a callback. ## Assignment, priority, labels, and flags Use the top bar of the selected conversation to keep work organized. | Control | Use it to | | --- | --- | | Assigned agent | Move ownership to yourself or another agent. | | Assigned team | Route the conversation to a [team](../product/teams.md) instead of one person. A `⚡` marks a team that auto-assigns to an online member. Hidden when the account has no teams. | | Priority | Mark urgency as low, medium, high, or urgent. | | Flag | Add a visual signal for follow-up or special handling. | | Labels | Group conversations by topic, department, campaign, or issue type. | | On Hold | Park the conversation until a chosen time. It leaves your active queues and returns by itself — when the time is up, or the moment the customer replies. See [On Hold](../product/on-hold.md). | | Resolve | Close the conversation when no more action is needed. | Teloring keeps the agent and the team consistent with each other. Assigning an agent who is **not** in the conversation's team clears the team, and moving a conversation to a team its current owner is not in clears the agent. **Send back in line** keeps the team, so the same team keeps first refusal. Full rules: [Teams](../product/teams.md#teams-and-the-agent-field-together). ## Bulk actions When multiple conversations need the same update, select conversations from the list and use the bulk toolbar to assign, label, mark read/unread, or resolve them. :::warning Bulk actions affect every selected conversation. Before applying them, confirm the selected count and filter context. ::: --- # Teloring Glossary Source: https://docs.teloring.com/docs/glossary Markdown: https://docs.teloring.com/markdown/docs/glossary.md Section: Glossary Last modified: 2026-08-20T20:49:57.000Z Use this glossary when a Teloring term is unfamiliar or when another product uses a different name for the same idea. ## Account A business workspace in Teloring. Its agents, inboxes, contacts, customers, conversations, Studio flows, files, reports, and settings are isolated from every other account. **Also known as:** business account, client account, tenant, workspace. ## Agent A person who signs in to Teloring to handle conversations and use the workspace. An agent holds exactly one [Role](#role), which decides what they may reach, plus individual settings, and can belong to one or more [Teams](#team). **Also known as:** human agent, team member, support representative, operator. **Not the same as:** an [AI Agent](#ai-agent). ## AI Agent An autonomous AI profile configured to participate in customer conversations using specific instructions, knowledge, data-collection rules, and human handover behavior. An AI Agent can be a member of a [Team](#team) and is treated as always online for team auto-assignment, though it never counts toward human presence. **Also known as:** virtual agent, AI representative, autonomous agent. **Not the same as:** AI Copilot, which assists a signed-in human agent. ## AI Copilot The in-conversation assistant that helps a human agent understand context, search selected knowledge bases, and prepare responses. **Also known as:** agent assistant, conversation copilot. ## AI Studio The Teloring AI capability that lets a person create a [Studio](#studio) [flow](#flow) by answering questions in plain language instead of drawing it on the canvas. It is switched on per account in [AI World](#ai-world), and its interviewer is [Hermes](#hermes). **Also known as:** AI flow builder, AI automation builder, generate a flow with AI. ## AI World The account control page for enabling or disabling Teloring AI capabilities. **Also known as:** AI settings, AI feature controls. ## Block One step on a Studio flow canvas. A block is a trigger (**WHEN**), action (**THEN**), condition (**IF**), or editor-only note. **Also known as:** node, workflow step, automation step. ## Channel The communication technology used by an inbox, such as WhatsApp, email, voice, SMS, Telegram, or live chat. In everyday Teloring use, *channel* and *inbox* are often used together, but the channel is the type while the inbox is the configured connection. **Also known as:** communication channel, source. ## Contact A person or address that communicates with the business. A contact can carry fields such as name, phone number, email address, company, status, and custom values. **Also known as:** end user, correspondent, lead contact. **Not the same as:** a [Customer](#customer), which can group multiple contacts and related business records. ## Conversation The shared thread or call record where agents handle customer communication from an inbox. A conversation contains messages or call information plus assignment, status, labels, priority, contact, and customer context. **Also known as:** ticket, thread, chat, interaction. ## Conversation attribute A custom field the account defines that belongs to **one [conversation](#conversation)** rather than to the [contact](#contact) or the [customer](#customer) — such as reason for contact, outcome, or order number. The account designs one set of attributes in **Settings → Conversation Attributes**; agents fill values in from the conversation's right sidebar, [Studio](#studio) can set them automatically, and they are reportable in Analytics. A new conversation with the same person always starts with an empty set. **Also known as:** conversation custom field, disposition, wrap-up code, wrap-up field, conversation metadata, ticket field, case field, outcome code. **Not the same as:** a contact or customer field, which describes a person or a business and persists across every conversation; or a conversation label, which is a free-form tag rather than a named field with its own type and allowed values. ## Customer The main CRM relationship record. A customer can represent a company, organization, household, account, or person and can connect multiple contacts, conversations, calls, documents, and custom object records. **Also known as:** CRM customer, organization, account record. ## Files Warehouse The account-wide inventory for files registered by supported Teloring features, including attachments, recordings, signed documents, and Studio voice prompts. **Also known as:** file inventory, storage catalog. ## Flow One Studio automation made from connected blocks. A flow has a draft canvas and, after publishing, a separate live version. **Also known as:** workflow, automation, Studio workflow. ## Form A public, structured data-collection page created with Forms Builder. A submission can feed CRM data and start a Studio flow. **Also known as:** intake form, survey, questionnaire. ## Future inbox A row in the **Channel permissions** tab of a [role](#role) that supplies the default abilities for every [inbox](#inbox) connected from then on — and for any existing inbox in that role you have not configured, which shows an **Inherited** badge. It means connecting a new channel never requires revisiting every role. Changing the Future inbox values also updates every inherited inbox in that role. **Also known as:** default inbox permissions, inbox defaults, inherited permissions. ## Hermes The AI flow builder inside [Studio](#studio). Hermes interviews the user one question at a time, then places a complete draft flow — blocks, settings, and connections — on the canvas. Building the flow ends the conversation; the flow is edited by hand from then on. Requires [AI Studio](#ai-studio) to be enabled. **Also known as:** the AI flow builder, the Studio AI assistant. **Not the same as:** an [AI Agent](#ai-agent), which talks to customers, or [AI Copilot](#ai-copilot), which assists an agent inside a conversation. ## Inbox One configured customer communication connection, such as a particular WhatsApp number, email mailbox, phone number, Telegram bot, or live-chat widget. Conversations arrive through inboxes. **Also known as:** connected channel, communication source. **Teloring navigation:** inboxes are managed in [My Ring](#ring). ## Knowledge Base An account-isolated collection of uploaded files and websites that Teloring processes for grounded AI answers. **Also known as:** KB, RAG knowledge base, private AI library. ## On Hold A top-level [conversation](#conversation) status, next to Open and Resolved, that parks a conversation until a chosen time. A held conversation leaves every active queue and its owner's dashboard counters, keeps its assigned agent, and returns automatically when the deadline passes **or** the moment the customer replies — whichever happens first. Deadlines are calculated in the account's business timezone. **Also known as:** snooze, snoozed, defer, park, pause, remind me later, follow up later, hold until. **Not the same as:** **Resolved** (the conversation is finished) or **Send back in line** (the conversation loses its owner and returns to the waiting queue). **Teloring navigation:** the **On Hold** button in a conversation's top bar, and the **Conversations → On Hold** queue. See [On Hold](./product/on-hold.md). ## Onboarding link The one-time link Teloring issues when a [WhatsApp inbox](./product/ring/whatsapp.md) is created, of the form `https://onboarding.direct/xxxxxxxx`. Opening it authorizes the number with Meta — choosing a business portfolio, creating the [WhatsApp Business account](#whatsapp-business-account-waba), and granting messaging access. Until it is completed the inbox stays **Pending Onboarding** and cannot send or receive. Teloring shows the link in three places: the setup wizard's final step, the WhatsApp list in My Ring, and the inbox's **Onboarding** tab. **Also known as:** Meta onboarding, WhatsApp onboarding, Embedded Signup, onboarding.direct link, activation link. **Not the same as:** the SMS or phone-call **verification code** Teloring uses to prove you control the number, which happens earlier and inside Teloring. **Teloring navigation:** **My Ring → WhatsApp**, or the inbox's **Onboarding** tab. See [Complete WhatsApp onboarding with Meta](./product/ring/whatsapp/onboarding.md). ## Notification A per-agent alert about something that happened in Teloring. Each agent chooses **what** to be told about (a conversation assigned to them, a new customer message, or a [Studio](#studio) alert) and **how** it should reach them (sound, email, browser push, or the [Notification bell](#notification-bell)). Every option is off until the agent turns it on, and one agent's choices never affect another's. **Also known as:** alert, agent notification, personal notification. **Not the same as:** an outbound message to a customer, or an internal note on a conversation. **Teloring navigation:** **My Profile → Notifications**. See [Notifications](./product/notifications.md). ## Notification bell The bell icon in the Teloring top bar. It shows a badge counting the notifications that have arrived since the agent last opened it, and lists the most recent 100. Opening the list marks everything as read but deletes nothing. **Also known as:** bell menu, alert centre, notification centre. ## Push notification A desktop notification delivered by the operating system, shown even when Teloring is in a background tab or another application is in front. It is one of the four notification delivery methods, and must be allowed once per browser and per device. **Also known as:** browser push, web push, desktop notification, Chrome push. **Not the same as:** a mobile app push — Teloring delivers push through the browser. ## Role A named bundle of permissions in a Teloring account. A role decides which features an agent may reach (with **Read**, **Create**, **Update** and **Delete** actions) and what they may do inside each [inbox](#inbox). Every agent holds exactly one role, and editing a role changes access for everyone on it immediately. Every account defines its own roles. Five are created with the account — Owner, Team Leader, Marketing, Agent and Viewer — and all of them except **Owner** can be renamed, re-scoped or deleted. **Also known as:** permission profile, permission group, access level, user role, security profile. **Not the same as:** a [Team](#team), which affects conversation routing and grants no access; or an agent's **Department**, which is a free-text display label. ## Ring Teloring's visual model and navigation area for connected inboxes. **My Ring** is where an account adds and manages communication connections. **Also known as:** inbox hub, channel hub, connected inboxes. **Not the same as:** a phone ring, an agent queue, or a Studio flow. ## Studio Teloring's visual workflow automation builder. Studio runs flows made from triggers, actions, conditions, variables, and connections. **Also known as:** automation builder, workflow builder, flow builder. ## Team An account-wide, named group of agents — for example *Sales* or *Support*. A conversation can be assigned to a team instead of one person. A team can auto-assign to a random online member, and it limits which waiting conversations an agent may pull with **Get next**. Human agents and [AI Agents](#ai-agent) can both be members, and an agent can belong to several teams. **Also known as:** agent group, queue, skill group, routing group. **Not the same as:** an agent's **Department**, which is a free-text display label with no routing behavior; or a [Role](#role) — team membership grants no access rights at all. ## Variable A Studio placeholder written with double curly braces, such as `{{contact.name}}`. At runtime, Studio replaces it with data produced by the trigger, an earlier block, or a saved `var.*` value. **Also known as:** template variable, workflow value, placeholder. ## View A saved, filterable, sortable table over customers or CRM object records. Views read live account data without changing the underlying records. **Also known as:** saved table, CRM view, filtered list. ## WhatsApp Business account (WABA) The account at Meta that holds one or more WhatsApp business phone numbers, created during the [onboarding link](#onboarding-link) flow and owned by your **business portfolio** (Meta's container for a company's business assets, also called a Business Manager account). Meta attaches the display name, messaging limits, and message templates to the WABA — which is why some of those values are read-only in Teloring and can only be changed at Meta. **Also known as:** WABA, WhatsApp Business Account, Meta WhatsApp account. **Not the same as:** the **WhatsApp Business App** (the phone app for small businesses), or a Teloring [inbox](#inbox) (the connection Teloring configures on top of the WABA). --- # The Ring — inboxes overview Source: https://docs.teloring.com/docs/product/ring/overview Markdown: https://docs.teloring.com/markdown/docs/product/ring/overview.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z **The Ring** is where you connect and manage every channel your customers use to reach you. Each channel you connect becomes an **inbox**, and every inbox feeds the same [Conversations](../../getting-started/conversations.md) workspace — so WhatsApp, email, a website chat, a phone call, and an Instagram comment all land in one place, handled the same way. The page is called **My Ring** (in the sidebar and at `/dashboard/ring`). Its tagline says it best: *One Ring, Endless Possibilities.* :::info An **inbox** and a **channel** are the same thing in Teloring — one connected communication line (for example, one WhatsApp number, one mailbox, or one website widget). This guide uses "inbox" for the connected line and "channel type" for the kind of line (WhatsApp, Email, SMS, and so on). ::: ## Key facts | Fact | Meaning | | --- | --- | | One place for every channel | Connect WhatsApp, Email, SMS, Messenger, Facebook, Instagram, Telegram, LINE, Live Chat, Voice, TikTok, and a developer API — all from one page. | | One channel type, many inboxes | You can connect several inboxes of the same type (for example, two WhatsApp numbers or three mailboxes). Each is its own inbox with its own name. | | Everything routes to Conversations | Every inbound message, comment, or call creates or updates a conversation. Agents never need to leave Teloring to reply. | | Permission-managed | Adding, configuring and removing inboxes need **My Ring → Create / Update / Delete**. Working *inside* an inbox is a separate set of per-inbox permissions, so a front-line agent normally answers in every inbox while having no My Ring access at all. See [Roles and Permissions](../roles/overview.md). | | Account-isolated | An inbox belongs to one account (one business). It is never visible to another account. | | Safe to remove | Deleting an inbox stops new messages on that line but **keeps** all existing conversations and history. | ## The supported inbox types Each channel type has its own guide page. Click through for the connect steps, screens, and settings specific to that channel. | Inbox | What it is for | Guide | | --- | --- | --- | | WhatsApp | Support and sales on a WhatsApp Business number. | [WhatsApp](./whatsapp.md) · [Meta onboarding](./whatsapp/onboarding.md) | | Email | A shared team mailbox (Teloring-managed, Microsoft 365, Gmail, or any IMAP/SMTP address). | [Email](./email.md) | | SMS | Two-way text-message conversations. | [SMS](./sms.md) | | Messenger | Private messages sent to your Facebook Page. | [Messenger](./messenger.md) | | Facebook Page | Comments and activity on your Facebook Page posts. | [Facebook Page](./facebook-page.md) | | Instagram DM | Direct messages from your Instagram account. | [Instagram DM](./instagram-dm.md) | | Instagram Posts | Comments on your Instagram posts. | [Instagram Posts](./instagram-posts.md) | | Telegram | Conversations through a Telegram bot. | [Telegram](./telegram.md) | | LINE | Conversations through a LINE Official Account. | [LINE](./line.md) | | Live Chat | A chat widget you embed on your website. | [Live Chat](./live-chat.md) | | Voice | A phone number with an in-browser softphone for calls. | [Voice](./voice.md) | | TikTok Messenger | Direct messages from TikTok. | [TikTok Messenger](./tiktok.md) | | API | A developer inbox for pushing messages in from any custom system. | [API](./api.md) | ## The My Ring page Open **My Ring** from the sidebar. Instead of a plain list, Teloring draws your channels as a **ring** — a circle divided into one colored arc per channel type, with the channel's icon on each arc and the Teloring mark in the center. ![The My Ring page](pathname:///img/screenshots/product/ring/overview/my-ring.png) | Element | What it tells you | | --- | --- | | A colored arc + icon | A channel type shown in its brand color means at least one inbox of that type is connected. | | A grey arc + faded icon | That channel type has no inbox connected yet — it is available to add. | | Hover tooltip | Hovering an arc or icon shows the channel name and how many inboxes you have connected (for example, *"You have 2 inboxes connected"* or *"No inboxes connected yet"*). | | Center mark | The Teloring ring logo and the *One Ring — Endless Possibilities* catchphrase. | Click any arc or icon to open that channel's **modal**. ### The channel modal The channel modal lists every inbox you already have of that type and lets you add another. ![A channel modal listing connected inboxes](pathname:///img/screenshots/product/ring/overview/channel-modal.png) | Item | Meaning | | --- | --- | | Inbox rows | Each connected inbox of this type, with its **name**, its **ID**, and the date it was created. | | Status badge | For channels that report a connection state (such as WhatsApp), a badge shows whether the inbox is Active, Pending, Receive Only, and so on — see [Inbox statuses](#inbox-statuses). | | Edit (pencil) | Opens that inbox's settings page. | | Add button | **Add to your ring** (when none are connected) or **Add another channel** (when one or more already exist) — starts the setup flow for this channel type. | ## Connect an inbox The exact steps depend on the channel — some need a provider login, a phone number, or a token — but the shape is always the same: 1. Open **My Ring**. 2. Click the channel type you want (its arc or icon). 3. In the modal, click **Add**. 4. Follow the channel's setup flow (name the inbox and enter or authorize its connection details). 5. Complete any provider-side steps (a Facebook or Microsoft login, a WhatsApp number verification, pasting a webhook URL, and so on). 6. Confirm the inbox appears connected on the Ring. 7. Send a **test message** to the new line and check that a conversation is created in [Conversations](../../getting-started/conversations.md). :::note Setup differs by channel. WhatsApp runs a step-by-step verification wizard, Meta and email OAuth options open a provider login, Telegram and LINE ask for a bot token, Live Chat generates an embed snippet, Voice assigns a phone number, and API generates an endpoint. Each guide page walks through its own flow. ::: ## What every inbox has in common However different the channels are, every inbox shares the same core: | Property | Detail | | --- | --- | | Name | A label you choose (for example, *WhatsApp Support* or *Sales Mailbox*). Agents filter and identify conversations by it, so make it clear. You can rename an inbox any time from its edit page. | | Active state | Whether the inbox is live. Some channels (like WhatsApp) set this automatically once the provider approves the connection. | | Inbox ID | A short sequential number (1, 2, 3, …) unique within your account. It appears in the modal and in the edit-page URL. | | Settings | Channel-specific options shown as tabs on the edit page (for example, WhatsApp Profile and Templates, or the Live Chat Appearance tab). | | Danger Zone | Every inbox edit page ends with a **Danger Zone** to delete the inbox. | ### The inbox edit page Click the **pencil** on an inbox (or use its row in the modal) to open its edit page at `/dashboard/ring/{id}/edit`. The page shows tabs tailored to that channel type. Most channels open on their main settings; the tabs are described on each channel's guide page. ### Inbox statuses Simple channels are either connected or not. Channels that depend on an outside provider report a more detailed status, shown as a badge in the channel modal. WhatsApp uses the full set: | Status | Meaning | | --- | --- | | **Pending Onboarding** | The inbox exists in Teloring, but the provider setup (for example, Meta onboarding) is not finished. Not yet sending or receiving. | | **Pending Approval** | Setup is done; waiting for the provider to approve the line. | | **Receive Only** | The inbox can receive messages but cannot send yet. | | **Active** | Fully live — sending and receiving. | | **Error** | Something went wrong with the connection. Contact support. | | **Deleted** | The provider account for this line was removed. | ### Deleting an inbox (Danger Zone) Every edit page ends with a **Danger Zone**. Deleting is deliberately hard to do by accident: 1. Click **Delete this channel**. 2. Confirm the first warning. 3. Type the exact inbox **name** to confirm. If it doesn't match, nothing happens. :::warning Deleting an inbox is permanent and cannot be undone. You will no longer send or receive messages on that line. **Existing conversations stay in the system** — they are not deleted — but the inbox is removed for good. Deleting needs **My Ring → Delete**. ::: ## After an inbox is connected Once an inbox is live, new customer activity flows straight into the product: - **Conversations are created automatically.** An inbound message, comment, or call finds or creates the contact, then opens a new conversation or reuses the customer's existing open one. Media is saved into Teloring. See [Conversations](../../getting-started/conversations.md). - **Agents work every channel the same way.** Reply, assign, label, prioritize, resolve, and link the conversation to a [CRM customer](../crm.md) — regardless of which channel it came from. - **Filter by inbox.** In any conversation queue, agents can filter by channel type and by inbox name, so a team can focus on just one line. - **Automations react to inbox events.** A [Studio](../studio.md) flow can trigger on an incoming message to auto-reply, run a bot, assign the conversation, or update customer fields. - **AI assists on every inbox.** AI Copilot (and, where enabled, an AI Agent) runs on incoming messages to summarize, suggest replies, and answer from your knowledge base. ## Admin tips | Tip | Why it helps | | --- | --- | | Use clear inbox names | Agents filter conversations by inbox name and instantly see where a message came from. | | Connect one channel at a time | It is easier to verify routing and test replies before adding the next line. | | Always send a test message | Every new inbox should be proven with a real inbound message before agents rely on it. | | Keep provider logins with few people | Sensitive tokens and provider accounts (Meta, Microsoft, WhatsApp) should sit with the small group holding **My Ring → Update**. | | Add multiple inboxes per type when it fits | Separate numbers or mailboxes (Sales vs Support) keep queues clean and reporting meaningful. | --- # Complete WhatsApp onboarding with Meta Source: https://docs.teloring.com/docs/product/ring/whatsapp/onboarding Markdown: https://docs.teloring.com/markdown/docs/product/ring/whatsapp/onboarding.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z Creating a WhatsApp inbox in Teloring does **two** things: it reserves your phone number, and it hands you a one-time **onboarding link**. The link is where you connect that number to Meta — the company behind WhatsApp — and it is the step people most often stop halfway through. Until the link is completed, the inbox exists in Teloring but **cannot send or receive anything**. It shows as **Pending Onboarding**, and Teloring keeps offering you the link until it's done. The whole process takes about **5 to 10 minutes** and needs no technical knowledge. This page walks through every screen you will see. :::info Why Meta is involved at all WhatsApp is Meta's platform, and only Meta can authorize a business number to send messages through it. Teloring cannot do this on your behalf — Meta requires the business owner to approve the connection while signed in to their own Facebook account. That approval is exactly what the onboarding link collects. ::: ## Where to find your onboarding link The same link is available in three places, so you never have to hunt for it: | Where | When you see it | | --- | --- | | **The setup wizard, step 4** | Right after you create the inbox — the "WhatsApp Inbox Created!" screen shows the link and an **Open Meta Onboarding ↗** button. | | **My Ring → WhatsApp** | Click the WhatsApp icon in your Ring. Every WhatsApp inbox is listed; a pending one carries a ⚠️ notice with the **Open Meta Onboarding ↗** button. | | **The inbox edit page → Onboarding tab** | Open the inbox (pencil icon) and go to the **Onboarding** tab. The button sits there until onboarding is complete. | The link looks like `https://onboarding.direct/xxxxxxxx`. It is **specific to your number** — do not reuse a link from another inbox, and treat it as private. :::tip You can send the link to whoever administers your company's Facebook and business accounts — they don't need a Teloring login to open it. They do need to be signed in to the correct Facebook account. ::: ## Before you start | You need | Why | | --- | --- | | Inbox permission in Teloring | Reaching the link needs **My Ring → Read**; the edit page needs **My Ring → Update**. See [Roles and Permissions](../../roles/overview.md). | | An existing personal Facebook account | Meta requires it to authorize the connection. A **brand-new** Facebook account will not be approved for Business Manager — use an established one. | | Your business details | Legal or trading business name, website, and country. | | Pop-ups allowed in your browser | Meta's flow opens in a pop-up window. If nothing happens when you click, a pop-up blocker is the usual cause. | :::warning Finish it in one sitting Use a desktop browser and complete all the steps in a single session. Closing the pop-up mid-flow means starting the link again from the beginning. Nothing breaks — but nothing is saved either. ::: ## Step 1 — Open the link and start Opening the link lands you on the onboarding page for your number. ![The WhatsApp onboarding welcome page with the Click to start button](pathname:///img/screenshots/product/ring/whatsapp/onboarding/welcome.png) Click **Click to start**. Meta's sign-in window opens on top of the page. Leave this page open in the background. It waits for Meta to report back, and it is where you will see the final confirmation in [Step 7](#step-7--wait-for-the-confirmation-in-teloring). ## Step 2 — Continue with your Facebook account Meta asks whether to continue as the account you are currently signed in to. ![Facebook Login for Business asking to continue as the signed-in account](pathname:///img/screenshots/product/ring/whatsapp/onboarding/meta-start.png) Click **Continue as \[your name\]**. :::caution Check the name first This is the moment to make sure you are on the right Facebook account — the one that owns (or should own) your company's business assets. If the name shown is wrong, click **Log into another account** before continuing. Connecting the wrong account is the most common mistake here, and undoing it later means going through Meta Business Manager. ::: ## Step 3 — Confirm the connection Meta explains what the process does and lists what you'll be able to do once connected. ![Meta's Seamlessly connect your account screen with the Continue button](pathname:///img/screenshots/product/ring/whatsapp/onboarding/meta-first-connection.png) Read the terms at the bottom — the Marketing Messages API for WhatsApp Terms, the Meta Business Tools Terms, the Meta Hosting Terms for Cloud API, and the Meta Terms for WhatsApp Business — then click **Continue**. ## Step 4 — Choose or create your business portfolio A **business portfolio** (Meta also calls it a Business Manager account) is the container that holds your company's business assets at Meta. ![Meta's Fill in your business information screen with the Business portfolio dropdown](pathname:///img/screenshots/product/ring/whatsapp/onboarding/meta-business-select.png) | Field | What to do | | --- | --- | | **Business portfolio** | Pick your existing portfolio from the dropdown. If your business has none, choose the option to create one — Meta builds it here. | | **Business name** | Your legal or trading business name. | | **Business website or profile page** | Your website, or your Facebook page if you have no site. | | **Country** | Where the business is registered. | | **Turn on insights for your business** | Optional Meta analytics. Leave it as you prefer — it does not affect your Teloring inbox. | Click **Next**. :::note Selecting an existing portfolio is always preferable to creating a second one. Businesses that accidentally create a duplicate portfolio end up with WhatsApp assets split across two places, which makes later verification harder. ::: ## Step 5 — Create the WhatsApp Business account Now you create the WhatsApp Business account (**WABA**) that will hold your number. ![Meta's Create or select your WhatsApp Business account screen](pathname:///img/screenshots/product/ring/whatsapp/onboarding/meta-new-waba.png) | Field | What to do | | --- | --- | | **Choose a WhatsApp Business account** | Select **Create a WhatsApp Business account** from the dropdown — this is the normal choice. Pick an existing account only if your business already has a WABA you intend to add this number to. | | **WhatsApp Business account name** | An internal name for the account. Your customers do not see it. | | **Timezone** | Your business timezone — for example, `(GMT+03:00) Asia/Jerusalem`. Meta uses it for messaging metrics and daily limits, so set it correctly. | Click **Next**. ## Step 6 — Review and confirm access Meta summarizes the permissions it is about to grant, so your number can actually send and receive through Teloring. ![Meta's Review access request screen with the Confirm button](pathname:///img/screenshots/product/ring/whatsapp/onboarding/meta-confirm.png) The list covers managing your business, managing your WhatsApp accounts, accessing conversations in WhatsApp, and logging message events back to Meta. All four are required — without them, messages cannot reach your inbox. Click **Confirm**. Meta then confirms you're connected: ![Meta's You're now ready to chat with people on WhatsApp screen with the Finish button](pathname:///img/screenshots/product/ring/whatsapp/onboarding/meta-final.png) This screen also tells you your starting messaging capacity: **at least 2,000 business-initiated conversations** in a rolling 24-hour period once display-name review is done, and **unlimited customer-initiated conversations**. Meta reviews your business against its Commerce Policy and only contacts you (within about 24 hours) if there is a problem. Click **Finish** and the Meta window closes. ## Step 7 — Wait for the confirmation in Teloring Return to the onboarding page you left open. It finishes on its own — no action needed — and confirms the number is connected. ![The onboarding page showing the success confirmation](pathname:///img/screenshots/product/ring/whatsapp/onboarding/onboarding-success.png) Once you see this confirmation, your side of the work is done. You can close the page. ## What happens next Meta and the WhatsApp platform now finish provisioning the number in the background. :::info Allow up to one hour The number is usually usable within minutes, but it can take **up to one hour** to become fully operational. This is automatic — nothing is stuck and nothing is waiting on you. **There is no need to open a support ticket during that hour.** If the inbox is still not Active after an hour, then contact support. ::: While this settles, the inbox status in Teloring moves along on its own: | Status | Meaning | | --- | --- | | **Pending Onboarding** | The link has not been completed. Go back to [Step 1](#step-1--open-the-link-and-start). | | **Pending Approval** | Onboarding is done; Meta is still approving the number. | | **Receive Only** | Incoming messages arrive; sending is not enabled yet. | | **Active** | Fully live — sending and receiving. | You do not need to refresh or re-run anything. When the status reaches **Active**, the **Profile** and **Templates** tabs unlock on the inbox edit page and agents can message customers. See [WhatsApp](../whatsapp.md) for what to configure next, and [Conversations](../../../getting-started/conversations.md) for day-to-day handling. :::note Your first outbound message still needs a template Even on an Active inbox, you can only send free-form messages inside the 24-hour window that opens when a customer messages you. To start a conversation yourself, you need an approved **template** — see [the Templates tab](../whatsapp.md#templates-tab). ::: ## Troubleshooting | Symptom | What to do | | --- | --- | | **Clicking "Click to start" does nothing** | A pop-up blocker is stopping Meta's window. Allow pop-ups for the onboarding page and click again. | | **The wrong Facebook account is shown** | Click **Log into another account** on the "Continue as" screen before continuing. | | **"New accounts won't be approved for Business Manager"** | The Facebook account is too new. Use an established personal Facebook account belonging to someone at the business. | | **You closed the window mid-flow** | Reopen the same onboarding link from any of [the three places](#where-to-find-your-onboarding-link) and start again. Partial progress is not saved, and restarting is safe. | | **The Teloring page never shows the success box** | Make sure you clicked **Finish** on Meta's last screen. If you did, reopen the link — a completed connection is recognized immediately. | | **Still "Pending Onboarding" after finishing** | Give it up to an hour, then reopen the inbox. If it hasn't changed after that, contact support with your inbox name and number. | | **You can't find the link** | It is in all three places listed [above](#where-to-find-your-onboarding-link). If none of them shows it, the inbox may already be onboarded — check its status badge. | ## Related - [WhatsApp](../whatsapp.md) — creating the inbox, business profile, templates, and channel limits - [The Ring — Inboxes](../overview.md) — how inboxes work across channels - [Roles and Permissions](../../roles/overview.md) — who may create and configure an inbox --- # WhatsApp Source: https://docs.teloring.com/docs/product/ring/whatsapp Markdown: https://docs.teloring.com/markdown/docs/product/ring/whatsapp.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **WhatsApp** inbox connects a WhatsApp Business number to Teloring. Every message a customer sends to that number becomes a conversation in the shared inbox, and agents reply from the same place they handle every other channel. WhatsApp also supports rich features unique to the channel: a managed business profile, pre-approved message **templates** for reaching customers outside the 24-hour window, media, and delivery/read receipts. :::info WhatsApp Business runs on Meta's official platform. Connecting an inbox means verifying a phone number and completing Meta's onboarding — Teloring guides you through both. You do not need any technical setup or code. ::: ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Adding or verifying a number needs **My Ring → Create**; configuring the inbox needs **My Ring → Update**. See [Roles and Permissions](../roles/overview.md). | | A phone number | Either a number you own (that is **not** already active on the WhatsApp or WhatsApp Business app), an existing WhatsApp Business App account, or a number already running on the WhatsApp Business API. | | Access to that number | To receive a verification code by SMS or phone call (for the "bring your own number" path). | | A business name and display name | The display name is what customers see on WhatsApp. | | Meta approval | After you create the inbox, Meta must complete onboarding and approve the number before it can send. | ## Connect a WhatsApp inbox Open **My Ring**, click the **WhatsApp** icon, and choose **Add**. A four-step wizard opens. ### Step 1 — Name and number type ![WhatsApp setup — step 1](pathname:///img/screenshots/product/ring/whatsapp/wizard-step1.png) | Field | What to enter | | --- | --- | | **Channel Name** | The internal name for this inbox (for example, *WhatsApp Support*). Agents see it in Conversations. | | **Number type** | Choose one of the three cards below. | | Number type | Use when | | --- | --- | | 📱 **Bring Your Own Number** | You want to verify a phone number you own and use it as your WhatsApp business line. | | 💼 **WhatsApp Business App** | You already have a WhatsApp Business App account and will connect it during Meta onboarding. | | 🔗 **Connect existing account** | The number is already connected to the WhatsApp API — you have its sender number and API key. | Click **Next →**. *Bring Your Own Number* goes to Step 2; *WhatsApp Business App* skips straight to Step 3; *Connect existing account* goes to its own one-step screen ([below](#connect-an-account-already-on-the-whatsapp-api)). ### Step 2 — Verify your number (Bring Your Own Number) You'll see any numbers you've already verified. Pick one, or click **+ Add New Number** to verify a new one. ![WhatsApp setup — verify number](pathname:///img/screenshots/product/ring/whatsapp/wizard-verify.png) The verification sub-flow asks for: | Field | Detail | | --- | --- | | **Phone Number** | Enter with the country code and no spaces or dashes (for example, `972501234567`). | | **Verification Method** | 📩 **SMS** or 📞 **Phone Call**. | | **Code Language** | The language of the code message — English, Hebrew, Arabic, Russian, Spanish, Chinese, Hindi, Thai, or French. | Click **Send Code**, then type the **6-digit code** you receive into the boxes and click **Verify**. If it doesn't arrive, use **Resend SMS** or **Resend via Call**. :::note Meta allows up to **2 verification attempts per number**. Make sure you can receive the code before sending it. ::: ### Step 3 — Business details | Field | What to enter | | --- | --- | | **Business Name** | Your company's legal or business name. | | **Display Name** | The name customers see on WhatsApp (for example, *My Company Support*). | Click **Create WhatsApp Inbox**. ### Step 4 — Complete Meta onboarding The inbox is created but not yet live. Click **Open Meta Onboarding ↗** to finish setup with Meta (or copy the link and open it later). When Meta approves the number, the inbox becomes **Active** and can send and receive. ![WhatsApp setup — inbox created](pathname:///img/screenshots/product/ring/whatsapp/wizard-done.png) :::tip This is the step people get stuck on Onboarding happens on Meta's side, in a pop-up, across six screens. **[Complete WhatsApp onboarding with Meta](whatsapp/onboarding.md)** walks through every one of them with screenshots, and explains what happens in the hour after you finish. ::: ### Connect an account already on the WhatsApp API If the number is already live on the WhatsApp Business API — it was set up before you moved to Teloring, or it runs through another system today — there is nothing to verify and no Meta onboarding to complete. Pick **🔗 Connect existing account** in Step 1 and fill in the two details your WhatsApp provider gave you: | Field | What to enter | | --- | --- | | **Sender number ("From")** | The number messages are sent from, with the country code and no spaces or dashes (for example, `972501234567`). | | **API key** | The API key issued for that number. It is stored on our servers, never shown again, and never sent to your browser. | Click **Connect Inbox**. Teloring checks the pair against the provider, points the provider's incoming-message webhook at your account, and the inbox goes live as **Active** straight away — messages, templates and the business profile all work immediately. :::caution The number's incoming messages move to Teloring Setting the webhook replaces whatever address the provider was posting to before. If another system is still handling this number, it stops receiving from the moment you connect. Connect the inbox when you are ready to switch over. ::: If the credentials are refused, check the number for typos (digits only, with the country code) and confirm the API key belongs to that exact sender number. A number that is already connected to another inbox is rejected — one number can have only one live webhook. ## Inbox status A WhatsApp inbox moves through these states, shown as a badge in the channel modal: | Status | Meaning | | --- | --- | | **Pending Onboarding** | Created in Teloring; Meta onboarding not finished yet. Not sending or receiving. | | **Pending Approval** | Onboarding done; waiting for Meta to approve the number. | | **Receive Only** | Can receive messages but cannot send yet. | | **Active** | Fully live — sending and receiving. | | **Error** | Something went wrong. Contact support. | | **Deleted** | The WhatsApp account for this number was removed. | While the inbox is pending, its edit page shows an **Onboarding** tab with the **Open Meta Onboarding ↗** button so you can finish setup at any time. See [Complete WhatsApp onboarding with Meta](whatsapp/onboarding.md) for the full walkthrough. Once onboarding is finished, allow **up to one hour** for the number to become fully operational. That wait is automatic — no support ticket is needed unless the inbox is still not Active after an hour. ## The WhatsApp edit page Open the inbox from My Ring (the pencil icon) to reach its edit page. It has four tabs. The **Profile** and **Templates** tabs unlock once the inbox is Active (or Receive Only); before that, you'll land on **Onboarding**. ### Profile tab Manage the business profile customers see on WhatsApp. ![WhatsApp edit — Profile tab](pathname:///img/screenshots/product/ring/whatsapp/edit-profile.png) | Field | Notes | | --- | --- | | **Profile picture** | Upload a JPEG or PNG, up to 5 MB. Use a square image. | | **About** | A short line visible to your contacts (up to 139 characters). Cannot be left empty. | | **Address** | Up to 256 characters. | | **Email** | A contact email for the business. | | **Website** | Must start with `http://` or `https://`. | | **Business Type** | One of Meta's categories (Automotive, Beauty, Education, Finance, Medical, Retail, Restaurant, and so on). | | **Description** | A longer description, up to 256 characters. | | **Display Name** | Read-only. It can only be changed in Meta Business Manager. | | **Daily Limit** | Read-only. Meta's messaging limit for the number. | A stats bar shows conversations this month, the daily limit, and the number's **verification** status (Verified, Not Verified, Under Review, and so on). ### Templates tab WhatsApp **message templates** are pre-written message formats that Meta reviews and approves. You need a template to message a customer **outside** the 24-hour window (see [Capabilities](#capabilities-and-limits)). ![WhatsApp edit — Templates](pathname:///img/screenshots/product/ring/whatsapp/edit-templates.png) The list shows each template with a status pill (**Approved / Pending / Rejected**), a category (Utility / Marketing / Authentication), a language, and its content. You can search, filter by status, **duplicate** a template, or **delete** one. :::warning A template cannot be edited after it is submitted, and a deleted template's name cannot be reused for **30 days**. ::: **Create a template** with the three-step wizard (Setup → Content → Review), which shows a live WhatsApp preview as you build: | Step | What you set | | --- | --- | | **Setup** | Language; template type (**Regular**, **Authentication**, or **Document signature**); and a template name (lowercase English letters, numbers, and underscores; at least 5 characters; unique). | | **Content** | For a Regular template: the header type (text, or text with an image / video / document), the **body** (up to 1024 characters, with variables `{{1}}`–`{{10}}`), an optional **footer** (up to 60 characters, no emoji), and up to 10 **buttons** (quick replies, a website link, a call button, or a coupon code). | | **Review** | A summary, then **Submit for review**. Meta reviews the template before it can be used. | :::note Templates are **created** here but **sent** from inside a conversation. Sending a template uses account credits based on its category; the charge is refunded automatically if the send fails. ::: ### Inbox Settings tab | Field | Notes | | --- | --- | | **Channel Name** | Editable — rename the inbox. | | **Channel Type** | Read-only (WhatsApp). | | **Phone Number** | Read-only — the connected number. | | **Status** | Read-only — the current status label. | An active inbox also offers **🔄 Re-register webhook**. It tells your WhatsApp provider to send incoming messages to Teloring again — use it if the inbox suddenly stopped receiving because another tool pointed the number somewhere else. It is safe to click at any time and changes nothing else about the inbox. #### Deleting a WhatsApp inbox The **Danger Zone** at the bottom of this tab deletes the inbox. It needs **My Ring → Delete** and asks twice: a warning dialog, then typing the inbox name exactly. :::danger This also deletes the WhatsApp account for the number Deleting the inbox tells the provider to delete the WhatsApp account behind the number — that is the only way to release a number once it is onboarded on the WhatsApp API. The number stops sending and receiving, and using it again means going through onboarding from scratch. Existing conversations stay in Teloring; only the inbox and the WhatsApp account go away. ::: ### Onboarding tab Shows whether Meta onboarding is complete. While pending, it offers the **Open Meta Onboarding ↗** button and a **Read the docs** link to the walkthrough; once done, it confirms the inbox is active and ready. See [Complete WhatsApp onboarding with Meta](whatsapp/onboarding.md). ## Capabilities and limits | Capability | Detail | | --- | --- | | Send text | Free-form text with WhatsApp formatting (`*bold*`, `_italic_`, `~strikethrough~`) and line breaks. | | Send media | Images, video, audio, and documents, with an optional caption. | | Receive | Text, images, audio, video, voice notes, documents, location (shown as a map link), contacts, reactions, and stickers. Incoming media is saved into Teloring (up to 25 MB). | | Delivery & read receipts | Outgoing messages show sent, delivered, and read status. | | Reply to a message | Both text and media can quote a specific earlier message. | ### The 24-hour window (session vs template messages) WhatsApp only allows free-form replies within a **24-hour customer-care window** that reopens each time the customer messages you. | Message type | When it works | | --- | --- | | **Session message** (free-form text or media) | Only within 24 hours of the customer's last message. | | **Template message** | Any time — this is how you reach a customer after the 24-hour window has closed, or start a conversation. Templates must be pre-approved by Meta. | Teloring shows the remaining session time on the conversation so agents know when a template is required. ### Other limits - The **display name** can only be changed in Meta Business Manager, not in Teloring. - Template names must be unique, cannot be edited after submission, and a deleted name is reserved for 30 days. - Profile editing and template management require the inbox to be **Active** or **Receive Only**. - Profile pictures must be JPEG or PNG, square, and up to 5 MB. ## How WhatsApp messages become conversations When a customer messages your number: 1. Teloring matches the contact by phone number, or creates a new contact (and a customer record) if it's the first time. 2. It reuses the customer's existing open conversation on this inbox, or opens a new one. 3. The message — and any media — is stored, and the conversation updates with a preview and unread count. 4. Real-time updates, [Studio](../studio.md) automations, and AI Copilot all fire, so the conversation is ready for an agent instantly. From there, agents reply, assign, label, prioritize, resolve, and link the conversation to a [CRM customer](../crm.md) — see [Conversations](../../getting-started/conversations.md). --- # Email Source: https://docs.teloring.com/docs/product/ring/email Markdown: https://docs.teloring.com/markdown/docs/product/ring/email.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Email** inbox turns an email address into a **shared team inbox**. Incoming mail is threaded into conversations, so agents reply from Teloring instead of a personal mail client, and replies go back out from the same address and stay attached to the same conversation. Rich HTML, attachments, CC/BCC, reply/reply-all/forward, and signatures all work as you'd expect from a full email client. You can connect email in four ways. They all share the same conversation view, composer, and threading — only *how mail is sent and received* differs. ## Choose a connection type Open **My Ring**, click the **Email** icon, choose **Add**, and pick a connection type. ![Email — choose a connection type](pathname:///img/screenshots/product/ring/email/connection-picker.png) | Type | What it is | Setup effort | Best for | | --- | --- | --- | --- | | **Teloring Email** ⭐ *Recommended* | A mailbox fully managed by Teloring — no mail server needed. | Lowest | Teams that want the fastest start, or a branded address on their own domain. | | **Microsoft Outlook** | Connect an Outlook / Microsoft 365 mailbox by signing in with Microsoft. | Low (one sign-in) | Microsoft 365 / Outlook users. | | **Gmail** | Connect a Gmail or Google Workspace mailbox with an App Password. | Medium | Gmail / Google Workspace users. | | **IMAP / SMTP** | Connect any provider using standard mail-server credentials. | Highest (manual) | Any other provider (Yahoo, a hosting mailbox, a custom server). | ### Conversations vs. sending only Every email inbox has a **purpose**, chosen right after the connection type: | Purpose | Behavior | | --- | --- | | **Conversations** | Receives and replies to customer email as conversations. This is the default. | | **Sending only** | Used for automated email, campaigns, and [Studio](../studio.md) flows. **No conversations are created** — inbound mail is ignored. | :::note Once a "Conversations" inbox has real conversations, its purpose is locked and cannot be switched to "Sending only". ::: ## Connect flow by type ### Teloring Email (managed) The recommended option has three modes: | Mode | What you get | DNS needed? | | --- | --- | --- | | **Zero Setup** | An address like `support@yourname.teloring.com`. Works instantly. | No | | **Email Forwarding** | Keep your current provider and forward incoming mail to a private Teloring address. | No | | **Bring Your Own Domain** | Send and receive on your own subdomain (for example, `support.yourcompany.com`) with your branding. | Yes | - **Zero Setup** — pick a prefix (like `support`) and a subdomain (`yourname`), and Teloring checks availability live (✅ Available / ❌ Not available). Add a display name and create the inbox. It's active immediately. - **Email Forwarding** — after you create the inbox, Teloring generates a private forwarding address. Add a forwarding rule at your current provider that sends mail to it. (The optional "original address" field is just a note for your agents.) - **Bring Your Own Domain (BYOD)** — enter a **subdomain** (root domains are not allowed) and a display name. Teloring shows two DNS records to add — a **DKIM** record (authorizes Teloring to send signed mail for your domain) and a **Return-Path** record (for bounce tracking) — plus a private address to forward inbound mail to. Add the records, then click **Verify DNS now**. The inbox becomes active once verification passes. ![Teloring Email — mode picker](pathname:///img/screenshots/product/ring/email/teloring-modes.png) ### Microsoft Outlook (sign-in) 1. Name the inbox and click **Continue with Microsoft**. 2. A Microsoft sign-in window opens. Sign in and review the permissions Teloring requests (read and send mail on your behalf). 3. Accept. The window closes and the inbox is created — no server settings needed. ![Microsoft consent popup](pathname:///img/screenshots/product/ring/email/microsoft-consent.png) If the connection ever expires, the inbox's edit page shows a **Re-authorize** button to sign in again. ### Gmail (App Password) Gmail connects with a Google **App Password** (not your normal Gmail password). :::warning Google requires **2-Step Verification** to be **on** before you can create an App Password. The setup screen links you straight to Google's 2-Step Verification and App Passwords pages. ::: 1. Turn on 2-Step Verification in your Google account. 2. Create an App Password named *Teloring* at Google's App Passwords page (a 16-character code). 3. In Teloring, enter the inbox name, your Gmail address, a display name, and paste the App Password. 4. Click **Test Connection**, then **Save & Connect** once the test passes. ![Gmail — App Password setup](pathname:///img/screenshots/product/ring/email/gmail-setup.png) ### IMAP / SMTP (any provider) Enter your provider's mail-server details: | Group | Fields | | --- | --- | | **General** | Inbox Name, Email Address (the From address), Display Name. | | **IMAP (incoming)** | Host, Port (usually `993`), Security (SSL/TLS, STARTTLS, or None), Username, Password. | | **SMTP (outgoing)** | Host, Port (usually `587`), Security, Username, Password. A **Use same credentials as IMAP** checkbox saves retyping. | ![IMAP / SMTP form](pathname:///img/screenshots/product/ring/email/imap-form.png) Click **Test Connection** — IMAP and SMTP are tested separately and each shows a ✅ or ❌ result. **Save & Connect** unlocks once the test passes. :::note IMAP and Gmail inboxes do **not** import old mail. Only messages that arrive **after** you connect flow into Teloring. ::: When setup finishes, the **Email Inbox Ready!** screen confirms the address (and, for BYOD, shows the DNS records and forwarding address). ## The email edit page The edit page keeps a small settings surface: | Field | Editable? | | --- | --- | | **Channel Name** | ✅ | | **Display Name** | ✅ | | **Connection Type** | Read-only (Teloring Email, Microsoft, Gmail, or IMAP/SMTP). | | **Email Address** | Read-only. | | **Status** | Read-only — ✅ Active, ⏳ Pending verification, or ❌ an error state. | Type-specific panels also appear here: - **Teloring Forwarding** — the forwarding address to copy. - **Teloring BYOD** — the DKIM / Return-Path DNS records and a **Verify DNS now** button. - **Microsoft** — a **Re-authorize** button plus subscription/sync/token details. A **signature** and **reply-to** are configured per inbox and inserted automatically on replies. ## Capabilities and limits | Capability | Detail | | --- | --- | | Rich HTML | Full formatting — fonts, colors, lists, tables, links, and inline images — in a rich composer. | | Attachments | Sent and received, up to **25 MB** per file and 25 MB total per message. | | CC / BCC | Fully supported in the composer. | | Reply / Reply All / Forward | Per-message, with correct recipients and quoted content. | | Sends as your address | Replies go out from the inbox address (or, for Forwarding, the verified original address). | | Threading | Replies attach to the right conversation using standard email headers. | | Signature | Configured per inbox and added automatically. | | DNS / SPF / DKIM | Only **Bring Your Own Domain** needs DNS (a DKIM and a Return-Path record). Zero Setup, Forwarding, Gmail, Microsoft, and IMAP need none. | | Real-time delivery | Microsoft and Teloring Email push new mail in instantly; Gmail and IMAP check for new mail about once a minute. | | Resolved threads | A resolved conversation never reopens — a new email starts a fresh conversation. | ## How inbound email becomes conversations 1. Mail arrives (pushed for Microsoft/Teloring, polled for Gmail/IMAP) and Teloring routes it to the right inbox. 2. Teloring threads it: a reply attaches to its existing conversation using the email's headers; anything new starts a new conversation. 3. The sender becomes (or matches) a contact, the message is stored with its attachments and inline images, and the conversation is marked unread. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire on the new content (quoted history is ignored). Agents then reply, assign, label, and link the conversation to a [CRM customer](../crm.md) — see [Conversations](../../getting-started/conversations.md). --- # SMS Source: https://docs.teloring.com/docs/product/ring/sms Markdown: https://docs.teloring.com/markdown/docs/product/ring/sms.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **SMS** inbox handles two-way text-message conversations. Teloring is **carrier-agnostic** — it doesn't lock you to one SMS provider. Instead, you connect your own carrier or SMS gateway: incoming texts arrive at a Teloring webhook URL that you paste into your carrier's dashboard, and outgoing texts are sent through an HTTP request you configure to match your carrier's send API. This lets SMS work with virtually any provider or private gateway that speaks HTTP. :::info SMS is **text-only** — no images, files, or MMS. Setting it up takes a little more work than other channels because you connect your own carrier, but the wizard captures a real inbound message and helps you map its fields automatically. ::: ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Adding an SMS inbox needs **My Ring → Create**; configuring one needs **My Ring → Update**. See [Roles and Permissions](../roles/overview.md). | | An SMS carrier or gateway | It must be able to forward inbound texts to a webhook URL, and/or accept an HTTP call to send texts. | | Your carrier's send-API details | Endpoint URL, HTTP method, authentication, and the request body format. | | A phone number or sender ID | Informational — stored on the inbox and used as the "from" value on outbound messages. | ## Connect an SMS inbox Open **My Ring**, click **SMS**, and choose **Add**. The wizard has four steps: **Basics → Inbound → Outbound → Done**. ### Step 1 — Basics ![SMS setup — Basics](pathname:///img/screenshots/product/ring/sms/setup-basics.png) | Field | What to enter | | --- | --- | | **Inbox Name** | A name such as *Main SMS* or *Support SMS*. | | **Phone Number / Sender ID** | Optional. The number or sender ID for this inbox (used as the "from" value). | | **Communication Direction** | **Bidirectional** (send and receive), **Inbound Only** (receive), or **Outbound Only** (send). | Click **Create Inbox & Continue**. Outbound-only inboxes skip to Step 3. ### Step 2 — Inbound (receive) Teloring gives you a unique **Webhook URL**. Copy it and paste it into your SMS carrier's webhook / callback settings. ![SMS setup — Inbound mapping](pathname:///img/screenshots/product/ring/sms/setup-inbound.png) Then send a test SMS to your number. When your carrier forwards it, it appears under **Captured Samples** (the page checks for it automatically). Once a sample arrives, map its fields to Teloring's: | Field | Required? | | --- | --- | | **Sender Phone** | Yes | | **Message Text** | Yes | | **Recipient** | Optional | | **Message ID** | Optional (enables duplicate detection) | | **Timestamp** | Optional | Click **Auto-detect Fields** to have Teloring guess the mapping from the sample, then adjust if needed. **Save Mapping & Continue** activates inbound once Sender and Message are mapped. ### Step 3 — Outbound (send) Configure the HTTP request Teloring uses to send texts through your carrier's API: | Section | Settings | | --- | --- | | **API Endpoint** | The send **URL**, **HTTP Method** (POST / PUT / GET), and **Content Type** (JSON / Form / XML / Plain Text). | | **Authentication** | **None**, **Basic Auth**, **Bearer Token**, **Custom Header**, or **Query Parameter**. | | **Credentials** | Store secrets (API keys, tokens) here and reference them with `{{credentials.name}}` in the URL, headers, or body. | | **Request Body Template** | The body your carrier expects, using the placeholders `{{to}}`, `{{from}}`, `{{message}}`, and `{{credentials.*}}`. | | **Response Handling** | The success status range (default 200–299) and an optional path to read the carrier's message ID from the response. | Use **Test Send** to send a real message to a number you choose and confirm it works — the result panel shows success or failure, the extracted message ID, and the raw response. Then click **Save & Finish**. ![SMS setup — Outbound](pathname:///img/screenshots/product/ring/sms/setup-outbound.png) ### Step 4 — Done The **SMS Inbox Ready!** screen confirms the inbox is created and configured. ## The SMS edit page The SMS inbox shows an information panel with: - **Channel Name** (editable) and Channel Type. - The **Webhook URL** (read-only) to paste into your carrier. - **Direction**, **Identifier** (number/sender ID), **Inbound State**, **Outbound State**, and whether **AI Copilot** is on. - A **Danger Zone** to delete the inbox. ## Capabilities and limits | Capability | Detail | | --- | --- | | Two-way text | Send and receive plain text (based on the direction you chose). | | Any carrier | Works with any provider that can post to a webhook and/or accept an HTTP send request. | | No media | Images, files, and MMS are not supported. | | Duplicate protection | Mapping a Message ID field lets Teloring ignore duplicate deliveries. | | Reliable inbound | Teloring accepts the carrier's webhook in common formats (JSON, form, XML, or raw) and always acknowledges it so the carrier doesn't retry. | | AI Copilot | Works on SMS like any other channel. | ## How inbound SMS becomes conversations 1. Your carrier posts the incoming text to the inbox's webhook URL. 2. Teloring applies your field mapping to read the sender and message. 3. It matches the sender to a contact by phone (or creates one), then reuses their open conversation on this inbox or opens a new one. 4. The message is stored, the conversation updates, and real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. A resolved conversation is never reopened — a later text from the same person starts a new conversation. See [Conversations](../../getting-started/conversations.md). --- # Telegram Source: https://docs.teloring.com/docs/product/ring/telegram Markdown: https://docs.teloring.com/markdown/docs/product/ring/telegram.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Telegram** inbox connects a Telegram **bot** to Teloring. Customers message your bot, and those messages become conversations in the shared inbox; agents reply through the bot. Connecting is quick — you create a bot in Telegram, paste its token, and Teloring wires up everything else automatically. ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Connecting a Telegram bot needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A Telegram bot | Create one in Telegram with **@BotFather** and copy its API token. | **How to get a bot token:** 1. Open Telegram and search for **@BotFather**. 2. Send the **/newbot** command. 3. Choose a name and username for your bot. 4. Copy the API token BotFather gives you (it looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`). :::note Each Telegram bot can be connected to only one Teloring account. ::: ## Connect a Telegram inbox Open **My Ring**, click **Telegram**, and choose **Add**. The wizard has three steps: **Bot Token → Verify → Connect**. ### Step 1 — Enter the bot token ![Telegram setup — bot token](pathname:///img/screenshots/product/ring/telegram/setup-token.png) | Field | What to enter | | --- | --- | | **Channel Name** | A name such as *Support Bot*. | | **Bot Token** | The token from BotFather. | Click **Verify Token**. Teloring checks the token with Telegram and shows a preview card with the bot's name, **@username**, and ID. If you left the channel name blank, it fills in with the bot's name. ![Telegram setup — verified bot](pathname:///img/screenshots/product/ring/telegram/setup-verified.png) ### Step 2–3 — Connect Click **Connect Bot**. Teloring registers the bot's webhook automatically — **you don't paste any URL anywhere** — sets up the `/start` command, and stores the connection securely. The **Telegram Bot Connected!** screen confirms it's live, with a **Manage Bot** button that opens the edit page. ## The Telegram edit page ![Telegram edit page](pathname:///img/screenshots/product/ring/telegram/edit-page.png) | Section | What it shows | | --- | --- | | **Bot profile** | The bot avatar, name, and @username. | | **Info** | Bot ID, Channel ID, status, and webhook state (Active / Inactive). | | **Settings** | The editable **Channel Name** (Save applies it). You can also replace the bot token here, which re-verifies and re-registers the webhook. | | **Discovered Channels & Groups** | Telegram channels and groups your bot belongs to. Add the bot as an admin to a channel to discover it, then **Refresh**. Shows each channel's title, member count, and whether it's ready to broadcast (which needs a linked discussion group). | | **Danger Zone** | **Disconnect Bot** — removes the webhook and disconnects the bot. Existing conversations are kept; no new messages will arrive. | ## Capabilities and limits | Capability | Detail | | --- | --- | | Two-way messaging | Receive and reply to direct messages with the bot. | | Send media | Text, images, video, audio, voice notes, documents, animations, stickers, video notes, locations, and contacts. | | Long messages | Text over 4,096 characters is automatically split into several messages. | | Typing indicator | Shown to the customer while an agent replies. | | Channels & groups | The bot can broadcast to a Telegram channel that has a linked discussion group, and comments on those posts become conversations. | | Agent-initiated DMs | Agents can start a direct message to a Telegram user the bot can reach. | ## How Telegram messages become conversations 1. A customer messages your bot (or comments in a linked discussion group). 2. Teloring matches the person to a contact by their Telegram ID, or creates one. 3. It reuses their open conversation on this inbox, or opens a new one, and stores the message. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. A resolved conversation is never reopened — a later message starts a new one. See [Conversations](../../getting-started/conversations.md). --- # LINE Source: https://docs.teloring.com/docs/product/ring/line Markdown: https://docs.teloring.com/markdown/docs/product/ring/line.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **LINE** inbox connects a **LINE Official Account** to Teloring. Messages people send to your Official Account become conversations in the shared inbox, and agents reply through LINE. You connect it with two credentials from the LINE Developers Console and then paste a webhook URL back into that console. ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Connecting a LINE Official Account needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A LINE Official Account with a Messaging API channel | Created in the LINE Developers Console. | | The Channel Secret and a Channel Access Token | Used to authenticate and secure the connection. | **How to get your LINE credentials:** 1. Go to the LINE Developers Console (developers.line.biz). 2. Create a Provider (or select an existing one). 3. Create a **Messaging API** channel. 4. Copy the **Channel Secret** from **Basic Settings** (a 32-character code). 5. Issue a **Channel Access Token** from the **Messaging API** tab. :::note Each LINE Official Account can be connected to only one Teloring account. ::: ## Connect a LINE inbox Open **My Ring**, click **LINE**, and choose **Add**. The wizard has three steps: **Credentials → Webhook → Done**. ### Step 1 — Enter credentials ![LINE setup — credentials](pathname:///img/screenshots/product/ring/line/setup-credentials.png) | Field | What to enter | | --- | --- | | **Channel Name** | A name such as *Support LINE*. | | **Channel Secret** | The 32-character secret from Basic Settings. | | **Channel Access Token** | The long-lived token from the Messaging API tab. | Click **Connect**. Teloring validates the credentials and shows a bot preview card (the Official Account's display name and avatar). ### Step 2 — Configure the webhook Teloring shows a **Webhook URL**. Copy it and paste it into the LINE Developers Console: 1. Open your channel in the LINE Developers Console. 2. Go to the **Messaging API** tab. 3. Paste the webhook URL and click **Verify**. 4. Enable the **Use webhook** toggle. ![LINE setup — webhook](pathname:///img/screenshots/product/ring/line/setup-webhook.png) Click **Finish Setup**. The **LINE Channel Connected!** screen confirms the inbox is live. ## Managing the inbox Open the inbox from My Ring to rename it, update its credentials, or **disconnect** it. Disconnecting stops new messages but keeps existing conversations. ## Capabilities and limits | Capability | Detail | | --- | --- | | Two-way messaging | Receive and reply to messages with your Official Account. | | Send media | Text, images, video, audio, and location. Documents are sent as a text message with a download link (LINE has no native file type). | | Long messages | Text over 5,000 characters is split into several messages. | | Agent-initiated DMs | Agents can message a user who has added your Official Account. | ### Reply window and message quota LINE distinguishes **reply** messages from **push** messages, which matters for your monthly quota: - Each incoming message gives a short-lived **reply token** (valid about 5 minutes, single-use). While it's valid, Teloring replies using the free **reply** channel. - After the token expires (or for agent-initiated messages), Teloring uses **push** messages, which count toward your Official Account's monthly message quota. If a customer has blocked or unfriended your Official Account, a push message can't be delivered and Teloring reports it. ## How LINE messages become conversations 1. LINE sends the incoming message to your webhook URL (Teloring verifies each delivery's signature). 2. Teloring matches the person to a contact by their LINE user ID (fetching their LINE profile when possible), or creates one. 3. It reuses their open conversation on this inbox or opens a new one, stores the message, and keeps the reply token for a fast free reply. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. A resolved conversation is never reopened. See [Conversations](../../getting-started/conversations.md). --- # Live Chat Source: https://docs.teloring.com/docs/product/ring/live-chat Markdown: https://docs.teloring.com/markdown/docs/product/ring/live-chat.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Live Chat** inbox is a chat widget you embed on your own website. Visitors click a floating bubble to open a chat panel and message your team; those messages arrive in Teloring as conversations, and agents reply from the same inbox they use for every other channel. You design how the widget looks and behaves, then paste one line of code into your site — no developer needed beyond that. ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Creating a Live Chat inbox needs **My Ring → Create**; changing its settings needs **My Ring → Update**. See [Roles and Permissions](../roles/overview.md). | | Access to your website's HTML | To paste the embed snippet before the closing `` tag. | ## Create a Live Chat inbox Open **My Ring**, click **Live Chat**, and choose **Add**. The setup page has a form on the left and a **live widget preview** on the right that updates as you edit. ![Live Chat setup with live preview](pathname:///img/screenshots/product/ring/live-chat/setup.png) | Field | What to enter | | --- | --- | | **Channel Name** | Optional internal name (defaults to the website name). | | **Website Name** | Required — shown in the widget. | | **Website Domain** | Optional — your site's domain. | | **Widget Color** | The primary color for the bubble and header (default teal). | | **Welcome Heading / Tagline** | The greeting shown at the top of the panel. | | **Button Text** | The label on the chat bubble (default *Chat with us*). | | **Bubble Size** | The bubble diameter in pixels (40–120). | | **Footer Text** | Text at the bottom of the widget. | | **Show Greeting Message** / **Show Agent Online Status** | Toggles for the greeting and the live "agents online" indicator. | | **Widget Position** | Distance from the right and bottom edges, in pixels. | | **Pre-Chat Form** | Optionally collect the visitor's name, email, and phone before the chat starts (each field can be shown and marked required). | Click **Create Live Chat Inbox**. Teloring saves the inbox and opens its edit page, where you'll find the embed code. ## The Live Chat edit page The edit page has six tabs, with the live preview alongside. ### Settings Website Name, Website Domain, and Channel Name — plus two image uploads unique to this tab: | Upload | Notes | | --- | --- | | **Website Avatar** | Shown in the widget header. Square image, up to 2 MB. | | **Chat Icon Image** | A custom bubble icon (64×64 recommended, up to 2 MB). | ### Appearance All the visual options (color, bubble size, headings, button text, footer, position, and the two toggles), plus two edit-only fields: | Field | Used for | | --- | --- | | **Resolved Message** | Shown after a conversation is resolved. | | **New Chat Button Text** | The label on the button that starts a fresh conversation. | ![Live Chat — Appearance tab](pathname:///img/screenshots/product/ring/live-chat/edit-appearance.png) ### Pre-Chat Form Enable a short form shown before the first message, and choose which of **Name**, **Email**, and **Phone** to ask for and which are required, plus a welcome message. ### Additional Channels Show links to your other channels inside the widget, so a visitor can reach you elsewhere. Pick a channel (WhatsApp, Messenger, Email, SMS, Phone, Telegram, Instagram, TikTok, X, or LinkedIn) and give each a label, a link or number, and a short explanation. ### Code The **embed snippet** to install the widget: ```html ``` Add it to your website's HTML just before the closing `` tag, then copy it with **Copy Code**. A **Force Open Widget** snippet is also provided if you want to open the chat from a button on your page. ![Live Chat — Code tab](pathname:///img/screenshots/product/ring/live-chat/edit-code.png) ### Danger Zone Delete the inbox. Existing conversations are kept; the widget stops working once removed. ## What the visitor sees The widget loads in an isolated layer so it never clashes with your site's styling. A visitor: - Sees the floating bubble in the corner; clicking it opens the chat panel with your heading, tagline, and a live *"N agents online"* indicator. - Fills in the pre-chat form (if enabled), then messages your team. - Gets replies in real time, with read receipts (✓ sent, ✓✓ read) and a notification sound when the panel is minimized. - Keeps their conversation across page refreshes and browser tabs. - After a conversation is resolved, sees your **Resolved Message** and a button to start a new chat — resolved conversations never silently reopen. ## How Live Chat messages become conversations 1. A visitor sends a message from the widget (with any pre-chat details they provided). 2. Teloring creates or matches the contact and opens a conversation on this inbox. 3. Agents reply from Teloring; the visitor sees replies live in the widget. See [Conversations](../../getting-started/conversations.md). --- # Messenger Source: https://docs.teloring.com/docs/product/ring/messenger Markdown: https://docs.teloring.com/markdown/docs/product/ring/messenger.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Messenger** inbox brings private messages sent to your **Facebook Page** into Teloring. When someone messages your Page on Facebook, it becomes a conversation in the shared inbox, and agents reply as the Page — from the same place they handle every other channel. :::info Messenger, [Facebook Page](./facebook-page.md), [Instagram DM](./instagram-dm.md), and [Instagram Posts](./instagram-posts.md) are the four **Meta** inboxes. Each is connected **separately** as its own inbox, but they all use one Facebook login and the same Page/Instagram account. One Page can power several of these inboxes at once. ::: ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Connecting a Meta inbox needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A Facebook Page | You must be an admin of the Page whose messages you want to handle. | | A Facebook login | You authorize Teloring during setup with **Continue with Facebook**. | :::note If setup finds no Pages, Facebook will say you need to be an **admin of at least one Page**. ::: ## Connect the Messenger inbox Open **My Ring**, click the **Facebook Messenger** icon, and choose **Add**. The Meta setup opens with a three-step bar: **Connect → Select Pages → Done**. 1. **Connect** — click **Continue with Facebook**. A Facebook login window opens; sign in and grant the requested permissions. Teloring's connection to Meta is a **Business Portfolio** connection that **never expires**, so you won't need to reconnect periodically. 2. **Select Your Pages** — choose the **one** Facebook Page to connect (Pages already connected to another account are shown as unavailable). The chip confirms you're connecting the **Messenger** inbox for that Page. 3. **Done** — the **Pages Connected!** screen confirms the inbox is live. Click **Go to My Ring**. ![Meta setup — Continue with Facebook](pathname:///img/screenshots/product/ring/messenger/setup-connect.png) ![Meta setup — select your Page](pathname:///img/screenshots/product/ring/messenger/setup-select-page.png) ## What it handles - **Private 1:1 conversations** between a person and your Facebook Page. - **Incoming**: text and attachments (image, video, audio, file). A shared location arrives as a map link. - **Delivery and read receipts**: outgoing messages show sent → delivered → read. - **Replies**: send text or a single attachment back as the Page. ### The 24-hour messaging window Facebook only lets you send free-form replies within **24 hours** of the customer's last message. A human agent can extend this to **7 days** for follow-up. After that window, you cannot message the person again until they message you first. ## The edit page Open the inbox from My Ring to manage it: | Element | What it shows / does | | --- | --- | | **Profile header** | The Page picture, name, category, and connection status. | | **Inbox Type** | Shows this inbox's type (Messenger). | | **Channel Name** | Editable — rename the inbox. | | **Connection info** | *Business Portfolio — this connection never expires.* | | **Token Health** | Confirms the connection is valid. | | 🔄 **Reconnect** | Re-authorizes the connection if ever needed. | | **Disconnect** | Stops receiving messages for this inbox. Existing conversations are kept. | | **Danger Zone** | Permanently deletes the inbox (and unsubscribes it from Meta). Conversations remain. | ## How Messenger messages become conversations 1. Someone messages your Facebook Page. 2. Teloring matches them to a contact (merging the same person across your channels where possible), or creates one. 3. It opens or reuses their conversation on this inbox and stores the message and any media. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. Agents then reply, assign, label, and link to a [CRM customer](../crm.md) — see [Conversations](../../getting-started/conversations.md). --- # Facebook Page Source: https://docs.teloring.com/docs/product/ring/facebook-page Markdown: https://docs.teloring.com/markdown/docs/product/ring/facebook-page.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Facebook Page** inbox brings **comments on your Facebook Page's posts** into Teloring. Each post's comment thread becomes a conversation, so your team can reply to public comments as the Page — right alongside every other channel. You can also publish new Page posts from Teloring. :::info This inbox is labeled **Page Comments** inside the setup and edit screens. It handles public comments — for private messages to your Page, use the [Messenger](./messenger.md) inbox. Both are [Meta](./messenger.md#prerequisites) inboxes and can run on the same Page at the same time, each connected separately. ::: ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Connecting a Meta inbox needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A Facebook Page | You must be an admin of the Page. | | A Facebook login | You authorize Teloring during setup. | ## Connect the Facebook Page inbox Open **My Ring**, click the **Facebook Page** icon, and choose **Add**. The Meta setup opens with a three-step bar: **Connect → Select Pages → Done**. 1. **Connect** — click **Continue with Facebook**, sign in, and grant the requested permissions. The connection **never expires**. 2. **Select Your Pages** — choose the **one** Page to connect. The chip confirms you're connecting the **Page Comments** inbox. 3. **Done** — **Pages Connected!** confirms it's live. Click **Go to My Ring**. ![Meta setup — select your Page](pathname:///img/screenshots/product/ring/facebook-page/setup-select-page.png) ## What it handles - **Public comment threads** on your Page's posts. Each post's comments become their own conversation. - **Post context**: the first time someone comments on a post, Teloring pulls in the post's text, image, permalink, like count, and time, so the agent has full context. A **View on Facebook** link opens the original. - **Replying**: agents reply publicly as the Page. Teloring mentions the commenter (`@name`) so Facebook notifies them. - **No messaging window**: unlike private messages, comment replies have no 24-hour limit. ![A comment conversation with post context](pathname:///img/screenshots/product/ring/facebook-page/conversation-comment.png) ### Publish a new post From the conversation area you can publish a new post to your Page: | Post type | Notes | | --- | --- | | **Text Only** | A text post. | | **Single Photo** | One image. | | **Multiple Photos (Album)** | Up to 10 images. | | **Video** | A video post. | Publishing a post does **not** create a conversation. But when someone comments on it, a new conversation opens automatically so you can reply from Teloring. ## The edit page Same layout as the other Meta inboxes: the Page profile header, the **Inbox Type** tile (Page Comments), an editable **Channel Name**, the *Business Portfolio — never expires* connection info, a **Token Health** card, **Reconnect** / **Disconnect** buttons, and a **Danger Zone**. Disconnecting or deleting keeps existing conversations. ## How comments become conversations 1. Someone comments on one of your Page's posts. 2. Teloring matches them to a contact or creates one, and finds (or creates) the conversation for **that post's** comment thread. 3. On the first comment it enriches the conversation with the post's context. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. Agents reply publicly as the Page from [Conversations](../../getting-started/conversations.md). --- # Instagram DM Source: https://docs.teloring.com/docs/product/ring/instagram-dm Markdown: https://docs.teloring.com/markdown/docs/product/ring/instagram-dm.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Instagram DM** inbox brings **direct messages** sent to your Instagram account into Teloring. Each Instagram conversation becomes a conversation in the shared inbox, and agents reply as your Instagram account — from the same place they handle every other channel. :::info Instagram DM is one of the four [Meta](./messenger.md#prerequisites) inboxes. It uses the Facebook Page that your Instagram account is linked to. For comments on your Instagram posts, use [Instagram Posts](./instagram-posts.md). ::: ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Connecting a Meta inbox needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A Facebook Page you admin | Instagram connects through its linked Facebook Page. | | An Instagram **Business or Creator** account **linked to that Page** | Instagram data only appears when the account is a linked business/creator account. | | A Facebook login | You authorize Teloring during setup. | ## Connect the Instagram DM inbox Open **My Ring**, click the **Instagram DM** icon, and choose **Add**. The Meta setup opens with a three-step bar: **Connect → Select Pages → Done**. 1. **Connect** — click **Continue with Facebook**, sign in, and grant the requested permissions. The connection **never expires**. 2. **Select Your Pages** — choose the Facebook Page whose linked Instagram account you want. For Instagram inboxes, the card shows a rich **Instagram profile** — profile picture, name, `@username`, bio, and Followers / Following / Posts stats — so you can confirm it's the right account. The chip confirms you're connecting the **Instagram DM** inbox. 3. **Done** — **Pages Connected!** confirms it's live. Click **Go to My Ring**. ![Meta setup — Instagram profile card](pathname:///img/screenshots/product/ring/instagram-dm/setup-select-page.png) ## What it handles - **Private Instagram Direct messages** to your linked account. - **Incoming**: text and attachments (image, video, audio, file). - **Story replies**: when someone replies to your story, Teloring saves the story image (Instagram's own link expires quickly) and shows it as context on the conversation. - **Read receipts**: outgoing messages show when they're read. - **Replies**: send text or a single attachment. ### The 24-hour messaging window Instagram, like Messenger, only lets you send free-form replies within **24 hours** of the customer's last message, extendable to **7 days** by a human agent for follow-up. After that, you cannot message the person until they message you again. ## The edit page Same layout as the other Meta inboxes, with Instagram extras: | Element | What it shows / does | | --- | --- | | **Profile header** | The Page name and status, plus an Instagram line (📸 @username). | | **Instagram profile card** | Profile picture, `@username`, bio, and Followers / Following / Posts, with a **Refresh Instagram Profile** button. | | **Inbox Type** | Instagram DM. | | **Channel Name** | Editable. | | **Connection info / Token Health** | *Business Portfolio — never expires.* | | **Reconnect / Disconnect / Danger Zone** | Manage or remove the inbox; conversations are kept. | ## How Instagram DMs become conversations 1. Someone sends your account a direct message. 2. Teloring matches them to a contact or creates one. 3. It opens or reuses their conversation on this inbox and stores the message, media, and any story context. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. Agents reply as your Instagram account from [Conversations](../../getting-started/conversations.md). --- # Instagram Posts Source: https://docs.teloring.com/docs/product/ring/instagram-posts Markdown: https://docs.teloring.com/markdown/docs/product/ring/instagram-posts.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Instagram Posts** inbox brings **comments on your Instagram posts and reels** into Teloring. Each post's comment thread becomes a conversation, so your team can reply to public comments as your Instagram account. You can also publish new Instagram content from Teloring. :::info This inbox is labeled **Instagram Comments** inside the setup and edit screens. It handles public comments — for private messages, use [Instagram DM](./instagram-dm.md). Both are [Meta](./messenger.md#prerequisites) inboxes and run on the Instagram account linked to your Facebook Page. ::: ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Connecting a Meta inbox needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A Facebook Page you admin | Instagram connects through its linked Facebook Page. | | An Instagram **Business or Creator** account linked to that Page | Required for Instagram data to appear. | | A Facebook login | You authorize Teloring during setup. | ## Connect the Instagram Posts inbox Open **My Ring**, click the **Instagram Posts** icon, and choose **Add**. The Meta setup opens with a three-step bar: **Connect → Select Pages → Done**. 1. **Connect** — click **Continue with Facebook**, sign in, and grant permissions. The connection **never expires**. 2. **Select Your Pages** — choose the Page whose linked Instagram account you want; its Instagram profile (with follower stats) is shown on the card. The chip confirms you're connecting the **Instagram Comments** inbox. 3. **Done** — **Pages Connected!** confirms it's live. Click **Go to My Ring**. ![Meta setup — select your Instagram account](pathname:///img/screenshots/product/ring/instagram-posts/setup-select-page.png) ## What it handles - **Public comment threads** on your Instagram posts and reels. Each post's comments become their own conversation. - **Post context**: on the first comment, Teloring pulls in the post's caption, image, permalink, like count, and time. A **View on Instagram** link opens the original. - **Replying**: agents reply publicly as your Instagram account. - **No messaging window**: comment replies have no 24-hour limit. ### Publish new content From the conversation area you can publish to Instagram: | Type | Notes | | --- | --- | | **Single Photo** | One image (under 8 MB). | | **Reel (Video)** | A reel (under 300 MB). | | **Carousel** | 2–10 items. | | **Story (Photo / Video)** | A photo or video story (video under 100 MB). | Captions can be up to 2,200 characters. Publishing does **not** create a conversation, but comments on the new post will. ## The edit page Same layout as the other Meta inboxes: the profile header with the Instagram line, the **Instagram profile card** with **Refresh Instagram Profile**, the **Inbox Type** tile (Instagram Comments), an editable **Channel Name**, the *Business Portfolio — never expires* connection info, a **Token Health** card, **Reconnect** / **Disconnect** buttons, and a **Danger Zone**. Removing the inbox keeps existing conversations. ## How comments become conversations 1. Someone comments on one of your Instagram posts or reels. 2. Teloring matches them to a contact or creates one, and finds (or creates) the conversation for that post's comment thread. 3. On the first comment it enriches the conversation with the post's context. 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. Agents reply publicly as your account from [Conversations](../../getting-started/conversations.md). --- # Voice Source: https://docs.teloring.com/docs/product/ring/voice Markdown: https://docs.teloring.com/markdown/docs/product/ring/voice.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **Voice** inbox is a phone-call channel. It gives your account a phone number, and agents answer and place calls from a **browser softphone** — a small popup window — instead of a physical desk phone. Every call becomes a conversation, so a call sits in the same inbox and on the same customer record as chats and emails. :::info Voice is a **call channel, not a text channel**. Voice conversations have **no reply box** — a conversation is a record of the call (with notes, recording, and history). Agents talk to customers through the softphone. ::: ## Prerequisites Voice depends on a few things being set up at the account and agent level (outside the inbox itself): | Requirement | Where it's set | | --- | --- | | **Voice enabled for the account** | An account-level master switch must be on. If it's off, adding a voice inbox or making calls returns "Voice is disabled for this account." | | **An available phone number** | Voice numbers come from a Teloring-managed pool. You pick an available number when you create the inbox. | | **Voice-enabled agents** | Each agent who will handle calls must be enabled for voice (which sets up their calling credentials). There's also a **Reset voice credentials** action to rotate an agent's credentials. | | **Inbox permission** | Creating a voice inbox needs **My Ring → Create**. Switching browser calling on for a person is **Agents → Update**. See [Roles and Permissions](../roles/overview.md). | ## Create a voice inbox Open **My Ring**, click the **Voice** icon, and choose **Add**. ![Voice inbox — number picker](pathname:///img/screenshots/product/ring/voice/setup.png) | Field | What to do | | --- | --- | | **Channel Name** | Name the line (for example, *Main Line* or *Support Line*). | | **Voice number** | Choose an available Teloring phone number from the dropdown (shown in a friendly format like `+972 73-398-3300`). | Click to create the inbox. Teloring claims the number for your account (two admins can't grab the same one) and the inbox goes live. If no numbers are free, you'll see *"No available voice numbers. Contact support."* Deleting the inbox releases its number back to the pool. ## Inbox properties A voice inbox carries these properties, set when it's created: | Property | Default | Meaning | | --- | --- | --- | | **Auto-resolve** | On | The conversation closes itself when the call ends, so agents don't manually close completed calls. (Missed calls stay open for follow-up.) | | **Recording** | Off | The default for call recording. Whether a specific call is recorded is controlled by your [Studio](../studio/voice-flows.md) call flow. | | **Business hours** | Default schedule | Which reusable schedule (open/closed hours, timezone, holidays) the call flow uses to decide how to route calls. | | **Agent extensions** | — | Which agents can receive calls forwarded from this line. | :::note Voice behavior — greetings, menus, business-hours routing, forwarding to agents, and recording — is built in a [Studio](../studio/voice-flows.md) call flow attached to the number, not in a settings tab on the inbox. The inbox's edit page shows its name and a delete option; day-to-day call handling is defined by the flow. ::: ## Capabilities | Capability | Detail | | --- | --- | | **Inbound calls** | A customer dials your number; the call runs through your Studio flow and can ring an agent's browser. | | **Outbound calls** | An agent places a call from the voice line to an external number. | | **Internal calls** | Agents can call each other, browser to browser. | | **Browser softphone** | A popup window with **Mute**, **Hold**, **Hang up**, and (for incoming calls) **Answer** controls. Keep it open for the duration of the call. | | **Call recording** | Recordings are saved and attached to the conversation, controlled per-call by the Studio flow. | | **AI Copilot** | Available on calls. | | **Live call state** | The call card updates in real time as the call rings, is answered, held, and ends. | ![Voice softphone popup](pathname:///img/screenshots/product/ring/voice/softphone.png) ## How calls become conversations Unlike messaging channels, **each call is its own conversation** (even repeat calls from the same number). - **Inbound**: when a customer dials your number, Teloring finds the inbox, matches or creates the contact (unknown callers become a lead), creates the conversation, and runs your Studio flow. A ringing **call card** appears in the agent inbox. - **Answered calls** auto-resolve when they end (if auto-resolve is on). - **Missed calls** stay open and get an automatic private note like *"Missed call from 050-773-0018 at 14:32."* so they can be followed up. - **Outbound calls** create a conversation the same way, assigned to the agent who placed the call. Every contact profile has a permanent **Phone calls** section listing all of their voice conversations. See [Conversations](../../getting-started/conversations.md). --- # TikTok Messenger Source: https://docs.teloring.com/docs/product/ring/tiktok Markdown: https://docs.teloring.com/markdown/docs/product/ring/tiktok.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **TikTok Messenger** inbox brings **direct messages** from a TikTok **Business** account into Teloring. When someone messages your business on TikTok — from your profile, an ad, or a `tiktok.me` link — it becomes a conversation in the shared inbox, and agents reply from the same place they handle every other channel. :::info TikTok Messenger is **inbound-first**: you can't start a conversation with a TikTok user. A conversation opens only when someone messages your business first. It also has a strict reply window (see [Capabilities](#capabilities-and-limits)). Post comments and TikTok Shop are not part of this inbox. ::: ## Prerequisites The setup wizard shows a **Before you connect** checklist: | Requirement | Detail | | --- | --- | | **TikTok Business account** | Messaging works only with **Business** accounts (not Personal or Creator) that have the messaging feature enabled. | | **Region availability** | TikTok Business Messaging isn't available in every country. If your region is unsupported, the connection fails with a clear error. | | **48-hour reply window** | You can reply only within 48 hours of the customer's last message, and at most 10 messages per window. A new incoming message resets both. | | **Inbound-only** | You cannot start a conversation — customers must message you first. | | **Inbox permission** | Connecting the inbox needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | ## Connect a TikTok inbox Open **My Ring**, click the **TikTok Messenger** icon, and choose **Add**. ![TikTok setup wizard](pathname:///img/screenshots/product/ring/tiktok/setup.png) 1. Review the **Before you connect** checklist. 2. Click **Connect TikTok**. A window opens on TikTok, where you authorize Teloring to read and send messages for your Business account. 3. When you approve, the window closes and Teloring opens the inbox's edit page. Re-authorizing the same TikTok account later updates the existing inbox rather than creating a duplicate. :::note If the feature is still awaiting approval for your account, the Connect button is disabled with a notice that TikTok Messenger is in staging. ::: ## The edit page The TikTok edit page has three cards on top of the inbox name: ### Connection Shows the connection status with a colored dot: | Status | Meaning | | --- | --- | | **Connected** | The inbox is authorized and working. | | **Authorization expired — reconnect required** | Re-authorize to restore it. | | **Not a Business account** | Switch the TikTok account to a Business account, then reconnect. | | **Region not supported** | TikTok messaging isn't available for this account's region. | | **Disconnected** | The inbox has been disconnected. | A **🔄 Reconnect / Reauthorize** button re-runs the TikTok authorization. ![TikTok — Connection and Capabilities](pathname:///img/screenshots/product/ring/tiktok/edit-capabilities.png) ### Capabilities A live check of what this connection can actually do, with ✅ / ❌ for each: | Capability | Meaning | | --- | --- | | **Account connected** | Teloring can reach the TikTok Business account. | | **Receive incoming messages** | Incoming DMs are delivered. | | **Send replies via API** | Whether Teloring can send replies (TikTok restricts sending to Business accounts). | | **Sync / list conversations** | Whether Teloring can list conversations from TikTok. | | **Webhook delivery registered** | Incoming-message delivery is set up. | :::tip This panel is the honest truth for your specific account — for example, a personal account can still **receive** messages but not **send** replies until it's switched to a Business account. ::: ### tiktok.me Link Builder Create trackable `tiktok.me` links. Add a **tracking label (ref)** — like `instagram_bio` — and Teloring builds a link such as `https://tiktok.me/@yourname?ref=instagram_bio`. When someone opens that link and messages you, the ref appears on the conversation, so you can see which source (Instagram bio, email footer, an ad, and so on) drives conversations. A **Link performance** table shows how many conversations each ref produced. :::note Your TikTok username appears here after the first customer message arrives; then you can build links. ::: ## Capabilities and limits | Capability | Detail | | --- | --- | | Text replies | Up to 6,000 characters; can quote-reply to a customer's text message. | | Typing & read indicators | Shown to the customer as agents type and open the conversation. | | Send images | JPG or PNG, up to 3 MB. A message can be **either** text **or** an image, not both. Image support varies by market. | | Receive | Text, images, video, shared posts, emoji, stickers, reactions, and template cards. | | **48-hour / 10-message window** | You can reply for 48 hours after the customer's last message, up to 10 messages. A new incoming message resets both the timer and the count. The composer shows the remaining time and count, and banners explain when the window has expired or the limit is reached. | | Inbound-only | No "new conversation" button — customers must message you first. | ## How TikTok messages become conversations 1. A customer messages your business on TikTok (or arrives via an ad or a `tiktok.me` link). 2. Teloring matches them to a contact or creates one, and opens or reuses their conversation on this inbox. 3. If they came from an ad or a link, the conversation shows the source (and the `ref`). 4. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire. A resolved conversation is never reopened — a later message starts a new one. See [Conversations](../../getting-started/conversations.md). --- # API Source: https://docs.teloring.com/docs/product/ring/api Markdown: https://docs.teloring.com/markdown/docs/product/ring/api.md Section: The Ring — Inboxes Last modified: 2026-08-20T20:49:57.000Z The **API** inbox is a developer inbox for pushing messages into Teloring from any custom system — your own app, a legacy platform, or a channel Teloring doesn't natively support. You create the inbox, get an endpoint, and POST messages to it. Each message becomes a conversation just like any other channel, so your custom integration lands in the same shared inbox agents already use. ## Prerequisites | You need | Why | | --- | --- | | Inbox permission | Creating an inbox needs **My Ring → Create**. See [Roles and Permissions](../roles/overview.md). | | A personal API token | Requests authenticate with an agent's personal token (created in your profile). | | A system that can send HTTP requests | To POST messages into the endpoint. | ## Create an API inbox Open **My Ring**, click the **API** icon, and choose **Add**. ![API inbox setup](pathname:///img/screenshots/product/ring/api/setup.png) | Field | What to enter | | --- | --- | | **Channel Name** | A name such as *My API Inbox*. | | **Channel Type** | Read-only (API). | | **Webhook URL (for outgoing messages)** | Optional. If you provide it, Teloring will POST **outgoing** messages (agent replies) to this URL so your system can deliver them. Leave it empty if you only push messages in. | Click **Create Channel**. The success screen (and the inbox's edit page) shows the details you need to integrate. ## Sending messages in After creation you get: - **Your Channel ID** — the inbox's numeric ID. - **Endpoint** — the URL to POST messages to, of the form `.../accounts/{account}/channels/{channel}/incoming`. - **Sample cURL** and **Sample Python** — ready-to-use code you can copy. ![API inbox — sample code](pathname:///img/screenshots/product/ring/api/sample-code.png) Authenticate each request with your personal token in the `X-API-Key` header. The message payload accepts: | Field | Meaning | | --- | --- | | `message` | The message text (required). | | `contact_id` | An existing contact to attach to (optional). | | `contact_name`, `contact_phone`, `contact_email`, `contact_picture` | Details used to match or create the contact when no `contact_id` is given. | | `file_url` | An optional attachment. | | `contact_attributes` | Custom fields to set on the contact. | Teloring finds or creates the contact, finds or creates an open conversation, stores the message, and returns the resulting `contact_id`, `conversation_id`, and `message_id`. :::tip The setup and edit pages include the exact request format for your inbox. Copy the **cURL** or **Python** sample to get started quickly. ::: ## The API edit page The edit page lets you rename the inbox, set or change the outgoing **Webhook URL**, and review the sample code. A **Danger Zone** deletes the inbox (existing conversations are kept). ## Outgoing messages (optional) If you set a **Webhook URL**, agent replies on this inbox are POSTed to it so your system can deliver them to the customer. This makes the API inbox fully two-way for a custom channel. ## How API messages become conversations 1. Your system POSTs a message to the inbox's `incoming` endpoint with your `X-API-Key`. 2. Teloring matches or creates the contact, opens or reuses a conversation, and stores the message. 3. Real-time updates, [Studio](../studio.md) triggers, and AI Copilot fire, and agents reply from [Conversations](../../getting-started/conversations.md) as usual. --- # Build a flow with AI (Hermes) Source: https://docs.teloring.com/docs/product/studio/ai-flow-builder Markdown: https://docs.teloring.com/markdown/docs/product/studio/ai-flow-builder.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z **Hermes** is the AI flow builder inside Studio. Instead of dragging blocks onto a canvas, you describe what you want in your own words. Hermes asks a handful of follow-up questions, and when it has everything it needs it builds the whole flow for you — the blocks, their settings, and the connections between them. The result is a normal Studio flow. Nothing about it is locked or special: you open it in the [canvas editor](../studio.md#the-editor), change anything you like, and publish it yourself. ![The Hermes AI flow builder mid-interview](pathname:///img/screenshots/product/studio/ai/ai-builder-chat.png) ## When to use it | Use Hermes when | Build it yourself when | | --- | --- | | You know what you want to happen but not which blocks to use | You already know the blocks and just want to place them | | You are new to Studio and want a working example to learn from | You are making a small edit to an existing flow | | You want a first draft fast, then to refine it by hand | The flow depends on an uploaded file or a WhatsApp template you must pick yourself | | Your flow has several branches and you want the wiring done for you | You are copying an existing flow's structure | :::tip Hermes is a starting point, not a replacement for the editor. Most teams let Hermes build the skeleton, then spend two minutes polishing the wording of the replies on the canvas. ::: ## Before you start | Requirement | Detail | | --- | --- | | **AI Studio must be on** | Somebody with **AI World → Update** turns on the **AI Studio** switch in [AI World](../ai-world.md). Until then the AI option in Studio is visible but not selectable. | | **Who can use it** | Any signed-in agent with **Studio → Create**. See [Roles and Permissions](../roles/overview.md). | | **Your inboxes should exist first** | Hermes offers your real inboxes, teams, agents, schedules, and CRM objects by name. If the inbox you want to automate is not connected yet, connect it first — see [The Ring](../ring/overview.md). | | **Language** | Hermes writes to you in your Teloring interface language (English or Hebrew), and writes the customer-facing message text inside the blocks in that same language. | :::note If the **Use AI to build** card is greyed out with *"Enable AI Studio to use this"*, ask an account administrator to switch **AI Studio** on in AI World. Agents cannot change AI switches themselves. ::: ## Start a flow with AI 1. Open **Studio** from the sidebar and click **New Flow**. 2. Give the flow a **name** and, ideally, a short **description**. Hermes reads both — `WhatsApp — route to sales or support` tells it much more than `Flow 4`. 3. Under **How would you like to build it?**, choose one of the two cards. **Neither is pre-selected**, and the button stays disabled until you pick one. 4. Click **Start with AI**. ![The New Flow dialog with the two build-mode cards](pathname:///img/screenshots/product/studio/ai/new-flow-choose-mode.png) | Card | What happens | | --- | --- | | **I'll build my own** | The flow is created and the canvas editor opens, exactly as it always has. | | **Use AI to build** | The flow is created and the Hermes chat opens. The button label changes to **Start with AI**. | :::info The flow is created as a **draft either way, before the conversation starts**. If you abandon the interview halfway, you have not lost anything — you are left with an ordinary empty draft flow you can open in the editor or delete. ::: ## The Hermes screen The page has three parts: the conversation in the middle, a progress rail on the right, and a header with two exit actions. ![The parts of the Hermes screen](pathname:///img/screenshots/product/studio/ai/ai-builder-anatomy.png) ### Header | Element | What it is | | --- | --- | | **←** | Back to the Studio flow list. | | **AI Studio · Hermes** | The kicker, with the flow's name underneath. | | **Start over** | Throws this conversation away and begins a new interview for the same flow. You are asked to confirm, because everything Hermes has collected is lost. | | **Save & exit** | Leaves the conversation. Nothing is lost — every answer is already saved. You return to the flow list. | Neither header button builds anything. There is exactly **one** build action on the page, and it lives in the panel above the message box. ### The conversation Hermes opens with the same greeting every time: > Hi, I'm Hermes — the AI Studio flow builder. Tell me in short what you'd like to build? Answer in plain language. There is no syntax, no block names to learn, and no need to know how Studio works: > *"I want customers who message us on WhatsApp to choose sales or support, and go to the right team."* From there, **every question depends on your last answer**. There is no fixed questionnaire. If you said "departments", Hermes asks which departments; if you said "abandoned carts", it asks something else entirely. Along the way it asks about the things that decide which blocks it needs — which inbox, who handles what, what the customer should see, what happens on each branch, what happens when nobody answers, and when the automation should stop. | Element | What it is | | --- | --- | | **Hermes bubble** | A question, a short confirmation, or the closing summary. | | **You bubble** | Your answer. | | **Thinking…** | Hermes is working out the next question and redrawing the flow. This takes a few seconds. | | **Message box** | Type your answer. **Enter** sends it; **Shift + Enter** starts a new line. Up to 2,000 characters per answer. | :::tip Answer with real detail. *"Sales and support"* is fine, but *"Sales and support — after hours everyone goes to support"* saves Hermes two questions and gets you a better flow. ::: ### Progress rail The rail on the right shows what Hermes has understood so far, so you can catch a misunderstanding early instead of at the end. | Section | What it shows | | --- | --- | | **Progress** | A percentage and bar — Hermes's own estimate of how far the interview is. It is a guide, not a countdown. | | **What Hermes understood** | Every decision collected so far, one line each. This list is **rewritten in full after every answer**, so it always reflects the current design. Read it. If a line is wrong, say so in your next message. | | **Blocks so far** | How many blocks the flow currently contains. Hermes redraws the whole flow after each answer, so this number can go up **or down**. | | **Needs your attention** | Things you will have to finish by hand after the flow is built — see [Warnings](#warnings). Only appears when there is something to say. | :::note "Blocks so far" is a count, not a preview. You see the actual flow on the canvas after you build it. ::: ## Stop and continue later The interview is saved **after every single answer**. You can close the tab at any question — mid-sentence, mid-branch, at the end of the day — and nothing is lost. To pick it up again: 1. Open **Studio**. 2. The flow's card shows a **⚡ Continue with AI** badge. 3. Click the card. The conversation reopens with the full transcript, the progress bar, and everything Hermes had understood. ![A flow card with an unfinished AI interview](pathname:///img/screenshots/product/studio/ai/flow-card-continue.png) | Where you click | Where you land | | --- | --- | | The card itself, while **Continue with AI** is shown | Back into the Hermes conversation | | The card's **✏️ Edit** button | The canvas editor, at any time | | The card itself, once the flow has been built | The canvas editor, like any other flow | :::warning If you open the editor mid-interview and add blocks by hand, Hermes will refuse to build over your work later — see [Hermes will not overwrite your edits](#hermes-will-not-overwrite-your-edits). Finish the interview first, then edit. ::: ## Build the flow When Hermes has everything it needs, it says so and a panel appears above the message box. ![The build panel, with the one-way warning](pathname:///img/screenshots/product/studio/ai/build-panel.png) | Element | What it does | | --- | --- | | **Your flow is ready to build** | Plus the number of blocks waiting to be placed. | | The amber note | *"This is the last step: the blocks go onto your canvas and this conversation closes. Anything you want Hermes to change, ask now."* | | **Keep refining** | Puts your cursor back in the message box. Use it to ask for a change before committing. | | **Build my flow** | Opens the confirmation dialog. | ### Ask for changes first Until you press **Build my flow**, nothing has been written to the canvas and you can keep talking. Hermes redraws the entire flow after each answer, so changes are cheap: > *"Add a message before the menu that says we're open 9 to 5."* > > *"If nobody picks a department, send it to support instead of asking again."* > > *"Make the greeting shorter."* ### The confirmation **Build my flow** opens a dialog that spells out all three consequences, because two of them are one-way: ![The build confirmation dialog](pathname:///img/screenshots/product/studio/ai/build-confirm-modal.png) | | What it means | | --- | --- | | ✅ **The blocks are created and wired for you** | You can move, edit, add, or delete any of them afterwards. Nothing is locked. | | ✅ **The flow stays a draft** | Nothing runs until **you** publish it from the editor. No customer is affected by pressing Build. | | ⚠️ **This ends the conversation with Hermes** | You cannot ask for another version of this flow afterwards. From then on you edit it by hand. | Click **Yes, build it** and Studio places the blocks and opens the canvas editor. Click **Keep refining** to go back to the conversation. ### Why building is final Once the blocks are on the canvas, they are yours. If Hermes could rebuild the flow later it would have to replace whatever you had changed in the meantime — so instead the conversation closes and the editor takes over. The message box is disabled and reads *"The flow is built — continue in the editor."* If you want a different flow built by AI, create a **new flow** and start a new interview. ## After Hermes builds You land in the normal [canvas editor](../studio.md#the-editor) with the flow laid out top-to-bottom. ![A flow built by Hermes, on the canvas](pathname:///img/screenshots/product/studio/ai/built-flow-canvas.png) Your next steps are the ordinary Studio ones: 1. **Read the blocks.** Click each one and check its settings in the right panel. Hermes writes real message text — make it sound like your brand. 2. **Clear any warning badges.** Anything Hermes could not fill in (an uploaded voice prompt, a WhatsApp template) shows a ⚠ badge on the block. See [warnings on a block](../studio.md#warnings-on-a-block). 3. **Test Run.** Walk the draft with sample data — nothing reaches real customers. See [Test Run](./publishing.md#test-run). 4. **Publish.** The flow goes live only when you press **Publish**. See [Publishing](./publishing.md#publishing). :::info A flow Hermes built is a completely ordinary flow. Version history, pause and resume, Test Run, saved variables, and delete all work exactly as they do for a flow you drew by hand. ::: ## What Hermes knows Two things, and both come from your live account rather than from a generic template library. This is why Hermes asks *"Support or Sales?"* using your real inbox names, and why the blocks it produces are already pointing at the right things. | Hermes knows | So it can | | --- | --- | | Every Studio block — triggers, actions, and conditions, with all of their real settings | Choose the correct block and fill in its properties, including branch rules and output ports | | Your **inboxes**, by name and channel type | Ask which inbox, and write the real inbox into the trigger | | Your **agents** (and which of them are AI agents) | Route to a named person, and avoid sending "wait for a human" to an AI agent | | Your **teams** | Hand a conversation to Sales or Support by name | | Your **labels**, **forms**, and **business-hours schedules** | Tag conversations, listen to the right form, and branch on opening hours | | Your **CRM objects** and their fields | Create or update a Deal, Service Call, or Task with the right field keys | | Your **analytics alerts** | Start a flow when one of your own thresholds trips | Hermes can only see **your account**. It never sees another business's inboxes, conversations, contacts, or flows. ### What Hermes cannot do | Not possible | What to do instead | | --- | --- | | Upload a file for you — a voice prompt (WAV) or WhatsApp template media | Hermes builds the block and tells you; you attach the file in the editor | | Pick a WhatsApp template | Choose the approved template on the block in the editor | | Publish the flow | You publish, always | | Edit a flow that already has blocks | Start a new flow, or edit the existing one by hand | | Use an inbox, team, or object you have not created | Create it first, then start the interview | ## Warnings **Needs your attention** in the right rail lists anything Hermes wants you to know before the flow can work. The same items are worth re-reading after the flow is built. | Warning | Meaning | What to do | | --- | --- | --- | | *"…is not one of this account's resources"* | Hermes referred to an inbox, team, agent, or object that does not exist | Open the block on the canvas and pick the right one from the dropdown | | *"…removed a selection that does not exist in this account"* | Same, for a multiple-choice field such as an inbox filter | Tick the correct inboxes on the block | | *"…is not connected to anything and will not run"* | A block has nothing pointing into it | Wire it in from an earlier block, or delete it | | *"…the '…' branch has nothing wired to it"* | A condition or IVR branch leads nowhere | Connect it, or accept that this path simply ends | | *"…cannot be used in a … flow and was removed"* | A voice block landed in a messaging flow, or the reverse | Usually nothing — Hermes already removed it. Check the flow still does what you asked | | *"upload the … in the editor"* | A block needs a file only you can provide | Open the block and upload it | :::note Warnings do not stop you from building. They are the short list of things to finish by hand. ::: ## Hermes will not overwrite your edits Studio protects work that a person did: | Situation | What happens | | --- | --- | | You start an interview on a flow that already has blocks | Refused: *"This flow already has blocks. Create a new flow to build one with AI."* | | You edit the canvas by hand mid-interview, then press **Build my flow** | Refused, with a message pointing you to the editor. Your edits stay untouched | | You press **Build my flow** on an untouched draft | The blocks are placed | ## Limits and good practice | Limit | Value | | --- | --- | | Length of one answer | 2,000 characters | | Blocks in a flow Hermes builds | Up to 60 | | Connections in a flow Hermes builds | Up to 120 | | Questions in one interview | Up to 60 (a normal interview is 6–15) | | Messages per account | Throttled — if you hit it, wait a minute and continue. Nothing is lost | :::tip Good practice - **Name the flow well before you start.** Hermes reads the name and description as its first clue. - **Read "What Hermes understood" as you go.** Correcting a misunderstanding at question three is much cheaper than at the end. - **Say what should happen when things go wrong** — nobody answers, the customer replies with something unexpected, it is 2 a.m. Hermes will ask, but you know your business better. - **Ask for changes before you build**, not after. After building, changes are yours to make on the canvas. - **Always Test Run before publishing**, exactly as with a hand-built flow. ::: ## Frequently asked questions **Does the flow go live automatically?** No. Hermes always produces a **draft**. Nothing runs until you press **Publish** in the editor. **Can I edit a flow Hermes built?** Yes — completely. Move, retype, rewire, add, and delete anything. It is an ordinary Studio flow. **Can I ask Hermes to change a flow it already built?** No. Building closes the conversation. Edit it on the canvas, or create a new flow and run a new interview. **What if I close the tab in the middle?** Nothing is lost. Every answer is saved as you go. Reopen the flow from the Studio list — it shows **⚡ Continue with AI**. **Which language does Hermes speak?** Your Teloring interface language. It also writes the customer-facing text inside the blocks in that language. You can rewrite any of it afterwards. **Does Hermes see other businesses' data?** No. It only ever reads your own account's inboxes, teams, agents, labels, forms, schedules, and CRM objects. Flows and conversations are account-isolated. **Can Hermes build voice (phone) flows?** Yes. Tell it the automation starts with a phone call and it builds a [voice flow](./voice-flows.md) with IVR menus and transfers. It cannot record the audio prompts for you — upload those in the editor. **Nothing happened when I clicked "Use AI to build".** The card is disabled unless **AI Studio** is on in [AI World](../ai-world.md). A greyed card shows *"Enable AI Studio to use this"* with a link to the page. **The conversation says it hit a limit.** An interview is capped at 60 questions, and each account has a short-term message throttle. Your progress is saved either way — wait a moment and continue, or open the flow in the editor and finish it by hand. ## Where to go next | Page | What it covers | | --- | --- | | [Studio overview](../studio.md) | The canvas, blocks, ports, and how a flow runs | | [Triggers — the WHEN blocks](./triggers.md) | Every trigger Hermes can choose from | | [Actions — the THEN blocks](./actions.md) | Every action, its properties, and its outputs | | [Conditions — the IF blocks](./conditions.md) | How the branches Hermes wires actually decide | | [Test, publish, and versions](./publishing.md) | What to do with the flow Hermes just built | | [AI World](../ai-world.md) | Turning AI Studio on, and every other AI switch | | [Flow recipes](./examples.md) | Hand-built examples, useful for checking Hermes's work | --- # Triggers — the WHEN blocks Source: https://docs.teloring.com/docs/product/studio/triggers Markdown: https://docs.teloring.com/markdown/docs/product/studio/triggers.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z A **trigger** is the entry point of a flow. It answers one question: *what has to happen for this flow to run?* Triggers carry the coral **WHEN** badge, sit in the **Triggers** section of the left panel, and are the only blocks you drag onto the canvas directly. Every flow needs at least one — a flow with no trigger cannot be published. ![Studio trigger palette](pathname:///img/screenshots/product/studio/trigger-palette.png) ## The full list | Trigger | Fires when | Flow kind | | --- | --- | --- | | [Incoming Message](#incoming-message) | A customer sends a message to a selected inbox | Messaging | | [Incoming Call](#incoming-call) | A phone call arrives on a voice inbox | **Voice** | | [Form filled](#form-filled) | Someone submits a Teloring form | Messaging | | [Conversation Changed](#conversation-changed) | A conversation is opened, resolved, assigned to an agent or a team, labelled, flagged, prioritized, or shows an AI signal | Messaging | | [Customer trigger](#customer-trigger) | A CRM customer is created or edited | Messaging | | [Customer record trigger](#customer-record-trigger) | A contact record or CRM object record is created, edited, or deleted | Messaging | | [Agent status changes](#agent-status-changes) | An agent signs in or out of Teloring | Messaging | | [Recurring Schedule](#recurring-schedule) | A fixed interval elapses (every N minutes / hours / days) | Messaging | | [Scheduled Time](#scheduled-time) | A weekly day-and-time comes around | Messaging | | [Incoming webhook](#incoming-webhook) | An external system calls your unique webhook URL | Messaging | | [Analytics Alert](#analytics-alert) | A report metric crosses a threshold you defined in Analytics | Messaging | ## Rules that apply to every trigger - **Only live flows fire.** A flow in Draft or Paused never runs on real events. Use **Test Run** while building. - **Several flows can match one event.** If three live flows all trigger on incoming WhatsApp messages, all three run. - **One flow can hold several triggers.** Studio runs the trigger node whose own settings match the event — not simply the first trigger in the flow. This lets you keep channel-specific entry points side by side in one flow. - **Leaving a filter empty means "everything".** An Incoming Message trigger with no inboxes selected listens on every inbox. - **Trigger failures never break Teloring.** If a flow errors, the message, call, or form submission is still delivered and stored normally. --- ## Incoming Message Fires when a **new message arrives from a customer** on one of the inboxes you select. This is the trigger behind auto-replies, chatbots, qualification questions, keyword routing, and out-of-hours messages. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Inboxes** | Tick the inboxes this flow should listen on. Leave every box unticked to listen on **all** inboxes. | All inboxes | ![Incoming Message trigger configuration](pathname:///img/screenshots/product/studio/trigger-incoming-message.png) ### When it does *not* fire | Situation | Why | | --- | --- | | A human agent is assigned to the conversation | The agent owns the conversation; Studio stays out. | | A flow already handed the conversation to a human | Same reason — the handover sticks until the conversation is resolved or a flow runs **End Session**. | | The message is outgoing | Only inbound customer messages count. | | The message is the reply a paused flow was waiting for | It is consumed by that flow instead of starting a new run. | ### Variables it produces | Variable | Holds | | --- | --- | | `{{message.content}}` | The message text | | `{{message.content_type}}` | `text`, `image`, `audio`, and so on | | `{{message.id}}` | Message ID | | `{{message.direction}}` | Message direction | | `{{message.created_at}}` | When it arrived | | `{{conversation.id}}` | Conversation ID | | `{{conversation.status}}` | Conversation status | | `{{conversation.channel_id}}` · `{{conversation.channel_type}}` | Which inbox and which channel type | | `{{conversation.assigned_agent_id}}` | Assigned agent, if any | | `{{conversation.custom_attributes.*}}` | Your account's [conversation attributes](../conversation-attributes.md), as already filled in on this conversation | | `{{contact.id}}` · `{{contact.name}}` · `{{contact.phone}}` · `{{contact.email}}` · `{{contact.company}}` | The customer's contact record | | `{{channel.id}}` · `{{channel.name}}` · `{{channel.type}}` | The inbox the message arrived on | :::tip Works the same on every messaging inbox — WhatsApp, Email, SMS, Telegram, LINE, Live Chat, Messenger, Facebook, Instagram, TikTok, and the developer API. ::: --- ## Incoming Call Fires when a **phone call arrives** on one of your voice numbers. This is the only trigger that makes a flow a **voice flow**, which unlocks the Voice blocks and hides the messaging ones. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Voice inbox** *(required)* | The voice inbox / DID whose calls run this flow. | — | | **Record this call** | Records every call that enters this flow. The recording is uploaded, attached to the conversation as a private note, and stored in the customer's record and the Files Warehouse. | Off | :::note Recording is controlled **only here**, at the trigger. There is no separate "start recording" action. ::: ### Variables it produces | Variable | Holds | | --- | --- | | `{{call.uuid}}` | Unique ID of this call | | `{{call.caller_id}}` | The number that is calling you | | `{{call.destination}}` | The number they dialled (your DID) | | `{{call.direction}}` · `{{call.timestamp}}` | Direction and arrival time | | `{{call.inbox_id}}` | The voice inbox | | `{{call.contact_id}}` · `{{call.contact_name}}` | The matched contact (unknown callers become a lead) | | `{{conversation.id}}` | The conversation created for the call | | `{{contact.id}}` · `{{contact.name}}` · `{{contact.phone}}` | Contact details | | `{{channel.id}}` · `{{channel.type}}` | The voice inbox | See [Voice call flows](./voice-flows.md) for the complete guide, including IVR menus and transfers. --- ## Form filled Fires when someone **submits a Teloring form**. Use it to route leads, notify a team, create CRM records, or start a conversation from a form. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Form** | The form to listen to, or **All forms**. | All forms | ### Variables it produces | Variable | Holds | | --- | --- | | `{{form.id}}` · `{{form.name}}` · `{{form.version}}` | Which form, and which version of it | | `{{submission.id}}` | The submission | | `{{contact.id}}` | The contact, when the form is tied to one | | `{{conversation.id}}` | The conversation, when the form is tied to one | | `{{answers.list}}` | An array of the visible answers, each with field ID, label, type, and value | | `{{answers}}` | The answers as an object, keyed by field ID | | `{{hiddenValues}}` | Hidden field values, keyed by hidden field ID | | `{{sourceParams}}` | URL parameters the form page was opened with | **Exact answers by field ID.** If a form field has the Field ID `email`, use `{{answers.email}}`. If a hidden field has the ID `campaign_id`, use `{{hiddenValues.campaign_id}}`. If the public form URL was `?utm_source=google`, use `{{sourceParams.utm_source}}`. :::tip Give every form field a readable Field ID before you build the flow — the ID is the variable name. See [Forms Builder](../forms.md). ::: --- ## Conversation Changed Fires when **something about a conversation changes**: it was opened or resolved, an agent or a [team](../teams.md) was assigned or removed, labels were added, the flag or priority changed, or AI detected a signal. This is the trigger for escalation rules, SLA notifications, "customer sounds unhappy" alerts, and post-resolution follow-ups. ### Properties Every filter defaults to *any*. Combine them to narrow down exactly which change you care about. | Property | Options | What it does | | --- | --- | --- | | **Inboxes** | Any inboxes | Only react to conversations on these inboxes. Empty = all. | | **Status Change** | Any change · Conversation opened · Conversation resolved | Which status event to react to. | | **Agent Assignment** | Any agent · Agent assigned (any) · Agent removed · Specific agent assigned | Which assignment event to react to. | | **Specific Agents** | Agent picker | Appears when **Specific agent assigned** is chosen. Pick one or more agents. | | **Team Assignment** | Any team · Team assigned (any) · Team removed · Specific team assigned | Which [team](../teams.md) assignment event to react to. | | **Specific Teams** | Team picker | Appears when **Specific team assigned** is chosen. Pick one or more teams. | | **Labels Added** | Any label · Specific labels | React to any new label, or only to the ones you list. | | **Specific Labels** | One label per line | Appears when **Specific labels** is chosen. | | **Flag** | Any flag · 🔴 Red · 🟠 Orange · 🟡 Yellow · 🟢 Green · 🔵 Blue · 🟣 Purple | React to a specific flag color. | | **Priority** | Any priority · Urgent · High · Medium · Low | React to a specific priority. | | **AI Signals** | Any AI signal · Feelings / emotion detected · Churn risk · Upsale opportunity | React to an AI-detected signal on the conversation. | ![Conversation Changed trigger configuration](pathname:///img/screenshots/product/studio/trigger-conversation-changed.png) ### Variables it produces Alongside the usual `contact.*` and `channel.*` variables: | Variable | Holds | | --- | --- | | `{{conversation.id}}` · `{{conversation.status}}` · `{{conversation.previous_status}}` | The conversation and its status before and after | | `{{conversation.assigned_agent_id}}` · `{{conversation.previous_agent_id}}` | Agent assignment before and after | | `{{conversation.assigned_team_id}}` · `{{conversation.assigned_team_name}}` · `{{conversation.previous_team_id}}` | [Team](../teams.md) assignment before and after, plus the current team's name | | `{{conversation.priority}}` · `{{conversation.previous_priority}}` | Priority before and after | | `{{conversation.flag}}` · `{{conversation.previous_flag}}` | Flag before and after | | `{{conversation.labels}}` · `{{conversation.labels_added}}` | All labels, and just the ones added by this change | | `{{conversation.customer_emotion}}` · `{{conversation.previous_customer_emotion}}` | Emotion score before and after | | `{{conversation.custom_attributes.*}}` | Your account's [conversation attributes](../conversation-attributes.md), as currently stored on the conversation | | `{{conversation.channel_id}}` · `{{conversation.channel_type}}` | The inbox | | `{{change.type}}` · `{{change.field}}` | What kind of change it was, and which field changed | | `{{ai.signal}}` · `{{ai.message}}` | The AI signal and its explanation | :::info A brand-new conversation fires this trigger with `change.type` = `opened`, **after** the conversation exists — so `{{conversation.id}}` is always safe to use downstream. ::: `{{change.type}}` reports team changes separately from agent changes: `team_assigned` and `team_unassigned`, versus `assigned` and `unassigned` for an individual agent. That lets a flow react to "handed to Sales" without also firing on every personal assignment. :::tip React to an agent filling in a conversation attribute Saving the [Conversation Attributes](../conversation-attributes.md) panel counts as a conversation change, so this trigger fires. Follow it with a [Condition](./conditions.md) on `{{conversation.custom_attributes.outcome}}` to build rules such as *"when Outcome is set to Escalated, notify the duty manager"*. ::: :::note Two things to know about the team filter - Flows published **before** Teams existed keep working unchanged — **Team Assignment** defaults to *Any team*. - **Specific team assigned** with **nothing selected never fires.** An empty selection means "no team matches", not "every team", so an unfinished trigger cannot fire on assignments you never asked for. ::: --- ## Customer trigger Fires when a **CRM customer** is created or edited. ### Properties | Property | Options | Default | | --- | --- | --- | | **Events** | Customer created · Customer edited | Both | ### Variables it produces | Variable | Holds | | --- | --- | | `{{customer.id}}` · `{{customer.name}}` · `{{customer.email}}` · `{{customer.phone}}` | The customer | | `{{event.type}}` · `{{event.action}}` | What happened | | `{{customer.old}}` · `{{customer.new}}` | The full record before and after the change | --- ## Customer record trigger Fires when a **record** under a customer is created, edited, or deleted. That covers the fixed contact records and every custom CRM object your account has enabled (service calls, orders, notes, contracts — whatever you defined). ### Properties | Property | Options | Default | | --- | --- | --- | | **Actions** | Record created · Record edited · Record deleted | All three | | **Object Types** | One object type ID per line. Leave empty for contacts **and** every enabled custom object. | Empty (all) | ### Variables it produces | Variable | Holds | | --- | --- | | `{{record.id}}` | The record | | `{{record.schema_id}}` | Which object type it belongs to | | `{{record.old}}` · `{{record.new}}` | The record before and after | | `{{customer.id}}` · `{{customer.name}}` · `{{customer.email}}` · `{{customer.phone}}` | The customer that owns it | | `{{event.type}}` · `{{event.action}}` | What happened | **Field-level variables.** Use `{{record.}}` for a field on the record that changed, and `{{objects..}}` when you want a specific object's field — for example `{{objects.service_calls.subject}}` or `{{objects.notes.content}}`. --- ## Agent status changes Fires when an **agent signs in to or out of Teloring**. "Online" here means the same green dot you see in Team Chat — a live session, not a status the agent picks. ### Properties | Property | Options | Default | | --- | --- | --- | | **Status** | Agent goes online · Agent goes offline | Both | | **Agents** | Pick specific agents, or leave empty for all agents. | All agents | AI Agents are never included — they hold no session. ### Variables it produces | Variable | Holds | | --- | --- | | `{{agent.id}}` · `{{agent.name}}` · `{{agent.email}}` | Who | | `{{agent.status}}` · `{{agent.previous_status}}` | New and previous status | | `{{agent.changed_at}}` | When | **Good uses:** notify a manager when the last agent signs out, post a private note when the on-call agent comes online, or re-route waiting conversations at shift change. --- ## Recurring Schedule Runs the flow **repeatedly at a fixed interval** — the Studio equivalent of a cron job. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Every** | How many units between runs (1–1440). | 1 | | **Unit** | Minutes · Hours · Days | Minutes | | Limit | Value | | --- | --- | | Shortest interval | 1 minute | | Longest interval | 24 hours (a **Days** value is capped at one day) | ### Variables it produces | Variable | Holds | | --- | --- | | `{{schedule.triggered_at}}` | When this run started | | `{{schedule.interval_seconds}}` | The configured interval in seconds | :::caution A recurring flow runs on its own, with no conversation attached. Blocks that default to `{{conversation.id}}` have nothing to work with unless you supply a conversation ID yourself — usually from an HTTP Request or a saved variable. ::: --- ## Scheduled Time Runs the flow on a **weekly timetable** — one or more day-and-time rows, each with its own timezone. ### Properties | Property | What it does | | --- | --- | | **Times** | A list of schedule rows. Each row has a **day of week**, an **hour** and **minute** (24-hour), and a **timezone**. Add as many rows as you need. | Use one row for "every Monday at 09:00", or seven rows for "every day at 08:00". Different rows can use different timezones, which is useful for teams spread across regions. ![Scheduled Time trigger configuration](pathname:///img/screenshots/product/studio/trigger-scheduled-time.png) ### Variables it produces | Variable | Holds | | --- | --- | | `{{schedule.triggered_at}}` | When this run started | | `{{schedule.day_of_week}}` · `{{schedule.hour}}` · `{{schedule.minute}}` | The row that fired | | `{{schedule.timezone}}` | That row's timezone | --- ## Incoming webhook Gives the flow its **own public URL**. When an external system calls that URL, the flow runs — with the request's body, query string, and headers available as variables. Use it to start a flow from your website, your billing system, a CRM, an order platform, Zapier/Make, or any service that can send an HTTP request. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Webhook URL** | The unique URL for this trigger, ready to copy. Every trigger node gets its own. | Generated | | **Allowed Methods** | Which HTTP methods are accepted: GET, POST, PUT, PATCH, DELETE. | POST | | **Learn next request** | Captures the **next** request that arrives and remembers its shape. | On | | **Learned Variables** | Read-only chips showing every variable Studio found in the learned payload. | Empty | ![Incoming webhook trigger configuration](pathname:///img/screenshots/product/studio/trigger-webhook.png) ### How to set one up 1. Add the **Incoming webhook** trigger and copy its URL. 2. Leave **Learn next request** on. 3. Send one **real** request from the external system to that URL — the exact request you intend to use in production. 4. Studio captures it. The editor updates by itself: **Learn next request** switches off and the **Learned Variables** chips appear. 5. Drag those variables into the blocks below. ### After learning Once a format is learned, Studio only accepts requests that match it: the same method, the same content type, the same body kind, and the required query and body keys. Anything else is rejected, which keeps a malformed or unrelated call from running your flow. To accept a different shape, turn **Learn next request** back on and send the new request. ### Variables it produces | Variable | Holds | | --- | --- | | `{{webhook.method}}` | GET, POST, … | | `{{webhook.content_type}}` | The request's content type | | `{{webhook.sender_ip}}` · `{{webhook.host}}` · `{{webhook.user_agent}}` | Who called, and how | | `{{webhook.body}}` | The whole body | | `{{webhook.query}}` | The query string as an object | | `{{webhook.headers}}` | The headers as an object | Plus one variable per field found in the learned payload — for example `{{webhook.body.order_id}}` or `{{webhook.query.token}}`. :::caution The webhook URL is public and unguessable. Treat it like a password: don't publish it, and rotate it (by deleting the trigger and adding a new one) if it leaks. ::: --- ## Analytics Alert Fires when a **report metric crosses a threshold** you defined in Analytics — for example "open conversations above 50", "average first response above 10 minutes", or "CSAT below 4". ### Properties | Property | What it does | | --- | --- | | **Alerts to monitor** *(required)* | Tick one or more alerts you created in Analytics. Publishing a **live** flow that references them switches their monitoring on. | If the list is empty, create an alert first from a report in [Analytics](../analytics.md). ### Two outputs ![Analytics Alert trigger with both outputs wired](pathname:///img/screenshots/product/studio/trigger-analytics-alert.png) | Output | Fires when | | --- | --- | | **Alert** | The metric crossed the threshold. | | **Recovered** | The metric came back to normal. Wiring this is optional. | The alert fires **once per crossing**. While the metric stays over the line it will not fire again — you get one alert, then one recovery, not a message every minute. ### Variables it produces | Variable | Holds | | --- | --- | | `{{alert.name}}` | The alert's name | | `{{alert.report_title}}` · `{{alert.report_type}}` | The report behind it | | `{{alert.current_value}}` · `{{alert.threshold}}` | The value now, and the line it crossed | | `{{alert.direction}}` | `above` or `below` | | `{{alert.series}}` | Which series or category crossed, for grouped reports | | `{{alert.state}}` | `in_alert` or `normal` | | `{{alert.event}}` | `alert` or `recovered` | | `{{alert.crossed_at}}` | When it crossed | | `{{alert.id}}` · `{{alert.report_id}}` · `{{alert.dashboard_id}}` | IDs, for building links | :::caution **Deleting an alert disables the flows that use it.** If an alert (or the report behind it) is deleted, every flow referencing it gets a warning badge on its card and is paused if it was live. Choose a different alert and republish to clear it. ::: ## Next - [Actions — the THEN blocks](./actions.md) — what to do once a trigger fires. - [Variables](./variables.md) — using everything a trigger produced. - [Flow recipes](./examples.md) — complete examples per trigger. --- # Actions — the THEN blocks Source: https://docs.teloring.com/docs/product/studio/actions Markdown: https://docs.teloring.com/markdown/docs/product/studio/actions.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z An **action** is a step that *does something*: sends a message, updates a conversation, writes to your CRM, calls an external API, sends an email, or transforms a value for the next block. Actions carry the teal **THEN** badge. You add them from the block picker: drag a connector out of any block and release it on empty canvas. ## The full list | Action | Group | What it does | | --- | --- | --- | | [Reply Message](#reply-message) | Conversations | Sends a message to the customer, and can pause the flow until they answer. | | [Private Note](#private-note) | Conversations | Adds an internal note that the customer never sees. | | [Change Conversation](#change-conversation) | Conversations | Hands over to a human, a team, or the waiting line; labels, prioritizes, resolves, renames, and sets conversation attributes. | | [End Session](#end-session) | Conversations | Releases the conversation from Studio, optionally resolving it. | | [Wait](#wait) | Flow | Pauses this path for 1–15 seconds. | | [Save as Variable](#save-as-variable) | Flow | Stores a value permanently under `var.*` for future runs. | | [Contact Update](#contact-update) | CRM | Writes to fields on the contact record. | | [Customer Record](#customer-record) | CRM | Creates or updates a CRM object record under a customer. | | [HTTP Request](#http-request) | External | Calls an external API, optionally capturing the response. | | [Send Email](#send-email) | External | Sends an email from an inbox or from the Teloring system sender. | | [Code](#code) | Tools | Runs a small sandboxed JavaScript transform. | | [Date and Time](#date-and-time) | Tools | Gets, formats, adds, subtracts, compares, extracts, or rounds dates. | | [Send Teloring Notification](#send-teloring-notification) | Tools | Alerts agents inside Teloring — bell, sound, email, and browser push. | | [Play Sound](./voice-flows.md#play-sound) | Voice | Plays an audio prompt to a caller. | | [Wait / Pause](./voice-flows.md#wait--pause) | Voice | Pauses the call briefly. | | [IVR Menu](./voice-flows.md#ivr-menu) | Voice | Plays a menu and routes by keypad digit. | | [Forward to Agent](./voice-flows.md#forward-to-agent) | Voice | Rings an agent in the browser and bridges the call. | | [Forward to External Phone](./voice-flows.md#forward-to-external-phone) | Voice | Transfers the call to an outside number. | | [Hang Up](./voice-flows.md#hang-up) | Voice | Ends the call. | Branching blocks — **Condition If/Else**, **Business Hours**, **Agent Availability** — carry the amber **IF** badge and are documented in [Conditions](./conditions.md). ## Things that are true for every action - **Text fields accept variables.** Type `{{` or drag a variable in from the **Available Variables** section. See [Variables](./variables.md). - **Outputs become variables.** Everything an action produces is available to every block below it. - **Fan-out runs everything.** If an action has three connectors leaving it, all three paths run. - **A failed action stops its own path**, not the whole flow — other branches keep going. --- ## Reply Message Sends a message to the customer in the conversation, exactly as if an agent had typed it. It goes out on whichever channel the conversation is on — WhatsApp, email, SMS, Telegram, live chat, and so on. This is also the block that turns a flow into a conversation: switch **Wait for client response** on and the flow pauses until the customer answers. *Messaging flows only.* ### Properties | Property | What it does | Default | | --- | --- | --- | | **Conversation ID** | Which conversation to send in. Leave the default to reply in the conversation that triggered the flow. | `{{conversation.id}}` | | **Message** *(required)* | The text to send. Use variables for personalization. | Empty | | **Wait for client response** | Pauses this path until the customer replies. Their reply becomes the new `{{message.content}}` and is also available as `{{client_reply.content}}`. | Off | | **Wait timeout (minutes)** | How long to wait before giving up. **0 means no timeout** — the flow keeps waiting. Teloring holds a waiting flow for up to 30 days either way. Appears only when waiting is on. | 0 | ![Reply Message configuration](pathname:///img/screenshots/product/studio/action-reply-message.png) ### Outputs | Variable | Holds | | --- | --- | | `{{reply.message_id}}` | The sent message | | `{{reply.conversation_id}}` | Where it was sent | | `{{reply.sent_at}}` | When | | `{{reply.status}}` | Send status | | `{{client_reply.content}}` | What the customer replied (when waiting) | | `{{client_reply.content_type}}` | The reply's type | | `{{client_reply.message_id}}` · `{{client_reply.received_at}}` | Reply message and timestamp | ### How waiting behaves - While the flow waits, the conversation stays in the **Studio Bot** queue. - The customer's reply is consumed by the waiting flow — it does **not** start a second run of the same flow. - After the wait, you can test the answer with either `{{message.content}}` or `{{client_reply.content}}`; they hold the same text. - If a condition after a wait matches no branch and there is no ELSE branch, the flow keeps waiting at that condition and re-evaluates on the customer's next message. Add an ELSE branch, or an [End Session](#end-session) block, so a customer can never get stuck in the flow. - If the timeout expires, the run ends as `timed_out`. :::tip Ask one question per Reply Message. Two questions in one message get one answer, and your condition has nothing clean to match. ::: --- ## Private Note Adds an **internal note** to a conversation. It appears in the conversation timeline for agents and is never sent to the customer, on any channel. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Conversation ID** | Which conversation gets the note. | `{{conversation.id}}` | | **Private note** | The note text. Variables are supported. | Empty | ### Outputs | Variable | Holds | | --- | --- | | `{{private_note.message_id}}` | The note | | `{{private_note.conversation_id}}` | Where it was added | | `{{private_note.created_at}}` · `{{private_note.status}}` | When, and the result | **Good uses:** record what a bot collected before handing over, paste an order status pulled from an API, or leave the reason a conversation was escalated. --- ## Change Conversation Updates the conversation — and, most importantly, is where you **hand it over to a human**: one specific agent, a whole [team](../teams.md), or the waiting line. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Conversation ID** | Text / variable | Which conversation to update. Defaults to `{{conversation.id}}`. | | **Human intervention** | On / Off | Hands the conversation to a person. Studio stops owning it, so the next customer message goes to the agent instead of back into the flow. | | **Hand over to** | Waiting in line (next available agent) · A specific agent · A team | Appears when Human intervention is on. | | **Agent** | Agent picker | Appears when handing over to a specific agent. | | **Team** | Team picker | Appears when handing over to a [team](../teams.md). A `⚡` marks a team that auto-assigns to an online member; the number in brackets is how many agents it has. | | **Labels mode** | Add labels · Replace labels · Remove labels | How the labels below are applied. | | **Labels** | One label per line | The labels to add, set, or remove. | | **Priority** | No change · Low · Medium · High · Urgent | Sets the conversation priority. | | **Status** | No change · Open · Pending · Resolved | Sets the conversation status. | | **Flag** | No change · None · Important · Follow up | Sets the conversation flag. | | **Subject** | Text / variable | Renames the conversation. | | **Conversation attributes** | Attribute picker + value | Sets your account's [Conversation Attributes](../conversation-attributes.md) on this conversation. Pick the attribute, type the value — variables allowed. See below. | ![Change Conversation configuration](pathname:///img/screenshots/product/studio/action-conversation-update.png) ### Outputs | Variable | Holds | | --- | --- | | `{{conversation.status}}` | Result of the update | | `{{conversation.updated_fields}}` | Which fields changed | | `{{conversation.handover}}` | `queue`, `agent`, `team`, or empty | | `{{conversation.handover_agent_id}}` | The agent it was handed to — for a team handover, the member who was auto-assigned, or empty if it waits in line | | `{{conversation.handover_team_id}}` | The [team](../teams.md) it was handed to | | `{{conversation.handover_team_name}}` | That team's name | | `{{conversation.custom_attributes}}` | Every conversation attribute, as one object | | `{{conversation.custom_attributes.}}` | One attribute — for example `{{conversation.custom_attributes.reason_for_contact}}` | ### Setting conversation attributes [Conversation Attributes](../conversation-attributes.md) are your account's own fields on a conversation — *Reason for contact*, *Outcome*, *Order number*. They live in this block rather than a block of their own, because they are fields on the conversation exactly like priority and subject. Click **Add field** under **Conversation attributes**, pick an attribute, and give it a value. The value accepts variables, so a flow can classify a conversation from what it already knows: | Flow | Sets | | --- | --- | | A menu asks "what is this about?" | *Reason for contact* = the button the customer pressed | | A form starts the conversation | *Order number* = `{{answers.order_number}}` | | An [HTTP Request](#http-request) looks the customer up | *Account tier* = `{{http.json.tier}}` | | The bot resolves the conversation itself | *Outcome* = `Solved by bot` | | Rule | Behavior | | --- | --- | | Values are validated | A value that is not one of a dropdown's options **fails the block**, so a flow can never write something the agent panel would refuse to show. | | Deleted attributes are skipped | An attribute removed from Settings after the flow was built is ignored, and the block keeps running. | | Other attributes are kept | Setting one attribute never clears the rest. | | Multi-select | Separate values with commas or new lines. | The block outputs the **new** values, so every block below it — an HTTP Request above all — sees what was just written. Attributes are also available from the trigger, without this block, on **Incoming Message**, **Incoming Call** and **Conversation Changed**. See [Variables](./variables.md#conversation-attributes). ### Understanding Human intervention | Setting | What happens | | --- | --- | | **Off** | Only the labels, priority, status, flag, and subject change. Studio keeps owning the conversation and later messages still run the flow. | | **On → A specific agent** | The conversation is assigned to that agent and leaves the Studio Bot queue. If the conversation was on a team that agent does not belong to, the team is cleared. | | **On → A team** | The team takes ownership. If the team auto-assigns to an online agent, one of its online members receives it immediately; otherwise it waits in line and **only members of that team** can pull it with **Get next**. A resolved conversation is re-opened first. | | **On → Waiting in line** | The conversation is unassigned and dropped into the **Waiting in line** queue for whoever is free next. A resolved conversation is re-opened first, because a resolved conversation cannot wait in line. | Either way, the handover **sticks**: later messages on that conversation will not be pulled back into this flow — or into any other live flow. The handover is cleared automatically when the conversation is resolved, when the conversation is assigned to a specific agent, or when a flow runs [End Session](#end-session). :::warning Two things to check on a team handover - **Pick the team.** If **Hand over to** is **A team** but no team is selected, the handover falls back to the plain waiting line. The editor flags the block while you are editing. - **Deleting a team breaks the block.** If the selected team is later deleted, the block **fails** at runtime rather than parking the conversation on a team that no longer exists. Review your live flows after deleting a team. ::: :::tip Every customer-facing flow should have a route to a human. Wire an "I want to talk to someone" branch, or a fallback branch, into a Change Conversation block with **Human intervention** on. ::: --- ## End Session Ends Studio's involvement with the conversation. The next message from that customer starts trigger matching from scratch, as if the flow had never run. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Conversation ID** | Which conversation to release. | `{{conversation.id}}` | | **Should we also resolve the conversation?** | Also marks the conversation resolved. | Off | ### Outputs | Variable | Holds | | --- | --- | | `{{session.status}}` | Result | | `{{session.conversation_id}}` | The conversation | | `{{session.resolved}}` | Whether it was resolved too | ### End Session vs. Human intervention | Use | When | | --- | --- | | **End Session** | The bot has finished its job. Nobody in particular needs to act, and the *next* message should be able to start a flow again. | | **Change Conversation → Human intervention** | A person or a team needs to take this conversation now. | --- ## Wait Pauses **this path** of the flow for a few seconds before continuing. Use it to space out messages so a bot feels less robotic. *Messaging flows only. Voice flows use [Wait / Pause](./voice-flows.md#wait--pause).* ### Properties | Property | What it does | Default | | --- | --- | --- | | **Wait duration (seconds)** | Between 1 and 15 seconds. | 3 | ### Outputs | Variable | Holds | | --- | --- | | `{{wait.seconds}}` | How long it waited | :::info Wait only holds up the branch it sits on. If the trigger also feeds another branch, that branch runs immediately — it does not queue behind the wait. ::: --- ## Save as Variable Stores a value **permanently**, so later runs of the same flow can read it back. Ordinary variables live only for one run; a saved variable outlives it. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Variable key** | The name to store it under. Always inside the `var.` namespace. Dynamic keys are allowed, for example `var.{{contact.phone}}.address`. | `var.my_value` | | **Value** | What to store. Variables are supported. | `{{message.content}}` | | **Value type** | Text · Number · Boolean · JSON | Text | | **Overwrite existing variable** | Whether an existing value with the same key may be replaced. | On | ### Outputs | Variable | Holds | | --- | --- | | `{{saved_variable.key}}` | The normalized key that was written | | `{{saved_variable.value}}` | The stored value | | `{{saved_variable.status}}` | Result | ### How saved variables work - They are **per flow**. Two flows can each have their own `var.counter` without colliding. - They are loaded into **every** run of that flow, so `{{var.my_value}}` is available from the first block onward. - Keys are forced into the `var.` namespace, so a saved value can never overwrite a system, contact, conversation, or message variable. - Unsupported characters in a key become underscores. - Review and delete them in **⚙ Flow Settings → Saved variables**. **Good uses:** remember a per-customer preference keyed by phone number, store the last synced ID from an external system, or keep a running counter. --- ## Contact Update Writes to fields on the contact record — the person, not the company. ### Properties | Property | What it does | Default | | --- | --- | --- | | **Contact ID** | Which contact to update. | `{{contact.id}}` | | **Fields to update** | Rows of field → value. The field name is a **dropdown of the contact fields your account actually defined** in the Field Editor. A field already used in one row disappears from the other dropdowns. Values support variables. | Empty | ### Outputs | Variable | Holds | | --- | --- | | `{{contact.status}}` | Result | | `{{contact.updated_fields}}` | Which fields were written | :::note Protected system fields cannot be written by a flow. If a field you expect is missing from the dropdown, add it in the contact **Field Editor** first — see [CRM and Customers](../crm.md). ::: --- ## Customer Record Creates or updates a **CRM object record** under a customer — a service call, an order, a note, a contract, or any other object your account has defined. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Operation** | Add new record · Edit existing record | Whether to create or update. | | **Customer ID** | Text / variable | Which customer the record belongs to. Defaults to `{{customer.id}}`. | | **Object type** *(required)* | Dropdown of the account's enabled CRM objects | Which object this record is. **The field list below follows this choice.** | | **Record ID** | Text / variable | Which record to edit. Appears only for **Edit existing record**. | | **Record fields** | Rows of field → value | The dropdown lists the real fields of the selected object type. Disabled until an object type is chosen. Values support variables. | ![Customer Record configuration](pathname:///img/screenshots/product/studio/action-customer-record.png) ### Outputs | Variable | Holds | | --- | --- | | `{{record.status}}` | `created` or `updated` | | `{{record.id}}` | The record | | `{{record.schema_id}}` | The object type | | `{{record.customer_id}}` | The customer | Values are validated against the object's field definitions before anything is written, so a bad value fails the block instead of corrupting the record. :::tip Creating a record here fires the [Customer record trigger](./triggers.md#customer-record-trigger). That is useful for chaining flows — but watch out for a flow that triggers itself. ::: --- ## HTTP Request Sends data to an external system, or fetches data from one. This is the general-purpose bridge between Teloring and the rest of your stack. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Method** | GET · POST · PUT · PATCH · DELETE · COPY · HEAD · OPTIONS | The HTTP method. | | **URL** *(required)* | Text / variable | The full URL. Variables are supported, for example `https://api.example.com/orders/{{contact.id}}`. | | **Request headers** | Key/value rows | Any headers you need. `Content-Type`, `Cache-Control`, `User-Agent`, and `Accept` are offered as presets. Values support variables. | | **Body type** | None · JSON · Form data | What to send in the body. | | **JSON body** | Text area | Appears for JSON. Must be valid JSON. | | **Form fields** | Key/value rows | Appears for Form data. Values support variables. | | **Request timeout (seconds)** | 1–60 | How long to wait for the server. | | **Capture response for next actions** | On / Off | See below. | ![HTTP Request configuration](pathname:///img/screenshots/product/studio/action-http-request.png) ### Capture response — on or off? | Setting | Behavior | Use when | | --- | --- | --- | | **Off** | Fire-and-forget. The request is queued and sent in the background; the flow continues immediately. | You are notifying an external system and do not need its answer. | | **On** | The flow waits for the response and exposes it as variables. | You need the answer — an order status, a price, a customer ID. | ### Outputs | Variable | Holds | | --- | --- | | `{{http.status}}` | Send status | | `{{http.task_id}}` | Background job ID, when capture is off | | `{{http.status_code}}` | HTTP status code, for example `200` | | `{{http.ok}}` | `true` for a 2xx response | | `{{http.content_type}}` | The response content type | | `{{http.body}}` | The raw response body | | `{{http.json}}` | The response parsed as JSON | | `{{http.headers}}` | The response headers | | `{{http.error}}` | The error, if the call failed | When the response is a JSON object, its fields are also flattened into their own variables — `{{http.json.order_id}}`, `{{http.json.customer.name}}`, and so on. ### Variables inside a JSON body Studio is type-aware when it fills a JSON body: - A variable that fills a **whole value** — written bare (`"answers": {{answers.list}}`) or as a complete quoted string (`"answers": "{{answers.list}}"`) — keeps its real JSON type. Arrays stay arrays, numbers stay numbers, objects stay objects. - A variable **inside a longer string** (`"greeting": "Hi {{contact.name}}!"`) is substituted as text, with quotes and special characters safely escaped. - A variable that resolves to nothing is left as-is. The editor validates the JSON while you type. Invalid JSON turns the box red and puts a warning badge on the block; you can keep editing, but fix it before publishing. ### Security Studio only calls **public** `http://` and `https://` addresses. Localhost, private networks, loopback, link-local, and cloud metadata addresses are blocked, so a flow can never be used to reach inside infrastructure. --- ## Send Email Sends an email. This is a pure send — it does **not** create a conversation, a contact, or a message in any inbox timeline, so you can email a manager, a supplier, or an internal alias without polluting an inbox. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Send from** | One of my email inboxes · Teloring system sender | Who the email comes from. | | **Email inbox** | Dropdown of connected email inboxes | Appears for the inbox option. Any connected email inbox can send — conversation inboxes and sending-only inboxes alike. | | **System sender** | Read-only notice | Appears for the system option, showing the address that will be used. | | **To** *(required)* | Text / variable | One or more addresses. Defaults to `{{contact.email}}`. | | **CC** · **BCC** · **Reply-To** | Text / variable | Optional. | | **Subject** *(required)* | Text / variable | The subject line. | | **Body format** | Plain text · HTML | How the body is written. | | **Body** *(required)* | Text area | The email content. Variables are supported. | | **Custom headers** | Key/value rows | Optional technical headers. `X-Teloring-Flow`, `X-Campaign`, `X-Priority`, and `List-Unsubscribe` are offered as presets. | ![Send Email configuration](pathname:///img/screenshots/product/studio/action-send-email.png) ### Outputs | Variable | Holds | | --- | --- | | `{{email.status}}` | `sent`, `failed`, or `test` | | `{{email.message_id}}` | The sent message | | `{{email.from}}` · `{{email.to}}` · `{{email.subject}}` | What was sent, and to whom | | `{{email.provider}}` | Which transport delivered it | | `{{email.error}}` | The error, if it failed | ### Recipients and limits - **To**, **CC**, **BCC**, and **Reply-To** accept several addresses separated by commas, semicolons, or new lines, and understand the `Name ` form. - Every address is validated and de-duplicated. **25 recipients** in total, at most. - At most **10** custom headers. Addressing and threading headers (From, To, Cc, Bcc, Reply-To, Subject, Message-ID, Content-Type, …) are set in the fields above and cannot be overridden here. - Whichever body format you choose, both a text and an HTML part are sent, so the email renders everywhere. :::caution Replies to the **Teloring system sender** do not come back into Teloring. If you want answers, either send from one of your own inboxes or set a **Reply-To**. ::: :::note A **Test Run** resolves the sender and validates everything, but sends nothing. The block reports `email.status` = `test`. ::: --- ## Code Runs a small **JavaScript** transform and returns a value for the blocks below it. Use it for the things a text field cannot do: cleaning a phone number, splitting a name, reformatting an ID, picking one item out of a list. ### Properties | Property | What it does | | --- | --- | | **JavaScript code** *(required)* | The code to run. It **must** `return` a value. | New blocks start with a working example: ```javascript const phone = "{{contact.phone}}"; const cleanNumber = phone.replace(/^\+/, ''); return cleanNumber; ``` ### Reading variables Two ways, both fine: ```javascript // 1 — substituted before the code runs const name = "{{contact.name}}"; // 2 — read from the frozen variables object const phone = variables["contact.phone"]; ``` ### Outputs | Variable | Holds | | --- | --- | | `{{code.status}}` | Result | | `{{code.result}}` | The returned value, with its type preserved | | `{{code.result_text}}` | The returned value as text | | `{{code.error}}` | The error, if the code failed | ### What the sandbox allows The Code block runs isolated, with a memory cap and a short time limit. It is meant for data manipulation only: | Allowed | Blocked | | --- | --- | | String, number, array, object, date, and regex operations | `fetch`, `XMLHttpRequest`, `WebSocket` — no network | | The `variables` object and any `{{variable}}` you substitute | `require`, `import`, `process` — no modules, no environment | | Returning any JSON-serializable value | `eval`, `Function`, `WebAssembly` | Code that does not return a value fails the block on purpose, so the flow never continues with missing data. To call an external service, use [HTTP Request](#http-request). --- ## Date and Time Calculates and formats dates. Every operation is timezone-aware. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Operation** | Get current date/time · Add time · Subtract time · Format date · Extract part · Time between dates · Round date | What to calculate. | | **Input date** | Text / variable | The date to work on, in ISO form. **Leave empty for "now".** | | **Second date** | Text / variable | The other date. Appears for **Time between dates**. | | **Amount** | Number | How much to add or subtract. Appears for **Add** and **Subtract**. | | **Unit** | Seconds · Minutes · Hours · Days · Weeks | The unit for Amount. | | **Part** | Date · Time · Year · Month · Day · Hour · Minute · Weekday | Which piece to pull out. Appears for **Extract part**. | | **Format** | Text | The output pattern, for example `%Y-%m-%d %H:%M:%S`. Appears for **Format date**. | | **Timezone** | Text | The timezone the calculation runs in. Defaults to `Asia/Jerusalem`. | ### Outputs | Variable | Holds | | --- | --- | | `{{datetime.status}}` | Result | | `{{datetime.result}}` | The calculated value | | `{{datetime.result_text}}` | The value as text | | `{{datetime.date}}` · `{{datetime.time}}` | Date part and time part | | `{{datetime.timestamp}}` | Unix timestamp | **Good uses:** work out a follow-up date three days out, format a timestamp for a customer-facing message, or measure how long a conversation has been open before deciding to escalate. --- ## Send Teloring Notification Alerts agents **inside Teloring** — the notification bell, a sound, an email, and a browser push. Use it for anything the two built-in notification types do not cover: a new lead, an analytics threshold, an SLA about to breach, a form submission, a VIP customer writing in. This is the flexible half of [Notifications](../notifications.md). The profile page ships two ready-made types ("a conversation was assigned to me" and "a new message arrived") so an agent who never opens Studio still gets something useful. Everything beyond that is built here. :::info The flow chooses what and who. The recipient chooses how. This block decides the **text** and the **recipients**. It never decides how the notification reaches them — that stays with each agent, in their own profile. An agent who enabled only the bell gets a bell entry. A colleague on the same notification who enabled all four gets a sound, an email, a push, *and* a bell entry. An agent with notifications switched off — or with **Studio notifications** switched off — gets nothing at all, and the flow carries on normally. ::: ### Properties | Property | Options | What it does | | --- | --- | --- | | **Send to** *(required)* | Specific agents · The agent assigned to this conversation · Everyone in a team | Who is notified. | | **Agents** | Checkbox list of agents | Appears for *Specific agents*. Human agents only — an AI Agent has no inbox to notify. | | **Team** | Dropdown of teams | Appears for *Everyone in a team*. Every member is notified. | | **Conversation ID** | Text / variable | Appears for *The agent assigned to this conversation*. Defaults to `{{conversation.id}}`. | | **Message** *(required)* | Text area | The text agents see. Variables are supported — `New contact {{contact.name}} created!` | | **Extra details** | Text area | An optional second line, shown in the bell list, the email, and the browser push. | | **Clicking the notification opens** | The conversation from this flow · Nothing — text only · A specific Teloring page | Where the notification links to. | | **Teloring page** | Text / variable | Appears for the specific-page option. A path inside Teloring, such as `/dashboard/customers`. | ![Send Teloring Notification configuration](pathname:///img/screenshots/product/studio/action-notify-agents.png) ### Outputs | Variable | Holds | | --- | --- | | `{{notification.status}}` | `sent`, `no_recipients`, `test_mode`, or `failed` | | `{{notification.recipients}}` | How many agents were targeted | | `{{notification.delivered}}` | How many actually received something, after their own settings were applied | | `{{notification.message}}` | The final text, with variables resolved | | `{{notification.error}}` | The error, if it failed | `recipients` and `delivered` are usually the numbers you want when debugging. `recipients: 3, delivered: 0` means the flow found three agents and none of them had Studio notifications switched on. ### Understanding "Send to" | Option | Resolves to | When nobody matches | | --- | --- | --- | | **Specific agents** | Exactly the agents you ticked. | The block reports `no_recipients`. | | **The agent assigned to this conversation** | Whoever currently owns the conversation. | An unassigned conversation has no owner, so the block completes with `no_recipients`. This is **not** an error — the flow continues. | | **Everyone in a team** | Every member of the chosen team, at the moment the block runs. | An empty or deleted team reports `no_recipients`. | ### Limits and safety - **External links are impossible.** The **Teloring page** field only accepts a path inside Teloring. An absolute URL is dropped, so a notification can never be turned into a link to an outside site. - **Message** is trimmed to 160 characters and **Extra details** to 600. - The text is displayed as plain text everywhere it appears, including inside the email. - An empty **Message** fails the block. As everywhere in Studio, a variable that cannot be resolved is left visible (`{{contact.name}}`) rather than silently blanked, so you can spot the mistake. - The same notification cannot reach the same agent twice within 60 seconds. :::note A **Test Run** resolves the recipients and the text and validates everything, but notifies nobody. The block reports `notification.status` = `test_mode`. Testing a flow never rings real agents. ::: ### Example — tell the Sales team about a new lead 1. **Trigger:** Customer Changed → *created* 2. **Condition:** If/Else → `{{customer.new.lifecycle_stage}}` equals `lead` 3. **Then:** Send Teloring Notification - **Send to:** Everyone in a team → *Sales* - **Message:** `New lead: {{customer.new.name}}` - **Extra details:** `Phone {{contact.phone}} · Source {{customer.new.source}}` - **Clicking the notification opens:** A specific Teloring page → `/dashboard/customers` Every member of Sales who has **Studio notifications** enabled is alerted, each through their own chosen methods. ## Next - [Conditions — the IF blocks](./conditions.md) — sending the flow down the right path. - [Variables](./variables.md) — the full variable reference. - [Flow recipes](./examples.md) — these actions used in complete flows. --- # Conditions — the IF blocks Source: https://docs.teloring.com/docs/product/studio/conditions Markdown: https://docs.teloring.com/markdown/docs/product/studio/conditions.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z A **condition** decides which way the flow goes. It carries the amber **IF** badge and has **one output port per outcome**, so you can wire a different path to each one. Studio has three condition blocks: | Block | Question it asks | Outputs | | --- | --- | --- | | [Condition If/Else](#condition-ifelse) | Does this value match my rule? | One port per IF branch, plus an optional ELSE | | [Business Hours](#business-hours) | Are we open right now? | **Open** · **Closed** | | [Agent Availability](#agent-availability) | Is anyone signed in to take this? | **Online** · **Offline** | All three appear in the **Flow** group of the block picker, and all three work in both messaging and voice flows. ![A flow branching on a condition](pathname:///img/screenshots/product/studio/condition-branches-canvas.png) --- ## Condition If/Else Routes the flow by comparing a value against a rule. Each rule you add becomes its own labelled output port. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Match mode** | First match only · All matching branches | What to do when more than one rule matches. | | **IF branches** | A list of rules | Each row is one branch. See below. | | **Add ELSE branch** | On / Off | Adds a catch-all port for everything that matched nothing. | | **ELSE label** | Text | The name shown under the ELSE port. Defaults to *Everything else*. | ### Anatomy of a rule Each IF row has four parts: | Part | What to put in it | | --- | --- | | **Branch label** | A short name — `Sales`, `Support`, `VIP`. It becomes the port label on the canvas, so make it readable. | | **Value / variable** | The thing being tested, written as a plain variable key: `message.content`, `client_reply.content`, `http.json.status`. | | **Operator** | How to compare. See the table below. | | **Compare as** | Text · Number · Boolean · Variable — how to read the right-hand side. | | **Compare to** | What to compare against: a word, a number, `true`, or another variable. | ![Condition If/Else configuration](pathname:///img/screenshots/product/studio/condition-if-else.png) ### Operators | Operator | True when | Notes | | --- | --- | --- | | **equals** | The two values are the same | | | **does not equal** | They differ | | | **contains** | The right-hand text appears anywhere in the left-hand value | Not case-sensitive | | **does not contain** | It does not appear | Not case-sensitive | | **starts with** | The value begins with the text | Not case-sensitive | | **ends with** | The value ends with the text | Not case-sensitive | | **greater than** | Left > right | Numbers only; a non-numeric value is never a match | | **greater/equal** | Left ≥ right | Numbers only | | **less than** | Left < right | Numbers only | | **less/equal** | Left ≤ right | Numbers only | | **exists** | The value is present and not empty | **Compare to** is ignored | | **does not exist** | The value is missing or empty | **Compare to** is ignored | :::tip `contains` is the workhorse for customer replies — people type "sales please" and "I need SALES", not "sales". Reach for `equals` only when you control the value, for example an HTTP response code or an IVR digit. ::: ### Match mode | Mode | Behavior | | --- | --- | | **First match only** | Rules are checked top to bottom; the first one that matches wins and only its branch runs. Order your rules from most specific to most general. | | **All matching branches** | Every rule that matches runs its branch, in parallel. | The **ELSE** branch runs only when no IF rule matched at all. ### Branch ports Every IF rule adds a port under the block, labelled with the branch name; ELSE adds one more. Drag a connector from each port to whatever should happen on that path. A port you leave unconnected simply ends that path — which is a perfectly good way to say "do nothing in this case". ### Conditions after a wait When a condition sits after a **Reply Message** with *Wait for client response* on, it evaluates against the customer's answer. Both `{{message.content}}` and `{{client_reply.content}}` hold that answer. :::caution If a post-wait condition matches nothing **and has no ELSE branch**, the flow stays parked at the condition and re-evaluates on the customer's next message. That is useful for "keep asking until they pick a valid option", but it means a customer can loop forever. Always give them a way out: an ELSE branch, a handover to a human, or an [End Session](./actions.md#end-session) block. ::: --- ## Business Hours Routes the flow by a **named schedule** you defined in Settings — weekly opening hours in a chosen timezone, with optional holiday calendars. ### Properties | Property | What it does | | --- | --- | | **Schedule** *(required)* | Pick one of the account's business-hours schedules. | ### Outputs | Port | Runs when | | --- | --- | | **Open** | The current time falls inside the schedule's opening hours. | | **Closed** | It falls outside them, or the day is a holiday on a calendar the schedule considers. | | Variable | Holds | | --- | --- | | `{{business_hours.status}}` | `open` or `closed` | | `{{business_hours.schedule_id}}` | Which schedule was evaluated | | `{{business_hours.timezone}}` | The schedule's timezone | ### Notes - The schedule's **own timezone** is used, not the customer's and not the browser's. A team in Tel Aviv and a team in London can each have their own schedule in the same account. - Schedules are created in **Settings → Business Hours**. New accounts have none — create the ones you actually need. See [Settings](../settings.md). - The same schedule can be reused by any number of flows. Change the hours once and every flow follows. **Good uses:** an out-of-hours auto-reply on messaging, and a "we're closed, leave a message" branch on a phone flow. --- ## Agent Availability Asks whether anyone is **signed in to Teloring right now** — the same green dot you see in Team Chat. It is a live-session check, not a status an agent sets. ### Properties | Property | Options | What it does | | --- | --- | --- | | **Check** | Specific agents · Anyone in the account | Who to look at. | | **Agents to check** *(required for Specific)* | Agent picker | The agents this branch depends on. | | **Consider online when** | At least one selected agent is online · All selected agents are online | How strict the check is. Appears for **Specific agents**. | ![Agent Availability configuration](pathname:///img/screenshots/product/studio/condition-agent-availability.png) ### Outputs | Port | Runs when | | --- | --- | | **Online** | The check passed. | | **Offline** | It did not. | | Variable | Holds | | --- | --- | | `{{availability.status}}` | `online` or `offline` | | `{{availability.online_count}}` · `{{availability.offline_count}}` · `{{availability.checked_count}}` | The counts behind the answer | | `{{availability.online_ids}}` · `{{availability.offline_ids}}` | Which agents | | `{{availability.first_online_id}}` · `{{availability.first_online_name}}` | A convenient "someone who can take this" | ### Two rules worth knowing - **An empty selection is never "everybody".** If **Check** is set to *Specific agents* and no agent is selected, the result is **Offline** and the block shows a warning. This is deliberate: an unfinished block must not quietly behave like *Anyone in the account* and pass because some unrelated teammate happens to be signed in. - **AI Agents never count as online.** They hold no session, so an always-available AI Agent cannot satisfy a human-availability branch. They are also left out of the picker. :::tip `{{availability.first_online_name}}` is handy for a message like `Connecting you to {{availability.first_online_name}}…` right before you hand the conversation over. ::: ## Next - [Actions — the THEN blocks](./actions.md) — what each branch can do. - [Variables](./variables.md) — what you can test in a rule. - [Flow recipes](./examples.md) — branching used in complete flows. --- # Studio Source: https://docs.teloring.com/docs/product/studio Markdown: https://docs.teloring.com/markdown/docs/product/studio.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z **Studio** is Teloring's visual flow builder. You draw a flow on a canvas — *when this happens, do that* — and Teloring runs it automatically, around the clock, for every conversation, call, form, schedule, or external event you point it at. Anything a person does repeatedly in Teloring can usually be moved into Studio: greeting a new WhatsApp message, asking two qualifying questions and routing the answer to the right team, opening an IVR menu for phone calls, pushing a new lead into an external CRM, emailing a manager when a report crosses a threshold, or tagging and closing conversations on a schedule. Studio is built from three kinds of block: | Badge | Block kind | Question it answers | | --- | --- | --- | | **WHEN** | [Trigger](./studio/triggers.md) | What starts this flow? | | **THEN** | [Action](./studio/actions.md) | What should Teloring do? | | **IF** | [Condition](./studio/conditions.md) | Which way should the flow go? | You connect the blocks with lines, press **Publish**, and the flow is live. ![Teloring Studio flow editor](pathname:///img/screenshots/product/studio/flow-editor.png) ## Two ways to build a flow Every flow can be built by hand or by AI. You choose when you create it. | Way | How it works | Guide | | --- | --- | --- | | **I'll build my own** | You drag blocks onto the canvas and configure them yourself. | This page | | **Use AI to build** | You answer a short interview in plain language and **Hermes** builds the flow for you. | [Build a flow with AI](./studio/ai-flow-builder.md) | Both produce the same thing: an ordinary draft flow you can edit and publish. Building with AI requires the **AI Studio** switch in [AI World](./ai-world.md). ## Key facts | Fact | Meaning | | --- | --- | | Every flow starts with a trigger | A flow with no **WHEN** block can never run and cannot be published. | | Draft and live are separate | Editing never touches the running version. Only **Publish** does. | | One flow can have several triggers | For example one Incoming Message trigger for WhatsApp and another for Telegram, in the same flow. Only the trigger that matches the real event runs. | | Blocks can branch and fan out | One block can feed several blocks. All connected paths run. | | Studio respects human agents | If a human agent owns a conversation, Studio stays out of it completely. | | Values flow forward as variables | Anything an earlier block produced can be dropped into a later block as `{{a.variable}}`. | | Two kinds of flow | **Voice flows** (started by Incoming Call) and **messaging flows** (everything else). Each has its own blocks. | | Account-isolated | Flows, variables, and executions belong to one account and are never visible to another. | | Test before you publish | **Test Run** executes the draft with sample data and sends nothing to real customers. | | AI can build the first draft | With **AI Studio** enabled, [Hermes](./studio/ai-flow-builder.md) interviews you and lays out the whole flow. What it produces is a normal draft you edit and publish yourself. | ## Who uses Studio | Role | Typical use | | --- | --- | | Admins | Build and publish flows, connect webhooks and external systems, manage saved variables and versions. | | Team managers | Design routing, business-hours behavior, escalation, and follow-up rules. | | Agents | Benefit from the results — pre-qualified conversations, correct labels, auto-assigned queues, private notes with context. | ## Core concepts ### Flow A **flow** is one automation: a canvas holding blocks and the lines between them. Flows have a name, an optional description, and a status (**Draft**, **Live**, or **Paused**). ### Block A **block** is one step. Every block has: - a **badge** — WHEN, THEN, or IF — and a color that matches it; - an **input port** on top (except triggers, which start the flow); - one or more **output ports** on the bottom; - a **Configuration** panel on the right where you set its properties; - **output variables** it hands to every block downstream of it. | Badge | Color | Meaning | | --- | --- | --- | | **WHEN** | Coral | Trigger — the entry point | | **THEN** | Teal | Action — does something | | **IF** | Amber | Condition — chooses a path | | **NOTE** | Amber | Sticky note — a comment for your team, never executed | ### Connection A line from one block's **output port** to the next block's **input port**. The line shows the direction of travel with an animated dotted flow. Blocks with more than one output — a condition, an IVR menu, Forward to Agent, an Analytics Alert — have one port per outcome, labelled underneath. Wire each outcome to whatever should happen next; a port you leave unconnected simply ends that path. ### Messaging flows vs. voice flows The moment you drop an **Incoming Call** trigger on the canvas, the flow becomes a **voice flow** and the block library changes: | Flow kind | Starts with | Blocks available | | --- | --- | --- | | **Messaging flow** | Any trigger except Incoming Call | Reply Message, Wait, and every general block | | **Voice flow** | Incoming Call | Play Sound, IVR Menu, Wait / Pause, Forward to Agent, Forward to External Phone, Hang Up, and every general block | Studio hides out-of-scope blocks from the picker, flags them on the canvas if a flow somehow contains one, and refuses to publish a flow that mixes them. See [Voice call flows](./studio/voice-flows.md). ## The Studio list Open **Studio** from the left sidebar to see every flow in the account. ![Teloring Studio flow list](pathname:///img/screenshots/product/studio/flow-list.png) | Control | Use it to | | --- | --- | | **New Flow** | Create a flow. You are asked for a name, an optional description, and whether to build it yourself or with AI. | | **Search** | Filter the list by flow name. | | **All / Draft / Live / Paused** | Filter by status. | | **Flow card** | Click anywhere on the card to open the flow. | | **Card footer** | Shows when the flow was created, when it was last edited, and who edited it. | | **⚡ Continue with AI badge** | The flow has an unfinished [Hermes interview](./studio/ai-flow-builder.md). Clicking the card reopens the conversation instead of the canvas; the **Edit** button still opens the canvas. | | **Edit / Delete** | Row actions. Delete works on any flow, live included — you must type the flow's name to confirm. See [deleting a flow](./studio/publishing.md#deleting-a-flow). | | **Warning badge** | Appears when a flow depends on something that no longer exists (for example a deleted analytics alert). The flow is paused automatically until you fix and republish it. | ### Create your first flow 1. Click **New Flow**. 2. Give it a clear, specific name — `WhatsApp — after-hours auto reply` beats `Flow 3`. 3. Add a description so your teammates know what it does. 4. Choose **How would you like to build it?** — **I'll build my own** or **Use AI to build**. One of the two is required; the button stays disabled until you pick. Choosing AI opens the [Hermes interview](./studio/ai-flow-builder.md) instead of the canvas. 5. Click **Create Flow**. The editor opens on an empty canvas. 6. Drag a **trigger** from the left panel onto the canvas. 7. Drag a connector from the trigger's bottom port and release it on empty canvas — the **block picker** opens. 8. Pick an action, configure it on the right, and repeat. 9. **Test Run**, then **Publish**. ![Choosing how to build a new flow](pathname:///img/screenshots/product/studio/ai/new-flow-choose-mode.png) ## The editor ![Studio editor anatomy](pathname:///img/screenshots/product/studio/editor-anatomy.png) ### Top bar | Control | What it does | | --- | --- | | **←** | Back to the flow list. | | **Flow name** | Click to rename. Saved with the flow. | | **Status badge** | Draft, Live, or Paused. | | **Save indicator** | Shows *Saving…*, *Saved*, *Unsaved*, or *Save failed*. | | **Test Run** | Runs the draft with sample data. Nothing reaches real customers. | | **⚙ Flow Settings** | Auto-save switch, **Pause / Resume flow**, and the list of saved `var.*` variables. | | **Auto-save pill** | Shows whether auto-save is On or Off. | | **💾 Save now** | Saves the draft immediately (`Cmd/Ctrl+S`). | | **Publish** | Makes the current draft the live version. | ### Left panel — Block Library The left panel holds the two things you drag onto the canvas: - **WHEN — Triggers.** Every trigger available to the account. - **NOTE — Editor Tools.** The **Sticky Note**. Below them, the **Version** bar shows the current version number and the last save time. Click it to open [version history](./studio/publishing.md#version-history). :::tip Actions and conditions are **not** in the left panel. You add them from the block picker, which opens when you drag a connector out of a block and drop it on empty canvas. That way every new block is already connected to the one before it. ::: ### Adding an action or condition 1. Point at the bottom port of an existing block. 2. Drag out a line and release it on empty canvas. 3. The **block picker** opens. 4. Either type in **Search all blocks…** to search every block at once by name, description, or group, or browse the groups and open one to see its blocks. 5. Click a block. It is created on the canvas, already connected. ![Studio block picker](pathname:///img/screenshots/product/studio/block-picker.png) Blocks are organized into six groups: | Group | What's in it | | --- | --- | | **Conversations** | Reply Message, Private Note, Change Conversation, End Session | | **Flow** | Condition If/Else, Business Hours, Agent Availability, Wait, Save as Variable | | **CRM** | Contact Update, Customer Record | | **Voice** | Play Sound, Wait / Pause, IVR Menu, Forward to Agent, Forward to External Phone, Hang Up | | **External** | HTTP Request, Send Email | | **Tools** | Code, Date and Time | The picker only ever lists blocks that are legal in the current flow — a messaging flow never shows voice blocks, and a voice flow never shows Reply Message or Wait. ### Canvas | Gesture | Result | | --- | --- | | Drag empty canvas | Pan the view. | | Scroll wheel | Zoom in and out. | | Drag a block | Move it. | | Click a block | Select it and open its properties. | | Drag output port → input port | Connect two blocks. | | Hover a connection, click **✂** | Disconnect the two blocks. Both blocks stay on the canvas. | | Click a connection | Select it. | The bottom toolbar has zoom in/out, the zoom percentage, **Fit to View**, **Undo**, **Redo**, **Duplicate selected**, and **Delete selected**. A **minimap** in the bottom-right corner shows the whole flow and where you are in it. :::note You cannot connect anything *into* a trigger — triggers are always the start of a path. You also cannot connect a sticky note to anything. ::: ### Right panel — Properties Select any block and the right panel fills with its settings. ![Studio properties panel](pathname:///img/screenshots/product/studio/properties-panel.png) | Section | What it holds | | --- | --- | | **Configuration** | Every property of the selected block. Fields appear and disappear based on your choices — for example **Wait timeout** only appears once **Wait for client response** is on. | | **Available Variables** | Everything the blocks *above* this one produce, grouped by namespace (System, Message, Conversation, Contact, Channel, Reply, and more). Drag a variable straight into a text field, or click it to copy. See [Variables](./studio/variables.md). | | **Execution Log** · *Soon* | Per-block run history. Not available yet — the section is marked **Soon**, and an empty log there does not mean the block failed to run. | ### Warnings on a block A block shows a **⚠ warning badge** on the canvas, and an explanation at the top of its properties panel, when Studio can see it will not work: | Warning | What it means | | --- | --- | | This block is not connected to anything | Nothing points into it, so it can never run. Drag a connector from an earlier block into its top port. | | This is a voice block | It is in a messaging flow. Voice blocks only work in a flow that starts with Incoming Call. | | This block is not supported in Incoming Call voice flows | Use Play Sound, IVR, or a voice transfer instead. | | A required choice is missing | For example Send Email with no inbox, or Customer Record with no object type. | | Invalid JSON body | An HTTP Request whose JSON body no longer parses. | | The selected analytics alert no longer exists | The alert was deleted in Analytics. | You can keep editing with warnings on the canvas, but fix them before you publish — the publish dialog reminds you, and some warnings block publishing outright. ### Sticky notes Drag **Sticky Note** from **Editor Tools** onto the canvas to leave a comment for whoever opens the flow next: why a branch exists, what an external system expects, who to ask about it. Sticky notes have a title and a body, can be resized from the bottom-right corner, and have no ports. They are **editor-only** — they are never executed and are not part of the published flow. ### Keyboard shortcuts | Shortcut | Action | | --- | --- | | `Cmd/Ctrl + S` | Save the draft now | | `Cmd/Ctrl + Z` | Undo (up to 50 steps) | | `Cmd/Ctrl + Y` | Redo | | `Cmd/Ctrl + D` | Duplicate the selected block | | `Delete` | Delete the selected block or connection | Duplicating a block copies its type and all of its settings, but not its connections — wire the copy in yourself. ## How a flow runs 1. **An event happens** — a customer messages you, a call arrives, a form is submitted, a webhook is called, a schedule comes due, a record changes. 2. **Studio looks for live flows** whose trigger matches that event. Draft and paused flows are ignored. 3. **The matching trigger node runs.** If a flow holds two Incoming Message triggers — one for WhatsApp, one for Telegram — only the one whose settings match the event starts. 4. **The flow walks forward** along the connections. Where a block has several outgoing lines, **all** of them run. Where a condition chose a branch, only that branch runs. 5. **Each block adds its outputs to the flow's variables**, so later blocks can use them. 6. **A block can pause the flow** — Reply Message waiting for the customer's answer, or a Wait counting down. The rest of the flow resumes later, exactly where it stopped. Other branches keep running in the meantime. 7. **The run finishes** when every path has ended. Every run is recorded as an **execution** with a status: | Status | Meaning | | --- | --- | | `running` | Currently executing. | | `waiting` | Paused for a customer reply or a timer. | | `completed` | Every path finished. | | `failed` | A block returned an error. | | `timed_out` | A wait expired before the customer replied. | | `cancelled` | The run was stopped. | ## Studio and human agents When a flow starts handling a conversation, the conversation moves into the **Studio Bot** queue and shows that a flow owns it. This keeps bots and people from replying over each other. | Situation | What Studio does | | --- | --- | | Conversation has no agent | A matching flow can take it over and run. | | Conversation is assigned to a human agent | Studio **skips it entirely** — no triggers, no waiting flows, no replies. | | A flow hands the conversation to a human (**Human intervention**) | Studio releases ownership. Later messages go to the person, not back into the flow. | | The conversation is resolved | The handover marker is cleared, so a future re-open can be automated again. | | A flow runs **End Session** | Studio releases the conversation, and the next customer message starts trigger matching from scratch. | See [Change Conversation](./studio/actions.md#change-conversation) and [End Session](./studio/actions.md#end-session). ## Limits | Limit | Value | | --- | --- | | Blocks per flow | 200 | | Connections per flow | 500 | | Saved versions kept per flow | 50 (the most recent) | | Undo history | 50 steps | | Wait block | 1–15 seconds | | Voice Wait / Pause | 0–30 seconds | | Wait for a customer reply | Up to 30 days | | Recurring Schedule interval | 1 minute – 24 hours | | HTTP Request timeout | 1–60 seconds | | Email recipients per Send Email | 25 | | Custom email headers | 10 | ## Where to go next | Page | What it covers | | --- | --- | | [Build a flow with AI (Hermes)](./studio/ai-flow-builder.md) | Describe what you want, answer a few questions, and let AI lay out the flow. | | [Triggers — the WHEN blocks](./studio/triggers.md) | Every trigger, its properties, and the variables it produces. | | [Actions — the THEN blocks](./studio/actions.md) | Every action, its properties, and its outputs. | | [Conditions — the IF blocks](./studio/conditions.md) | Branching, operators, business hours, and agent availability. | | [Variables](./studio/variables.md) | The `{{variable}}` system and the full variable reference. | | [Voice call flows](./studio/voice-flows.md) | Building phone flows: greetings, IVR menus, transfers, recording. | | [Test, publish, and versions](./studio/publishing.md) | Draft vs. live, testing, publishing, rolling back. | | [Flow recipes](./studio/examples.md) | Complete, worked examples you can copy. | | [Troubleshooting](./studio/troubleshooting.md) | Why a flow didn't fire, and how to fix it. | --- # Variables Source: https://docs.teloring.com/docs/product/studio/variables Markdown: https://docs.teloring.com/markdown/docs/product/studio/variables.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z A **variable** is a placeholder that Studio fills in while the flow runs. Write `{{contact.name}}` in a message and the customer sees *Dana*. Variables are what make a flow feel personal instead of canned, and they are how one block passes information to the next. ## The syntax Always two curly braces around a key: ```text Hi {{contact.name}}, we received your message about {{message.content}}. ``` | Rule | Detail | | --- | --- | | Format | `{{namespace.key}}` — for example `{{conversation.id}}` | | Case | Keys are lowercase with dots. | | Unknown keys | Left exactly as they are, so a typo shows up in the output instead of silently vanishing. | | Where they work | Any text field, text area, URL, header value, JSON body, email field, or condition operand. | ## Inserting a variable Select a block and open **Available Variables** in the right panel. It lists everything the blocks *above* this one produce, grouped by namespace. ![Available Variables panel](pathname:///img/screenshots/product/studio/variables-panel.png) | Action | Result | | --- | --- | | Drag a variable into a field | It is inserted at the drop point. | | Click a variable | It is copied, ready to paste. | | Click a namespace heading | Expands or collapses that group. | :::tip The list is position-aware. A block near the top of the flow sees fewer variables than a block at the bottom, because it genuinely has less to work with. If a variable you expect is missing, the block that produces it is not upstream of the block you selected. ::: ## The namespaces | Namespace | Comes from | Example | | --- | --- | --- | | `system.*` | Always available | `{{system.timestamp}}` | | `var.*` | [Save as Variable](./actions.md#save-as-variable) — persists between runs | `{{var.last_order_id}}` | | `message.*` | Incoming Message trigger | `{{message.content}}` | | `conversation.*` | Most conversation triggers and actions | `{{conversation.id}}` | | `conversation.custom_attributes.*` | Your account's [conversation attributes](../conversation-attributes.md) | `{{conversation.custom_attributes.outcome}}` | | `contact.*` | Conversation and message triggers | `{{contact.name}}` | | `channel.*` | Conversation and message triggers | `{{channel.name}}` | | `customer.*` | Customer triggers | `{{customer.name}}` | | `record.*` · `objects.*` | Customer record trigger and Customer Record action | `{{record.id}}` | | `agent.*` | Agent status trigger | `{{agent.name}}` | | `call.*` · `voice.*` | Voice trigger and voice actions | `{{call.caller_id}}` | | `form.*` · `answers.*` · `hiddenValues.*` · `sourceParams.*` | Form filled trigger | `{{answers.email}}` | | `webhook.*` | Incoming webhook trigger | `{{webhook.body.order_id}}` | | `schedule.*` | Schedule triggers | `{{schedule.triggered_at}}` | | `alert.*` | Analytics Alert trigger | `{{alert.current_value}}` | | `change.*` · `ai.*` | Conversation Changed trigger | `{{change.type}}` · `{{ai.signal}}` | | `reply.*` · `client_reply.*` | Reply Message action | `{{client_reply.content}}` | | `http.*` | HTTP Request action | `{{http.json.status}}` | | `email.*` | Send Email action | `{{email.status}}` | | `code.*` | Code action | `{{code.result}}` | | `datetime.*` | Date and Time action | `{{datetime.result}}` | | `condition.*` · `availability.*` · `business_hours.*` | Condition blocks | `{{availability.status}}` | | `session.*` · `saved_variable.*` · `private_note.*` · `wait.*` | The matching actions | `{{session.resolved}}` | ## System variables Always present, in every flow, from the very first block. | Variable | Holds | | --- | --- | | `{{system.timestamp}}` | The current time, in ISO format | | `{{system.account_id}}` | Your account ID | | `{{system.flow_id}}` | The flow that is running | | `{{system.execution_id}}` | This specific run | `{{system.execution_id}}` is worth including in HTTP requests and email headers — it is the fastest way to tie an external record back to one Studio run. ## Saved variables — `var.*` Ordinary variables live for exactly one run. A **saved variable** lives forever. | Property | Behavior | | --- | --- | | Created by | The [Save as Variable](./actions.md#save-as-variable) action | | Scope | Per flow — two flows can each hold their own `var.counter` | | Availability | Loaded into **every** run of that flow, so they work from the first block onward | | Namespace | Forced into `var.`, so a saved value can never overwrite a system, contact, conversation, or message variable | | Dynamic keys | Allowed — `var.{{contact.phone}}.address` stores one value per phone number | | Managed in | **⚙ Flow Settings → Saved variables**, where you can review and delete them | ## Reference by trigger Which variables you have depends on what started the flow. Each trigger's full list is on the [Triggers](./triggers.md) page; here is the short version. | Trigger | You get | | --- | --- | | Incoming Message | `message.*`, `conversation.*`, `contact.*`, `channel.*` | | Incoming Call | `call.*`, `conversation.*`, `contact.*`, `channel.*` | | Form filled | `form.*`, `submission.id`, `answers.*`, `hiddenValues.*`, `sourceParams.*`, `contact.id`, `conversation.id` | | Conversation Changed | `conversation.*` (including `previous_*`), `change.*`, `ai.*`, `contact.*`, `channel.*` | | Customer trigger | `customer.*` (including `customer.old` / `customer.new`), `event.*` | | Customer record trigger | `record.*`, `objects.*`, `customer.*`, `event.*` | | Agent status changes | `agent.*` | | Recurring Schedule / Scheduled Time | `schedule.*` | | Incoming webhook | `webhook.*`, plus one variable per learned field | | Analytics Alert | `alert.*` | ### Object and array variables Some variables hold a whole object or list rather than a single value: | Variable | Shape | Reach inside it with | | --- | --- | --- | | `{{http.json}}` | The response object | `{{http.json.order_id}}` | | `{{webhook.body}}` | The request body | `{{webhook.body.customer.email}}` | | `{{webhook.query}}` · `{{webhook.headers}}` | Objects | `{{webhook.query.token}}` | | `{{answers}}` | Answers keyed by field ID | `{{answers.email}}` | | `{{hiddenValues}}` | Hidden values keyed by field ID | `{{hiddenValues.campaign_id}}` | | `{{sourceParams}}` | URL parameters | `{{sourceParams.utm_source}}` | | `{{answers.list}}` | An array of answers | Pass it whole to an HTTP request, or loop over it in a [Code](./actions.md#code) block | | `{{customer.old}}` · `{{customer.new}}` · `{{record.old}}` · `{{record.new}}` | Before/after snapshots | `{{record.new.status}}` | | `{{conversation.custom_attributes}}` | Every [conversation attribute](../conversation-attributes.md) | `{{conversation.custom_attributes.order_number}}` | The exact keys inside these objects come from **your** data. `{{answers.email}}` only works if a form field has the Field ID `email`; `{{webhook.body.order_id}}` only works if the payload actually contains `order_id`. For webhooks, use **Learn next request** and Studio will list the real keys for you. ## Conversation attributes [Conversation Attributes](../conversation-attributes.md) are your account's own fields on a conversation — *Reason for contact*, *Outcome*, *Order number*. Each one becomes a variable named after its **API ID**: ``` {{conversation.custom_attributes.reason_for_contact}} {{conversation.custom_attributes.order_number}} {{conversation.custom_attributes}} ← the whole set, as one object ``` | Fact | Detail | | --- | --- | | Where they come from | The **Incoming Message**, **Incoming Call** and **Conversation Changed** triggers all load the conversation's current values, so they are available from the first block. | | After they are written | A [Change Conversation](./actions.md#setting-conversation-attributes) block that sets attributes updates these variables, so every block below it reads the **new** values. | | Never filled in | Resolves to an empty value rather than leaving the raw `{{placeholder}}` in your request. | | Naming | The **API ID**, not the label. Renaming an attribute's label is safe; renaming its API ID changes the variable name. | Send the whole set to an external system in one field by putting `{{conversation.custom_attributes}}` in a JSON body, or pick one out for a lookup: ```json { "conversation_id": "{{conversation.id}}", "order": "{{conversation.custom_attributes.order_number}}", "disposition": {{conversation.custom_attributes}} } ``` ## Variables in a JSON body The [HTTP Request](./actions.md#http-request) block is type-aware when it fills a JSON body: ```json { "customer": "{{contact.name}}", "answers": {{answers.list}}, "greeting": "Hi {{contact.name}}!" } ``` | Placement | Result | | --- | --- | | A variable filling a whole value, bare or fully quoted | Keeps its real JSON type — an array stays an array, a number stays a number | | A variable inside a longer string | Substituted as text, with quotes and special characters safely escaped | | A variable that resolves to nothing | Left untouched | ## Variables in a Code block Inside a [Code](./actions.md#code) block you can either substitute a variable into the source, or read it from the frozen `variables` object: ```javascript // substituted before the code runs const name = "{{contact.name}}"; // read by key — better for values that might contain quotes const phone = variables["contact.phone"]; return name + " / " + phone.replace(/^\+/, ''); ``` ## Variables in a condition In a [Condition If/Else](./conditions.md#condition-ifelse) rule, the **Value / variable** field takes a plain key **without** the braces: | Field | Write | | --- | --- | | Value / variable | `message.content` | | Compare to (as *Variable*) | `var.expected_answer` | | Compare to (as *Text*) | `sales` | ## Practical tips - **Personalize safely.** `{{contact.name}}` can be empty for a brand-new WhatsApp contact. Either accept a slightly bare greeting, or branch on `contact.name` with the **exists** operator first. - **Copy IDs into your systems.** `{{conversation.id}}`, `{{contact.id}}`, and `{{system.execution_id}}` are the values worth pushing into an external CRM so both sides can be reconciled later. - **Use the panel, not memory.** Dragging a variable from **Available Variables** guarantees the key is spelled the way the runtime expects. - **Print it to check it.** If you are not sure what a variable holds, drop a temporary [Private Note](./actions.md#private-note) into the branch containing it. The note is internal, so it costs you nothing and shows the resolved value exactly as the flow saw it. ## Next - [Actions](./actions.md) — every block's outputs. - [Triggers](./triggers.md) — every trigger's variables. - [Troubleshooting](./troubleshooting.md) — what to do when a variable renders empty. --- # Voice call flows Source: https://docs.teloring.com/docs/product/studio/voice-flows Markdown: https://docs.teloring.com/markdown/docs/product/studio/voice-flows.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z A **voice flow** is a Studio flow that answers the phone. It plays your greeting, offers a keypad menu, checks whether you are open, rings an agent's browser, transfers to an outside number, and hangs up — all from the same canvas you use for messaging flows. Everything a caller experiences on a Teloring number is defined here. There is no separate "call settings" screen: the [voice inbox](../ring/voice.md) holds the number, and the flow holds the behavior. ![A voice flow on the canvas](pathname:///img/screenshots/product/studio/voice-flow-canvas.png) ## What makes a flow a voice flow Drop an **Incoming Call** trigger on the canvas and the flow becomes a voice flow. From that moment: - The **Voice** group appears in the block picker — Play Sound, Wait / Pause, IVR Menu, Forward to Agent, Forward to External Phone, Hang Up. - **Reply Message** and **Wait** disappear. A phone call has no message thread to reply into. - The general blocks stay available: conditions, HTTP Request, Send Email, Private Note, Change Conversation, Contact Update, Customer Record, Code, Date and Time, Save as Variable. If a flow somehow ends up with a block from the wrong side — pasted in, or left over from an earlier design — the block gets a warning badge and the flow cannot be published until you remove it. ## Before you build | Step | Where | | --- | --- | | Connect a voice number | [My Ring → Voice](../ring/voice.md) | | Create your business-hours schedules | [Settings → Business Hours](../settings.md) | | Record your prompts as WAV files | Any audio tool. 8 kHz mono PCM is the safe format. | | Give agents a voice extension | [Agents](../agents.md) | :::tip Record every prompt before you start building. A voice flow is mostly audio, and it is much easier to lay out when you already know what each prompt says. ::: --- ## Incoming Call — the trigger Starts the flow when a call arrives on the selected number. | Property | What it does | Default | | --- | --- | --- | | **Voice inbox** *(required)* | Which voice inbox / DID runs this flow. | — | | **Record this call** | Records every call that enters the flow. | Off | ### Recording Recording is controlled **only here**. When it is on: - The whole call is recorded, from the moment it enters the flow. - When the call ends, the recording is uploaded to your account's private storage. - A **private note** with the recording details is added to the conversation. - The recording is attached to the customer's record and appears in the [Files Warehouse](../files-warehouse.md). :::caution Call recording carries legal obligations in most countries — usually an announcement at the start of the call. Add a **Play Sound** block with a recording notice as the first step of a recorded flow, and check your local rules. ::: ### Variables `{{call.uuid}}`, `{{call.caller_id}}`, `{{call.destination}}`, `{{call.direction}}`, `{{call.timestamp}}`, `{{call.inbox_id}}`, `{{call.contact_id}}`, `{{call.contact_name}}`, plus `{{conversation.id}}`, `{{contact.*}}`, and `{{channel.*}}`. Unknown callers are matched or created as a lead automatically, so `{{contact.id}}` is always usable. --- ## Play Sound Plays an audio prompt to the caller, then continues to the next block. | Property | What it does | | --- | --- | | **Audio prompt** *(required)* | Upload a WAV file, or pick one you already uploaded. | | Output | Holds | | --- | --- | | `{{voice.play_sound.file_id}}` | The file that was played | ### Audio requirements | Requirement | Detail | | --- | --- | | Format | **WAV only.** Other formats are rejected at upload. | | Recommended encoding | 8 kHz, mono, PCM | | Storage | Uploaded to your account's private file storage and served only to the phone system | Free — playing audio does not consume credits. --- ## Wait / Pause Inserts a short silence before the next block. Useful between two prompts, or to give a caller a beat before a menu. | Property | Range | Default | | --- | --- | --- | | **Wait duration (seconds)** | 0–30 | 2 | | Output | Holds | | --- | --- | | `{{wait.seconds}}` | How long it paused | *Voice flows only. Messaging flows use the [Wait](./actions.md#wait) block instead.* --- ## IVR Menu Plays a menu prompt and routes the call by whichever key the caller presses. This is the heart of most phone flows. ![IVR Menu configuration](pathname:///img/screenshots/product/studio/voice-ivr-menu.png) | Property | What it does | Default | | --- | --- | --- | | **Menu audio prompt** *(required)* | The WAV that reads out the options. | — | | **Accepted digits** | The keypad options. Each row has a **digit** and a **label**. | `1 · Sales`, `2 · Support` | | **Input timeout (ms)** | How long to wait for a keypress, in milliseconds (1000–60000). | 7000 | | **Max attempts** | How many times to replay the menu before giving up (1–5). | 2 | ### Outputs on the canvas The block grows **one port per digit**, plus two more: | Port | Runs when | | --- | --- | | `1`, `2`, `3` … | The caller pressed that key. The port is labelled with the digit and your label, for example `1 · Sales`. | | **Timeout** | The caller pressed nothing within the input timeout. | | **Invalid** | The caller pressed a key that is not in your list. | | Variable | Holds | | --- | --- | | `{{voice.ivr.digit}}` | The digit that was pressed | | `{{voice.ivr.branch}}` | The branch that was taken | | `{{call.digit}}` · `{{call.gathered_digits}}` | The last digit, and everything gathered | :::tip Always wire **Timeout** and **Invalid** to something — usually back into the same menu, or straight to an agent. A caller who presses the wrong key and hits a dead end just hears silence. ::: Free — an IVR menu does not consume credits. --- ## Forward to Agent Rings an agent **in their browser** and connects the caller once they answer. | Property | Options | Default | | --- | --- | --- | | **Routing** | Specific agent · Any available agent | Specific agent | | **Agent** | Agent picker. Appears for **Specific agent**. | — | | **Ring timeout (seconds)** | 5–120 | 30 | **Any available agent** picks the first agent who is currently signed in for voice. If nobody is signed in, it falls back to the first agent who has a voice extension. ### Two outputs | Port | Runs when | | --- | --- | | **Completed** | The agent answered and the call has now ended. Use this for post-call work — logging, a CRM record, a satisfaction email. | | **Rejected** | The agent declined, or the ring timed out with no answer. Use it to try another agent, offer voicemail, or hang up politely. | An unconnected output simply ends the call. ### What the caller and the agent experience 1. The caller hears ringback while Teloring waits. 2. A call popup appears for the agent, with the caller's number and contact details. 3. **Answer** connects the two sides immediately. 4. **Reject**, or letting the ring timeout expire, takes the **Rejected** path. 5. When either side hangs up, the **Completed** path runs. ### Variables available on Completed Because these appear only after the call, they are ideal for pushing a full call record into an external system: | Variable | Holds | | --- | --- | | `{{voice.forward.status}}` · `{{voice.forward.agent_id}}` | Result of the transfer | | `{{call.agent_id}}` · `{{call.agent_name}}` | Who took the call | | `{{call.duration_seconds}}` | Total call length, arrival to hangup | | `{{call.talk_duration_seconds}}` | Talk time, answer to hangup | | `{{call.wait_duration_seconds}}` | How long the caller waited before being answered | | `{{call.started_at}}` · `{{call.answered_at}}` · `{{call.ended_at}}` | Timestamps | | `{{call.conversation_id}}` · `{{call.customer_id}}` | Where the call is recorded | Free — internal transfers do not consume credits. :::note Agents must have their Teloring tab open to be rung. There is no permanent phone registration, so a signed-out agent is simply not reachable — pair this block with an [Agent Availability](./conditions.md#agent-availability) condition to choose a different path when nobody is around. ::: --- ## Forward to External Phone Transfers the caller to an outside phone number — an on-call mobile, a partner office, an answering service. | Property | What it does | Default | | --- | --- | --- | | **External phone number** *(required)* | The destination, in international form (`+972501234567`). Variables are supported. | — | | **Ring timeout (seconds)** | 5–120 | 30 | | Variable | Holds | | --- | --- | | `{{voice.forward.status}}` | Result of the transfer | | `{{voice.forward.external_number}}` | The number that was dialled | The number you were originally called on is used as the outbound caller ID, so the person receiving the transfer sees your business number. :::caution **This block bills credits.** Forwarding to an external phone number places a real outbound call. Internal transfers to agents are free. ::: --- ## Hang Up Ends the call. | Property | Options | Default | | --- | --- | --- | | **Hangup cause** | Normal clearing · Busy · No answer | Normal clearing | | Variable | Holds | | --- | --- | | `{{voice.hangup.cause}}` | The cause that was sent | Use **Normal clearing** for an ordinary goodbye. **Busy** and **No answer** exist so the calling network sees a meaningful reason, which matters if callers are routed by another system before they reach you. :::tip End every path with either a transfer or an explicit Hang Up, after a closing prompt. A path that just stops leaves the caller in silence until the line drops. ::: --- ## Conditions in a voice flow All three [condition blocks](./conditions.md) work on calls: | Condition | Typical voice use | | --- | --- | | **Business Hours** | Open → menu; Closed → "we're closed" prompt and hang up. | | **Agent Availability** | Online → Forward to Agent; Offline → voicemail prompt or external forward. | | **Condition If/Else** | Route VIP callers by `call.caller_id`, or branch on a customer status you fetched with HTTP Request. | ## A typical structure ```text Incoming Call (record: on) └─ Play Sound "Welcome to Acme. This call may be recorded." └─ Business Hours ├─ Open ──── IVR Menu "Press 1 for sales, 2 for support" │ ├─ 1 · Sales ──── Agent Availability │ │ ├─ Online ── Forward to Agent ──┬─ Completed ─ HTTP Request (log the call) │ │ │ └─ Rejected ── Play Sound "Sorry we missed you" ─ Hang Up │ │ └─ Offline ─ Play Sound "Leave a message" ─ Hang Up │ ├─ 2 · Support ── Forward to External Phone │ ├─ Timeout ────── Play Sound (replay) ─ IVR Menu │ └─ Invalid ────── Play Sound "That wasn't an option" ─ IVR Menu └─ Closed ── Play Sound "We're closed. Our hours are…" ─ Hang Up ``` ## Checklist before you publish - [ ] Every IVR digit port is wired, including **Timeout** and **Invalid**. - [ ] Every path ends in a transfer or a Hang Up. - [ ] The closed-hours path says something useful, not just silence. - [ ] If recording is on, the first prompt announces it. - [ ] Every prompt is a WAV file, and you have listened to each one. - [ ] **Forward to Agent** has a **Rejected** path. - [ ] You called the number yourself and walked every branch. :::note **Test Run** exercises the flow's logic with sample data, but it cannot place a real call. The only true test of a voice flow is to dial the number. ::: ## Next - [Voice inbox](../ring/voice.md) — connecting the number and the agent softphone. - [Conditions](./conditions.md) — business hours and availability branching. - [Flow recipes](./examples.md) — a complete phone-menu example. --- # Test, publish, and versions Source: https://docs.teloring.com/docs/product/studio/publishing Markdown: https://docs.teloring.com/markdown/docs/product/studio/publishing.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z Studio keeps **what you are editing** and **what is running** strictly apart. You can rebuild a live flow in the middle of a busy Monday and nothing changes for your customers until you press **Publish**. ## Draft, live, paused | Status | Meaning | | --- | --- | | **Draft** | The flow has never been published. It does not react to anything. | | **Live** | A published version is running and handling real events. | | **Paused** | The flow still exists, with every block intact, but it reacts to nothing. You set this with [Pause flow](#pause-and-resume); Teloring also sets it automatically when a flow depends on something that was deleted. | Every flow actually holds **two copies** of the canvas: | Copy | What it is | Changed by | | --- | --- | --- | | **Draft** | What you see in the editor. | Every edit you make, saved automatically. | | **Live** | What real events run against. | **Publish**, and nothing else. | Editing a live flow is safe. Your changes accumulate in the draft; the version that customers hit is the one you last published. :::note A flow built by [Hermes](./ai-flow-builder.md) arrives as a **draft** too. The AI never publishes anything — you review it on the canvas, Test Run, and publish exactly as you would a flow you drew yourself. ::: ## Saving ### Auto-save Auto-save is on by default. A couple of seconds after you stop editing, the draft is saved and the indicator in the top bar moves from **Unsaved** to **Saving…** to **Saved**. ### Manual save Turn auto-save off in **⚙ Flow Settings** when you want full control. Canvas changes then mark the editor as **Unsaved** and nothing is written until you click the **💾** button or press `Cmd/Ctrl+S`. ![Flow settings](pathname:///img/screenshots/product/studio/flow-settings.png) The Flow Settings dialog also lists the flow's [saved variables](./actions.md#save-as-variable), where you can review and delete them. :::note Saving is **not** publishing. A saved draft still has no effect on live traffic. ::: ## Test Run **Test Run** executes the draft — the version on your screen — with sample data. | What it does | What it does not do | | --- | --- | | Walks the flow from the first trigger | Send messages to customers | | Runs conditions and reports which branches matched | Send emails (Send Email validates and reports `test`) | | Reports how many blocks executed | Write CRM records | | Surfaces configuration errors immediately | Place phone calls | ![Test run result](pathname:///img/screenshots/product/studio/test-run.png) The result shows the run **Status** and the number of **Blocks executed**. If the flow has no trigger yet, Studio tells you to add one first. :::tip Test Run proves the flow's *shape* — that the blocks are wired, configured, and reachable. It cannot prove the wording of a message or the timing of a wait. For those, publish to a test inbox and message yourself. ::: ## Publishing Click **Publish** to make the draft the live version. ![Publish confirmation](pathname:///img/screenshots/product/studio/publish-modal.png) The confirmation dialog summarizes what you are about to release: | Line | Meaning | | --- | --- | | **Triggers** | How many trigger blocks the flow has. | | **Blocks** | How many blocks in total. | | **Version** | The version number the flow will become. | | **Warning** | Appears when any block still shows a warning badge. | Confirm and the flow goes **Live** immediately. ### What publishing does 1. Copies the draft onto the live version. 2. Increments the version number. 3. Saves a snapshot in version history. 4. Clears the "unpublished changes" state. 5. Switches on monitoring for any [Analytics Alerts](./triggers.md#analytics-alert) the flow references. 6. Clears any dependency warning that had paused the flow. ### What blocks a publish | Reason | Fix | | --- | --- | | The flow has no trigger | Add a **WHEN** block. | | A voice block is in a messaging flow, or the reverse | Remove the out-of-scope block. Its warning badge names the problem. | Other warnings — an unconnected block, a missing email inbox, invalid JSON — do not hard-block publishing, but the dialog reminds you and you should fix them first. :::caution Publishing affects **real customers immediately**. Test with a quiet inbox, or with a trigger filtered to a single test inbox, before you publish anything that replies to people. ::: ## Version history Studio keeps the **50 most recent snapshots** of each flow. Click the **Version** bar at the bottom of the left panel to open the list. ![Version history](pathname:///img/screenshots/product/studio/version-history.png) Each entry shows the version number, when it was saved, who saved it, how many blocks and connections it had, whether it is the live one, and how it was created: | Source | Created by | | --- | --- | | **Auto save** | Auto-save while editing | | **Manual save** | The 💾 button or `Cmd/Ctrl+S` | | **Published** | A publish | | **Restored** | Making an older version live | ### Previewing a version Click a version to open it on the canvas in **read-only preview**. A banner across the top says *Read-only preview*, and editing, saving, and testing are switched off so you cannot accidentally work on the wrong copy. From the banner you can: | Button | What it does | | --- | --- | | **Make live** | Promotes this snapshot to the live version. | | **Exit preview** | Returns to your draft, exactly as you left it. | If you have unsaved changes when you open a preview, Studio warns you first. Your draft is not lost — it is hidden until you exit the preview. ### Rolling back **Make live** is the rollback button. It: 1. Checks that the snapshot has at least one trigger. 2. Promotes it to the live version **and** into your draft. 3. Increments the version number and marks the flow **Live**. 4. Writes a restore snapshot, so the rollback itself is undoable. :::tip Rolling back is the fastest fix when a freshly published flow misbehaves. Open version history, preview the version that worked, and click **Make live** — then debug the broken draft without any pressure. ::: ## Pause and resume **Pause** switches a live flow off without changing or deleting anything. Open the flow, click **⚙ Flow Settings**, and use **Pause flow** under **Flow activity**. ![Pause a flow from Flow Settings](pathname:///img/screenshots/product/studio/flow-pause.png) | While paused | Detail | | --- | --- | | The flow reacts to nothing | Incoming messages, calls, form submissions, schedules, webhooks, and analytics alerts all pass it by. | | Nothing is deleted | Every block, connection, saved version, and saved variable stays exactly as it was. | | The status badge reads **Paused** | Both in the editor and on the flow's card in the list. | | Conversations are handed back | Anything the flow was holding leaves the Studio Bot queue for **Waiting in line**, so a customer mid-bot-conversation is not left waiting for a bot that will never answer. | | Branches parked on a wait stop too | A flow waiting on a customer reply or a Wait countdown does not continue while paused. | | You can keep editing | The draft behaves as normal. | | Analytics alerts are released | A paused flow stops monitoring the alerts it referenced. | **Resume flow** — the same button, once the flow is paused — switches it back on. :::note Resuming restores the **last published version**, not your current draft. Un-pausing can therefore never ship a half-finished edit by accident. To make draft changes live, use **Publish**. ::: Resuming brings the flow back for *new* events. Conversations that were released while it was paused stay with the agents who picked them up — they are not pulled back into the bot. Pause is only available on a live flow. On a draft, the button is disabled — there is nothing running to stop. | Goal | How | | --- | --- | | Stop a flow temporarily | **⚙ Flow Settings → Pause flow.** Reversible in one click. | | Start it again | **⚙ Flow Settings → Resume flow.** | | Ship draft changes | **Publish.** | | Remove a flow for good | [Delete it](#deleting-a-flow). | | Change a flow safely | Edit freely. The draft has no effect until you publish. | ## Deleting a flow Every flow card in the list has a **Delete** action, live flows included. Because deleting is permanent, the dialog asks you to type the flow's exact name before the button unlocks. ![Delete a flow](pathname:///img/screenshots/product/studio/delete-flow-modal.png) Deleting is a full teardown: | What goes | Detail | | --- | --- | | Every block and connection | The canvas is emptied and the flow is removed. | | The flow itself | No trigger, schedule, or webhook can ever start it again. | | All saved versions | The 50-snapshot history goes with it — there is no rollback afterwards. | | The flow's saved variables | Every `var.*` value this flow stored is removed. | | Runs that were still waiting | A run parked on a customer reply or a timer is cancelled rather than left to resume into nothing. | Conversations the flow was handling are **not** deleted. They are released from the Studio Bot queue and land back in **Waiting in line**, so an agent can pick them up straight away. :::caution Deleting a **live** flow stops it instantly, including mid-conversation. If a customer was halfway through a bot conversation, the bot simply stops replying and the conversation moves to the waiting queue. If you only need to switch a flow off, [pause it](#pause-and-resume) instead. ::: ## Automatic pausing If a flow depends on something that gets deleted, Teloring pauses it rather than letting it fail quietly. Today this applies to [Analytics Alerts](./triggers.md#analytics-alert): delete an alert (or the report behind it) and every flow referencing it is flagged. The flow card shows a warning badge with the reason, the block that references the missing alert is marked invalid in the editor, and a live flow is switched to **Paused**. Pick a different alert — or remove the block — and publish again. Publishing clears the flag. ## A safe release routine 1. Build on a draft. 2. **Test Run** and fix anything it reports. 3. Clear every warning badge on the canvas. 4. Point the trigger at a single test inbox and publish. 5. Message that inbox yourself and walk each branch. 6. Widen the trigger to the real inboxes and publish again. 7. Keep watching that inbox for the first few real runs. ## Next - [Troubleshooting](./troubleshooting.md) — when a flow does not fire. - [Flow recipes](./examples.md) — complete flows to start from. --- # Flow recipes Source: https://docs.teloring.com/docs/product/studio/examples Markdown: https://docs.teloring.com/markdown/docs/product/studio/examples.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z Complete, working flows you can build in a few minutes each. Every recipe lists the blocks, their settings, and the reasoning behind them. :::tip Every recipe below can also be described to [Hermes](./ai-flow-builder.md) in a sentence — *"qualify a new WhatsApp lead and send them to sales or support"* — and built for you. The recipes are still worth reading: they show what a good flow looks like, which makes it easy to check the AI's work. ::: | Recipe | Trigger | Good for | | --- | --- | --- | | [Instant welcome reply](#1-instant-welcome-reply) | Incoming Message | Any new inbox | | [After-hours auto-reply](#2-after-hours-auto-reply) | Incoming Message | Teams with fixed hours | | [Qualify and route a new lead](#3-qualify-and-route-a-new-lead) | Incoming Message | Sales and support split | | [Escalate an unhappy customer](#4-escalate-an-unhappy-customer) | Conversation Changed | Retention | | [Push a new lead into an external CRM](#5-push-a-new-lead-into-an-external-crm) | Form filled | Integrations | | [Start a conversation from an external system](#6-start-a-conversation-from-an-external-system) | Incoming webhook | Order and delivery updates | | [Daily morning summary](#7-daily-morning-summary) | Scheduled Time | Managers | | [Alert a manager when a metric slips](#8-alert-a-manager-when-a-metric-slips) | Analytics Alert | Operations | | [Phone menu with agent transfer](#9-phone-menu-with-agent-transfer) | Incoming Call | Voice | --- ## 1. Instant welcome reply Answer within a second, so nobody waits in silence. ```text Incoming Message (Inboxes: WhatsApp) └─ Reply Message └─ End Session ``` | Block | Settings | | --- | --- | | **Incoming Message** | Tick your WhatsApp inbox. | | **Reply Message** | `Hi {{contact.name}}! Thanks for contacting Acme. One of our team will be with you shortly.` · Wait for client response: **off** | | **End Session** | Resolve the conversation: **off** | **Why End Session?** Without it, Studio keeps owning the conversation and it sits in the Studio Bot queue. End Session releases it so it appears in **Waiting in line** for an agent to pick up. :::tip `{{contact.name}}` is empty for a first-time contact on some channels. Either write a greeting that reads well without it, or branch on `contact.name` with the **exists** operator. ::: --- ## 2. After-hours auto-reply Say something useful when you are closed, and stay quiet when you are open. ```text Incoming Message └─ Business Hours ├─ Open ──── (nothing — let agents handle it) └─ Closed ── Reply Message ── End Session ``` | Block | Settings | | --- | --- | | **Incoming Message** | Leave inboxes empty to cover every channel. | | **Business Hours** | Pick the schedule you created in Settings → Business Hours. | | **Reply Message** (Closed) | `Thanks for your message! Our team is offline right now. We're open Sunday–Thursday, 09:00–18:00, and will reply first thing.` | | **End Session** | Resolve: **off** | Leaving the **Open** port unconnected is deliberate — during working hours the flow should do nothing at all and let agents reply normally. --- ## 3. Qualify and route a new lead Ask one question, then send the conversation to the right team with the right label. ```text Incoming Message └─ Reply Message (wait for reply) └─ Condition If/Else ├─ Sales ───── Change Conversation (label: sales, hand over to queue) ├─ Support ─── Change Conversation (label: support, hand over to queue) └─ Else ────── Reply Message "Sorry, I didn't catch that…" ``` | Block | Settings | | --- | --- | | **Reply Message** | `Hi! Are you contacting us about **sales** or **support**? Just reply with one word.` · Wait for client response: **on** · Wait timeout: `60` | | **Condition If/Else** | Match mode: **First match only** · Add ELSE branch: **on** | | — IF 1 | Label `Sales` · Value `message.content` · Operator **contains** · Compare as Text · Compare to `sales` | | — IF 2 | Label `Support` · Value `message.content` · Operator **contains** · Compare as Text · Compare to `support` | | **Change Conversation** (Sales) | Labels mode: Add · Labels: `sales` · Human intervention: **on** · Hand over to: **Waiting in line** | | **Change Conversation** (Support) | Same, with the `support` label. | | **Reply Message** (Else) | `Sorry, I didn't catch that. Please reply with "sales" or "support".` · Wait for client response: **on** | **Why `contains` and not `equals`?** People type *"sales please"* and *"I need SALES"*. `contains` is not case-sensitive and matches inside a sentence. **The ELSE loop.** The ELSE branch asks again and waits again, so the customer gets another chance. Consider adding a **Save as Variable** counter, or a third strike that hands over to a human, so a confused customer is never stuck. --- ## 4. Escalate an unhappy customer React the moment AI detects frustration. ```text Conversation Changed (AI Signals: Feelings / emotion detected) └─ Condition If/Else └─ Negative ── Change Conversation (priority: urgent, flag: important) └─ Private Note └─ Send Email ``` | Block | Settings | | --- | --- | | **Conversation Changed** | AI Signals: **Feelings / emotion detected**. Leave the other filters on *any*. | | **Condition If/Else** | IF `Negative` · Value `conversation.customer_emotion` · Operator **less than** · Compare as Number · Compare to `3` | | **Change Conversation** | Priority: **Urgent** · Flag: **Important** · Human intervention: **on** · Hand over to: **Waiting in line** | | **Private Note** | `⚠️ AI detected negative sentiment ({{conversation.customer_emotion}}). Signal: {{ai.message}}` | | **Send Email** | To your team lead · Subject `Escalation: {{contact.name}}` · Body includes `{{conversation.id}}` and `{{ai.message}}` | --- ## 5. Push a new lead into an external CRM Send every form submission straight to another system, and record the result. ```text Form filled (Form: Contact us) └─ HTTP Request (capture response: on) └─ Condition If/Else ├─ Success ── Save as Variable ── Private Note └─ Else ───── Send Email (alert the admin) ``` | Block | Settings | | --- | --- | | **Form filled** | Pick the specific form. | | **HTTP Request** | Method **POST** · URL your CRM endpoint · Header `Content-Type: application/json` · Body type **JSON** · Capture response **on** · Timeout `15` | | **Condition If/Else** | IF `Success` · Value `http.ok` · Operator **equals** · Compare as Boolean · Compare to `true` | | **Save as Variable** | Key `var.{{contact.id}}.crm_id` · Value `{{http.json.id}}` · Type Text | | **Private Note** | `Lead synced to CRM as {{http.json.id}}.` | | **Send Email** (Else) | To your admin · Body includes `{{http.status_code}}` and `{{http.error}}` | JSON body: ```json { "name": "{{answers.full_name}}", "email": "{{answers.email}}", "phone": "{{answers.phone}}", "source": "{{sourceParams.utm_source}}", "answers": {{answers.list}}, "teloring_contact_id": "{{contact.id}}", "teloring_execution_id": "{{system.execution_id}}" } ``` **Note the unquoted `{{answers.list}}`.** Because the variable fills a whole value, Studio inserts the real array instead of a string. See [Variables in a JSON body](./variables.md#variables-in-a-json-body). --- ## 6. Start a conversation from an external system Let your order platform tell a customer their delivery is on the way. ```text Incoming webhook └─ Reply Message └─ Contact Update ``` | Block | Settings | | --- | --- | | **Incoming webhook** | Copy the URL · Allowed methods **POST** · Learn next request **on**, then send one real request. | | **Reply Message** | Conversation ID `{{webhook.body.conversation_id}}` · Message `Good news {{contact.name}} — order {{webhook.body.order_id}} is out for delivery. Track it here: {{webhook.body.tracking_url}}` | | **Contact Update** | Field `last_order_status` → `{{webhook.body.status}}` | **Getting the conversation ID.** A webhook flow has no conversation of its own, so `{{conversation.id}}` is empty. Either have the caller send a conversation ID in the payload, as above, or look it up with an HTTP Request first. --- ## 7. Daily morning summary A private note in a chosen conversation, or an email, every working morning. ```text Scheduled Time (Sun–Thu, 08:30, Asia/Jerusalem) └─ HTTP Request (capture response: on) └─ Send Email ``` | Block | Settings | | --- | --- | | **Scheduled Time** | Five rows: Sunday–Thursday, hour `8`, minute `30`, timezone `Asia/Jerusalem`. | | **HTTP Request** | Fetch whatever numbers you want to report. Capture response **on**. | | **Send Email** | To the team · Subject `Morning summary — {{datetime.result}}` · Body built from `{{http.json...}}` values | Add a **Date and Time** block before the email (operation **Format date**, format `%d/%m/%Y`) if you want a friendly date in the subject. --- ## 8. Alert a manager when a metric slips Wire an Analytics alert to a real notification, and let people know when it recovers. ```text Analytics Alert (Alerts: "Waiting conversations over 20") ├─ Alert ────── Send Email ── Change Conversation (priority: urgent) └─ Recovered ── Send Email ``` | Block | Settings | | --- | --- | | **Analytics Alert** | Tick the alert you created in Analytics. | | **Send Email** (Alert) | Subject `🔴 {{alert.name}}` · Body `{{alert.report_title}} is {{alert.current_value}} ({{alert.direction}} the threshold of {{alert.threshold}}) as of {{alert.crossed_at}}.` | | **Send Email** (Recovered) | Subject `🟢 {{alert.name}} recovered` · Body `{{alert.report_title}} is back to {{alert.current_value}}.` | The alert fires **once** per crossing, so you get one email — not one per minute while the number stays high. --- ## 9. Phone menu with agent transfer A complete inbound call experience. ```text Incoming Call (record: on) └─ Play Sound "Welcome to Acme. This call may be recorded." └─ Business Hours ├─ Open ──── IVR Menu │ ├─ 1 · Sales ──── Agent Availability │ │ ├─ Online ── Forward to Agent ──┬─ Completed ─ HTTP Request │ │ │ └─ Rejected ── Play Sound ─ Hang Up │ │ └─ Offline ─ Play Sound ─ Hang Up │ ├─ 2 · Support ── Forward to External Phone │ ├─ Timeout ────── Play Sound ─ Hang Up │ └─ Invalid ────── Play Sound ─ Hang Up └─ Closed ── Play Sound ─ Hang Up ``` | Block | Settings | | --- | --- | | **Incoming Call** | Voice inbox: your number · Record this call: **on** | | **Play Sound** (greeting) | WAV that includes the recording announcement. | | **Business Hours** | Your schedule. | | **IVR Menu** | Menu prompt WAV · Digits `1 · Sales`, `2 · Support` · Input timeout `7000` · Max attempts `2` | | **Agent Availability** | Check **Specific agents** → your sales team · Consider online when **At least one** | | **Forward to Agent** | Routing **Any available agent** · Ring timeout `30` | | **HTTP Request** (Completed) | Log `{{call.duration_seconds}}`, `{{call.talk_duration_seconds}}`, `{{call.agent_name}}` to your system. | | **Forward to External Phone** | Your support line, in international form. **Bills credits.** | | **Hang Up** | Cause **Normal clearing** | See [Voice call flows](./voice-flows.md) for the full block reference. --- ## Patterns worth reusing | Pattern | How | | --- | --- | | **Always give people an exit** | Every waiting flow needs an ELSE branch or a handover, so a customer is never trapped. | | **Label before you hand over** | A conversation that arrives in the queue already labelled and prioritized saves the agent a step. | | **Leave a note, not a mystery** | A Private Note explaining what the bot collected is worth more to an agent than a clean timeline. | | **Log the IDs** | Send `{{conversation.id}}`, `{{contact.id}}`, and `{{system.execution_id}}` to any external system you call. | | **Sticky-note your branches** | Six months later, a sticky note explaining *why* a branch exists is the difference between improving a flow and rebuilding it. | | **One question per message** | Two questions get one answer, and your condition has nothing clean to match. | ## Next - [Troubleshooting](./troubleshooting.md) — when a recipe does not behave. - [Testing & publishing](./publishing.md) — the safe way to release a flow. --- # Troubleshooting Source: https://docs.teloring.com/docs/product/studio/troubleshooting Markdown: https://docs.teloring.com/markdown/docs/product/studio/troubleshooting.md Section: Studio Last modified: 2026-08-20T20:49:57.000Z Most Studio problems fall into three buckets: the flow never started, the flow started but took the wrong path, or a block did not do what you expected. Work through them in that order. ## Start here 1. **Is the flow Live?** Draft and Paused flows never run on real events. 2. **Did you publish after your last edit?** Editing changes the draft only. 3. **Is the conversation owned by a human?** Studio skips conversations assigned to an agent. 4. **Run a Test Run.** It walks the draft with sample data and reports how many blocks executed, which is the quickest way to tell a configuration problem from a trigger that never matched. :::note The **Execution Log** section in the right panel is marked **Soon** — per-block run history is not available yet. An empty log there is not evidence that a block failed to run. ::: --- ## The flow never runs | Symptom | Likely cause | Fix | | --- | --- | --- | | Nothing happens on a real message | The flow is still Draft, or the last edit was never published | Click **Publish**. | | Nothing happens and the badge reads **Paused** | Someone paused the flow, or Teloring paused it because a dependency was deleted | Open **⚙ Flow Settings → Resume flow**. If the flow card shows a warning badge, fix the block it names and publish instead. | | Nothing happens, and the flow *is* live | The trigger's inbox filter does not include the inbox you tested from | Open the trigger and tick the right inbox — or untick everything to listen on all. | | It worked, then stopped | An agent is assigned to the conversation | Studio stays out of conversations a human owns. Test with a fresh conversation. | | It stopped for one specific customer | A previous run handed that conversation to a human | The handover sticks until the conversation is resolved or a flow runs **End Session**. Resolve it and try again. | | The flow card shows a warning badge | A dependency was deleted — usually an analytics alert | Fix the block it names, then publish again. | | A scheduled flow never fires | The schedule row's timezone, or the day/time, is not what you think | Check the row. Remember a **Days** interval on Recurring Schedule is capped at 24 hours. | | A webhook returns an error | The request does not match the learned format | Turn **Learn next request** back on and send the new shape once. | | Only one of several matching flows runs | It usually does not — all matching live flows run. But once one hands the conversation to a human, the rest are skipped | Check whether an earlier flow has **Human intervention** on. | ## The flow runs but takes the wrong path | Symptom | Likely cause | Fix | | --- | --- | --- | | A condition never matches | The **Value / variable** field has braces around it | Write `message.content`, not `{{message.content}}`, in a condition operand. | | A condition never matches, part two | Using **equals** on free text | Switch to **contains**. Real people type "sales please", not "sales". | | A numeric comparison always fails | The value is not a number | `greater than` and friends only work on numbers. A non-numeric value never matches. | | Two branches ran when you expected one | Match mode is **All matching branches** | Switch to **First match only**, and order the rules from most specific to most general. | | Nothing after the condition ran | No rule matched and there is no ELSE branch | Add an ELSE branch. | | The flow is stuck after a question | A post-wait condition matched nothing and there is no ELSE | The flow waits for the next message and re-evaluates. Add an ELSE branch or an **End Session** block. | | A branch runs but does nothing | Its output port is not connected | Drag a connector from that port. | | A block never runs | It has no incoming connection | The block shows *This block is not connected to anything*. Wire it in. | | Two messages arrived at the same time despite a Wait | Wait only delays its own branch | Siblings run immediately by design. Put the Wait on the shared path if you want everything delayed. | ## A variable is empty | Symptom | Likely cause | Fix | | --- | --- | --- | | `{{some.variable}}` shows up literally in a message | The key does not exist at that point in the flow | Drag it from **Available Variables** instead of typing it. If it is not listed, the block that produces it is not upstream. | | `{{contact.name}}` is empty | The contact is brand new and has no name yet | Branch on `contact.name` with **exists**, or write a greeting that reads well without it. | | `{{conversation.id}}` is empty | The trigger has no conversation — schedule, webhook, analytics alert, agent status | Supply a conversation ID yourself, from the payload or a lookup. | | `{{http.json.something}}` is empty | Capture response is off, or the field is not in the response | Turn **Capture response for next actions** on, then send `{{http.body}}` to a Private Note to see exactly what came back. | | `{{answers.my_field}}` is empty | The form field's **Field ID** is not `my_field` | Field IDs are the variable names. Check the form. | | `{{webhook.body.x}}` is empty | The payload does not contain `x`, or the format was never learned | Use **Learn next request** and read the learned variable chips. | | `{{var.something}}` is empty | Saved variables are per flow | A `var.*` value saved by one flow is not visible to another. | ## A block fails | Block | Symptom | Fix | | --- | --- | --- | | **Reply Message** | Nothing is sent | Check the conversation ID resolves, and that the channel can still send (an expired WhatsApp window, a disconnected inbox). | | **HTTP Request** | Always fails | Studio only calls public addresses. Localhost, private networks, and internal hostnames are blocked. | | **HTTP Request** | Red JSON box | The body is not valid JSON after variables are filled in. Watch for a missing comma or an unquoted string. | | **Send Email** | *Choose which email inbox sends this email* | Pick an inbox, or switch **Send from** to the Teloring system sender. | | **Send Email** | No inboxes in the dropdown | Connect an email inbox in [My Ring](../ring/email.md), or use the system sender. | | **Send Email** | Recipients rejected | Maximum 25 addresses across To, CC, and BCC. Check for a typo. | | **Code** | Fails every time | The code must `return` a value. It also has no network access — use HTTP Request for that. | | **Customer Record** | *Select which object type this record belongs to* | Choose an object type; the field list follows that choice. | | **Customer Record** | Validation failed | A value does not fit the field's type. Check the object's field definitions. | | **Contact Update** | A field is missing from the dropdown | Only fields defined in the contact Field Editor appear. Protected system fields cannot be written. | | **Agent Availability** | Always **Offline** | With **Specific agents** selected and nobody ticked, the answer is always Offline — by design. Pick agents, or switch to *Anyone in the account*. | | **Agent Availability** | An AI Agent is not counted | AI Agents never count as online; they hold no session. | | **Business Hours** | Always **Closed** | Check the schedule's timezone and its weekly hours in Settings, and whether a holiday calendar is closing the day. | ## Voice problems | Symptom | Likely cause | Fix | | --- | --- | --- | | Voice blocks are missing from the picker | The flow has no **Incoming Call** trigger | Only a flow that starts with Incoming Call is a voice flow. | | Publishing is blocked | A messaging block is in a voice flow, or the reverse | Remove the block the warning badge names. | | The prompt does not play | The file is not WAV | WAV only. 8 kHz mono PCM is the safe format. | | Callers hear silence and the line drops | A path ends without a transfer or Hang Up | End every path with a closing prompt and **Hang Up**. | | Pressing a key does nothing | That digit's port is not connected | Wire every digit, plus **Timeout** and **Invalid**. | | Forward to Agent never connects | The agent is not signed in — there is no permanent phone registration | Pair it with **Agent Availability**, and always wire the **Rejected** output. | | No recording was saved | Recording is off at the trigger | Recording is controlled only by **Record this call** on the Incoming Call trigger. | | Test Run does not ring the phone | Test Run cannot place calls | Dial the number for real. | ## Building with AI (Hermes) | Symptom | Likely cause | Fix | | --- | --- | --- | | **Use AI to build** is greyed out | The **AI Studio** switch is off for the account | An admin turns it on in [AI World](../ai-world.md). | | *"This flow already has blocks. Create a new flow to build one with AI."* | You opened the AI builder on a flow that already has a canvas | Hermes only builds into an empty flow, so it can never delete work somebody did by hand. Create a new flow. | | **Build my flow** is refused, pointing at the editor | The canvas was edited by hand during the interview | Your edits win. Finish the flow in the editor, or start a new flow and a new interview. | | The message box is disabled | The flow has been built — the conversation is closed by design | Edit the flow on the canvas, or create a new flow to run a new interview. | | The conversation reopens instead of the canvas | The flow still shows **⚡ Continue with AI** | That is the unfinished interview. Use the card's **Edit** button to reach the canvas instead. | | Hermes picked the wrong inbox or team | It was told the wrong thing, or the resource did not exist yet | Open the block on the canvas and choose the right one. Create missing inboxes and teams *before* the interview. | | A block Hermes made has a ⚠ badge | It needs something only you can supply — usually an uploaded WAV prompt or a WhatsApp template | Open the block and fill it in. The rail's **Needs your attention** list said so during the interview. | | *"Hermes didn't manage to answer that one. Send your message again."* | The AI returned an answer Studio could not read. The turn was **not** saved, so nothing is out of step | Your message is put back in the box — press send again. | | *"That answer was too long for Hermes to finish."* | A single reply exceeded what the AI can produce in one turn | Send the same thing in shorter pieces, or split it across two answers. | | The interview stopped, saying it hit a limit | An interview is capped at 60 questions, and accounts have a short message throttle | Progress is saved. Wait a moment and continue, or finish the flow by hand in the editor. | | I closed the tab and lost my place | You did not — every answer is saved | Reopen the flow from the Studio list and click the card. | ## Things that surprise people | Behavior | Why it works that way | | --- | --- | | Editing a live flow changes nothing until you publish | Draft and live are separate copies on purpose. | | Deleting asks you to type the flow name | Deletion is permanent and takes the versions and saved variables with it, so it needs a deliberate confirmation. | | Pausing is not the same as deleting | A paused flow keeps every block and can be resumed in one click. | | An empty filter means "everything" | An Incoming Message trigger with no inboxes ticked listens on all of them. | | An empty agent selection means "nobody" | On Agent Availability, an unfinished **Specific agents** block must not behave like *anyone*. | | A Wait does not delay other branches | Only the branch the Wait sits on is paused. | | A saved variable is not shared between flows | `var.*` is scoped per flow so two flows cannot overwrite each other. | | Duplicating a block does not copy its connections | You almost never want the copy wired the same way. | | Sticky notes never run | They are editor-only comments and are not part of the published flow. | | Building an AI flow ends the conversation | Once the blocks are yours to edit, a rebuild would have to overwrite your changes. | ## Getting more detail | Where | What it tells you | | --- | --- | | **Test Run** | Whether the draft's shape is valid, without touching customers. | | **A temporary Private Note** | Drop one into a branch with the variables you are unsure about — it is the quickest way to see what a block really produced. | | **Version history** (Version bar) | What changed, when, and who changed it — and the button to roll back. | | **Audit Log** (Settings) | Who published, paused, resumed, restored, or deleted a flow. | ## Next - [Testing & publishing](./publishing.md) — a safe release routine. - [Flow recipes](./examples.md) — known-good flows to compare against. --- # Roles and Permissions Source: https://docs.teloring.com/docs/product/roles/overview Markdown: https://docs.teloring.com/markdown/docs/product/roles/overview.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z 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. ![The Roles and Permissions page showing the five default role cards](pathname:///img/screenshots/product/roles/roles-overview.png) 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. ![A single role card showing its badge, description, agent count and permission count](pathname:///img/screenshots/product/roles/role-card.png) | 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**. ![The role editor with the name and description fields and the two tabs](pathname:///img/screenshots/product/roles/role-editor-header.png) ### 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. ![Delete role dialog asking which role the affected agents move to](pathname:///img/screenshots/product/roles/delete-role.png) | 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 role picker on the agent form, showing the role description underneath](pathname:///img/screenshots/product/roles/agent-role-picker.png) 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. --- # CRM & Customers Source: https://docs.teloring.com/docs/product/crm Markdown: https://docs.teloring.com/markdown/docs/product/crm.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Customers is Teloring's mini CRM. It connects conversations, contacts, calls, documents, journey events, and custom business records around a customer profile. Think of a customer as the main record for a relationship. A customer can represent a business, account, household, organization, or person, depending on how your team works. Around that customer, Teloring connects the people who contact you, their conversations, call history, signed documents, and any custom objects your account creates. ## Customers list Open Customers from the sidebar to see the CRM list. The list includes: | Control | Use it to | | --- | --- | | Search | Find customers by name, contact details, or other searchable information. | | Lifecycle stages | Filter customers by status such as lead, active, inactive, or irrelevant. | | Create customer | Add a new customer manually. | | Field editor | Customize fields shown on customer records. | | Customer cards/grid | Open a customer profile for details and history. | ![Teloring customers list](/img/screenshots/product/crm/customers-list.png) The customer list is usually the best starting point for managers and admins. Agents will often reach the same customer profile from a conversation, using the Customers section in the conversation right sidebar. ## Create a customer To create a customer manually: 1. Open Customers. 2. Click Create customer. 3. Enter the required name. 4. Add optional details such as industry, phone, email, website, assigned agent, address, tags, and notes. 5. Save the customer. ## Customer profile Open a customer to view the full profile. Depending on enabled features and available data, the profile can include: | Area | What it shows | | --- | --- | | Overview | Core customer fields and summary details. | | Journey | Important customer events over time. | | Contacts | Linked contacts and identities. | | Conversations | Related customer conversations across inboxes. | | Calls | Voice activity connected to the customer. | | Documents | Signed or uploaded documents connected to the customer. | | Custom objects | Account-specific records such as assets, service calls, deals, subscriptions, or other business objects. | ![Teloring customer profile](/img/screenshots/product/crm/customer-profile.png) ## Customer header The top of the customer profile shows the most important customer details. This area is meant for quick identification before opening the deeper tabs. It can include: | Item | Meaning | | --- | --- | | Customer name | The primary customer display name. | | Lifecycle stage | The current customer stage, such as lead, active, inactive, or irrelevant. | | Industry | The customer's industry or business category. | | Contact details | Phone, email, website, address, or other key fields. | | Assigned agent | The agent responsible for the customer, when used by the account. | | Tags and notes | Short customer-level context. | Admins can customize the top-level customer fields with the field editor. ## Built-in customer tabs Every customer profile is organized into tabs. Tabs separate different kinds of information so agents and managers can find history quickly. ### Journey Journey is a timeline of important customer events. It helps teams understand how the customer record changed over time. Journey can include events such as: | Event type | Example | | --- | --- | | Customer created | A new customer record was added. | | Field changed | A lifecycle stage, owner, or other field was updated. | | Contact added | A new contact was linked to the customer. | | Object record activity | A custom object record was created or updated. | Use Journey when you need to understand the sequence of events, not just the current state. ### Contacts Contacts are the people connected to the customer. A business customer may have several contacts, such as an owner, finance contact, support contact, or branch manager. Use Contacts to: | Task | Why it matters | | --- | --- | | Link an existing contact | Connect a person who already exists in Teloring to this customer. | | Review all customer contacts | See who can contact your team on behalf of the customer. | | Edit contact fields | Keep names, phones, emails, roles, preferred channels, and notes accurate. | | Merge customer records | Clean up duplicate customers when needed. | Contacts are different from customers. A contact is the person. A customer is the account or relationship the person belongs to. ### Conversations The Conversations tab shows conversations connected to the customer. It can include open and resolved conversations across different inboxes. Use it to: | Task | Why it matters | | --- | --- | | Review open conversations | See active work connected to the customer. | | Review resolved conversations | Understand previous issues and outcomes. | | Switch from CRM to conversation handling | Open a related conversation from the customer profile. | | Compare channels | See whether the customer contacted you by WhatsApp, email, live chat, voice, or another inbox. | ### Calls The Calls tab shows voice activity connected to the customer when voice is enabled. Use it to review: | Item | Meaning | | --- | --- | | Call direction and status | Whether the call was answered, missed, rejected, or completed. | | Agent | The agent connected to the call, when available. | | Duration | How long the call lasted. | | Related conversation | The conversation or customer context connected to the call. | ### Documents The Documents tab shows documents connected to the customer, including document signature activity when enabled. Use it to review: | Status | Meaning | | --- | --- | | Ready | A document is prepared and ready for signing or sending. | | Signed | A customer completed the document. | | Declined or expired | The document was not completed. | Documents help teams keep agreements, forms, approvals, and signed files close to the customer history. ## Link contacts to customers Contacts can be linked to customer records so agents see the full business context while handling conversations. Common examples: | Example | Why to link | | --- | --- | | One customer, many contacts | Several employees contact support for the same company. | | One contact, many conversations | A customer reaches out through WhatsApp, email, and live chat. | | Historical lookup | Managers want to review all interactions for one business. | ## Lifecycle stages Lifecycle stages help teams group customers by relationship status. | Stage | Typical meaning | | --- | --- | | Lead | A potential customer or new opportunity. | | Active | A current customer. | | Inactive | A customer that is not currently active. | | Irrelevant | A record that should not be treated as an active opportunity or customer. | Your team can decide the exact operational meaning of each stage. ## Custom objects Custom objects let your account model business data that does not fit into the basic customer fields. Examples: | Object | What it can represent | | --- | --- | | Service Calls | Support cases, technical visits, complaints, or operational requests. | | Deals | Sales opportunities, quotes, renewals, or commercial processes. | | Assets | Products, devices, locations, subscriptions, contracts, or equipment connected to the customer. | | Projects | Onboarding work, implementation stages, or long-running work. | | Any custom object | A record type your admin creates for your business process. | Custom objects appear as additional tabs on the customer profile. Each tab contains records of that object type for the current customer. For example, one customer could have: | Customer | Related custom records | | --- | --- | | Acme Ltd. | 3 service calls, 2 deals, 5 assets, 1 renewal project | Each object record has its own fields, its own detail panel, and optional related links to other object records. ![Teloring customer custom object tabs](/img/screenshots/product/crm/customer-object-tabs.png) ## Creating object types Admins can create new object types from the customer profile. When creating an object type, the admin defines: | Setting | Meaning | | --- | --- | | Plural label | The tab name, such as "Assets" or "Projects". | | Singular label | The name for one record, such as "Asset" or "Project". | | Icon | The visual icon shown on the customer tab. | | API ID | A stable technical identifier for the object. This is useful for integrations and automation. | After an object type is created, it appears as a customer tab. Admins can then use the field editor to define the fields for that object. ## Field editor The field editor controls which fields appear on customers, contacts, and custom objects. Admins can use it to: | Action | What it does | | --- | --- | | Add sections | Organize fields into groups, such as General, Billing, Contract, or Service Details. | | Add fields | Add new fields from the toolbox. | | Reorder sections and fields | Drag fields into the right order for agents. | | Mark fields as required | Make important data mandatory. | | Edit labels | Rename fields so they match your team's language. | | Edit options | Define dropdown, radio, checkbox, and multi-select values. | | Save the schema | Apply the updated layout to that object type. | ![Teloring field editor](/img/screenshots/product/crm/field-editor.png) The available field types include: | Field type | Best for | | --- | --- | | Text | Short values such as name, serial number, or reference. | | Textarea | Longer notes or descriptions. | | Number | Quantities, counts, or numeric IDs. | | Email | Email addresses. | | Phone | Phone numbers. | | Date | A single date, such as renewal date. | | Datetime | Date and time together. | | Checkbox | A yes/no value. | | Radio | One choice from a small fixed set. | | Dropdown | One choice from a list. | | Multi-select | Multiple choices from a list. | | Currency | Money amounts. | | URL | Links to external resources. | | Rich text | Formatted notes or longer content. | | Agent picker | Assign an internal agent. | | File | File attachment fields where supported. | | Caption | A visual label or separator inside the form. | Some fields are system fields. System fields are required by Teloring and cannot be removed, although admins may be able to control how they are displayed. :::note Field editor or conversation attributes? The field editor shapes records that **outlive a conversation** — the person, the business, and the objects underneath them. If what you want to record belongs to **one conversation** instead ("why did they write today?", "how did this end?"), use [Conversation Attributes](./conversation-attributes.md), which are designed in Settings and filled in from the conversation itself. A quick test: *if the same person contacted you again tomorrow, should this value still be there?* **Yes** → a contact or customer field. **No** → a conversation attribute. ::: ## Top-level customer fields vs object fields Top-level customer fields describe the customer itself. Object fields describe one record under that customer. | Field location | Example fields | Use it for | | --- | --- | --- | | Customer fields | Name, lifecycle stage, industry, phone, email, website, address, assigned agent, tags, notes | Information that belongs directly to the customer. | | Contact fields | First name, last name, phone, email, role, preferred channel, notes | Information about a person linked to the customer. | | Object fields | Service status, deal amount, asset serial number, renewal date, project owner | Information that belongs to one custom object record. | For example, "Customer email" belongs on the customer. "Technician assigned to this service call" belongs on the Service Call object. "Serial number" belongs on an Asset object. ## Linking records between objects Custom object records can be linked to other object records. This creates a relationship between two records so users can navigate between them. Example relationships: | Source record | Linked record | Why link them | | --- | --- | --- | | Service Call | Asset | The service call is about a specific product or device. | | Deal | Project | A won deal started an onboarding project. | | Subscription | Document | A signed agreement belongs to the subscription. | | Service Call | Deal | A support issue created a renewal or upsell opportunity. | When you link records, Teloring shows the relationship in the Related Items area. The source record shows the linked item. The target record also knows that another record links back to it. This means users can open a service call, see the related asset, open the asset, and still see that the service call is connected to it. ![Teloring related object records](/img/screenshots/product/crm/related-items.png) ## Record lists and column settings Each custom object tab shows a record table. Users can open a record to view details, edit it, delete it when allowed, or review related items. Some object tables allow column settings, so users can choose which fields appear in the list and whether related links should appear as a column. This helps each team keep the most important fields visible. ## Practical example A service company might use the CRM like this: 1. The customer profile stores the company name, lifecycle stage, contact details, assigned agent, and notes. 2. Contacts store the people who call or message the company. 3. Conversations store every WhatsApp, email, voice, or live chat interaction. 4. Service Calls store support cases. 5. Assets store the customer's products or equipment. 6. A Service Call is linked to the Asset it is about. 7. Documents store signed service agreements. 8. Journey shows the important changes over time. This keeps the customer relationship, daily communication, and structured business records connected in one place. --- # On Hold Source: https://docs.teloring.com/docs/product/on-hold Markdown: https://docs.teloring.com/markdown/docs/product/on-hold.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z **On Hold parks a conversation until a time you choose.** The customer asked you to call back after lunch, you are waiting for a delivery to arrive, a colleague has to check something tomorrow morning — put the conversation on hold and stop thinking about it. Teloring brings it back on its own. It comes back in **two** ways, whichever happens first: 1. **The time is up.** Teloring returns it to your queue and marks it unread. 2. **The customer writes again.** The hold ends immediately — even at 2 minutes into a 5-hour hold. That second rule is the important one. A customer who says "call me in five hours" and then writes back in twenty minutes should be in front of you now, not asleep until the deadline. :::info On Hold is a status, not a folder On Hold is a **top-level conversation status**, next to Open and Resolved — not a sub-state of Open. A conversation on hold **disappears** from Mine, Waiting in line, Studio Bot, AI Agent and All Open, and stops counting in your dashboard numbers. That is the whole point: parked work must not sit in your active list creating false urgency. ::: ## Key facts | Fact | Meaning | | --- | --- | | It keeps its owner | The conversation stays assigned to you. When it comes back, it comes back to **you**, not to the general queue. | | It has its own queue | **Conversations → On Hold** in the sidebar, at the same level as Mine and Waiting in line. | | The queue is account-wide | Every agent sees every held conversation, like All Open. Filter by **Assigned agent** to see only yours. | | A customer reply cancels it | On every channel, and without you being online. | | The timer is accurate to about a minute | Teloring checks for expired holds once a minute, so a conversation returns within roughly a minute of its deadline. | | Deadlines use the **business** timezone | Not your personal one. See [Which timezone is used](#which-timezone-is-used). | | Resolved conversations cannot be held | Reopen it first. A hold on a closed conversation would mean nothing. | | It is recorded | Entering and leaving a hold appear in the conversation's timeline and in the account audit log. | ## When to use it | Situation | Why On Hold fits | | --- | --- | | "Call me back this afternoon." | The conversation returns at the time you agreed, without a personal reminder or a sticky note. | | Waiting on a delivery, refund, or repair | Park it for a realistic date instead of re-reading it every hour. | | Waiting on a colleague or another department | It leaves your active list but stays yours, so nothing is dropped. | | The customer is unreachable right now | Try again tomorrow morning without losing the thread. | | A promise with a date on it | "We'll check on Sunday" becomes something the system remembers, not something you have to. | When **not** to use it: | Situation | Do this instead | | --- | --- | | The issue is finished | **Resolve** it. On Hold is for work that is still open. | | Somebody else should handle it | **Send back in line** or assign it to an agent or [team](./teams.md). | | You need the whole team to see it is blocked | Add a **label** or a **flag** as well — the On Hold queue shows the deadline, but a label explains *why*. | --- ## Put a conversation on hold Open the conversation and use the **On Hold** button in the top bar, next to **Resolve**. ![Conversation top bar with the On Hold button next to Resolve](pathname:///img/screenshots/product/on-hold/on-hold-button.png) That opens the duration picker. ![On Hold duration picker with the preset buttons and the custom date field](pathname:///img/screenshots/product/on-hold/on-hold-picker.png) ### The duration picker | Element | What it does | | --- | --- | | **1 hour** | Comes back one hour from now. | | **4 hours** | Comes back four hours from now. | | **Tomorrow 9:00** | Comes back at 09:00 the next calendar day, in the business timezone. | | **1 week** | Comes back seven days from now. | | **Custom** | Reveals a date-and-time field so you can pick any moment. | | **Date and time** (Custom only) | The exact return time. Read in the business timezone. | | Timezone note | Names the timezone the times are calculated in, so there is never a silent mismatch. | | **Put on hold** | Confirms and parks the conversation. | | **Cancel** | Closes the picker and changes nothing. | A custom time must be at least **one minute** away and no more than **365 days** away. Anything outside that is rejected with a message in the picker, and the conversation is not touched. ### What happens the moment you confirm 1. The conversation's status becomes **On Hold**. 2. It **leaves** whichever queue you were looking at, and the chat panel closes. 3. It **appears** in the On Hold queue for everyone in the account. 4. It stays **assigned to you**. 5. Everyone else's screen updates immediately — no refresh needed. :::note Your assignment is deliberately kept On Hold does not release ownership. This is not "send back in line with a timer" — it is "come back to *me* later". ::: --- ## The On Hold queue Open **Conversations → On Hold** in the sidebar. The badge counts every held conversation in the account, and is hidden when nothing is on hold. ![On Hold entry in the Teloring sidebar showing a badge with one held conversation](pathname:///img/screenshots/product/on-hold/on-hold-queue.png) In the list itself, each row carries a **⏸ deadline** chip, so you can scan the queue and see what is waking up when. | Element | What it shows | | --- | --- | | Sidebar badge | How many conversations in the account are on hold. Hidden at zero. | | **⏸** chip on a card | When that conversation is due back, in **your** display timezone. | | Search, sort, filters | Work exactly as in the other queues. | | **Assigned agent** filter | Use it to narrow the queue to your own held conversations. | :::tip See only your own held conversations The queue is account-wide on purpose — a supervisor needs to see what the team has parked. To see just yours, open the **Filter** panel and pick yourself under **Assigned agent**. ::: Opening a held conversation works normally: you can read it, add a private note, change labels, and even reply. **Replying does not end the hold** — only the three triggers below do. --- ## How a hold ends ### 1. The time is up Teloring checks once a minute for holds that have expired. When one has: | What changes | Detail | | --- | --- | | Status | Back to **Open**. | | Assignment | Unchanged — it returns to the same agent. | | Unread | Marked **unread**, so it stands out in the list. | | Queue | Leaves On Hold, reappears in **Mine** for its owner and in **All Open**. | You do not need to be online. If the hold expires overnight, the conversation is waiting, unread, when you sign in. ### 2. The customer replies If the customer sends anything before the deadline, the hold ends **at once**: - the conversation returns to **Open**, still assigned to you; - it reappears in **Mine** and **All Open** with the new message; - the deadline is discarded. This works on **every channel** — WhatsApp, Email, SMS, Telegram, LINE, Live Chat, Messenger, Facebook and Instagram, TikTok, and the API inbox — and it happens on Teloring's side, so it does not depend on anyone having the app open. :::info The reply lands in the same conversation A customer writing to a held conversation continues **that** conversation. Teloring does not start a second one alongside it. ::: A WhatsApp **reaction** counts as the customer speaking, so it also ends a hold. Removing a reaction does not. ### 3. You end it yourself While a conversation is on hold, the top-bar button changes to **On hold until …** and becomes the release control. Because that label does not announce that clicking it undoes the hold, Teloring asks first, in a small confirmation next to the button. ![On hold until button with the small take-off-hold confirmation open beneath it](pathname:///img/screenshots/product/on-hold/on-hold-release-confirm.png) | Element | What it does | | --- | --- | | **On hold until …** (button) | Shows the deadline. Click to start taking it off hold. | | **Take off hold** | Returns the conversation to Open immediately. | | **Cancel** | Leaves the hold as it is. | Pressing `Esc` or clicking anywhere outside also cancels. Released this way, the conversation goes back to **Open** with the same owner. It is **not** marked unread — you are already looking at it. ### Resolving or reopening also clears it If you **Resolve** a held conversation, or move it to another status, the hold is dropped in the same action. A closed conversation can never be woken up by an old timer. --- ## Change a deadline To move a deadline, take the conversation **off hold** and put it on hold again with the new time. There is no "extend" control in the picker. --- ## Which timezone is used Two different timezones exist in Teloring, and On Hold uses both — for different jobs. | Timezone | Where it is set | What it does for On Hold | | --- | --- | --- | | **Business timezone** | **Settings → General** (admin) | **Calculates** the deadline. "Tomorrow 9:00" means 09:00 for the business, so two agents in two countries parking the same conversation get the same moment. | | **Your display timezone** | **Profile → Personal Information** | **Displays** the deadline. It changes what you read on the button and the ⏸ chip, never when the conversation actually returns. | Leave your profile timezone empty and Teloring shows times in your browser's own timezone, which is what most agents expect. :::warning A deadline is a business rule, not a personal preference This is the same principle as business hours, SLA windows and report periods: they all follow the **business** timezone. If your personal timezone differs from the business one, the picker's note tells you which zone the times are in — read it before choosing a custom time. ::: **Example.** The business timezone is `Asia/Jerusalem` and you work from London. You pick **Tomorrow 9:00**. The conversation returns at 09:00 Jerusalem time, which your screen shows as 07:00 — correct in both places, and the same instant for everyone. --- ## Permissions | Action | Who can do it | | --- | --- | | Put a conversation on hold | The **assigned agent**, or an **Admin**. | | Take it off hold | The assigned agent, the agent who parked it, or an **Admin**. | | See the On Hold queue | Every agent in the account. | A conversation that nobody owns — sitting in Waiting in line, or held by Studio Bot or an AI Agent — can only be put on hold by an Admin. Normally you would **take** the conversation first, then hold it. These rules are enforced on the server, not only hidden in the interface. --- ## On Hold and the rest of Teloring | Feature | Behavior | | --- | --- | | **Dashboard** | Held conversations are excluded from the *Mine* and *Waiting* counters, so parked work does not inflate your workload. | | **Conversation timeline** | Entering and leaving a hold appear in the resolved conversation's timeline, including how long it was held for and why it ended (timer or customer reply). | | **Reports** | Conversations can be filtered by the **On Hold** status in [Analytics](./analytics.md). | | **Audit log** | Every hold and every release writes an entry — who parked it, until when, and what ended it. A release by the timer is recorded as a system action. Releases caused by a customer reply are recorded on the conversation itself, not in the audit log, because they happen on the busiest path in the platform. | | **AI Copilot** | Still available inside a held conversation. On hold means parked, not closed. | | **Studio** | A **Conversation Changed** trigger fires when a conversation enters or leaves a hold. The trigger's status filter offers *any*, *opened* and *resolved* only, so use *any* and read the conversation's status inside the flow. | | **Webhooks** | Emits `conversation.on_hold` and `conversation.on_hold_released`. | :::note Studio cannot put a conversation on hold The Studio **Change Conversation** action can set Open, Pending or Resolved — not On Hold. A hold carries a deadline and an owner, so it is an agent action. ::: --- ## Limitations | Limitation | Detail | | --- | --- | | No extend | Change a deadline by releasing and re-holding. | | No per-agent queue | The On Hold queue is account-wide; use the **Assigned agent** filter to narrow it. | | Maximum 365 days | Longer than that is rejected. | | Minimum one minute | A time in the past, or less than a minute away, is rejected. | | Not settable from Studio or the AI Agent | Agents (or an Admin) put conversations on hold. | | Replying does not release | Only the timer, a customer reply, or an explicit release ends a hold. | | Resolved conversations cannot be held | Reopen first. | ## Troubleshooting | Symptom | Cause and fix | | --- | --- | | A held conversation did not come back at its deadline | Holds are swept once a minute, so allow about a minute. If it is much later than that, contact your administrator — the platform's minute schedule may not be running. | | The time I picked is not the time shown on the button | The deadline is calculated in the **business** timezone and displayed in **your** timezone. Both are correct. See [Which timezone is used](#which-timezone-is-used). | | The **On Hold** button is missing | The conversation is resolved. Reopen it first. | | "Reopen the conversation before putting it on hold" | You are on a resolved conversation. | | "Only the assigned agent or an admin can put this conversation on hold" | Take the conversation first, or ask an Admin. | | "Pick a time at least a minute from now" | The custom time is in the past or too close. | | A customer replied but the conversation is still on hold | Reload the page. If it persists, the message may not have reached Teloring — check the inbox connection in [The Ring](./ring/overview.md). | | I cannot find my held conversations | They are in **Conversations → On Hold**, not in Mine. Filter by **Assigned agent** to see only yours. | ## Related - [Conversations](../getting-started/conversations.md) — the queues, filters, and everyday handling workflow. - [Teams](./teams.md) — routing conversations to a group instead of one person. - [Settings](./settings.md) — where the business timezone is set. - [Analytics](./analytics.md) — reporting on conversation statuses. --- # System permissions reference Source: https://docs.teloring.com/docs/product/roles/system-permissions Markdown: https://docs.teloring.com/markdown/docs/product/roles/system-permissions.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z The **System permissions** tab answers one question for every feature in Teloring: *may this role reach it, and may it change anything there?* ![The System permissions tab, grouped into Customers, Workspace, Tools, Settings, Agents and teams, and Billing](pathname:///img/screenshots/product/roles/system-permissions-tab.png) ## How the grid works Each row is a feature. Each column is an action. Tick a box to grant it. | Element | What it does | | --- | --- | | **Group heading** | Six groups — *Customers*, *Workspace*, *Tools*, *Settings*, *Agents & teams*, *Billing*. Purely for orientation; grouping grants nothing. | | **Row label** | The feature, matching the sidebar wording so you can find it in the product. Some rows carry a one-line hint underneath explaining a non-obvious action. | | **Column header** | **Read**, **Create**, **Update**, **Delete**. Click a header to tick or untick that action for **every row in the group at once** — one click to grant a whole column, a second to clear it. | | **Checkbox** | The permission itself. | | **`—` dash** | This action does not exist for this feature. There is nothing to grant. Hovering says *Not applicable to this item*. | | Indented rows | Objects that live **inside a customer**, shown nested under *Customers*. | ## How the four actions work | Action | What it grants | | --- | --- | | **Read** | Reach the feature and look at it. Nothing can be changed. | | **Create** | Add a new item. | | **Update** | Change an existing item. | | **Delete** | Remove an item. | **Create, Update and Delete each include Read automatically.** You cannot create a customer you are not allowed to see, so the moment you tick any write action, **Read** switches on and locks — it turns a lighter shade and cannot be unticked while a write action is set. ![A row where Read is locked on because Update is ticked](pathname:///img/screenshots/product/roles/implied-read.png) To release Read, untick the write actions first. :::note Why a lock rather than a hidden box The alternative — quietly storing "Update but not Read" and then ignoring it — would mean the grid on screen did not match what the role actually does. The lock keeps the two identical: what you see ticked is exactly what is stored. ::: :::tip Read-only roles are the useful ones An auditor, an accountant, a consultant, a stakeholder who wants dashboards — all of them want **Read** on a few things and nothing else. Tick the Read column, save, done. ::: --- ## Customers The CRM. The first row is the customer record itself; the indented rows below are the objects inside a customer. | Feature | Read | Create | Update | Delete | | --- | --- | --- | --- | --- | | **Customers** | Open the Customers page and a customer record | Add a customer | Edit a customer, **and edit the fields of any customer object** in the field editor | Delete a customer | | **Journey** | See the customer's timeline | `—` | `—` | `—` | | **Conversations** | See the customer's conversations tab | `—` | `—` | `—` | | **Calls** | See the customer's calls tab | `—` | `—` | `—` | | **Documents** | See the customer's signed documents tab | `—` | `—` | `—` | | **Contacts**, **Service Calls**, **Deals**, **Tasks**, **Notes**, and any object you create | See records of that type | Add a record | Edit a record | Delete a record | ### Why some rows are Read-only **Journey**, **Conversations**, **Calls** and **Documents** are written by Teloring itself. A journey entry is a record of something that already happened; a call log is a record of a call. There is nothing to create or edit from the customer page, so only **Read** exists. ### Your own object types appear here automatically Every CRM object type in your account gets its own row with all four actions, including ones you designed yourself in the field editor. Create a *Contracts* object today and it is on this grid immediately, with its own label and icon — no waiting, no separate setup. Disabled object types are not listed, since there is nothing to permit. :::warning "Update" on Customers also grants the field editor **Customers → Update** covers two things: editing a customer record, *and* changing the **shape** of your CRM — adding an object type, adding or removing fields, reordering them. That is how the product is built: both are "changing the customer model". If you want somebody to edit customer data but never restructure the CRM, that separation does not exist today. Give **Update** on the individual object rows and leave **Customers → Update** off — they can then edit records of those objects without reaching the designer. ::: --- ## Workspace | Feature | Read | Create | Update | Delete | | --- | --- | --- | --- | --- | | **Views** | Open Views and run a saved view | Build a new view | Edit an existing view | Delete a view | | **My Ring (inboxes)** | Open My Ring and see inbox configuration | Connect a new inbox | Change inbox settings | Disconnect an inbox | | **Analytics** | Open Analytics, read boards and reports, export | Create a report or board | Edit a report, board or tab | Delete a report or a whole board | | **Conversation attributes** | See the attributes panel in a conversation and on a resolved one, and open the Settings page | `—` | Fill values in on a conversation, **and** add or edit attributes in Settings | Remove an attribute from the account's design | :::note Conversation attributes has no Create An attribute is part of one account-wide design, not a separate item — so adding one *is* editing that design, and it needs **Update**. See [Conversation Attributes](../conversation-attributes.md). **Update covers both filling in and designing**, the same way **Customers → Update** also covers the field editor. If you want front-line agents to record a reason and an outcome without being able to restructure the form, that separation does not exist today; in practice the Settings page is not somewhere agents go. **Delete** is only ever "remove an attribute from the design". It never deletes the values already stored on conversations — those are kept, and re-creating the attribute with the same API ID brings them back into view. ::: :::info My Ring is inbox *setup*, not inbox *access* **My Ring** governs the configuration page — connecting a WhatsApp number, editing email settings, disconnecting a channel. Whether an agent can *work in* an inbox is a completely separate thing, on the [Channel permissions](./channel-permissions.md) tab. A front-line agent normally has **no** My Ring access at all while working in every inbox all day. One consequence worth knowing: an agent with **My Ring → Read** sees every inbox in the account listed there, including ones they cannot work in. If that matters for you, do not grant it. ::: --- ## Tools | Feature | Read | Create | Update | Delete | | --- | --- | --- | --- | --- | | **Studio** | Open Studio, read flows, versions and run history | Create a flow or a schedule | Edit, publish, pause, resume or test a flow | Delete a flow or schedule | | **AI World** | Open AI World and see which features are on | `—` | **Switch AI features on and off** | `—` | | **Knowledge base** | Open it, browse sources, ask questions | Create a knowledge base, upload a source | Refresh a source | Delete a knowledge base or a source | | **Quick replies** | Open quick replies and use them in a conversation | Create a quick reply or category | Edit one | Delete one | | **Forms builder** | Open Forms, read forms and submissions, export | Create or duplicate a form | Edit a form, publish it, upload an image | Delete a form | | **Document signature** | Open it and read documents | Create a document and send it for signing | Edit a document | Delete a document | | **Files warehouse** | Open it, view and **download** files | `—` | `—` | Delete files | | **Achievements** | Open the Achievements page and see progress | `—` | **Collect a completed achievement** | `—` | ### The unusual ones **AI World** has no items to create or delete — it is a board of switches. **Update** is what lets somebody flip them. With **Read** only, an agent sees which AI features are on but cannot change any. **Achievements** works the same way. **Read** shows the page and progress; **Update** is what lets somebody press **Collect** and add the reward credits to the account. **Files warehouse** has no Create, because files arrive by being uploaded elsewhere — a conversation attachment, a knowledge base source, a form image. **Read** includes downloading. **Delete** is the one that matters, and it is the permission that also allows deleting somebody *else's* upload and using **Delete all**. :::note Quick replies: personal versus shared Writing a **personal** quick reply only you can see is self-service — anybody with **Read** can do it. **Create**, **Update** and **Delete** govern the **account-wide** ones every agent sees. The default **Agent** role has all four, so front-line agents can build the shared library. If you would rather they only used it, drop the role to **Read** and keep the write actions for supervisors. ::: --- ## Settings Each settings tab is a separate row, because they are genuinely different concerns — reading the business address is not reading the API keys. A role that grants none of them does not see **Settings** in the sidebar at all; a role that grants one lands directly on that tab. | Feature | Read | Create | Update | Delete | | --- | --- | --- | --- | --- | | **General info** | Open the tab | `—` | Change business name, logo, language, timezone, currency, country | `—` | | **Business hours** | Open the tab | Add a schedule or holiday calendar | Edit one | Delete one | | **Security & login** | Open the tab, see active sessions | `—` | Change IP allowlist, enforced 2FA, idle timeout; **force-sign-out a session** | `—` | | **API** | Open the tab and see the key list | **Issue a new API key** | `—` | **Revoke a key** | | **Data & privacy** | Open the tab | **Request a data export** | `—` | **Delete the entire account** | :::danger Data & privacy → Delete deletes the workspace This is the single most destructive permission in Teloring. It is what allows the **Danger Zone → Delete account** action. The default roles give it to **Owner only**. Keep it that way unless you have a specific reason. ::: :::note API has no Update An API key cannot be edited — a key is a secret, and changing it would mean issuing a new one. So the actions are **Create** (issue) and **Delete** (revoke). Webhook subscriptions are governed by the same row, since they are part of the same developer surface. ::: --- ## Agents & teams | Feature | Read | Create | Update | Delete | | --- | --- | --- | --- | --- | | **Agents** | Open the Agents directory and search it | Invite a new agent, create an AI Agent | Edit any agent — role, language, 2FA, department, notes, **their voice access**; reset **another** agent's password; move **another** agent's email; resend an invitation; deactivate | Delete an agent profile | | **Teams** | Open Teams and see the team list | Create a team | Edit a team — name, members, rules | Delete a team | | **Roles & permissions** | Open this page and read every role | Create a role | Edit a role | Delete a role | | **Audit log** | Open the audit log and read it | `—` | `—` | `—` | ### Things that are always self-service Two actions on the Agents page never need a permission, because they concern the agent themselves: - resetting **their own** password; - changing **their own** sign-in email. Both travel through a one-time link sent to their own inbox. **Agents → Update** is what extends those actions to *other* people. :::danger Roles & permissions is the master key Anybody who can create or edit a role can give themselves — or anybody else — every other permission in Teloring, including billing and account deletion. That is not a flaw; it is what editing a role means. Treat it exactly like an administrator password. The default roles give **Create**, **Update** and **Delete** to **Owner only**, and **Read** to Team Leader so a manager can see the structure without changing it. ::: :::note Voice access lives under Agents Switching Teloring browser calling on for a specific person is part of editing that agent, so it needs **Agents → Update**. The account-wide voice switch and voice *inbox* configuration are under **My Ring**. ::: --- ## Billing | Feature | Read | Create | Update | Delete | | --- | --- | --- | --- | --- | | **Credits** | See the credit balance, the header credit badge, and transaction history | `—` | `—` | `—` | | **Subscription** | See the current plan, seats and usage meters | `—` | **Change plan** | `—` | | **Credit cards** | See stored cards — brand and last four digits only | Add a card | Update a card's expiry | Remove a card | | **Usage pricing** | See the per-action price list | `—` | `—` | `—` | The **Billing** entry disappears from the sidebar entirely when a role grants none of these. If a role grants some, only those tabs appear, and opening Billing lands on one the agent can read. :::note The credit badge in the header The monthly and top-up credit figures in the top bar are shown only to roles with **Credits → Read**. Roles without it never see the account's balance. ::: --- ## What the default roles grant `R` Read · `C` Create · `U` Update · `D` Delete · `—` no access | Feature | Owner | Team Leader | Marketing | Agent | Viewer | | --- | --- | --- | --- | --- | --- | | **Customers** | R C U D | R C U D | R C U | R C U | R | | Journey | R | R | R | R | R | | Conversations (in customer) | R | R | R | R | R | | Calls | R | R | R | R | R | | Documents | R | R | R | R | R | | Contacts / Service Calls / Deals / Tasks / Notes | R C U D | R C U D | R C U | R C U | R | | **Views** | R C U D | R C U D | R C U D | R | R | | **My Ring (inboxes)** | R C U D | R U | R | — | R | | **Analytics** | R C U D | R C U D | R C U D | — | R | | **Conversation attributes** | R U D | R U D | R U | R U | R | | **Studio** | R C U D | R C U D | R C U D | — | — | | **AI World** | R U | R U | R U | — | — | | **Knowledge base** | R C U D | R C U D | R C U D | R | R | | **Quick replies** | R C U D | R C U D | R C U D | R C U D | R | | **Forms builder** | R C U D | R C U D | R C U D | — | R | | **Document signature** | R C U D | R C U D | R | R C | R | | **Files warehouse** | R D | R D | R | R | R | | **Achievements** | R U | R U | R U | R U | R | | **Settings → General info** | R U | R | R | — | R | | **Settings → Business hours** | R C U D | R C U D | R | — | — | | **Settings → Security & login** | R U | R | — | — | — | | **Settings → API** | R C D | R | — | — | — | | **Settings → Data & privacy** | R C D | — | — | — | — | | **Agents** | R C U D | R | R | R | R | | **Teams** | R C U D | R C U D | R | R | R | | **Roles & permissions** | R C U D | R | — | — | — | | **Audit log** | R | R | — | — | — | | **Billing → Credits** | R | — | — | — | — | | **Billing → Subscription** | R U | — | — | — | — | | **Billing → Credit cards** | R C U D | — | — | — | — | | **Billing → Usage pricing** | R | — | — | — | — | Owner is shown fully ticked for reference. In practice it is not a stored grid at all — it is permanent full access that cannot be edited. :::note New permissions are not added to existing roles This table is what a **newly created account** gets. A permission added to Teloring after your account was created is **not** ticked on your existing roles — nothing is ever granted behind your back. **Conversation attributes** is the most recent example: until you tick it, only Owner reaches the feature. Open a role, tick the row, and save. ::: ### Reading the table - **Team Leader** is a full support manager with no financial or administrative reach. It can see the API key list and the security settings but change neither, so a manager can answer "is 2FA enforced?" without being able to rotate a key. - **Marketing** builds and measures. It can restructure Studio, forms and analytics but cannot connect an inbox, manage agents or reach billing. - **Agent** is deliberately narrow outside conversations: customers, quick replies, the knowledge base to look things up, and sending documents for signature. No Studio, no analytics, no settings. It does get **Conversation attributes → Update**, because recording a reason and an outcome is part of handling a conversation. - **Viewer** is Read almost everywhere and write nowhere — and, crucially, **no conversations at all** (see [Channel permissions](./channel-permissions.md#what-the-default-roles-grant)). --- ## Related guides - [Roles and Permissions](./overview.md) — creating, editing, assigning and deleting roles. - [Channel permissions reference](./channel-permissions.md) — the other half of a role. - [Example roles and recipes](./examples.md) — setups to copy. - [Account settings](../settings.md) — the settings tabs this grid refers to. - [CRM and customers](../crm.md) — customer objects and the field editor. - [Conversation Attributes](../conversation-attributes.md) — the feature behind the Conversation attributes row. --- # Channel permissions reference Source: https://docs.teloring.com/docs/product/roles/channel-permissions Markdown: https://docs.teloring.com/markdown/docs/product/roles/channel-permissions.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z The **Channel permissions** tab decides what an agent may do **in each inbox**. It is the half of a role that shapes an agent's actual working day. ![The Channel permissions tab with the Future inbox card open above the connected inboxes](pathname:///img/screenshots/product/roles/channel-permissions-tab.png) These are not read/create/update/delete. An inbox is a *place*, and the useful questions about a place are different: can they see its waiting line, can they be handed work from it, may they reply, may they resolve. So each inbox has the same **18 on/off abilities**. ## How the tab works | Element | What it does | | --- | --- | | **Future inbox (default)** | The first card, marked with a dashed border. Sets the defaults for every inbox you connect from now on — and for any inbox below that you have not configured. Always expanded. | | **Inbox card** | One per connected inbox, showing its name and channel type. Click the header to expand or collapse. | | **Counter** (`12/18`) | How many of the 18 abilities are on for that inbox. Read it at a glance without expanding. | | **Inherited** badge | This inbox has never been configured in this role, so it is following **Future inbox**. | | **Checkbox** | The ability. Each has a one-line explanation underneath. | | **Select all** / **Clear all** | Tick or clear all 18 for that inbox in one click. | :::tip Set Future inbox first, then handle exceptions The efficient order is: 1. Expand **Future inbox** and set what this role should normally be able to do in any inbox. 2. Leave every inbox that matches those defaults alone — they will show **Inherited** and follow along. 3. Only expand and change the inboxes that are genuinely different. A role for a WhatsApp-only team is therefore: clear everything in **Future inbox**, then tick what you need on the WhatsApp inbox alone. Two cards touched instead of ten. ::: --- ## Future inbox — how inheritance works This is the most important idea on the page, and it saves the most work. An inbox card in a role is in one of two states: | State | Badge | Behaviour | | --- | --- | --- | | **Inherited** | **Inherited** | You have never changed this inbox in this role. It uses the **Future inbox** values, and keeps following them — including if you change Future inbox later. | | **Explicit** | none | You have changed at least one box on this inbox. It now has its own settings and no longer follows Future inbox. | The moment you tick or untick anything on an inherited card, it becomes explicit. Teloring copies the current Future inbox values across first, so changing one box never silently clears the other seventeen. ### Why this matters **Connect a new inbox and every role already knows what to do with it.** A new WhatsApp number, a second support mailbox, a Telegram bot — each one picks up each role's Future inbox settings automatically. You do not revisit this page, and no role is accidentally left with access to a channel nobody reviewed. It works in both directions: | Situation | What happens | | --- | --- | | You connect a new inbox | Every role applies its own **Future inbox** values to it, immediately. | | You later change **Future inbox** in a role | Every inbox in that role still showing **Inherited** updates too. Explicit ones are untouched. | | You create a new role after connecting the inbox | Same rule — nothing about the order matters. | | You delete an inbox | Its stored settings stay harmlessly in each role and disappear from the editor. | :::warning Future inbox is a permission, not a placeholder It is easy to read *"Future inbox"* as a template that does nothing until a channel arrives. It is a live rule: any inbox showing **Inherited** is being governed by it right now. Ticking **See All Open conversations** in Future inbox grants it on every inherited inbox in that role immediately — not just future ones. ::: --- ## The 18 abilities They are grouped below by what they do. In the product they appear in this exact order. ### What the agent can see | Ability | What it grants | Where the agent notices | | --- | --- | --- | | **See the waiting line** | Access to *Waiting in line* conversations from this inbox | The **Waiting in line** queue and its badge count | | **Get Next in Line** | Allows taking the next waiting conversation from this inbox | The **Get next in line** button | | **See Studio Bot conversations** | Conversations currently handled by a Studio flow | The **Studio Bot** queue | | **See AI Agent conversations** | Conversations currently handled by an AI Agent | The **AI Agent** queue | | **See On Hold conversations** | Conversations parked until a deadline | The **On Hold** queue | | **See All Open conversations** | Every open conversation in this inbox, whoever owns it | The **All Open** queue | | **See all resolved conversations** | Every resolved conversation in this inbox | The **Resolved** queue | | **See previous conversations** | The *Previous conversations* panel inside a conversation | The right-hand panel | ### What the agent can do | Ability | What it grants | | --- | --- | | **Send a new message** | Reply to the customer in this inbox | | **Start a new conversation** | This inbox appears in the **+ New conversation** picker | | **Send a private note** | Write an internal note on a conversation in this inbox | | **Put a conversation on hold** | Use the **On Hold** button | | **Can assign conversations** | Change **Assigned to** or **Assigned team** | | **Resolve a conversation** | Use the **Resolve** button | | **Delete a conversation** | The **Delete** button — **email inboxes only** | | **Set conversation priority** | The priority picker | | **Set a flag for a conversation** | The flag picker | | **Set a label for a conversation** | Add, change or remove labels | ### Notes on individual abilities **See the waiting line** and **Get Next in Line** are deliberately separate. A role can watch a queue filling up without being handed work from it — useful for a supervisor who monitors but does not take conversations, and for a team that should only receive work from its own channel. **See All Open conversations** is the broad one. It shows conversations owned by other agents. Leave it off and the agent works only from *Mine* plus whatever they take from the waiting line — the classic front-line setup. **Send a new message** and **Send a private note** are separate on purpose. A role can annotate a conversation for colleagues without being allowed to speak to the customer — a quality reviewer, a specialist adding context, a trainee whose replies are still being checked. **Start a new conversation** controls the inbox picker. When an agent clicks **+ New conversation**, only inboxes with this ability are offered. **Can assign conversations** covers both the agent picker and the team picker. Handing back **your own** conversation with **Send back in line** never needs it — an agent must always be able to let go of their own work. **Delete a conversation** only appears on **email** inboxes, because email is the only channel where deleting a thread is a normal action. Ticking it on a WhatsApp inbox is harmless and does nothing. It is the most destructive conversation permission there is — it destroys the message history — and it is never implied by **Resolve**. **See previous conversations** deserves a moment. The panel shows other conversations with the same customer, which may be from inboxes the agent otherwise cannot work in. Teloring filters that panel per inbox, so each previous conversation only appears if the agent has this ability **on the inbox that conversation belongs to** — not the one they are currently reading. --- ## Why "Mine" is never filtered **Conversations assigned to an agent are always fully accessible to them, in every inbox, regardless of channel permissions.** The reason is practical. If an agent is assigned an Email conversation and Email is later restricted for their role, filtering it out of *Mine* would leave a real customer waiting on a conversation nobody can see. Assignment always wins. So: | Queue | Filtered by inbox? | | --- | --- | | **Mine** | **No.** Never. | | Waiting in line | Yes — `See the waiting line` | | Studio Bot | Yes — `See Studio Bot conversations` | | AI Agent | Yes — `See AI Agent conversations` | | On Hold | Yes — `See On Hold conversations` | | All Open | Yes — `See All Open conversations` | | Resolved | Yes — `See all resolved conversations` | The same applies to a conversation reached by link or by search: if it is assigned to that agent, they can open it. :::info The Conversations menu never disappears Whatever a role allows, the **Conversations** section and all seven queues stay in the sidebar. Only the *contents* change. That is intentional. A menu that changes shape per person is hard to support — "click Waiting in line" stops being reliable advice. A queue an agent cannot see anything in simply shows an empty list. ::: --- ## What else follows these permissions Channel permissions are applied everywhere a conversation could appear, not only in the queue lists. | Place | Behaviour | | --- | --- | | **Sidebar badge counts** | Counted with the same rules as the list, so a badge never says 12 over a list of 3. An inflated badge would itself reveal how much traffic an agent is not allowed to see. | | **Conversation search** | Scoped to the same inboxes as the queue being searched, so search cannot surface something the list hides. | | **Message search** | Same — message *contents* from a restricted inbox are never returned. | | **Get next in line** | Only offers conversations from inboxes with **Get Next in Line**. | | **Filters** | The filter panel can only ever narrow what the agent may already see. It cannot be used to reach past a restriction. | | **Previous conversations** | Filtered per inbox, as described above. | | **Dashboard tiles** | The *waiting* and *resolved today* figures on the home page follow the same rules. | | **AI Copilot** | Available where the agent may **Send a new message**, since Copilot drafts replies. Nothing to draft, nothing to show. | | **Opening by ID** | A conversation in a restricted inbox reports *not found*, rather than *forbidden* — whether it exists at all is itself information. | | **The API** | Same rules, same results. A script using an agent's session sees exactly what the agent sees. | :::note What an agent sees when a control is removed Buttons — **Resolve**, **On Hold**, **Delete** — are hidden entirely. Pickers that display a current value — priority, flag, labels, assignment — are shown **greyed out** instead. The agent can still read that a conversation is Urgent without being able to change it. Removing them would hide information the agent legitimately needs. ::: --- ## What the default roles grant These are each role's **Future inbox** values, which every inbox inherits until you say otherwise. | Ability | Owner | Team Leader | Marketing | Agent | Viewer | | --- | --- | --- | --- | --- | --- | | See the waiting line | Yes | Yes | No | Yes | No | | Get Next in Line | Yes | Yes | No | Yes | No | | See Studio Bot conversations | Yes | Yes | No | No | No | | See AI Agent conversations | Yes | Yes | No | No | No | | See On Hold conversations | Yes | Yes | No | Yes | No | | See All Open conversations | Yes | Yes | No | Yes | No | | See all resolved conversations | Yes | Yes | No | Yes | No | | Send a new message | Yes | Yes | Yes | Yes | No | | Start a new conversation | Yes | Yes | Yes | Yes | No | | Send a private note | Yes | Yes | Yes | Yes | No | | See previous conversations | Yes | Yes | Yes | Yes | No | | Put a conversation on hold | Yes | Yes | Yes | Yes | No | | Can assign conversations | Yes | Yes | Yes | Yes | No | | Resolve a conversation | Yes | Yes | Yes | Yes | No | | Delete a conversation | Yes | Yes | No | No | No | | Set conversation priority | Yes | Yes | Yes | Yes | No | | Set a flag for a conversation | Yes | Yes | Yes | Yes | No | | Set a label for a conversation | Yes | Yes | Yes | Yes | No | ### Reading the table - **Team Leader** has everything, in every inbox, including deleting email threads. It is the support-floor role. - **Marketing** can work conversations — reply, start, assign, resolve, label — but sees **none of the shared queues**. In practice it works only from *Mine*: conversations assigned to it, or ones it started. That is what "cannot see everyone's conversations" means in a permission grid. - **Agent** has the full front-line set, minus the two bot queues and minus deleting. Front-line agents do not need to watch what Studio and the AI are handling, and should not be able to destroy an email thread. - **Viewer** has **nothing**. It is a reporting role with no conversation access at all — every queue is empty for it, and it can still read Analytics and customers. --- ## Common setups ### One team, one channel *A WhatsApp team that must not see Email.* 1. Duplicate the **Agent** role and name it *WhatsApp team*. 2. Open **Channel permissions** → **Future inbox** → **Clear all**. 3. Expand the WhatsApp inbox → **Select all**, then untick **Delete a conversation**. 4. Save. Every other inbox stays inherited from an empty Future inbox, so they see nothing there — including any inbox connected later, which is the point. ### A supervisor who watches but does not answer 1. Duplicate **Agent**, name it *Floor supervisor*. 2. In **Future inbox**, keep all the *see* abilities on. 3. Untick **Get Next in Line** — they monitor rather than take work. 4. Keep **Can assign conversations** on, so they can route. 5. Untick **Send a new message** if they should never reply directly. ### A quality reviewer who comments but never replies 1. Duplicate **Agent**, name it *Quality review*. 2. In **Future inbox**, keep **See All Open conversations**, **See all resolved conversations** and **See previous conversations** on. 3. Untick **Send a new message**, **Start a new conversation**, **Resolve a conversation** and **Get Next in Line**. 4. Keep **Send a private note** on, and **Set a label for a conversation** so they can tag what they reviewed. They can read every conversation and annotate it, and the customer never hears from them. ### An external contractor on one channel 1. Create a role, name it after the contractor. 2. **System permissions**: tick **Customers → Read** and nothing else. 3. **Channel permissions**: **Future inbox** → **Clear all**. 4. On their one inbox, tick only what they need: *see the waiting line*, *Get Next in Line*, *send a message*, *resolve*, *see previous conversations*. 5. Save. More recipes in [Example roles and recipes](./examples.md). --- ## Limitations and what to watch for | Item | What actually happens | Do this instead | | --- | --- | --- | | **No per-conversation permission** | Permissions are per inbox, never per individual conversation, customer or label. | Separate the traffic by inbox if it must be separated. | | **"Mine" cannot be restricted** | An assigned conversation is always visible to its owner, by design. | Control who can be *assigned* using **Can assign conversations** and [Teams](../teams.md). | | **The queues are always in the sidebar** | An agent with no channel access still sees seven queue links, all empty. | Nothing to do. They will not click twice. | | **Delete only applies to email** | Ticking **Delete a conversation** on a WhatsApp or SMS inbox has no effect — there is no delete action on those channels. | Harmless; leave it or clear it. | | **My Ring → Read shows every inbox** | An agent with inbox *setup* access sees all inboxes listed there, including ones they cannot work in. | Do not grant **My Ring → Read** to roles that should not know an inbox exists. | | **Teams are a separate limit** | Even with **Get Next in Line**, an agent is only handed conversations with no team, or from a team they belong to. | Check [Teams](../teams.md) when work is not arriving. | | **A deleted inbox keeps its entry** | Its settings stay stored in the role, harmlessly, and are no longer shown. | Nothing to do. | | **No per-role schedule** | A role cannot grant access only during a shift. | Deactivate the agent, or handle it in Studio. | --- ## Troubleshooting ### A queue is empty for one agent but not another Their roles differ, or the same role has different inboxes configured. Open the role's **Channel permissions** tab, expand the relevant inbox, and check the ability for that queue. Remember the **Inherited** badge: if the inbox is inherited, the answer is in **Future inbox**, not on that card. ### "Get next in line" says nothing is waiting, but I can see conversations waiting Two possible reasons, in this order: 1. **Get Next in Line** is off for those inboxes, while **See the waiting line** is on. The role is set to watch, not take. 2. Everything waiting belongs to a [team](../teams.md) the agent is not in. ### An agent cannot reply, but the conversation is open in front of them **Send a new message** is off for that inbox. If **Send a private note** is on, they will land on the private note tab — that is deliberate, so they are not staring at a composer that will be refused. ### An agent cannot change a conversation's priority, but can see it Correct behaviour. **Set conversation priority** is off, so the picker is greyed out rather than hidden — they can read the value, not change it. ### A new inbox is visible to a role that should not have it That role's **Future inbox** grants it, and the new inbox inherited those defaults. Either clear Future inbox for that role, or expand the new inbox and clear it there. ### The Previous conversations panel is missing **See previous conversations** is off for the inbox the agent is reading. If the panel is there but shorter than expected, the missing entries belong to inboxes where the ability is off. ### An agent sees a conversation from a restricted inbox Almost always because it is **assigned to them** — *Mine* is never filtered. Check **Assigned to** on the conversation. If it is genuinely not theirs, check whether the inbox card is **Inherited** and what **Future inbox** grants. --- ## Related guides - [Roles and Permissions](./overview.md) — creating, editing and assigning roles. - [System permissions reference](./system-permissions.md) — the other half of a role. - [Example roles and recipes](./examples.md) — complete setups to copy. - [Conversations](../../getting-started/conversations.md) — the queues, **Get next**, filters and actions. - [The Ring — inboxes](../ring/overview.md) — connecting the inboxes these permissions apply to. - [Teams](../teams.md) — routing, which also affects what an agent is handed. - [On Hold](../on-hold.md) — the queue behind **See On Hold conversations**. --- # Views Source: https://docs.teloring.com/docs/product/views Markdown: https://docs.teloring.com/markdown/docs/product/views.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Views turn your CRM into tables you build yourself. A **view** is a saved, filterable, sortable table over any object in Teloring — your customers, or any record that lives under a customer (notes, calls, deals, tasks, service calls, documents, form data, and any custom object your account creates). The idea is simple. Normally, a note or a deal is trapped inside one customer's profile. To answer a question like *"show me every note in the system, with the email of the customer it belongs to"*, you would have to open customers one by one. A view does it in one table: pick the object each row represents, choose the columns to show — including columns pulled from the customer — filter and sort the result, and save it with a name. If you have used Airtable views, HubSpot custom reports, or Notion linked databases, Views will feel familiar. It is the same idea, built into Teloring's CRM. Use Views to answer questions like *"all open deals whose customer has already signed a document"*, *"every service call opened this week, with the customer's phone number"*, *"customers who have no tasks"*, or *"notes where the created date matches the customer's renewal date"*. :::info A view only **reads** data. It never changes, moves, or deletes a record. Clicking a row simply opens the real record where you can edit it. ::: ## Key facts | Fact | Meaning | | --- | --- | | A view is a saved table | You define it once — object, columns, filters, sort — and reopen it any time. | | Always live | A view reflects your current data every time you open or refresh it. It is not a frozen snapshot. | | Account-isolated | A view only ever reads your own account's data. | | One base object per view | Every row in a view is the same kind of record — all notes, all deals, all customers, and so on. | | Pull in customer columns | On any object under a customer, you can add columns from that customer (its email, stage, and so on) — the **From Customer** group. | | Powerful filters | Combine conditions with **AND** / **OR**, compare a field to another field, and filter on the customer's *other* records ("has at least one document"). | | Personal or shared | Keep a view to yourself, or share it with everyone in your account. | | Pin your favorites | Pin up to five views to the sidebar for one-click access. | | Export anywhere | Download the full result as Excel or PDF, with your columns and labels. | | Works with any object | Custom object types you create appear as view base objects automatically — no setup needed. | ## Who uses Views | Role | Typical use | | --- | --- | | Agents | Build personal working lists — "my open service calls this week", "leads with no task" — and pin them to the sidebar. | | Team managers | Share account views that the whole team relies on, such as "all open deals with signed documents". | | Admins | Curate a set of shared views per business process and control which are personal vs shared. | ## The Views landing page Open **Views** from the sidebar to reach the landing page. This is the home for all of your views. ![Teloring Views landing page](pathname:///img/screenshots/product/views/views-landing.png) It has two tabs: | Tab | What it shows | | --- | --- | | My Views | Views you created and kept **personal**. Only you can see these. | | Account Views | Views **shared** with the whole account. Everyone can see and open these. | Each row is one view and shows: | Column | Meaning | | --- | --- | | Name and description | The view's title and its optional one-line description. | | Object | The base object the view is built on, with its icon (for example 💰 Deals). | | Scope | A **Personal** or **Account** badge. | | Owner | Who created the view (shows *You* for your own). | | Last modified | When the view was last changed. | | Actions | The **pin** button and a **⋮** menu — see below. | Click any row to open the view. Click **+ New View** (top right) to build one. ### Row actions | Action | Where | What it does | | --- | --- | --- | | Pin / Unpin | The 📌 button on the row | Adds or removes the view from your sidebar shortcuts (up to five). | | Open | ⋮ menu | Opens the view. | | Edit | ⋮ menu | Opens the builder to change the view. | | Duplicate | ⋮ menu | Makes a personal copy you own, named "… (copy)". | | Export to Excel | ⋮ menu | Downloads the full result as an `.xlsx` file. | | Export to PDF | ⋮ menu | Downloads the full result as a PDF. | | Delete | ⋮ menu | Permanently deletes the view. Shared views warn you first. | ### Starter views The first time anyone in your account opens Views, Teloring creates three ready-made **account** views so you have working examples right away: | Starter view | Shows | | --- | --- | | All Notes | Every note across all customers, with each note's customer name and email. | | Open Leads | All customers currently in the **Lead** lifecycle stage. | | Service Calls This Week | Service calls opened this week, with the customer's name and phone. | These are normal views — you can edit, duplicate, or delete them like any other. They are created once; deleting them will not bring them back. ## How a view works Every view is built from four choices. Once these click, the whole builder is easy. | Choice | Question it answers | Example | | --- | --- | --- | | Base object | What does each row represent? | Deals | | Columns | Which fields do I want to see? | Deal name, amount, stage, **customer email** | | Filters | Which rows should be included? | Stage is Open, and the customer has a signed document | | Sort | In what order? | Highest amount first | A view named **"Open deals with a signed document"** is simply: base object = Deals, columns = deal name + amount + stage + customer email, filters = stage is Open **and** the customer has at least one signed document, sort = amount descending. ## Create a view 1. Open **Views** and click **+ New View**. 2. Work through the five sections (base object, columns, filters, sort, and details). 3. Watch the **live preview** on the right update as you go. 4. Click **Save view**. The builder is a single page with five numbered sections. A **live preview** of the first rows sits alongside it and refreshes as you make changes. ![Teloring view builder](pathname:///img/screenshots/product/views/view-builder-overview.png) ### Step 1 — Base object Pick the object each row in the table represents. You can choose: | Base object | Each row is | | --- | --- | | Customers | One customer. | | Contacts | One contact (a person linked to a customer). | | Conversations | One conversation. | | Any custom object | One record of that object — Notes, Deals, Tasks, Service Calls, or any object type your account created. | Click a card to select it. :::warning If you change the base object after you have already picked columns or filters, Teloring warns you and resets them — because columns and filters belong to the object you started with. ::: ### Step 2 — Columns Choose which fields become table columns. The field picker has two groups: | Group | What it contains | | --- | --- | | **[Object] fields** | The native fields of the base object (for example, a deal's name, amount, and stage). | | **From Customer** | Fields from the **customer** the record belongs to (for example, the customer's email or lifecycle stage). | ![Teloring view builder columns](pathname:///img/screenshots/product/views/builder-columns.png) Check a field to add it as a column. On the right, your chosen columns can be: | Control | What it does | | --- | --- | | Drag handle (⠿) | Drag a column up or down to reorder it. | | Rename box | Click the column name and type your own header label. | | Remove (×) | Take the column out of the view. | A **From Customer** column carries a small *Customer* tag so it is clear the value comes from the customer, not the record. :::note The **From Customer** group appears for every base object **except Customers** — on a Customers view, the customer *is* the row, so its fields are already in the first group. ::: #### Why customer columns, but not "sibling" columns Every record under a customer belongs to exactly **one** customer, so "the customer's email" is always a single, clear answer. That is why you can pull customer columns onto a deal, a note, or a service call. You cannot pull columns from another object — for example, you cannot add "the deal's amount" as a column on a **Notes** view. A customer can have many deals, so *which* deal's amount is unclear. When you need to filter on the customer's other records, use a **related-records filter** instead (see below), which asks a yes/no question ("does the customer have a deal?") and has no such ambiguity. ### Step 3 — Filters Filters decide which rows appear. A view with no filters shows every record of the base object. Filters are organized into **groups**. Each group combines its conditions with one setting: | Match mode | Meaning | | --- | --- | | AND | A row is included only if **every** condition in the group is true. | | OR | A row is included if **at least one** condition is true. | Toggle **AND** / **OR** at the top of each group. You can nest one group inside another (up to two levels) to build logic like *"stage is Open **AND** (amount over 1000 **OR** priority is High)"*. ![Teloring view filters](pathname:///img/screenshots/product/views/builder-filters.png) Inside a group you can add three kinds of conditions. #### 1. A field condition Click **+ Add filter** to add a row that tests one field. A field condition has three parts: | Part | Meaning | | --- | --- | | Field | The field to test. The picker is grouped into the object's own fields and **From Customer** fields, so you can filter on either the record or its customer. | | Operator | How to compare — equals, is any of, contains, before, in the last…, and more. The available operators match the field type. | | Value | What to compare against. Where the value is a known list (a dropdown field, an agent, a stage), Teloring shows a **dropdown** instead of a free text box. | The operators are exactly the same set used across **Analytics**, so "This month" or "In the last 7 days" means the same thing everywhere in Teloring. See [Operators](#operators) below for the full list. #### 2. Compare to another field Any field condition can compare a field to **another field** instead of to a fixed value. Click the **⇄ Compare to field** toggle on a condition row and pick the field to compare against. This is useful for questions like: | Example | Meaning | | --- | --- | | Deal *created date* **equals** customer *renewal date* | Deals created exactly on the renewal date. | | Deal *amount* **is greater than** customer *credit limit* | Deals above the customer's limit. | Teloring only offers fields of the **same type** on the other side — a date can only be compared to another date, a number to another number — so a comparison can never be set up incorrectly. :::note When comparing two **date** fields for equality, Teloring matches on the **day**, not the exact second — so a record created at any time on the renewal date counts as a match. ::: #### 3. A related-records filter Click **+ Add related-records filter** to filter on the customer's **other** records — without adding them as columns. These rows look different on purpose (a dashed, highlighted style) because they ask about the customer, not about the row itself. They read as a sentence: > **Customer** [ has at least ] [ 1 ] [ Documents ] *(optional: where …)* | Part | Choices | | --- | --- | | Quantity | **has at least**, **has no**, **has exactly**, or **has more than**. | | Number | How many records (hidden when you choose *has no*). | | Object | Which related object to look at — Documents, Tasks, Deals, and so on. | | Where (optional) | One or more conditions the related records must match, added with **+ Add condition**. | Examples: | Filter | Meaning | | --- | --- | | Customer **has at least 1** Documents | The customer has signed or uploaded at least one document. | | Customer **has no** Tasks | The customer has no task records at all. | | Customer **has at least 1** Tasks *where Created at is In the last 24 hours* | The customer got a new task in the last day. | :::tip **"Has none"** is just the **has no** quantity — there is no separate switch. Use it to find customers missing something, such as leads with no task or customers with no signed document. ::: ### Step 4 — Sort Choose the order of the rows. Add one or more **sort levels**; each has a field and a direction (**Ascending** or **Descending**). You can sort by the object's own fields or by **From Customer** fields, and you can add up to three levels — for example, sort by stage, then by amount within each stage. ### Step 5 — Name & sharing Finish the view with: | Field | Meaning | | --- | --- | | View name | Required. A clear title such as *Open deals with documents*. | | Description | Optional one-line summary shown on the landing page. | | Who can see this view | **Personal** (only you) or **Shared with account** (everyone). See [Sharing and scope](#sharing-and-scope). | Click **Save view** to create it. You land on the opened view. ### Live preview As you configure the view, the **Live preview** pane shows the first rows and a running row count, so you can see the effect of each change immediately. While you are still filling in a condition, the preview simply ignores it until it is complete — so you always see data, not an error. Full validation happens when you save. ## The opened view Opening a view shows its full-width table. ![Teloring opened view](pathname:///img/screenshots/product/views/view-runner.png) | Area | What it is | | --- | --- | | Header | The view name, its scope badge, and description. | | Toolbar | **Edit**, **Duplicate**, **Export ▾**, **Pin / Unpin**, and **Delete**. | | Filter chips | A read-only summary of the view's filters. Click any chip to open the builder and change them. | | Table | The rows, with sticky column headers. Columns pulled **From Customer** are marked with a small ⤷ indicator. | | Footer | The total row count and pagination (50 rows per page). | ### Sort by clicking a column Click any column header to sort the table by it; click again to reverse. This is a quick, temporary sort — it does **not** change the saved view. When your click-sort differs from the view's saved sort, a **Save sort to view** bar appears so you can either keep the new order permanently or **Reset** back to the saved one. ### Open a record from a row Views are a way *into* your existing records, not a new place to edit them. Click any row to jump to the real record: | Row type | Opens | | --- | --- | | A customer | That customer's profile. | | A record under a customer (note, deal, task, and so on) | That customer's profile with the record open. | | A contact | The customer the contact belongs to. | | A conversation | That conversation. | ### Empty result If nothing matches, the view shows *"No records match this view's filters"* with a shortcut to edit the filters. Widen or remove a condition to see rows. ## Sharing and scope Every view is either personal or shared with the account. | Scope | Who can see it | | --- | --- | | Personal | Only you (the creator). It appears on your **My Views** tab. | | Shared with account | Everyone in the account. It appears on the **Account Views** tab. | | Behavior | Detail | | --- | --- | | Set at creation | Choose the scope in Step 5 when you build the view. | | Changeable later | Edit the view and change the scope at any time. | | Reverting to personal | Only the view's **owner** can turn a shared view back into a personal one. | | Editing shared views | Any agent can open and edit an account view — keep that in mind for views the whole team relies on. | | Deleting shared views | Deleting an account view warns you that it is shared with the whole account before removing it for everyone. | ## Pinned views Pin the views you use most to the sidebar for one-click access. ![Teloring pinned views in the sidebar](pathname:///img/screenshots/product/views/pinned-views-sidebar.png) | Fact | Detail | | --- | --- | | Where to pin | Use the 📌 button on a landing-page row, or the **Pin** button inside an open view. | | Where they appear | Under the **Views** item in the sidebar, as named shortcuts. | | Per person | Pins are yours alone. Pinning a view does not pin it for anyone else. | | Limit | Up to **five** pinned views. To pin a sixth, unpin one first — Teloring reminds you when you hit the limit. | ## Export to Excel or PDF You can export a view's results from the landing-page **⋮** menu or the **Export ▾** button inside an open view. | Format | Best for | | --- | --- | | Excel (`.xlsx`) | Working with the data in a spreadsheet. Columns keep your labels, and dates and numbers export as real dates and numbers. | | PDF | Sharing a clean, printable table. It carries the view name, your account name, and the export time in the header. | | Fact | Detail | | --- | --- | | Full result | The export includes the **entire** result set — every matching row, not just the page you are viewing. | | Your setup | Columns, labels, filters, and current sort are all respected. | | Download | The file downloads to your computer when it is ready. | :::note A PDF export is capped at the first 3,000 rows to keep the document usable. For very large results, use Excel. ::: ## Worked examples These recipes show how the pieces fit together. | Goal | Base object | Columns | Filters | Sort | | --- | --- | --- | --- | --- | | All notes with their customer's email | Notes | Note title, content, created at, **customer email** | — | Created at, descending | | Open leads | Customers | Name, email, phone, lifecycle stage | Lifecycle stage is **Lead** | Created at, descending | | Service calls opened this week | Service Calls | Subject, status, created at, **customer name**, **customer phone** | Created at is **This week** | Created at, descending | | Open deals whose customer has a signed document | Deals | Deal name, amount, stage, **customer email** | Stage is **Open** **AND** customer **has at least 1** Documents | Amount, descending | | Deals created on the customer's renewal date | Deals | Deal name, amount, **customer renewal date** | Deal *created date* **equals** customer *renewal date* (compare to field) | — | | Customers with no open tasks | Customers | Name, lifecycle stage, assigned agent | Customer **has no** Tasks | Name, ascending | | High-value deals over the customer's credit limit | Deals | Deal name, amount, **customer credit limit** | Deal *amount* **is greater than** customer *credit limit* (compare to field) | Amount, descending | ## Operators Field conditions offer operators that match the field's type. These are the same operators used in [Analytics](./analytics.md). ### Text, number, choice, and list fields | Operator | Use it to | | --- | --- | | Equals / Not equals | Match an exact value. | | Is any of / Is none of | Match against several values at once. | | Contains / Doesn't contain | Match part of a text value, or membership in a list field such as tags. | | Starts with / Ends with | Match the beginning or end of a text value. | | Greater than / Less than (and or-equal) | Compare numbers. | | Between | Match a numeric range. | | Is empty / Is not empty | Match rows with no value, or any value, in the field. | | Is true / Is false | Match a yes/no field. | ### Date fields Date fields offer a rich set of **relative** time operators — they always move with the current date, so a view set to *This month* keeps showing the current month over time. | Group | Operators | | --- | --- | | Exact | On date, Not on date, Before date, After date, Between dates. | | Relative (number + unit) | In the last…, In the next…, More than … ago. Units: minutes, hours, days, weeks, months. | | Day | Today, Yesterday, Tomorrow, Today & yesterday, Today & tomorrow. | | Week | This week, Last week, Next week, 2 weeks ago, Next 2 weeks. | | Month | This month, Last month, Next month, Last 2 months, Next 2 months. | | Quarter | This quarter, Last quarter, Next quarter, Q1–Q4 of this year. | | Year | This year, Last year, Next year. | | Rolling | In the last hour / 2 hours, Last 30 / 60 / 90 days, Next 30 / 60 / 90 days. | | Presence | Has a value, Has no value. | ## Tips | Tip | Why it helps | | --- | --- | | Name views clearly | A good title explains the view at a glance on the shared Account Views tab. | | Start from a starter view | Duplicate "All Notes" or "Open Leads" and adjust it instead of building from scratch. | | Use **From Customer** columns | Add the customer's email or phone to any object view so a row is actionable on its own. | | Prefer relative date filters | "This week" or "In the last 7 days" stays correct over time without editing. | | Use related-records filters for "has / has no" | They answer "does this customer have any X" without the ambiguity of pulling in sibling columns. | | Pin your daily views | Keep the two or three lists you use every day one click away in the sidebar. | | Share the team's core views | Put views the whole team relies on in **Account** scope so everyone works from the same list. | ## Troubleshooting | Problem | What to check | | --- | --- | | The view is empty | A filter may be too narrow. Open the filters and widen or remove a condition. Remember AND requires **every** condition to match. | | I can't add a customer column | You are on a **Customers** view — the customer's fields are already the row's own fields, so there is no separate **From Customer** group. | | I can't add a "sibling" object as a column | That is by design. Use a **related-records filter** to ask about the customer's other records, or add the value to the customer with your admin's help so it becomes a customer column. | | The right side of "Compare to field" has few options | Only fields of the **same type** are offered, so a date compares to a date and a number to a number. | | My column sort didn't save | Clicking a column header is a temporary sort. Use the **Save sort to view** bar that appears to keep it, or **Reset** to go back. | | The row count says "showing the first 10,000" | A view returns at most 10,000 rows. Add a filter (such as a date range) to narrow the result. | | I can't pin another view | You already have five pinned views. Unpin one first. | | A shared view was changed by someone else | Any agent can edit an account view. Move critical views to the **Account** tab deliberately, and use personal views for private working lists. | | A new custom object isn't listed as a base object | Make sure the object type is enabled in the CRM. New object types appear as view base objects automatically once created. | --- # Conversation Attributes Source: https://docs.teloring.com/docs/product/conversation-attributes Markdown: https://docs.teloring.com/markdown/docs/product/conversation-attributes.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z **Conversation Attributes are custom fields that belong to one conversation.** You design them once for the whole account — *Reason for contact*, *Outcome*, *Order number*, *Refund amount* — and agents fill them in from the right side of the conversation while they work. The important word is **conversation**. A contact field describes a *person* and follows them for ever. A conversation attribute describes *this exchange*: why they wrote in today, what you did about it, which order was involved. The same customer writing again next week starts with a **clean, empty set** — because it is a new conversation with a new reason and a new outcome. That is what makes them worth reporting on. "How many conversations were about billing this month?" is a question about conversations, and only a field stored on the conversation can answer it. :::info One set of attributes per account Unlike CRM objects, where you can create *Deals*, *Tasks* and *Contracts* side by side, an account has exactly **one** set of conversation attributes. Every conversation in the account — every channel, every inbox — can carry the same attributes. There is nothing to choose before you start filling them in. ::: ## Key facts | Fact | Meaning | | --- | --- | | Stored on the conversation | Values live with that one conversation, never on the contact or the customer. | | Fresh every conversation | A new conversation with the same person starts empty. Nothing is inherited or copied forward. | | One set per account | You design one layout in Settings; it applies to every conversation. | | One field per row | The conversation panel is a narrow column, so attributes always stack one per line. The builder previews it exactly that way. | | Filled in by people **or** automation | Agents type them in the panel; [Studio](./studio.md) flows set them automatically. | | Available to automation | Every attribute becomes a `{{conversation.custom_attributes.…}}` variable for later Studio blocks, including HTTP requests. | | Reportable | Attributes appear in [Analytics](./analytics.md) as fields you can group by, measure and filter on. | | Kept after resolve | Values travel with the conversation into the resolved archive and stay readable there. | | Permission-controlled | A separate [role permission](./roles/system-permissions.md#workspace) decides who can see, fill in, and change attributes. | ## What people use them for | Attribute | Type | Why | | --- | --- | --- | | Reason for contact | Dropdown — Billing, Technical, Sales, Complaint | The single most useful reporting field most support teams are missing. | | Outcome | Dropdown — Solved, Escalated, Refunded, No action | Lets you measure resolution quality, not just resolution speed. | | Order number | Text | Ties a conversation to an order in your own system, and can be pushed there by Studio. | | Refund amount | Currency | Sum it in Analytics to see money moved per month, per agent, per channel. | | Follow-up date | Date | A date you can filter and report on. | | Products discussed | Multi-select | Which products come up most often, per channel. | | Handled by (specialist) | Agent picker | Records who really solved it when it passed through several people. | | Escalated to vendor | Checkbox / dropdown | A simple flag you can count. | :::tip Attributes, labels, or tags? All three organize a conversation, but they answer different questions. - **Labels** are a flat, free-growing list agents add on the fly. Great for loose themes; hard to report on consistently because anyone can invent a new one. - **Attributes** are a **structured form**: a fixed set of named fields, each with its own type and its own allowed values. Use them when you want the same answer in the same place on every conversation. - **Tags** behave like labels. A good rule: if you would put it in a spreadsheet column, it is an attribute. ::: --- ## Part 1 — Build your attributes (Settings) Designing the attributes is an admin job you do once. Agents never see this screen. Open **Settings → Conversation Attributes** from the sidebar. ![The Conversation Attributes builder in Teloring Settings, with the layout on the left, the live preview underneath it, and the toolbox of attribute types on the right](pathname:///img/screenshots/product/conversation-attributes/builder-overview.png) The screen has three parts: | Area | What it is | | --- | --- | | **Left — layout** | Your sections and the attributes inside them. This is the thing you are building. | | **Left, below — preview** | A live mock-up of the panel agents will see in the conversation. It updates as you work. | | **Right — toolbox** | One draggable block per attribute type, plus a **Section** block. | If you have used the CRM [field editor](./crm.md#field-editor), this is the same idea with one deliberate difference: **conversation attributes are always one per row**, because the conversation panel is a narrow column and a two-column form would not fit. ### Add an attribute 1. **Drag** an attribute type from the toolbox on the right into a section on the left. 2. The edit popover opens automatically. Set the **Label**, and the **API ID** if you want something friendlier than the generated one. 3. For a choice type, add your **Options**. 4. Tick **Required** if agents must fill it in. 5. Click **Save** in the popover to close it. 6. Repeat for every attribute, then click **Save Attributes** at the top right. Nothing is live until you click **Save Attributes**. :::note Drag to a specific spot Dropping an attribute **onto an existing card** inserts it *above* that card. Dropping it into the empty area of a section adds it at the end. Drag existing cards around the same way to reorder them, or into another section to move them. ::: ### Attribute properties Click any attribute card to open its editor. ![The attribute edit popover showing Label, API ID, Options and the Required checkbox](pathname:///img/screenshots/product/conversation-attributes/attribute-edit-popover.png) | Property | What it does | Notes | | --- | --- | --- | | **Label** | The name agents see above the field. | Write it the way your team talks — *Reason for contact*, not *reason_code*. Change it whenever you like; it does not affect stored data. | | **API ID** | The stable technical name — used in Studio variables, Analytics field names, and the API. | Lowercase letters, numbers and underscores, starting with a letter (for example `reason_for_contact`). See the warning below before changing one. | | **Options** | The allowed values for a choice attribute. | Only shown for Dropdown, Radio, Multi-select and Checkbox. At least one option is required. | | **Required** | Marks the attribute with a red `*` for agents. | A visual signal for the team. It does not block an agent from saving the rest of the panel. | :::warning Changing an API ID does not move existing data The API ID is the key the values are stored under. Renaming `reason` to `contact_reason` gives you a **new, empty** attribute — the values already saved under the old name are no longer shown, and any Studio block or report referring to the old name stops finding data. Set the API ID when you create the attribute, then leave it alone. The **Label** is the safe thing to change later — rename it as often as you want. ::: ### Attribute types | Type | Agent sees | Best for | In Analytics | | --- | --- | --- | --- | | **Text** | A single-line box | Order number, reference, external ID | Filter only | | **Text Area** | A multi-line box | A short free-text note about the conversation | Filter only | | **Number** | A numeric box | Counts, quantities, scores | Sum, average, min, max | | **Currency** | A numeric box | Refund amount, order value, credit given | Sum, average, min, max | | **Dropdown** | A single-choice list | Reason for contact, outcome, department | **Group by**, filter | | **Radio** | A single-choice list | The same as Dropdown — in the narrow conversation panel both are shown as a dropdown list | **Group by**, filter | | **Multi-select** | A checkbox for each option, several allowed | Products discussed, systems affected | **Group by**, filter | | **Checkbox** | A checkbox for each option, several allowed | Multiple yes/no flags from one list | **Group by**, filter | | **Date** | A date picker | Follow-up date, promised date | Time grouping | | **Date & Time** | A date and time picker | Scheduled callback | Time grouping | | **Email** | A box with email keyboard | An alternative contact address for this issue only | Filter only | | **Phone** | A box with phone keyboard | A callback number for this issue only | Filter only | | **URL** | A link box | A ticket link in another system | Filter only | | **Agent Picker** | A list of your agents | Who really handled it, second-line owner | **Group by**, filter | | **Caption** | Read-only helper text | An instruction or divider inside the panel | Not stored, not reported | :::tip Choose Dropdown over Text whenever you can A dropdown gives you consistent, countable answers. A text box gives you `billing`, `Billing`, `billling` and `bill q`. If you ever want to chart the field, make it a choice type. ::: :::note About **Caption** A caption is a note to the agent — *"Only fill the refund fields when money was actually returned."* It is never stored on a conversation, never appears in Studio, and never appears in Analytics. It cannot be marked required. ::: ### Sections Sections group attributes under a small heading in the agent's panel. Use them when you have more than a handful of attributes — for example **Why they wrote** and **What we did**. | Action | How | | --- | --- | | Add a section | Click **➕ Add Section** and type a name, or drag the **Section** block from the toolbox. | | Rename a section | Click the ✏️ button on the section header. | | Reorder sections | Drag a section header up or down. | | Move an attribute between sections | Drag its card into the other section. | | Delete a section | Click the ✕ on the section header. Its attributes move to the first section — they are not deleted. | With a single section, agents see no heading at all — just the fields. Section headings only appear when there is more than one. ### The live preview Under the layout you get a **Conversation panel preview**: exactly what agents will see, in the same one-per-row order, with your section headings and your `*` marks. Use it to sanity-check length. A panel with twenty attributes is a panel nobody fills in. Most teams do well with **four to eight**. ### Limits | Limit | Value | | --- | --- | | Sections | 20 | | Attributes | 60 | | Options per choice attribute | 100 | ### Deleting an attribute Remove an attribute by clicking the **✕** on its card, then **Save Attributes**. | What happens | Detail | | --- | --- | | It disappears from the agent panel | Immediately, on the next conversation opened. | | Existing values are **kept** | The data stays on the conversations that already had it — it is history, and deleting a field should not destroy the record of what happened. | | Put it back and the data returns | Re-create the attribute with the **same API ID** and the old values are visible again. | | Studio blocks that set it | Skip it silently and keep running. Your flow does not break. | | Reports that use it | Stop finding new values. Edit the report to point at something else. | | Permission | Removing an attribute needs **Conversation attributes → Delete**, which is separate from editing. | --- ## Part 2 — Fill attributes in (the conversation) Agents work with attributes in the **right sidebar** of a conversation, in a section called **Conversation Attributes**, just above AI Copilot. ![The Conversation Attributes section in the conversation right sidebar, above AI Copilot](pathname:///img/screenshots/product/conversation-attributes/conversation-panel.png) 1. Open a conversation. 2. Expand **Conversation Attributes** in the right sidebar. 3. Fill in the fields. 4. Click **Save**. That is the whole workflow. Values save to **this conversation only**. | Behavior | Detail | | --- | --- | | Collapsible | Click the section header to open or close it, like the other sidebar sections. | | Saves what you see | Only the fields shown are saved. An attribute added after this conversation started is never wiped by an older panel. | | Does not bump the queue | Saving an attribute is bookkeeping, not a customer message — the conversation does **not** jump to the top of anyone's list. | | Partial is fine | Fill in what you know now and come back later. `*` marks an attribute your team considers important; it does not block saving. | | Read-only for some roles | With **Read** but not **Update**, the fields are visible but greyed out. | | Hidden when empty | If your account has not defined any attributes, the section does not appear at all. | ### Where it is not shown | Situation | Why | | --- | --- | | The account has no attributes yet | Nothing to show. Build them in Settings first. | | The role has no **Conversation attributes → Read** | The whole section is hidden. | | A resolved conversation | It becomes **read-only** — see below. | --- ## Part 3 — Resolved conversations When a conversation is resolved, its attributes go with it. Open the **Resolved** queue and select a conversation: the right panel shows a read-only **Conversation Attributes** block alongside the timeline, labels, emotion and contact details. ![Conversation Attributes shown read-only in the resolved conversation properties panel](pathname:///img/screenshots/product/conversation-attributes/resolved-panel.png) | Behavior | Detail | | --- | --- | | Read-only | A resolved conversation is a record of what happened. Re-open it if you genuinely need to correct a value. | | Only filled attributes | Attributes nobody answered are left out, so the block stays short and readable. | | Agent names, not IDs | An **Agent Picker** value shows the person's name. | | Multi-select values | Shown as a comma-separated list. | :::note Resolving does not force you to fill anything in Teloring does not block the **Resolve** button on an empty attribute. If your process needs "no resolve without a disposition", enforce it with team policy — or build a [Studio](./studio.md) flow that reacts to a resolve and notifies the agent when a key attribute is empty. ::: Attributes are also included in the `conversation.resolved` **webhook**, in full — not just the ones the closing action happened to change — so an external system receiving a resolved conversation gets the whole picture in one payload. --- ## Part 4 — Automation (Studio) [Studio](./studio.md) can both **read** and **write** conversation attributes. ### Setting attributes from a flow Attributes are set inside the existing **[Change Conversation](./studio/actions.md#change-conversation)** action — there is no separate block. They are fields on the conversation, exactly like priority and subject, so a flow that sets three attributes and a label stays one readable node. ![The Conversation attributes picker inside the Change Conversation action in Studio](pathname:///img/screenshots/product/conversation-attributes/studio-change-conversation.png) 1. Add or open a **Change Conversation** block. 2. Scroll to **Conversation attributes**. 3. Click **Add field**, choose an attribute from the **Select a field** list, and type its value. 4. Values accept `{{variables}}` — for example `{{webhook.body.order_id}}` or `{{answers.reason}}`. If the account has no attributes yet, the picker says *"No conversation attributes are set up for this account yet."* Build them in Settings first. Common uses: | Flow | What it sets | | --- | --- | | A bot asks "what is this about?" and offers three buttons | *Reason for contact* = the button the customer pressed | | A form is submitted and starts a conversation | *Order number* = the order number from the form answers | | An HTTP request looks the customer up in your ERP | *Account tier* = the tier the API returned | | A conversation is auto-resolved by the bot | *Outcome* = `Solved by bot` | | Rule | Behavior | | --- | --- | | Values are validated | A dropdown value that is not one of your options **fails the block**, so a flow can never write something the agent panel would refuse to display. | | Deleted attributes are skipped | If an attribute is removed from Settings after the flow was built, the block skips that line and keeps running. | | Existing values are merged | Setting one attribute does not clear the others. | | Multi-select values | Separate them with commas or new lines. | ### Reading attributes in a flow Every attribute becomes a variable named after its **API ID**: ``` {{conversation.custom_attributes.reason_for_contact}} {{conversation.custom_attributes.order_number}} ``` And the whole set is available as one object: ``` {{conversation.custom_attributes}} ``` | Where they come from | Detail | | --- | --- | | The trigger | **Incoming Message**, **Incoming Call** and **Conversation Changed** all load the conversation's current attributes. You do not need a Change Conversation block to read them. | | A Change Conversation block | After the block runs, the variables hold the **new** values, so every block below it sees what was just written. | | An attribute nobody filled in | Resolves to an empty value, not to the raw `{{placeholder}}`. | This is what makes attributes useful to an **[HTTP Request](./studio/actions.md#http-request)**: put `{{conversation.custom_attributes.order_number}}` in the URL or body to look the order up, or send `{{conversation.custom_attributes}}` to push the whole disposition into your own system in one field. Branch on them with a **[Condition If/Else](./studio/conditions.md)** block — for example, route every conversation whose *Reason for contact* is `Billing` to the finance [team](./teams.md). :::tip A flow can react to an agent filling one in Saving the attributes panel counts as a conversation change, so a **[Conversation Changed](./studio/triggers.md)** trigger fires. Use it for rules like *"when Outcome is set to Escalated, notify the duty manager"*. ::: --- ## Part 5 — Reporting (Analytics) Conversation attributes are first-class fields in [Analytics](./analytics.md). 1. Create a report and choose the **Conversations** data source. 2. Your attributes appear in the field lists, named with their labels. 3. Use them as **Group by**, as a **measure**, or as a **filter**. There is nothing to select first — an account has one attribute set, so they are always available on the Conversations source. | Question | Report | | --- | --- | | What are people contacting us about? | Pie, Conversations, **Group by** *Reason for contact* | | Which reasons take longest to resolve? | Bar, Conversations, **Average** of *Resolution time*, **Group by** *Reason for contact* | | How much did we refund this month? | Value card, Conversations, **Sum** of *Refund amount* | | Billing conversations per week | Line, Conversations, **Count**, **Group by** time, filtered to *Reason for contact* = `Billing` | | Which agent handles the most complaints? | Bar, Conversations, **Count**, **Group by** *Assigned agent*, filtered to *Reason for contact* = `Complaint` | | Outcomes by channel | Stacked bar, Conversations, **Count**, **Group by** *Channel type*, stacked by *Outcome* | What each type can do is in the [attribute types table](#attribute-types) above. In short: choice and agent-picker attributes can be **grouped by**; number and currency attributes can be **summed and averaged**; date attributes can drive **time grouping**; text attributes are for filtering. :::note Reports only see what was filled in An attribute added in March cannot describe a conversation from January, and conversations nobody filled in group under `(none)`. That is a good early signal — a large `(none)` slice usually means the attribute is not part of the team's routine yet. ::: --- ## Permissions Conversation attributes have their own row on the [System permissions](./roles/system-permissions.md#workspace) tab of a role, under **Workspace**. | Action | What it grants | | --- | --- | | **Read** | See the Conversation Attributes section in a conversation and on a resolved conversation, and open the Settings page to look at the design. | | **Update** | Fill values in on a conversation, **and** add or edit attributes in Settings. | | **Delete** | Remove an attribute from the account's design. | There is no **Create**, because an attribute is part of one account-wide design — adding one *is* editing that design. :::warning "Update" covers both filling in and designing This mirrors how **Customers → Update** also covers the CRM field editor. If you want front-line agents to fill attributes in without being able to redesign them, that separation does not exist today — the practical control is that the Settings page is not somewhere agents normally go. ::: Default roles: | Role | Access | | --- | --- | | Owner | Everything, always. | | Team Leader | Read, Update, Delete. | | Marketing | Read, Update. | | Agent | Read, Update — so front-line agents can fill attributes in. | | Viewer | Read. | :::note Existing accounts must grant it once This is a new permission. Roles that already existed before it was added do **not** have it ticked, so at first only the **Owner** sees the feature. Open **Roles & Permissions**, tick **Conversation attributes** on the roles that need it, and save. New accounts get the defaults above automatically. ::: --- ## Attributes vs. everything else | Store it as | When | Lives on | | --- | --- | --- | | **Conversation attribute** | It is true of *this conversation* — the reason, the outcome, the order being discussed. | The conversation | | **Contact field** ([field editor](./crm.md#field-editor)) | It is true of the *person* — their department, their preferred language. | The contact | | **Customer field** ([CRM](./crm.md)) | It is true of the *business* — their plan, their industry, their account manager. | The customer | | **CRM object record** ([CRM](./crm.md#custom-objects)) | It is a *thing* with its own life — a deal, a service call, a contract. It can outlive the conversation and there can be many per customer. | Its own record under the customer | | **Label** | A loose, quickly-added theme. | The conversation | A quick test: *if the same person contacted you again tomorrow, should this value still be there?* If **yes**, it is a contact or customer field. If **no**, it is a conversation attribute. --- ## Worked example — a support desk disposition A five-minute setup most support teams can copy. **In Settings → Conversation Attributes:** | Section | Attribute | Type | Options | | --- | --- | --- | --- | | Why they wrote | Reason for contact `reason_for_contact` | Dropdown, required | Billing · Technical · Sales · Complaint · Other | | Why they wrote | Order number `order_number` | Text | — | | What we did | Outcome `outcome` | Dropdown, required | Solved · Escalated · Refunded · No action needed | | What we did | Refund amount `refund_amount` | Currency | — | | What we did | Follow-up needed by `follow_up_by` | Date | — | **For agents:** fill the two dropdowns before resolving. Thirty seconds a conversation. **In Studio:** a welcome flow asks "What can we help with?" with three buttons and writes the answer straight into *Reason for contact*, so most conversations arrive pre-classified. **In Analytics:** a board with a pie of *Reason for contact*, a bar of average resolution time by reason, and a value card summing *Refund amount* this month. Within a month you can answer *"what do people actually contact us about, how long does each type take, and how much is it costing us"* — from data your team was already producing. --- ## Tips | Tip | Why it helps | | --- | --- | | Start with two attributes | *Reason* and *Outcome* answer most questions. Add more once the habit sticks. | | Prefer choice types | Consistent values are the difference between a chart and a mess. | | Keep the panel short | Four to eight attributes get filled in. Twenty do not. | | Add an **Other** option | Without it, people pick the nearest wrong answer and quietly poison the data. | | Use a **Caption** for instructions | One line of guidance in the panel beats a training document nobody re-reads. | | Pre-fill with Studio | Anything the bot, a form, or an API already knows should not be typed by a human. | | Watch the `(none)` slice | It tells you how well the team has adopted the field. | | Set API IDs deliberately | They are the names in your reports, your flows, and your API. Choose them once. | ## Troubleshooting | Problem | What to check | | --- | --- | | I don't see the section in a conversation | The account may have no attributes yet, or your role is missing **Conversation attributes → Read**. Existing roles do not get the new permission automatically. | | The fields are greyed out | Your role has **Read** but not **Update**. | | I can't open the Settings page | Your role needs **Conversation attributes → Read** to view it and **Update** to change it. | | Saving fails with "not one of the allowed options" | The value does not match the attribute's option list. This usually means a Studio block sends a value that was later renamed in Settings. | | A Studio block will not save the attribute | Check the attribute still exists in Settings and that its **API ID** has not been renamed. A renamed API ID is a different attribute. | | My old values disappeared | An **API ID** was probably renamed. Rename it back to the original and the values reappear — the data was never deleted. | | The attribute isn't in my report | Make sure the data source is **Conversations**. Text and text-area attributes can only be filtered on, not grouped by — use a choice type for grouping. | | A big `(none)` group in a report | Those conversations have no value for that attribute — usually conversations from before the attribute existed, or conversations nobody filled in. | | I deleted an attribute by mistake | Re-create it with the **same API ID**. The values were kept and become visible again. | | Values from an old conversation appeared on a new one | They cannot. Attributes are per conversation. If two conversations show the same value, both were filled in — check whether a Studio flow is setting it. | ## Related guides - [Conversations](../getting-started/conversations.md) — the agent workspace and the right sidebar. - [CRM and customers](./crm.md) — contact fields, customer fields, and custom objects. - [Studio — Change Conversation](./studio/actions.md#change-conversation) — setting attributes from a flow. - [Studio — Variables](./studio/variables.md) — using `{{conversation.custom_attributes.*}}`. - [Analytics](./analytics.md) — building reports on your attributes. - [System permissions reference](./roles/system-permissions.md#workspace) — the Conversation attributes permission. - [Account settings](./settings.md) — the rest of the Settings area. --- # Example roles and recipes Source: https://docs.teloring.com/docs/product/roles/examples Markdown: https://docs.teloring.com/markdown/docs/product/roles/examples.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Complete setups you can copy. Each one starts from **Duplicate** on an existing role, because that is far faster and safer than ticking an empty grid. Every recipe lists only what to **change**. Anything not mentioned stays as the role you duplicated had it. :::tip Test a role before you hand it out Create one spare agent — *test@yourcompany.com* — and assign the new role to it. Sign in as that agent in a private browser window and click through what they are supposed to do. Five minutes of that catches more than an hour of reading checkboxes, and it never risks your own access. ::: --- ## Front-line support agent The most common role. Answers customers, keeps records tidy, touches no configuration. **Already built for you** — the default **Agent** role is exactly this. Use it as-is. If you want to tighten it slightly: | Change | Why | | --- | --- | | **Quick replies** → drop to **Read** | The shared library is curated by supervisors; agents use it but do not add to it. | | **Customers → Create** off | Customers arrive from conversations and Studio, so agents never need to add one by hand. | | **Achievements → Update** off | Only a manager collects the account's achievement rewards. | --- ## Shift supervisor Runs a shift: sees everything, routes work, handles escalations. No billing, no agent management. **Duplicate:** Team Leader | Tab | Change | | --- | --- | | System | Leave as-is. Team Leader is already scoped for this. | | Channels | Leave as-is — full access to every inbox. | **Optional narrowing:** | Change | Why | | --- | --- | | **Settings → Business hours** → **Read** only | Shift leaders read the schedule; the manager sets it. | | **Files warehouse → Delete** off | Deleting account files is not a shift decision. | | **Delete a conversation** off in Future inbox | Removes the ability to destroy an email thread. | --- ## Floor monitor — watches, does not take A senior agent who oversees the queue, routes work and steps in, but is not part of the rotation. **Duplicate:** Agent | Tab | Change | | --- | --- | | Channels → **Future inbox** | Untick **Get Next in Line**. Keep every *see* ability on. Keep **Can assign conversations** on. | | System | Add **Analytics → Read** so they can see live volume. | They see the whole queue, route it, and are never handed a conversation themselves. --- ## Quality reviewer — comments, never replies Reads conversations for coaching and compliance, annotates them, and the customer never hears from them. **Duplicate:** Agent | Tab | Change | | --- | --- | | Channels → **Future inbox** | Untick **Send a new message**, **Start a new conversation**, **Resolve a conversation**, **Get Next in Line**, **Put a conversation on hold**. Keep **See All Open conversations**, **See all resolved conversations**, **See previous conversations**, **Send a private note**, **Set a label for a conversation**. | | System | **Analytics → Read**. Everything else off except **Customers → Read**. | The two abilities that make this role work are **Send a private note** on (so they can leave coaching notes) and **Send a new message** off (so nothing reaches the customer). --- ## Marketing and campaigns Builds automations, forms and reports. Works its own conversations, not the support queues. **Already built for you** — the default **Marketing** role. Worth knowing: Marketing intentionally has **none** of the *see* abilities, so it works only from *Mine* — conversations assigned to it, or ones it started. If your marketing team also covers a shared inbox, tick that inbox's *see* abilities explicitly and leave **Future inbox** empty. | Common addition | Why | | --- | --- | | **My Ring → Update** | If Marketing manages the live-chat widget's appearance. | | **Document signature → Create** | If Marketing sends contracts or agreements. | | On a specific inbox: **See All Open conversations** | If they share one campaign inbox with support. | --- ## Channel-specific team A team that works one channel and must not see the others — an outsourced WhatsApp team, a language-specific inbox, a regional line. **Duplicate:** Agent | Tab | Change | | --- | --- | | Channels → **Future inbox** | **Clear all**. This is the key step. | | Channels → their inbox | **Select all**, then untick **Delete a conversation**. | | System | Consider dropping **Quick replies** to **Read** and **Files warehouse** off. | Because **Future inbox** is empty, **any inbox you connect later is invisible to this role automatically** — you never have to remember to restrict it. :::warning Do not grant My Ring → Read here An agent with **My Ring → Read** sees every inbox in the account listed on that page, including ones they cannot work in. For a role whose whole purpose is channel separation, leave My Ring off entirely. ::: --- ## External contractor or agency Narrowest useful role. One channel, minimal data, nothing configurable. **Start from:** **+ New role** (an empty grid is right here — you want to grant deliberately, not remove) | Tab | Setting | | --- | --- | | System | **Customers → Read**. **Knowledge base → Read** so they can look up answers. Nothing else. | | Channels → **Future inbox** | Everything off. | | Channels → their inbox | **See the waiting line**, **Get Next in Line**, **Send a new message**, **Resolve a conversation**, **See previous conversations**, **Set a label for a conversation**. | Add [Teams](../teams.md) on top: put the contractor in one team and route only that team's work to them, so **Get Next in Line** hands them nothing outside their scope. | Also do | Why | | --- | --- | | Enforce 2FA — **Settings → Security & login** | External access deserves a second factor. | | Consider the IP allowlist | If they work from a fixed office. | | Check **Admin → Audit Log** periodically | It records what was done and by whom. | --- ## Accountant or bookkeeper Needs invoices, plan and card details. Should never see a customer conversation. **Start from:** **+ New role** | Tab | Setting | | --- | --- | | System | **Billing → Credits → Read**, **Billing → Subscription → Read**, **Billing → Credit cards → Read**, **Billing → Usage pricing → Read**. Nothing else. | | Channels → **Future inbox** | Everything off. | Add **Billing → Credit cards → Create / Update / Delete** only if they actually manage the company card. Leave **Subscription → Update** off unless they choose your plan — that changes what you pay. :::note They will see very little else This role has no **Customers → Read**, so the Customers page is gone too. The sidebar shows the Dashboard, Docs, Achievements if granted, and Billing. That is the point. ::: --- ## Read-only stakeholder A manager, investor or consultant who wants numbers and no access to anything else. **Already built for you** — the default **Viewer** role. Read almost everywhere, write nowhere, and no conversation access at all. If they should also see conversation *content* — an auditor, for instance: | Change | Why | | --- | --- | | Channels → **Future inbox** → tick **See All Open conversations**, **See all resolved conversations**, **See previous conversations** | They can read every conversation and change nothing, because Viewer has no send, resolve or assign abilities. | That combination — every *see* ability on, every *do* ability off — is genuinely read-only across the whole inbox. It is worth knowing it is possible. --- ## Trainee agent Somebody learning the job whose replies should be checked before they touch customers. **Duplicate:** Agent | Tab | Change | | --- | --- | | Channels → **Future inbox** | Untick **Send a new message**. Keep **Send a private note** on. Untick **Resolve a conversation**, **Delete a conversation** and **Can assign conversations**. | | System | Leave as-is. | They can open the whole queue, draft their answer as a **private note**, and a supervisor sends it. When they are ready, tick **Send a new message** — or simply move them to the **Agent** role, which is usually the cleaner step. --- ## AI operations Somebody who tunes Studio flows and AI Agents but is not a support manager. **Duplicate:** Marketing | Tab | Change | | --- | --- | | System | Keep **Studio → all four** and **AI World → Read + Update**. Keep **Knowledge base → all four**. Add **Agents → Read** so they can see AI Agent profiles. Drop **Forms** and **Views** if not needed. | | Channels → **Future inbox** | Tick **See Studio Bot conversations** and **See AI Agent conversations** — they need to watch what the automation is doing. | Those two queues are the ones the default **Agent** role deliberately lacks, and the ones this role most needs. :::note Editing an AI Agent profile needs Agents → Update An AI Agent is a row in the agents directory, so creating or editing one is **Agents → Create / Update** — the same permission as managing people. There is no separate AI-only permission today. If that is too broad, keep AI profile changes with the Owner or Team Leader and give this role **Agents → Read**. ::: --- ## A structure that scales If you are setting up an account from scratch, this is a sound starting point: | Role | Who | Based on | | --- | --- | --- | | **Owner** | You, plus one trusted second person | Fixed | | **Team Leader** | Support manager | Default | | **Agent** | Everyone on the front line | Default | | **Viewer** | Stakeholders who want dashboards | Default | | *(add as needed)* | Marketing, contractors, accountant | Recipes above | Four roles cover most accounts. Add a fifth when a real person does not fit one of them — not in advance. :::tip Two Owners, always One Owner is a single point of failure: on holiday, off sick, left the company. Two means Teloring's last-Owner protection never blocks a legitimate change, and somebody can always reach billing and settings. ::: ### Signs your roles need a rethink | Symptom | What it usually means | | --- | --- | | A role per person | You are modelling people, not jobs. Merge them. | | Everybody is Owner | Nothing is protected. Move most people to Team Leader or Agent. | | A role nobody holds | Delete it, or note in its description why it is being kept. | | A role's permission count keeps climbing | It has been widened one exception at a time. Split it, or promote its holders to a broader role deliberately. | | Agents keep asking for access | The role is too narrow for the actual job. Widen the role rather than moving people to a broader one. | --- ## Related guides - [Roles and Permissions](./overview.md) — creating, editing, assigning and deleting roles. - [System permissions reference](./system-permissions.md) — every feature and action. - [Channel permissions reference](./channel-permissions.md) — the 18 inbox abilities. - [Agents and AI Agents](../agents.md) — assigning a role to a person. - [Teams](../teams.md) — routing, which pairs well with channel-specific roles. --- # Forms Builder Source: https://docs.teloring.com/docs/product/forms Markdown: https://docs.teloring.com/markdown/docs/product/forms.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Forms Builder lets your team create structured forms, publish them to customers, collect submissions, and trigger Studio automations when a form is completed. Use Forms when you need controlled information from customers, such as onboarding details, service requests, surveys, quote requests, approvals, intake forms, or follow-up information after a conversation. Forms are separate from conversations. A form does not create a new inbox and does not become a communication channel. Instead, it collects data and can pass that data to Studio, CRM workflows, or external systems. ## Key facts | Fact | Meaning | | --- | --- | | Forms collect structured data | Customers fill fields on a public form page. | | Forms are versioned | Every save increments the form version. | | Submissions are snapshots | Existing submissions stay readable even if the form is edited or deleted later. | | Layout is column-based | The editor and public form use the same fixed column and row structure. | | Hidden fields do not show | Hidden fields store internal values without taking visible form space. | | Studio can react | Every successful submission fires the `trigger.form_filled` Studio trigger. | | Field IDs matter | Field IDs become Studio variables, export columns, and stable answer keys. | ## Who uses Forms | Role | Typical use | | --- | --- | | Admins | Build forms, configure branding, publish links, and connect submissions to Studio automations. | | Team managers | Review submissions, decide which fields are needed, and make sure forms match operational processes. | | Agents | Share form links with customers when they need structured information. | | Customers | Fill the public form from a browser on desktop or mobile. | ## Forms list Open Forms from the Teloring sidebar. The Forms page includes: | Area | Use it to | | --- | --- | | Forms tab | Create, search, open, duplicate, publish, copy links, and delete forms. | | Submissions tab | Review submitted answers across forms. | | Status filters | Separate drafts, published forms, closed forms, and archived forms. | | Form row actions | Edit a form, duplicate it, copy its public link, or delete it. | ![Teloring Forms list](pathname:///img/screenshots/product/forms/forms-list.png) ## Create a form To create a form: 1. Open Forms. 2. Click Create form. 3. Give the form a clear name. 4. Choose the form type. 5. Open the editor. 6. Add pages and fields. 7. Configure settings. 8. Save. 9. Publish when the form is ready. ## Form types Forms can be open or specific. | Type | Meaning | Best for | | --- | --- | --- | | Open public link | One reusable public link. Anyone with the link can open the form while it is published. | Website forms, public lead forms, general surveys, open requests. | | Specific contact link | A per-contact link generated for a known contact or conversation. The link can carry contact context and can be marked fill-once. | Customer-specific approvals, follow-ups, account updates, personalized requests. | Use an open form when the same form should be shared broadly. Use a specific form when the form belongs to one contact or conversation. ## Editor overview The editor has three main areas: | Area | What it does | | --- | --- | | Left panel | Field palette. Drag elements from here into the page columns. | | Center canvas | The form layout. Add pages, set columns, and reorder fields. | | Right panel | Properties for the selected page, field, or form settings. | ![Teloring Forms editor](pathname:///img/screenshots/product/forms/forms-editor.png) Forms use a fixed column layout. This keeps the public form aligned with the editor. A page can have 1, 2, 3, or 4 columns. Fields are placed into columns and stacked in order. Hidden fields appear in a hidden-field tray and do not take visible space on the public form. ## Pages and columns Use pages to split a long form into manageable steps. Page properties include: | Property | Meaning | | --- | --- | | Title | The heading shown for that page. | | Columns | The number of layout columns on the page, from 1 to 4. | | Visibility | Optional rules that decide whether the page appears. | Use one column for simple forms and mobile-first forms. Use two or more columns when related short fields should sit side by side, such as first name and last name, or phone and email. ## Add and move elements To add an element: 1. Drag an element from the left panel. 2. Drop it into a page column. 3. Select it to edit its properties in the right panel. To reorder fields, drag them within a column or between columns. The public form uses the same column and order structure. ## Field properties Most input fields share these properties: | Property | Meaning | | --- | --- | | Field ID | The stable technical key for the answer. Studio and exports use this ID. Keep it readable, such as `email`, `request_type`, or `campaign_id`. | | Label | The question or field name shown to the customer. | | Placeholder | Light helper text inside the input. | | Help text | Additional guidance shown near the field. | | Required | Forces the customer to fill the field before moving on or submitting. | | Value source | Decides whether the field is filled by the customer, the URL, a fixed hidden value, or contact data. | | Validation | Optional limits such as minimum, maximum, or length depending on field type. | | Visibility | Optional logic that decides whether the field appears. | ### Field ID and Studio Field ID is important. If a text field has field ID `email`, Studio can use: ```text {{answers.email}} ``` If a hidden field has field ID `campaign_id`, Studio can use: ```text {{hiddenValues.campaign_id}} ``` Changing a field ID affects future submissions and Studio variables. Existing submissions remain saved as snapshots. ## Value sources Value source controls where a value comes from. | Value source | Visible fields | Hidden fields | Meaning | | --- | --- | --- | --- | | User input | Yes | No | The customer fills the field. No extra configuration is needed. | | URL param | Yes | Yes | Teloring reads a value from the public form URL. | | Contact field | Yes, for specific forms | Yes, for specific forms | Teloring reads a value from the linked contact. | | Fixed value | No | Yes | A fixed internal value saved with the submission. | Visible fields do not use fixed values. If a value should be fixed and not shown to the customer, use a hidden field. ### URL param example If a visible short text field uses: | Setting | Value | | --- | --- | | Value source | URL param | | URL param | `hi` | Then this form URL: ```text https://forms.teloring.com/f/example?hi=333 ``` prefills the field with: ```text 333 ``` For hidden fields, the same URL param value is stored in `hiddenValues` under the hidden field ID. ## Visibility logic Visibility rules let a field or page appear only when conditions are met. Use visibility logic for: | Scenario | Example | | --- | --- | | Follow-up questions | Show "Describe the problem" only when request type equals "Support". | | Conditional pages | Show a billing page only when the customer selected "Invoice issue". | | Optional consent | Show a signature field only when the customer agrees to terms. | Visibility logic contains: | Part | Meaning | | --- | --- | | Logic | Whether all rules must match or any rule may match. | | Field | The field to check. | | Operator | The comparison, such as equals, contains, greater than, less than, is empty, or is checked. | | Value | The value to compare against when the operator needs one. | Required hidden fields and hidden pages are not forced when they are not visible. Server-side validation rechecks visibility when the customer submits the form. ## Element reference ### Inputs | Element | What customers do | Common use | Important properties | | --- | --- | --- | --- | | Short text | Type one short answer. | Name, city, serial number, account number, subject. | Placeholder, required, value source, min length, max length. | | Long text | Type a longer answer. | Description, notes, complaint details, instructions. | Placeholder, help text, required, min length, max length. | | Number | Enter a numeric value. | Quantity, age, budget, rating amount, ID number when numeric validation is needed. | Required, min, max. | | Email | Enter an email address. | Contact email, billing email, login email. | Required, email validation. | | Phone | Enter a phone number. | Callback number, WhatsApp number, alternate phone. | Required, phone validation. | | Date | Pick a date. | Appointment date, renewal date, birth date, requested service date. | Required, value source. | | Time | Pick a time. | Preferred callback time, appointment time, delivery window. | Required, value source. | | Rating | Choose a number rating. | Satisfaction score, service quality, urgency level. | Required, min, max. | | Checkbox | Check or uncheck one option. | Yes/no confirmation, optional preference. | Required, visibility logic can check whether it is checked. | | Consent | Confirm agreement. | Terms approval, privacy confirmation, marketing consent. | Required, help text. | | User signature | Draw a signature with mouse or finger. | Approvals, confirmations, acceptance, service completion. | Required, help text. The submission stores the signature image. | ### Choice fields | Element | What customers do | Common use | Important properties | | --- | --- | --- | --- | | Dropdown | Choose one option from a menu. | Request type, branch, department, product, issue category. | Options, required, visibility logic. | | Radio | Choose one visible option. | Yes/no with labels, priority, plan, preference. | Options, required, visibility logic. | | Multi-select | Choose multiple options. | Products of interest, symptoms, available days, requested services. | Options, required, visibility logic. | Each option has a label and a value. The label is what users see. The value is what submissions and Studio use. ### Display elements | Element | What it shows | Common use | Important properties | | --- | --- | --- | --- | | Heading | A section title. | Start of a section, page heading, instruction block. | Content. | | Description | Paragraph text. | Instructions, explanations, legal notes, customer guidance. | Content. | | Divider | A horizontal separator. | Separate groups of fields. | No answer is collected. | | Image | An image in the form. | Logo, product image, diagram, example, instruction screenshot. | Upload image or image URL. Uploaded images are stored privately and shown with signed links. | Display elements do not create answers. ### Hidden element Hidden fields save internal values without showing anything to the customer. Use hidden fields for: | Use case | Example | | --- | --- | | Campaign tracking | `campaign_id = summer_2026` | | Source tracking | `lead_source` from a URL param. | | Internal routing | `department = billing` | | External IDs | CRM ID, quote ID, order ID, or customer reference. | Hidden fields can use fixed value, URL param, or contact field as the value source. They do not occupy a visible column or row in the form. ## Form settings Click Settings in the editor to configure the form. ![Teloring form settings](pathname:///img/screenshots/product/forms/form-settings.png) ### General settings | Setting | Meaning | | --- | --- | | Type | Open public link or specific contact link. | | Status | Draft, published, closed, or archived. | | Language | The form language code. | | Direction | Right-to-left or left-to-right layout. | ### Branding settings | Setting | Meaning | | --- | --- | | Primary color | The main accent color used in the public form. | | Background color | The page background color. | | Font family | A bundled font used by the public form. | | Logo | Upload a logo image for the top of the form. | | Background image | Upload a background image instead of using only a color. | | Powered by Teloring | Show or hide the Teloring footer mark. | Uploaded logo, background, and field images are stored in Teloring private storage and count as account files. ### Submission settings | Setting | Meaning | | --- | --- | | Fill once | For specific links, prevents the same link from being submitted more than once. For open links, browser storage provides best-effort duplicate prevention. | | On submit | Show a thank-you message or redirect the customer to another URL. | | Submit button text | The text shown on the final submit button. | | Submit button color | The color of the final submit button. | | Thank you message | Message shown after submit when On submit is message. | | Redirect URL | Destination URL when On submit is redirect. | ### Spam protection | Setting | Meaning | | --- | --- | | Honeypot | An invisible spam trap. Keep it enabled unless support asks otherwise. | | Turnstile | Optional Cloudflare verification when enabled for the account. | ## Save, publish, and share | Action | Meaning | | --- | --- | | Save | Saves the current form as the next version. | | Publish | Makes the form available to customers if the form status is published. | | Copy link | Copies the reusable public URL for open forms. | | Duplicate | Creates a new draft based on an existing form. | | Delete | Deletes the form definition but keeps existing submissions exportable. | :::important After editing a published form, save the changes. New submissions use the latest saved version. Existing submissions keep the original answers and form snapshot. ::: ## Public form experience The public form is the customer-facing page. Customers can: | Action | Meaning | | --- | --- | | Move between pages | Use Previous and Next buttons on multi-page forms. | | Fill required fields | Required fields must be completed before continuing. | | View images | Images added by the form builder can appear as instructions or visual context. | | Sign | Draw a signature with a finger on mobile or a mouse on desktop. | | Submit | Send the completed form to Teloring. | ![Teloring public form](pathname:///img/screenshots/product/forms/public-form.png) ## Submissions Every submission is saved as an immutable snapshot. This means the submission remains readable even if the form is later edited or deleted. Submissions include: | Data | Meaning | | --- | --- | | Submission ID | Unique ID for the submission. | | Form name and version | The form version used by the customer. | | Answers | Visible fields that the customer answered or that were prefilled. | | Hidden values | Hidden fields saved with the submission. | | Source params | URL parameters received by the public form link. | | Contact ID | Present when the form used a specific contact link. | | Conversation ID | Present when the form link was generated from a conversation context. | | Submitted time | The time the form was submitted. | Open the Submissions tab to review submitted answers. Signature fields appear as signature previews instead of long image-data text. ## Studio integration When a form is submitted, Teloring fires the Studio trigger: ```text trigger.form_filled ``` Use this trigger to automate work after a form is completed. See [Form filled](./studio/triggers.md#form-filled) for the full trigger reference. Common examples: | Automation | Example | | --- | --- | | Notify a team | Add a private note or send an internal message when a service request form is submitted. | | Update CRM | Save answer values into contact, customer, or custom object fields. | | Route work | Assign a conversation or create a follow-up task based on selected options. | | Send data externally | Use an HTTP request action to send form data to another system. | ![Teloring Studio form trigger](pathname:///img/screenshots/product/forms/studio-form-trigger.png) ### Studio variables The Forms trigger exposes the submitted data as variables. | Variable | Meaning | | --- | --- | | `{{form.id}}` | Submitted form ID. | | `{{form.name}}` | Submitted form name. | | `{{form.version}}` | Submitted form version. | | `{{submission.id}}` | Submission ID. | | `{{contact.id}}` | Contact ID for specific forms. | | `{{conversation.id}}` | Conversation ID when available. | | `{{answers.list}}` | Array of visible answers, each with field ID, label, type, and value. | | `{{answers}}` | Object of answers keyed by field ID. | | `{{answers.email}}` | Exact answer for a field whose Field ID is `email`. | | `{{hiddenValues}}` | Object of hidden values keyed by hidden field ID. | | `{{hiddenValues.campaign_id}}` | Exact hidden value for hidden field ID `campaign_id`. | | `{{sourceParams}}` | Object of URL parameters from the public form URL. | | `{{sourceParams.utm_source}}` | Exact URL parameter value for `?utm_source=...`. | Use `answers.list` when sending all answers to another system. Use exact paths such as `answers.email` when one field should update one CRM field. ## Recommended form design Good forms are short, clear, and easy to submit. | Recommendation | Why it helps | | --- | --- | | Use clear field labels | Customers understand what to enter. | | Keep Field IDs stable | Studio flows and exports remain predictable. | | Use hidden fields for tracking | Customers do not see internal campaign or routing values. | | Split long forms into pages | Customers are less likely to abandon the form. | | Use columns carefully | Two columns can help short fields; too many columns can make mobile forms harder to scan. | | Test with a real public link | Confirms URL params, visibility rules, required fields, and Studio triggers. | | Review submissions before using automation | Make sure field IDs and values match what Studio expects. | ## Troubleshooting | Problem | What to check | | --- | --- | | Public link says form not found | Confirm the form is published, the link was copied from the current form, and the public token exists. | | A field does not appear | Check field visibility rules and page visibility rules. | | A required field blocks submit | Check whether the field is visible and whether the required setting is intentional. | | URL param did not prefill | Confirm the value source is URL param and the URL parameter name matches exactly. | | Hidden value missing in Studio | Confirm the hidden field has a Field ID, a value source, and a resolved value. Use `{{hiddenValues.field_id}}`, not a generic placeholder. | | Studio variable is unresolved | Confirm the placeholder uses the actual field ID or URL parameter name. | | Image does not display | Re-upload the image and save the form so Teloring can store the private file path and refresh the signed display URL. | --- # Analytics Source: https://docs.teloring.com/docs/product/analytics Markdown: https://docs.teloring.com/markdown/docs/product/analytics.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Analytics is where your team turns everyday activity into reports. You build dashboards from the data Teloring already collects — conversations, messages, contacts, agents, customers, custom objects, form submissions, and e‑signatures — and lay them out as cards on a free‑form canvas. Every report is a small recipe: pick a **data source**, choose **what to measure**, optionally **group** it, **filter** it, and choose **how to show it** (a number, a chart, a gauge, or a table). Teloring runs the recipe on demand against your live data and caches the result for speed. Use Analytics to answer questions like "How many conversations did we open per channel this month?", "Which agent resolves the most chats?", "How many documents were signed vs declined?", "What is the average rating from our feedback form?", or "Which conversations have had no agent reply in over an hour?". ## Key facts | Fact | Meaning | | --- | --- | | Reports are recipes, not snapshots | A report describes *how* to query your data. It always reflects live data when opened or refreshed. | | Account‑isolated | A report only ever reads your own account's data. | | Dashboards have tabs | Group related reports into tabs. Every dashboard starts with an **Overview** tab. | | Free‑form canvas | Drag cards to move them and pull the edges to resize. Positions are saved automatically. | | All time by default | A new report shows all matching data. You narrow the time window with a **date filter** on the report itself. | | Filters are flexible | Combine conditions with **All** (AND) or **Any** (OR) on any field, including dates and custom fields. | | Each card has its own design | Colors, number formatting, legends, axes, gauge bands, and table columns are set per card. | | See the raw rows | Every card has **View data** to inspect the exact records behind the number — and **export them to Excel or PDF**. | | Pin a tab to the home page | Any tab can replace the default boxes on the main dashboard home — for everyone in the account, or just for you. | | Build reports with AI | Describe the report you want in plain language and AI fills in the builder for you (when **AI Reports & analytics** is enabled). | ## Who uses Analytics | Role | Typical use | | --- | --- | | Admins | Build dashboards, design cards, and define the reports the team relies on. | | Team managers | Track volume, response times, agent workload, channel mix, signatures, and form results. | | Agents | Open shared dashboards to see queues, their own workload, and daily totals. | ## The Analytics workspace Open **Analytics** from the Teloring sidebar. ![Teloring Analytics dashboard](pathname:///img/screenshots/product/analytics/analytics-dashboard.png) The workspace has three parts: | Area | Use it to | | --- | --- | | Tabs (top left) | Switch between tabs. The **Overview** tab is always present and cannot be deleted. | | Top bar (top right) | **Add Report** opens the report builder. **Refresh** re‑runs every card on the current tab. **Add tab** creates a new tab. **Tab settings** (the gear) renames, reorders, deletes, or pins the current tab — see [Tab settings](#tab-settings). | | Canvas | The grid where report cards live. Drag, resize, zoom, and pan here. | ### Tabs Tabs let you organize reports by theme — for example *Overview*, *Conversations*, *Agents*, *Sales*, or *Documents*. | Action | How | | --- | --- | | Switch tab | Click the tab name. | | Add tab | Click the **Add tab** button and type a name. | | Rename, reorder, delete, or pin a tab | Open **Tab settings** (the gear in the top bar) — see below. | The **Overview** tab auto‑refreshes so it always shows current numbers. It cannot be deleted. A 📌 next to a tab name means that tab is currently shown on the main dashboard home page (see [Show a tab on your main dashboard](#show-a-tab-on-your-main-dashboard)). ### Tab settings Click the **gear** button in the top bar to open settings for the **current** tab. ![Teloring tab settings](pathname:///img/screenshots/product/analytics/tab-settings.png) | Setting | What it does | | --- | --- | | Tab name | Rename the tab. Click **Save changes** to apply. | | Tab order | Move the tab left or right relative to the other tabs with the **Move left / Move right** buttons. The current position (for example *2 / 4*) is shown between them. | | Show on main dashboard | Pin this tab to the dashboard home page — **Off**, **Everyone**, or **Only me**. See [Show a tab on your main dashboard](#show-a-tab-on-your-main-dashboard). | | Danger zone → Delete tab | Permanently delete the tab **and all of its reports**. Hidden for the Overview tab, which cannot be deleted. | :::note Renaming and reordering apply for everyone in the account. Deleting a tab also deletes every report on it and cannot be undone. ::: ### Canvas controls | Control | What it does | | --- | --- | | Drag a card | Click and hold the card header (or top edge) and move it. Cards snap to a light grid. | | Resize a card | Drag any corner or edge. | | Zoom | Use the zoom buttons in the corner: zoom out, zoom in, **Fit all**, and reset to 100%. | | Pan | Drag an empty area of the canvas to move the whole view. | Moving and resizing are saved automatically. ## Show a tab on your main dashboard The main dashboard — the **home** page you land on — normally shows four summary boxes (open conversations, waiting in line, resolved today, and agents online) above your recent conversations. You can replace those boxes with any analytics tab, so the metrics your team cares about are the first thing they see. ![Teloring dashboard home with a pinned analytics tab](pathname:///img/screenshots/product/analytics/dashboard-home-pinned.png) Open **Tab settings** for the tab you want to feature and choose under **Show on main dashboard**: | Choice | Who sees it | Notes | | --- | --- | --- | | Off | — | The home page shows the default four boxes again. | | Everyone | Everyone in the account | One shared "company front page". Pinning a tab replaces whatever was pinned for everyone before. | | Only me | Just you | Your personal home page. Other agents are not affected. | How Teloring decides what each person sees on their home page: 1. If **you** pinned a tab **Only me**, you see that tab. 2. Otherwise, if a tab is pinned for **Everyone**, you see that tab. 3. Otherwise, you see the default four boxes. So a personal pin always wins for you, and turning a pin **Off** brings the default boxes back. Only one tab can occupy each position (Everyone / Only me) — pinning a new tab replaces the previous one. The pinned tab's reports are shown in a clean, automatically arranged grid (not the free‑form canvas) and refresh on their own. Your recent conversations still appear below them. :::note A pinned tab reads the same account‑isolated data as everywhere else in Teloring, so each person only ever sees their own account's numbers. ::: ## How a report works Every report is built from a few simple choices. Understanding these makes the rest of Analytics easy. | Choice | Question it answers | Example | | --- | --- | --- | | Data source | What records am I reporting on? | Conversations | | Measurement | What number do I want? | Count | | Grouping | How should the number be split? | By channel type | | Time | If it's a trend, what time bucket? | By month | | Filters | Which records should be included? | Only WhatsApp, only this month | | Report type | How should it look? | Bar chart | | Goal | What target do I compare against? | 500 | | Design | What colors and formatting? | Brand colors, no decimals | A report named **"Open conversations by channel"** is simply: data source = Conversations, measurement = Count, grouping = Channel type, filter = Status is Open, report type = Bar chart. ## Create a report 1. Open Analytics and choose the tab where the report should live. 2. Click **Add Report**. 3. **Step 1** — pick a report type. 4. **Step 2** — configure the report (title, data source, measurement, grouping, filters, and more). 5. Click **Create Report**. The card appears on the canvas and runs immediately. To change it later, hover the card and click **Edit**. ## Build a report with AI If your account has **AI Reports & analytics** enabled (in **AI World**), you can describe the report you want in plain language and let AI build it — instead of filling in every field yourself. ![Teloring "Use AI to build the report" button](pathname:///img/screenshots/product/analytics/ai-build-button.png) 1. Click **Add Report**. At the top of the report‑type step you'll see **✨ Use AI to build the report** (the same button also appears in the top‑right while you configure a report). Click it. 2. Describe the report in your own words — for example *"conversations resolved each day in the last week"* or *"open conversations by channel"*. You can click an example chip to start. 3. Click **Generate report**. ![Teloring AI report builder](pathname:///img/screenshots/product/analytics/ai-report-builder.png) AI chooses the **report type, data source, measurement, grouping, time range, and filters**, then opens the builder on **Step 2** with everything pre‑filled so you can: | Then | How | | --- | --- | | Use it as‑is | Click **Create Report**. | | Adjust it | Change any field — title, measure, grouping, filters, design — before creating. | | Try again | Click **✨ Use AI** again and enter a new description (a new description replaces everything). | :::note AI only builds reports from data Teloring actually stores. If you ask for something it can't answer — such as a general‑knowledge question — it tells you it can't build that report rather than inventing one. Nothing is created until you click **Create Report**. ::: The button is hidden when **AI Reports & analytics** is off. Ask an administrator to enable it in **AI World** if you don't see it. ## Step 1: Choose a report type ![Teloring report type picker](pathname:///img/screenshots/product/analytics/report-type-picker.png) Report types fall into four groups. ### Single‑number cards | Type | Shows | Best for | | --- | --- | --- | | Value (KPI) | One big number. | Totals like "Open conversations" or "Messages today". | | Trend | A big number plus the **% change vs the previous period**, with a small sparkline. | "New conversations this week vs last week". | | Gauge | A speedometer of the number against a **goal**, with colored bands. | "Resolved today" toward a daily target. | | Progress | A progress bar of the number against a **goal**, with a percentage. | "Signed documents this month vs a 100 target". | ### Breakdown charts | Type | Shows | Best for | | --- | --- | --- | | Pie | Proportional slices. | Share of conversations by channel. | | Donut | Pie with the total in the center. | Same as pie, with the grand total visible. | | Bar | Vertical bars per group. | Conversations per agent. | | Horizontal bar | Bars laid out left to right. | Long group names, like inbox names. | | Stacked bar | Bars split by a second dimension. | Conversations per channel, split by status. | ### Time charts | Type | Shows | Best for | | --- | --- | --- | | Line | A line over time. | Daily or monthly conversation volume. | | Area | A filled line over time. | The same trend with emphasis on volume. | ### Detail and special | Type | Shows | Best for | | --- | --- | --- | | Table | Rows of data — either raw records or a grouped summary. | Listing records, or "Channel type \| count" summaries. | | Funnel | Sequential stages you define. | Step‑by‑step drop‑off, such as lead → qualified → won. | ## Step 2: Configure the report ![Teloring report builder](pathname:///img/screenshots/product/analytics/report-builder.png) The builder shows only the sections that apply to the report type you chose. ### Title A clear name for the card, such as *Open conversations* or *Signed documents this month*. ### Data source The data source is the kind of record the report reads. Click a source to select it. | Data source | What it contains | | --- | --- | | Conversations | Every conversation, with channel, status, assigned agent, **assigned team**, priority, timestamps, message counts, and your account's **[conversation attributes](./conversation-attributes.md)**. | | Messages | Individual messages across all conversations (direction, sender type, content type, channel). | | Contacts | Contact records. | | Agents | Individual team members (role, active status, login activity). | | Teams | [Team](./teams.md) records — team size and routing rules. Not the conversations a team handled; see the note below. | | Events | System activity events. | | Customers | CRM customer records (lifecycle stage, industry, assigned agent, tags). | | Custom Objects | Records of any custom object you built (deals, tasks, invoices, and so on). Pick the **object type** after choosing this source. | | Form Submissions | Submitted form answers. Optionally pick **one form** to analyze its questions. | | Signatures (signed) | Completed and declined e‑signature sessions. | | Documents (templates) | Signature document templates. | | Pending signatures | Signature links that were sent but not yet signed. | When you pick **Custom Objects** or **Form Submissions**, an extra selector appears so you can choose the specific object type or form. The available fields then update to match it. :::tip Your own conversation fields are here too If your account uses [Conversation Attributes](./conversation-attributes.md) — fields such as *Reason for contact*, *Outcome*, or *Refund amount* — they appear in the field lists of the **Conversations** source under their own labels. No extra selector is needed: an account has one attribute set, so they are always available. What each one can do follows its type: dropdown, radio, multi-select and agent-picker attributes can be **grouped by**; number and currency attributes can be **summed and averaged**; date attributes drive **time grouping**; text attributes are for filtering. ::: :::tip Reporting on teams — pick the right source Two different questions, two different sources: - **"How much work did each team handle?"** → data source **Conversations**, grouping **Assigned Team**. That is where volume, resolution time, priority, and channel live. Team IDs display as team **names**, and conversations with no team group under `(none)`. - **"How are our teams set up?"** → data source **Teams**. It answers how many teams exist, how big they are (**Agents in Team**, with average / sum / min / max), which use **Auto-assign to Online Agent** or **Human Agents Only**, and who created them. See [Teams](./teams.md#teams-in-analytics). ::: ### Measurement Measurement is the number the report calculates. | Measure | What it returns | | --- | --- | | Count | The number of matching records. This is the most common measure (for example, number of conversations). | | Count (distinct) | The number of unique values in a field (for example, distinct contacts). | | Sum | The total of a numeric field (for example, sum of message counts, or total deal value). | | Average | The average of a numeric field (for example, average rating). | | Minimum / Maximum | The lowest or highest value of a numeric field. | :::note **Count** counts records — it does not need a field. Choose **Count** for "how many conversations". To total a numeric field such as message volume or deal value, choose **Sum** and pick the field (for example, *Message count*). ::: ### Grouping Grouping splits the measurement into categories. For a bar or pie chart this is the breakdown; for a table it turns the report into a grouped summary. | Setting | Meaning | | --- | --- | | Group by | The field to split by, such as Channel type, Status, Assigned agent, or a custom field. Leave it empty for a single total. | | Time granularity | For line, area, and trend reports — the time bucket: Hour, Day, Week, or Month. | A **table** with a grouping shows two columns: the group and its measure (for example, *Channel type | Count*). A **table** with no grouping lists raw rows — see **Fields to show**. ### Fields to show (tables only) For a raw‑rows table, choose which columns appear. Each available field is a checkbox. Leave grouping empty to use this mode. ### Goal (trend, gauge, and progress) Trend, gauge, and progress compare the number to a **goal**. Set the goal in one of two ways: | Goal source | Meaning | Example | | --- | --- | --- | | Fixed number | You type a target. | A goal of `500`. | | Calculated | The goal is itself a measurement, defined with its own measure and filters. | Goal = number of conversations created last month, so this month is compared to last month automatically. | | Report type | How the goal is used | | --- | --- | | Progress | Fills a bar to `value ÷ goal` and shows the percentage. | | Gauge | Points the needle at the value within the goal range, across colored bands. | | Trend | Compares the latest period to the previous period and shows the % change (up or down). A goal can also be displayed for reference. | ### Funnel stages For a funnel, add a **stage** for each step. Each stage has a label and its own set of filters. Stages are shown in order with the drop‑off between them. ### Filters Filters decide which records are included. This is the most powerful part of the builder — see [Filtering data](#filtering-data) below. When you are done, click **Create Report** (or **Save Changes** when editing). ## Filtering data ![Teloring filter builder](pathname:///img/screenshots/product/analytics/filters.png) A filter is a set of **conditions**. You choose how they combine: | Match mode | Meaning | | --- | --- | | All conditions | A record is included only if **every** condition is true (AND). | | Any condition | A record is included if **at least one** condition is true (OR). | Click **Add condition** to add a row. Each condition has three parts: | Part | Meaning | | --- | --- | | Field | Which field to test (for example, Channel type, Status, Created at, or a custom field). | | Operator | How to compare (equals, is any of, contains, before, in the last…, and more). | | Value | What to compare against. Where the value is a known list — inboxes, agents, status, channel type — Teloring shows a **dropdown** instead of a text box, so you don't have to guess. | ### Operators for text, numbers, and lists | Operator | Use it to | | --- | --- | | Equals / Not equals | Match an exact value. | | Is any of / Is none of | Match against several values at once (for example, Status is any of Open, Missed). | | Contains / Doesn't contain | Match part of a text value, or membership in a list field such as tags. | | Starts with / Ends with | Match the beginning or end of a text value. | | Greater than / less than (and or‑equal) | Compare numbers. | | Between | Match a numeric range. | | Is empty / Is not empty | Match records that have no value, or any value, in the field. | ### Operators for dates Date fields (Created at, Resolved at, Last message at, custom date fields, and so on) offer a rich set of time operators. They are **relative** — they always move with the current date. | Group | Operators | | --- | --- | | Exact | On date, Not on date, Before date, After date, Between dates. | | Relative (you choose a number + unit) | In the last…, In the next…, More than … ago. Units are minutes, hours, days, weeks, or months. | | Day | Today, Yesterday, Tomorrow, Today & yesterday, Today & tomorrow. | | Week | This week, Last week, Next week, 2 weeks ago, Next 2 weeks. | | Month | This month, Last month, Next month, Last 2 months, Next 2 months. | | Quarter | This quarter, Last quarter, Next quarter, Q1–Q4 of this year. | | Year | This year, Last year, Next year. | | Rolling | In the last hour / 2 hours, Last 30 / 60 / 90 days, Next 30 / 60 / 90 days. | | Presence | Has a value, Has no value. | :::note Future windows (such as *Next month* or *In the next 30 days*) return nothing for "created" dates, because records cannot be created in the future. They are useful for custom date fields that hold future dates, such as a renewal date or a scheduled callback. ::: ### Filtering by a specific inbox Conversations and signatures store the inbox in the **Inbox** field. Filter **Inbox** and pick the channel by name (for example, *secret project WA (WhatsApp)*) to report on one inbox. Filter **Channel type** instead to report on a whole channel (for example, all Telegram inboxes). :::note Messages do not store which inbox they belong to — only the channel type. To report on messages from one specific inbox, report on **Conversations** for that inbox, or filter **Messages** by **Channel type**. ::: ### Studio‑handled conversations When a Studio flow handles a conversation, no agent is assigned. To find or group these conversations, use the conversation fields **Handled by Studio** (filter "is not empty") and **Studio Flow** (group by it to see the breakdown per flow). ## Designing how a card looks Each card has its own appearance. Hover a card and click the **design** (palette) action to open the **Design** panel. Changes preview live; click **Save** to keep them, **Reset** to return to defaults, or **Cancel** to discard. ![Teloring report design panel](pathname:///img/screenshots/product/analytics/design-drawer.png) The panel shows only the sections that apply to the card type. | Section | Applies to | What you can change | | --- | --- | --- | | Card | All | A title override and, for number cards, the number color and size. | | Numbers | Cards with numbers | Decimal places, thousands separator, prefix (such as `$`), suffix (such as ` min`), a multiplier, percent/plain style, and compact form (1.2k, 3.5M). | | Colors | Charts | A single series color and, when there are categories, a color per category. Bars can also **highlight the largest** value. | | Legend & labels | Charts | Show or hide the legend and its position, show values on the chart, and show percentages (pie/donut). | | Axes & grid | Bar, line, area | Show grid lines, axis titles, start the axis at zero, set min/max, smooth lines, and area fill opacity. | | Gauge | Gauge | The minimum value and the **color bands** (each band has an upper limit and a color). | | Progress | Progress | The bar color and whether the percentage is shown. | | Trend | Trend | Which direction is "good" (so up or down shows green), and whether the sparkline is shown. | | Table | Table | Striped rows, compact rows, and a **columns manager** to show/hide columns, rename headers, and reorder them. | Design is saved per card, so two cards built from the same data can look completely different. ## Working with a card Hover a report card to reveal its actions. | Action | What it does | | --- | --- | | View data | Opens the records behind the card in a full‑screen table. | | Edit | Reopens the report builder to change the recipe. | | Design | Opens the design panel described above. | | Refresh | Re‑runs just this card against live data. | | Delete | Removes the card from the tab. | ## View data and export (Excel & PDF) **View data** answers "where does this number come from?". It opens a full‑screen page with the exact records the card counted, and a **Back** button to return to your dashboard. ![Teloring view source data](pathname:///img/screenshots/product/analytics/view-data.png) In the data view you can: | Action | How | | --- | --- | | Filter the rows | Type in the search box to narrow the visible rows. | | Sort | Click a column header to sort by it; click again to reverse. | | Export to Excel | Click **Export to Excel** to download an `.xlsx` file of the rows. | | Export to PDF | Click **Export to PDF** to download a polished, shareable PDF — the report's chart (when it has one) followed by the data table. | Both exports **download to your computer**. The PDF is a good‑looking report you can send to someone directly; the Excel file is best when they want to work with the raw data in a spreadsheet. This is also the fastest way to verify a report before you trust it. ## Date ranges There is no global date picker. Instead, **each report controls its own time window** through a date filter. This keeps every card honest about what it is showing. | You want | Do this | | --- | --- | | All‑time totals | Add no date filter — the report includes everything. | | A fixed window | Filter a date field, for example **Created at is Between** two dates. | | A rolling window | Filter a date field with a relative operator, for example **Created at is This month** or **In the last 7 days**. | Because the operators are relative, a report set to **This month** keeps showing the current month as time passes — no editing needed. ## Worked examples These recipes show how the pieces fit together. | Goal | Data source | Measure | Grouping | Filters | Type | | --- | --- | --- | --- | --- | --- | | Open conversations right now | Conversations | Count | — | Status is **Open** | Value | | Conversations per channel this month | Conversations | Count | Channel type | Created at is **This month** | Bar | | Daily message volume | Messages | Count | Time = Day | Created at is **In the last 30 days** | Line | | Telegram messages, May–June | Messages | Count | — | Channel type is **Telegram**; Created at **Between** 1 May and 30 Jun | Value | | Signed vs declined documents | Signatures (signed) | Count | Status | — | Pie | | Average feedback rating | Form Submissions (pick the form) | Average | — | — | Value | | Deals won this quarter | Custom Objects → Deals | Count | — | Stage is **Won**; Created at is **This quarter** | Value | | Conversations with no agent reply in over an hour | Conversations | Count | — | Last message direction is **Incoming**; Last message at is **More than 1 hour ago**; Status is any of **Open, Missed** | Value | | Messages per inbox (one WhatsApp number) | Conversations | Sum of **Message count** | Inbox | Inbox is **(your WhatsApp inbox)** | Horizontal bar | | Open conversations by team | Conversations | Count | **Assigned Team** | Status is **Open** | Bar | | Average resolution time by team | Conversations | Average of **Resolution time (ms)** | **Assigned Team** | Resolved at is **This month** | Horizontal bar | | Sales queue with nobody on it | Conversations | Count | — | Assigned Team is **Sales**; Assigned agent **is empty** | Value | | Agents per team | Teams | Average of **Agents in Team** | — | — | Value | | Teams using auto-assignment | Teams | Count | **Auto-assign to Online Agent** | — | Pie | | What are people contacting us about? | Conversations | Count | **Reason for contact** *(attribute)* | Created at is **This month** | Pie | | Which contact reasons take longest | Conversations | Average of **Resolution time (ms)** | **Reason for contact** *(attribute)* | Resolved at is **This month** | Horizontal bar | | Total refunded this month | Conversations | Sum of **Refund amount** *(attribute)* | — | Resolved at is **This month** | Value | | Outcomes by channel | Conversations | Count | Channel type, stacked by **Outcome** *(attribute)* | — | Stacked bar | ## Tips | Tip | Why it helps | | --- | --- | | Name reports clearly | A good title explains the card at a glance on a shared dashboard. | | Use **View data** to verify | Confirms the number is built from the records you expect before you trust it. | | Prefer relative date filters | "This month" or "In the last 7 days" stays correct over time without editing. | | Use **Count** for records, **Sum** for totals | Count answers "how many"; Sum answers "how much" of a numeric field. | | Group tables for summaries | A grouped table is the simplest way to get a "category → count" list you can export. | | Keep one theme per tab | Separate Overview, Conversations, Agents, and Sales into tabs so each stays readable. | ## Troubleshooting | Problem | What to check | | --- | --- | | The number looks too low | Check the report's date filter. With no date filter it shows all time; with a relative filter such as *This week* it only shows that window. | | Two cards disagree | Make sure both use the same filters. Use **View data** on each to compare the underlying records. | | "Invalid report recipe" when saving | A filter condition is incomplete — for example, **In the last…** with no number, or **Between** missing a value. Complete the condition and save again. | | A status filter misses conversations | The conversation list treats **Open** as *Open + Missed*. To match it, filter Status **is any of** Open, Missed. | | A custom object or form shows no fields | Re‑select the object type or form so its fields load. | | A grouped report shows "(none)" | Some records have no value in the grouping field. That is expected; filter it out if you don't want it. For a [conversation attribute](./conversation-attributes.md), a large `(none)` group usually means conversations from before the attribute existed, or that the team is not filling it in yet. | | A conversation attribute isn't in the field list | Make sure the data source is **Conversations**. Text and text-area attributes can be filtered on but not grouped by — use a dropdown or multi-select attribute for grouping. | | Studio‑handled conversations show no agent | They are not assigned to an agent. Use **Handled by Studio** or **Studio Flow** to report on them. | | A report needs a Firestore index | Custom‑object reports may require a one‑time database index. If a card shows an index warning, ask your administrator to create it. | | The **Use AI** button isn't showing | **AI Reports & analytics** is turned off. An administrator can enable it in **AI World**. | | My pinned tab isn't on the home page | A personal pin (**Only me**) overrides an account pin **for you**. Check **Tab settings → Show on main dashboard**; set it **Off** to bring back the default boxes. | | AI says it can't build my report | The request asks for something Teloring doesn't store, or is too vague. Describe a metric over your data, e.g. "open conversations by channel this month". | --- # AI World Source: https://docs.teloring.com/docs/product/ai-world Markdown: https://docs.teloring.com/markdown/docs/product/ai-world.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z **AI World** is the control room for every artificial‑intelligence feature in Teloring. It's a single page of on/off switches — one per capability — that decide how much AI helps your team across conversations, the knowledge base, and analytics. Turn a switch **on** and that capability becomes available everywhere it belongs: the reply composer, the AI Copilot panel, the resolve action, the Knowledge Base page, or the Analytics report builder. Turn it **off** and it disappears again. Nothing here changes what your agents *can* do by hand — it only decides where AI lends a hand. Open **AI World** from the **Tools** section of the sidebar. ![The AI World page — the grid of AI feature switches](pathname:///img/screenshots/product/ai-world/ai-world-overview.png) ## Key facts | Fact | Meaning | | --- | --- | | Account‑wide | Every switch applies to your whole business. When an admin turns a feature on, it's on for **all** agents in the account. | | Admins change it, everyone benefits | Only account **administrators** can flip a switch. Agents can view the page but the toggles are read‑only for them. | | Off by default | Every feature starts **off**. Nothing sends data to AI until an admin turns it on. | | Saves instantly | There is no Save button. Each switch saves the moment you flip it and shows a short **Saving… → Saved!** status on the card. | | One master switch | **AI Copilot** is the master switch for the six live‑conversation helpers. Those six do nothing unless AI Copilot is also on — see [The AI Copilot dependency](#the-ai-copilot-dependency). | | Your data stays yours | AI only ever reads the conversations, files, and records of your own account. Features are fully account‑isolated. | | Some cards are on the roadmap | A few switches are shown for what's coming and are **not active yet** — see [Coming soon](#coming-soon). | ## Who uses AI World | Role | What they do here | | --- | --- | | Admins | Decide which AI features the account uses, and turn them on or off. | | Agents & managers | Benefit from whatever is enabled — Copilot tips, rephrase, summaries, and more — but cannot change the switches. A lock notice appears at the top of the page for them. | :::note If you open AI World and the switches won't move, you're signed in as a non‑admin. Ask an account administrator to change the settings for you. ::: ## How the page works Every capability is shown as a **card** with an icon, a name, a one‑line description, and a switch on the right. ![A single feature card, switched on](pathname:///img/screenshots/product/ai-world/feature-card-active.png) | Element | What it means | | --- | --- | | Card icon & title | The feature's name and a plain‑language description of what it does. | | Switch (right side) | Click to turn the feature on or off. | | **Active** highlight | When a feature is on, its card gets a teal border and subtle tint, so you can see at a glance what's enabled. | | Status text | A small label next to the title flashes **Saving…**, then **Saved!** (or **Failed to save** if something went wrong). | To enable a feature: click its switch **on**. To disable it: click it **off**. That's the whole workflow — the change takes effect across the account within moments. ## The AI Copilot dependency Six features are **helpers that run inside AI Copilot**. They only work when the **AI Copilot** switch is also on: - Help & Tips - Smart Subject Detection - Auto‑Assign Labels - Detect Churn Risk - Detect Upsale Opportunity - Auto Mark Urgent Think of **AI Copilot** as the engine and these six as options you bolt onto it. If AI Copilot is **off**, turning any of the six on has no effect. If AI Copilot is **on**, each of the six you enable adds one more thing Copilot watches for while a conversation is live. :::tip A good starting point for most teams: turn on **AI Copilot**, then enable **Help & Tips**, **Smart Subject Detection**, and **Auto‑Assign Labels**. Add churn, upsale, and urgency detection once your team is comfortable. ::: --- ## Feature reference The sections below cover every **live** feature — what it does, where you'll see it, and what it needs to work. ### Live‑conversation assistance (AI Copilot) These features act while agents are chatting with customers. Copilot analyzes each new incoming customer message in the background and surfaces its findings in the **AI Copilot** panel on the right of the conversation. See [AI Copilot in conversations](/docs/getting-started/conversations#ai-copilot) for the agent‑side view. Copilot only runs on conversations that are **open or pending** and **not** already handled by a Studio flow or an AI agent. #### 🧠 AI Copilot The master switch for live assistance. When on, Copilot reads each incoming customer message and can post insights into the Copilot panel. On its own it does nothing visible — pair it with the helpers below and with **Knowledge Base** (for answers). | | | | --- | --- | | **Where you see it** | The AI Copilot panel in the right sidebar of a conversation. | | **Requires** | Nothing, but only useful with at least one helper below turned on. | #### 💡 Help & Tips Copilot offers real‑time suggestions and coaching — how to respond, what the customer seems to need, and what tone fits. Tips can appear several times as a conversation develops. | | | | --- | --- | | **Where you see it** | As Copilot tips in the AI Copilot panel. | | **Requires** | **AI Copilot** on. | #### 🎯 Smart Subject Detection Copilot writes a short, clear subject line for the conversation once it understands the topic. | | | | --- | --- | | **Where you see it** | The conversation's subject updates automatically; Copilot notes that it set it. | | **Requires** | **AI Copilot** on. | | **Good to know** | Only sets the subject when the conversation **doesn't already have one**. It never overwrites a subject you set yourself. | #### 🏷️ Auto‑Assign Labels Copilot tags the conversation with relevant category labels (for example `billing, refund` or `technical, bug`), creating them in your account if they don't exist yet. | | | | --- | --- | | **Where you see it** | Labels appear on the conversation; Copilot notes what it added. | | **Requires** | **AI Copilot** on. | | **Good to know** | Only labels a conversation that has **no labels yet**, up to 5 labels. It won't touch conversations you've already labelled. | #### 🚪 Detect Churn Risk Copilot watches for signs that a customer wants to cancel, leave, or is deeply dissatisfied, and raises a clear alert describing what triggered it. | | | | --- | --- | | **Where you see it** | A churn alert in the AI Copilot panel. It can also start a **Studio** automation (a churn‑risk signal). | | **Requires** | **AI Copilot** on. | #### 💰 Detect Upsale Opportunity Copilot spots when a customer shows interest in buying, upgrading, or spending more, and flags the opportunity for the agent. | | | | --- | --- | | **Where you see it** | An upsale alert in the AI Copilot panel. It can also start a **Studio** automation (an upsale signal). | | **Requires** | **AI Copilot** on. | #### 🔥 Auto Mark Urgent Copilot assesses how urgent a conversation is and sets its priority — `urgent`, `high`, `medium`, or `low`. | | | | --- | --- | | **Where you see it** | The conversation's priority changes automatically. | | **Requires** | **AI Copilot** on. | | **Good to know** | Only adjusts priority while it's still at the default **medium**. It won't override a priority you set by hand. | ### Writing help #### ✍️ Rephrase Messages Gives agents a one‑click **✨ rephrase** button in the reply composer. Before sending, an agent can rewrite their draft in several ways. ![The rephrase picker in the reply composer](pathname:///img/screenshots/product/ai-world/rephrase-picker.png) | Rephrase option | What it does | | --- | --- | | Improve | Makes the text clearer, more polished, and professional. | | Fix spelling & grammar | Corrects mistakes without changing meaning or tone. | | Expand | Adds detail and elaboration. | | Shorten | Trims to the essentials. | | Friendly | Rewrites in a warm, approachable tone. | | Formal | Rewrites in a professional, business tone. | | Simplify | Uses short sentences and simple words. | | Translate | Translates the reply into the **customer's** language, detected from their last message. | | | | | --- | --- | | **Where you see it** | The ✨ button next to the reply composer's formatting tools. | | **Requires** | Nothing else — works on its own. | | **Good to know** | The AI keeps the agent's original language for every option except **Translate**. Agents always review the result before sending. | ### When a conversation is resolved These two features run automatically the moment an agent marks a conversation **Resolved**. They read the conversation (skipping private notes) and act in the background. #### 📝 Conversation Summary Generates a concise 2–4 sentence summary of the conversation — the topic, what the customer needed, and how it was resolved — written in the **same language** as the conversation. | | | | --- | --- | | **Where you see it** | Added as a **private note** (🤖 AI Summary) at the end of the conversation, visible to your team but never to the customer. | | **Requires** | Nothing else. | #### 💭 Feelings & Emotions Reads the customer's overall mood across the conversation and records it on a 20‑point scale — from *satisfied*, *happy*, and *appreciative*, through *neutral*, to *frustrated*, *angry*, and *threatening*. | | | | --- | --- | | **Where you see it** | Stored on the conversation (visible in resolved‑conversation views and available to **Analytics** and **Studio**). | | **Requires** | Nothing else. | | **Good to know** | A customer‑emotion change can start a **Studio** automation — useful for escalating an angry ending, for example. | ### Knowledge & media #### 📚 Knowledge Base Unlocks the **Knowledge Base** page, where you upload, scan, and store documents for AI to reference. It also lets **AI Copilot** answer agents' questions from your approved knowledge. | | | | --- | --- | | **Where you see it** | The Knowledge Base page (in the sidebar) becomes usable; Copilot can search it. | | **Requires** | Nothing to enable it. Copilot's knowledge answers need **AI Copilot** on as well. | | **Good to know** | While this is off, the Knowledge Base page shows a "feature disabled" message instead of your files. | #### 🖼️ Image Detection For every image a customer sends, AI looks at it and describes what's in it — objects, brands, documents, and any visible text. | | | | --- | --- | | **Where you see it** | The description is attached to the incoming image in the conversation, and appears as soon as the analysis is ready. | | **Requires** | Nothing else. | ### Automation #### 🎨 AI Studio Adds a second way to create a Studio flow: **Hermes**, an AI flow builder that interviews you in plain language and then lays out the whole automation — blocks, settings, and connections — on your canvas. ![The New Flow dialog with the two build-mode cards](pathname:///img/screenshots/product/studio/ai/new-flow-choose-mode.png) | | | | --- | --- | | **Where you see it** | Studio → **New Flow** → *How would you like to build it?* → **Use AI to build**. | | **Requires** | Nothing else. It helps to connect the inboxes, teams, and CRM objects you want to automate first, because Hermes offers your real ones by name. | | **Who can use it** | Any agent with **Studio → Create**. Flipping this switch is a different permission — **AI World → Update**. See [Roles and Permissions](./roles/overview.md). | | **Good to know** | Hermes always produces a **draft**. Nothing goes live until someone publishes it from the editor. Building the flow is a one-way step that ends the conversation; the flow is then edited by hand like any other. | While this switch is off, the **Use AI to build** card still appears in Studio but is greyed out, with a link back to this page. 📖 Full guide: [Build a flow with AI (Hermes)](/docs/product/studio/ai-flow-builder). ### Analytics #### 📊 AI Reports & Analytics Adds a **✨ Use AI to build the report** button to the Analytics report builder, so anyone can describe a report in plain language and let AI fill in the fields. | | | | --- | --- | | **Where you see it** | The **✨ Use AI to build the report** button in [Analytics](/docs/product/analytics#build-a-report-with-ai). | | **Requires** | Nothing else. When off, the button is hidden. | --- ## Coming soon A few switches appear on the AI World page to show what's on the roadmap. They are **not active yet** — turning them on does not change anything in the product today. We're listing them here so you know what each one is intended to do. :::info These features are in development. Leave them off until this guide marks them as live. ::: | Feature | Planned behaviour | | --- | --- | | 🌍 **Conversation Translation** | Translate whole conversations in real time to communicate across languages. | | 🎙️ **Conversation Transcription** | Turn voice messages and audio into text automatically. | | 🧩 **Enrich Knowledge Base** | Grow the knowledge base automatically from the solutions your agents give in real conversations. | | 🛡️ **Prevent Bad Language** | Stop agents from sending inappropriate language to customers. | | 🔗 **Detect Similar Issues** | Spot when several recent conversations report the same problem and alert your team. | | 🔐 **AI Security** | Detect security risks and signs of compromise in real time. | | 💡 **AI Suggestions** | Surface AI‑only insights and suggestions on the main dashboard. | | 🛡️ **AI File Protection** | Scan every incoming and outgoing file and block malicious ones. | | 🎓 **Auto Agent Skills** | Detect each agent's strengths automatically from their conversations and performance. | ## Frequently asked questions **Do I have to turn everything on?** No. Start with the features you need. Every switch is independent (except the six that need AI Copilot — see [above](#the-ai-copilot-dependency)). **Will customers know AI is involved?** Customer‑facing help is always in the agent's hands. Rephrase suggestions, Copilot tips, summaries, and emotion scores are shown to your **team** only — nothing is sent to the customer automatically. Summaries are saved as private notes. **Can agents change these settings?** No — only account administrators. Agents see the page in read‑only mode with a lock notice. **A switch flipped back off after I clicked it.** Enabled features stay on. If a switch won't stay on, it may be one of the roadmap items in [Coming soon](#coming-soon), which aren't active yet — check with your Teloring contact. **Where do I actually see the AI at work?** In the [conversation workspace](/docs/getting-started/conversations#ai-copilot) (Copilot panel, rephrase, image descriptions), on resolved conversations (summaries and emotions), on the Knowledge Base page, in [Studio](/docs/product/studio/ai-flow-builder) when you create a flow, and in [Analytics](/docs/product/analytics#build-a-report-with-ai). --- # Settings Source: https://docs.teloring.com/docs/product/settings Markdown: https://docs.teloring.com/markdown/docs/product/settings.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Settings is the account control center for identity, time logic, login security, API access, and account data. Most settings are account-wide, which means they affect every agent in the same Teloring account. Use Settings when you need to: - Update business identity and default account preferences. - Create business-hour schedules for Studio routing. - Manage holiday calendars that override business hours. - Control login security, two-factor verification, and active sessions. - Create account API keys. - Export account data or request account deletion. :::info Settings are account-scoped. Changing Settings in one account does not affect another account. ::: ## Open Settings Open **Admin → Settings** from the Teloring sidebar. Settings has six sections: | Section | What it controls | | --- | --- | | General Info | Business profile, logo, language, timezone, and currency. | | Business hours | Holiday calendars and named schedules used by Studio. | | Security & Login | IP restrictions, 2FA enforcement, idle timeout, sessions, and support access. | | API | Account API keys for system operations. | | Data & Privacy | Data export, retention policy area, and delete account danger zone. | | [Conversation Attributes](./conversation-attributes.md) | Custom fields agents fill in on a conversation — reason for contact, outcome, order number. | Each section is a separate [permission](./roles/system-permissions.md). A role that grants none of them does not see **Settings** in the sidebar at all; a role that grants one lands directly on that section. ![Settings general info page](pathname:///img/screenshots/product/settings/general-info.png) ## General Info General Info contains editable account details and read-only system details. ### Editable fields | Field | Meaning | Used by | | --- | --- | --- | | Business name | The account display name. | Header, account identity, admin views. | | Logo / avatar | The account visual identity. | Dashboard and account branding surfaces. | | Industry | Optional business category. | Internal account context and future reporting. | | Contact email | Main account contact email. | Admin contact and system references. | | Contact phone | Main account contact phone. | Admin contact and system references. | | Default language | Default account language. | Account defaults and new user experience. | | Timezone | Account timezone. Choose from the timezone dropdown. | Reports, business hours, dashboards, filters, and time-based Studio logic. | | Default currency | Account currency. | Billing, pricing, and account defaults. | ### Why timezone matters Timezone is not only display text. It controls how Teloring understands dates and times for the account. Timezone affects: - Business-hour schedules. - Holiday checks. - Studio conditions that depend on time. - Reports and dashboard filters. - Date-based account behavior. If the timezone is wrong, a Studio flow can treat a customer message as inside or outside working hours at the wrong moment. ### Read-only account details The account details block is system-owned. It is shown for reference and cannot be edited from this page. | Field | Meaning | | --- | --- | | Account ID | The internal account identifier. Useful for support and API debugging. | | Plan | The current account plan. | | Region | The hosting region label. For example, `Israel`. | | Created | Account creation date. | | Owner | The account owner or first admin. | ## Business Hours Business Hours has two tabs: - **Business Hours** — named weekly schedules. - **Holidays** — holiday calendars that can override schedules. Business hours are optional. New accounts do not receive a default schedule. Admins create only the schedules they actually need. ![Business hours schedule list](pathname:///img/screenshots/product/settings/business-hours-list.png) ## Business Hours tab The Business Hours tab shows schedule cards. Each card is a named schedule with a timezone, weekly opening hours, and optional holiday calendars. Use multiple schedules when different teams work different hours. Examples: | Schedule | Example use | | --- | --- | | Support hours | Customer support routing. | | Sales hours | Sales lead routing. | | VIP support hours | Special working hours for high-priority customers. | ### Add a business-hours schedule To create a schedule: 1. Open **Settings → Business hours**. 2. Stay on the **Business Hours** tab. 3. Click **Add new business hours**. 4. Enter a schedule name. 5. Choose the schedule timezone. 6. Fill the weekly opening hours. 7. Turn on **Consider holidays** if this schedule should close on selected holiday calendars. 8. Select one or more holiday calendars. 9. Click **Save schedule**. ![Add business hours modal](pathname:///img/screenshots/product/settings/business-hours-modal.png) ### Schedule fields | Field | Meaning | | --- | --- | | Name | Human-readable schedule name. Use clear names because Studio displays this name when selecting a schedule. | | Timezone | Timezone used to evaluate the schedule. This can differ from the account timezone when needed. | | Weekly rows | Opening time and closing time for each day. Leave a day empty when the business is closed that day. | | Consider holidays | Toggle that enables holiday override behavior for this schedule. | | Holiday checkboxes | The holiday calendars that should override weekly hours. | ### Holiday override behavior When **Consider holidays** is off, only weekly hours are checked. When **Consider holidays** is on, selected holiday calendars override weekly hours. Example: | Schedule rule | Holiday state | Studio result | | --- | --- | --- | | Monday 09:00-17:00 | No selected holiday today | `open` during 09:00-17:00 | | Monday 09:00-17:00 | Today is in a selected holiday calendar | `closed` all day | | Saturday empty | No selected holiday today | `closed` | This matters because Studio can branch on a business-hours condition. ## Studio business-hours condition Studio reads the schedules created in Settings. In Studio: 1. Add a **Business Hours** condition block. 2. Select a schedule from Settings. 3. Connect the **Open** output to the path for working hours. 4. Connect the **Closed** output to the path for after-hours or holiday handling. The block returns: | Output handle | Meaning | | --- | --- | | Open | The message arrived inside the selected schedule and not on a selected holiday. | | Closed | The message arrived outside the selected schedule, or on a selected holiday override. | ![Studio business hours block](pathname:///img/screenshots/product/settings/studio-business-hours.png) ## Holidays tab The Holidays tab shows holiday calendar cards. There are two system calendars: | Calendar | Editable? | Meaning | | --- | --- | --- | | Jewish Israel holidays | No | Global Jewish holiday calendar updated by Teloring super admin from Hebcal. | | Christian holidays | No | Fixed-date Christian holidays generated by Teloring. | Admins can also create custom holiday calendars for company-specific or local days. Examples: - Company annual event. - Local office closure. - Team offsite. - Regional special day. ![Holiday calendars tab](pathname:///img/screenshots/product/settings/holiday-calendars.png) ### System holiday calendars System calendars are view-only for account admins. You can: - See the dates. - Select them in business-hour schedules. - Use them as Studio override logic. You cannot: - Edit their dates. - Delete them. - Rename them. ### Custom holiday calendars To create a custom holiday calendar: 1. Open **Settings → Business hours → Holidays**. 2. Click **Add holiday calendar**. 3. Enter a calendar name. 4. Add one date per line. 5. Save. Use this format: ```text YYYY-MM-DD | Title | Hebrew title ``` Example: ```text 2026-09-01 | Company day | יום חברה 2026-12-31 | Office closed | המשרד סגור ``` The Hebrew title is optional. ## Security & Login Security & Login controls account access and session behavior. ![Security and login settings](pathname:///img/screenshots/product/settings/security-login.png) ### IP allow list The IP allow list is optional. When empty, users can sign in from any IP address that passes normal authentication. When filled, only the listed IP addresses or CIDR ranges can sign in. Rules: - Maximum 5 entries. - Supports single IP addresses. - Supports CIDR ranges. Examples: ```text 203.0.113.10 198.51.100.0/24 ``` Use IP allow list when an account should only be accessible from an office, VPN, or controlled network. ### Enforce 2FA for all members When enabled, every member must verify by email during login. Flow: 1. User enters email and password. 2. Teloring emails a verification code. 3. The user must enter the code within 5 minutes. 4. Login completes only after verification. ### New device verification Teloring also sends an email verification code when a user signs in from a browser that is not trusted yet. This can happen even when account-wide 2FA is off. Purpose: - Protect accounts when a password is correct but the browser is new. - Reduce risk from stolen credentials. ### Idle/session timeout Idle timeout signs inactive users out. When enabled: - Set a timeout between 1 and 60 minutes. - If an agent does not interact with Teloring during that time, the session is ended. - The agent is moved offline and returned to the login screen. ### Active sessions The Active sessions table shows recent dashboard sessions. Use it to: - See which agents are connected. - Review IP addresses and last-seen times. - Force logout a session. Force logout revokes the session. The affected user is signed out on the next authenticated request. ### Grant Teloring support temporary access This toggle allows temporary support access for Teloring staff. Use it when Teloring support needs to investigate account behavior with your permission. You can turn it off again at any time. ## API The API page manages account-level API keys. These keys are for system operations. They are not personal agent login keys. ![API settings page](pathname:///img/screenshots/product/settings/api-keys.png) ### Create an API key To create a key: 1. Open **Settings → API**. 2. Enter a key name. 3. Enter scopes separated by commas. 4. Click **Create key**. 5. Copy the key immediately. :::warning The raw key is shown only once. Store it securely before leaving the page. ::: ### API key properties | Property | Meaning | | --- | --- | | Name | Human-readable key name. Use names like `CRM sync` or `Warehouse integration`. | | Scopes | Permissions requested for this key. Scopes are comma-separated. | | Last used | Last known use time. Empty means the key has not been used yet. | | Revoke | Disables the key. Revoked keys cannot be used again. | ## Data & Privacy Data & Privacy contains export and account deletion tools. ![Data and privacy settings](pathname:///img/screenshots/product/settings/data-privacy.png) ### Data export Data export creates a zip backup of account data. The export includes account data such as conversations, messages, settings, and related Firestore document data. Flow: 1. Admin clicks **Request export**. 2. Teloring queues a background export job. 3. The button is disabled while the export is queued or running. 4. When ready, Teloring emails the requester. 5. The export table shows the download link when available. Only one unfinished export can be requested at a time. If an export is already queued, pending, running, processing, or in progress, the button shows **Export in progress**. ### Data retention policy The retention policy area is reserved for the account data-retention PDF. ### Danger zone: delete account Delete account is irreversible. When confirmed: - The account is marked deleted and inactive. - All members are disabled. - Users can no longer sign in to that account. To avoid accidental deletion, the admin must type their full name before confirming. :::danger Use Delete account only when the account should be permanently disabled. Contact Teloring support if you are unsure. ::: ## Conversation Attributes **Settings → Conversation Attributes** is where you design the custom fields agents fill in on a conversation — *Reason for contact*, *Outcome*, *Order number*, *Refund amount*. Unlike contact and customer fields, these belong to **one conversation**: the same customer writing again next week starts with an empty set. That is what makes them the fields you report on in [Analytics](./analytics.md), and the ones [Studio](./studio.md) can set automatically. You build the layout by dragging attribute types from a toolbox, with a live preview of the panel agents will see. Full guide: **[Conversation Attributes](./conversation-attributes.md)**. ## Roles & Permissions Roles & Permissions is no longer inside Settings. It appears as a separate Admin menu item below **Agents** and above **Audit Log**. The permission matrix is marked **Soon** until role-based permission editing is built. ## Recommended setup checklist For a new account: 1. Set business name, contact details, timezone, and currency in General Info. 2. Upload a logo. 3. Review the read-only account details. 4. Create any needed custom holiday calendars. 5. Create one or more business-hour schedules. 6. Connect schedules to Studio Business Hours conditions. 7. Decide whether to enable account-wide 2FA. 8. Add IP allow list entries only when login should be restricted to known networks. 9. Review active sessions after onboarding. 10. Create API keys only for trusted integrations. 11. Define your [Conversation Attributes](./conversation-attributes.md) — most teams start with *Reason for contact* and *Outcome*. --- # Achievements Source: https://docs.teloring.com/docs/product/achievements Markdown: https://docs.teloring.com/markdown/docs/product/achievements.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z **Achievements** turn everyday milestones — connecting your first channel, building an automation, growing your team — into **free top-up credits** you can spend anywhere in Teloring. Every time your account reaches a goal, a reward becomes ready to collect. Click **Collect** and the credits land in your balance. Think of it as a loyalty program built into the product: the more you set Teloring up and use it well, the more credits you earn. Open **Achievements** from the **Tools** section of the sidebar (just below AI World). ![The Achievements page — hero summary on top, then the state-grouped rows](pathname:///img/screenshots/product/achievements/achievements-overview.png) ## Key facts | Fact | Meaning | | --- | --- | | Rewards are **credits** | Each achievement pays out **top-up credits** into your account balance. Credits are the currency Teloring uses for messaging, AI, and other metered features. | | Credits last **365 days** | Collected credits are added to your top-up bucket and expire **one year** from the day you collect them. Collect them when you're ready to use them. | | **One-time per account** | Each achievement can be collected **once per business account** — not once per agent. Whoever clicks **Collect** first claims it for the whole account. | | **Account-wide progress** | Progress is measured across your entire account. If any agent connects a channel or resolves a conversation, it counts toward the account's achievements. | | **Server-verified** | The system checks the real criteria on its own servers before granting a reward. You can't unlock a reward you haven't actually earned, and the **Collect** button only appears once you qualify. | | **Any agent can collect** | There is no admin restriction — any signed-in agent on the account can collect a ready reward on the account's behalf. | | Some are **Coming soon** | A few achievements are shown as placeholders for features still being built. They're visible so you know what's ahead, but can't be collected yet — see [Coming soon](#coming-soon-achievements). | :::info For AI assistants and quick reference The Achievements page lists reward milestones for a single Teloring account. Each achievement has a **code**, an **icon**, a **name**, a **description of how to earn it**, and a **credit reward**. An achievement moves through states: *In progress* → *Ready to collect* → *Collected*. Rewards are paid as top-up credits with a 365-day expiry, granted once per account, and always verified server-side at the moment of collection. ::: ## The summary header The top of the page gives you an at-a-glance snapshot of how far you've come. ![The Achievements hero — completion ring, unlocked count, and credits earned](pathname:///img/screenshots/product/achievements/achievements-hero.png) | Element | What it shows | | --- | --- | | **Completion ring** | A circular progress meter with a percentage in the middle — how many of the total achievements you've unlocked. | | **Unlocked** | A count like `7 / 26` — achievements collected out of the total available. | | **Credits earned** | The running total of top-up credits you've collected from achievements so far. | | **Notice line** | A short reminder that these are free credits, valid for a year from collection. | ## The four sections Below the header, achievements are grouped by state so you always know where to look. Each section only appears when it has at least one achievement in it, and shows a count next to its title. ![The four state sections — Ready, In progress, Collected, Coming soon](pathname:///img/screenshots/product/achievements/achievements-sections.png) | Section | Colored dot | What's inside | Can you act? | | --- | --- | --- | --- | | **Ready to collect** | Green | You've earned these — the reward is waiting. | ✅ This is the only section with a **Collect** button. | | **In progress** | Blue | Not earned yet. Shows a progress bar and a `current / target` count where it applies. | No button — keep using Teloring to fill the bar. | | **Collected** | Purple | Already claimed. Shows the date you collected each one. | Nothing to do — the credits are already in your balance. | | **Coming soon** | Grey | Placeholder achievements for features still being built. | Not collectable yet — see [Coming soon](#coming-soon-achievements). | :::note The **In progress** section is sorted so the achievements closest to completion appear first — the ones you're about to unlock rise to the top. ::: ## Anatomy of an achievement row Every achievement is a single horizontal row, styled like a game-console trophy bar. ![A single achievement row, labelled](pathname:///img/screenshots/product/achievements/achievements-row.png) | Part | What it is | | --- | --- | | **Icon** (left) | An emoji badge that represents the achievement. | | **Progress bar** (the wide fill) | The colored fill shows how close you are. It's empty while locked, partly filled while in progress, and full once ready or collected. | | **Title** | The achievement's name. | | **Reward tag** | The credits you'll receive, e.g. `+150 credits`. Hidden achievements show a `?` instead. | | **Description** | A plain-language line telling you exactly how to earn it. | | **`current / target` count** | For measurable goals (e.g. resolve 500 conversations) this shows your live progress, such as `120 / 500`. | | **Right side** | Changes with the state — a **Collect** button, a **Collected ✓** stamp with a date, a **%** figure, a **Soon** label, or a **?** for hidden challenges. | ### What the right side means | Right-side state | Meaning | | --- | --- | | **Collect** button | Earned and ready — click to claim your credits. | | **Collected ✓** + date | Already claimed on the shown date. | | **percentage** (e.g. `40%`) | In progress — how far along you are. | | **Soon** | A Coming-soon placeholder; not available yet. | | **?** | A hidden challenge (see [The hidden Easter Egg](#the-hidden-easter-egg)). | ## Collecting a reward 1. Find an achievement in the **Ready to collect** section. 2. Click **Collect**. 3. A celebration pops up confirming the achievement and the credits awarded. 4. The credits are instantly added to your top-up balance, and the achievement moves to the **Collected** section. ![The celebration pop-up shown after collecting a reward](pathname:///img/screenshots/product/achievements/achievements-celebrate.png) :::tip There's no penalty for waiting, but remember credits start their **365-day** countdown the moment you collect. If you're not going to use them soon, it's fine to leave a reward as "Ready" until you need it. ::: :::caution If two agents on the same account click **Collect** on the same achievement at the same instant, only one will succeed — the reward is granted **once per account**. The second click will show "You already claimed this achievement," which is expected. ::: ## The full achievement list Here's every achievement, what it takes to earn it, and its reward. Rewards shown are the defaults — an account can have custom reward amounts set by Teloring. ### Getting set up | Icon | Achievement | How to earn it | Reward | | --- | --- | --- | --- | | 📞 | **First Ring** | Connect your first WhatsApp channel. | 40 | | 🌐 | **Omnichannel Rookie** | Connect 3 different channel *types* (e.g. WhatsApp + Email + Telegram). | 50 | | 📚 | **Knowledge is Power** | Upload your first document to the Knowledge Base. | 30 | | ⚡ | **Automation Boost** | Create your first Studio automation flow. | 25 | | 🧱 | **CRM Builder** | Create your first custom object type in the CRM. | 150 | | 🚀 | **We Are ALIVE!** | Connect a Live Chat widget to your website **and** receive your first message on it. | 100 | ### Growing your team & usage | Icon | Achievement | How to earn it | Reward | | --- | --- | --- | --- | | 🪑 | **Seat Expander** | Have 3 agents total on the account (you + 2 more). | 150 | | 👥 | **Team Player** | Have 5 agents online at the same time. | 300 | | 🔥 | **Weekly Warrior** | Any agent on the account logs in 7 days in a row. | 200 | | 🎓 | **Knowledge Master** | Upload 50 documents to the Knowledge Base. | 300 | | 🎨 | **Masterpiece** | Resolve 500 conversations. | 240 | | 🦉 | **Night Owl** | Resolve a conversation at 3am your local time. | 50 | | 📝 | **Note Taker** | Add your 100th internal note (the private "Note" tab inside a conversation). | 150 | | ✍️ | **Sealed & Signed** | Have 10 documents signed and completed by clients through Documents Signature. | 150 | ### Loyalty & value | Icon | Achievement | How to earn it | Reward | | --- | --- | --- | --- | | 💎 | **Believer** | Upgrade from Free to any paid plan. | 500 | | 🎂 | **1 Year Anniversary** | Your account turns 1 year old. | 1,000 | | 🏆 | **3 Years Loyalty** | Your account turns 3 years old. | 2,000 | | 🗝️ | **The Collector** | Unlock 10 achievements on this page. | 250 | ### AI-powered | Icon | Achievement | How to earn it | Reward | | --- | --- | --- | --- | | 🤖 | **AI Master** | Let AI Copilot help you (tips, suggestions, insights) on 10 conversations. | 100 | | 🪄 | **AI Whisperer** | The AI autonomously resolves 10 of your customer conversations. | 400 | | 😊 | **Happy AI** | Resolve 50 conversations where the customer felt happy. | 600 | | 🪃 | **Boomerang** | The same customer returns 10 times within 3 months. | 300 | :::note AI achievements depend on AI World The four AI achievements only make progress when the matching feature is switched **on** in [AI World](/docs/product/ai-world): - **AI Master** needs **AI Copilot** enabled — it counts conversations where Copilot generated a tip or suggestion. - **Happy AI** needs **Conversation Emotions** enabled — that's what records how each customer felt. - **AI Whisperer** needs an **AI agent** actively resolving conversations on its own. If the matching feature is off, these achievements will stay at 0% no matter how much you use the system. ::: ### Coming soon achievements These are visible as **Coming soon** placeholders. They represent features that aren't live yet, so **they can't be collected** — they're shown so you can see what's on the way. | Icon | Achievement | Planned goal | Reward | | --- | --- | --- | --- | | 💳 | **Topped Up** | Make your first credit-card top-up purchase. | 100 | | 👑 | **Referral King** | Refer a new customer to Teloring. | 250 | | 🔌 | **API Explorer** | Make your first Teloring API call. | 100 | ## The hidden Easter Egg | Icon | Achievement | Reward | | --- | --- | --- | | 🥚 | **Easter Egg** — *"There is an Easter egg hiding somewhere in the system. Can you find it?"* | 2,000 | The Easter Egg is a **secret** achievement. It doesn't show a goal or a progress bar — just a mysterious `?` — and it only unlocks when you discover a hidden trigger somewhere in Teloring. It sits with the **In progress** achievements until found. :::tip Keep exploring — the biggest single reward on the page is hidden on purpose. 🥚 ::: ## Rules & fine print - **One collect per account.** Every achievement can be collected a single time for the whole business. Adding more agents doesn't give each of them their own copy. - **You can only collect what you've earned.** The **Collect** button appears only after the real criteria are met, and the server double-checks at the moment you click. There's no way to collect early. - **Credits expire in a year.** Collected rewards are top-up credits valid for 365 days from the collection date. - **Progress can move both ways.** Some "in progress" goals depend on live conditions — for example, *Team Player* needs 5 agents **online at once**, and *Weekly Warrior* needs an unbroken login streak. If the condition drops, the bar reflects the current reality until you qualify again. - **Teloring can adjust rewards.** The credit amount for each achievement can be customized per account by Teloring, so what you see may differ from the defaults listed above. ## Frequently asked questions **I did the thing, but the achievement still says "In progress." Why?** A few checks depend on background data or on a feature being switched on: - **AI achievements** (AI Master, Happy AI, AI Whisperer) only advance when the matching switch is on in [AI World](/docs/product/ai-world). - **Note Taker** counts internal notes going forward; very old notes created before this feature may not be counted. - **Night Owl** looks at your recent resolved conversations — resolve one at 3am and it will register. If everything looks right and it still hasn't updated after a short while, refresh the page. **Do credits from achievements work like paid credits?** Yes — they go into the same balance and are spent the same way. The only difference is they're free and carry a 365-day expiry from when you collect them. **Can an agent lose an achievement the account already collected?** No. Once collected, it stays in the **Collected** section permanently and the credits are already yours. --- ## Related pages - [AI World](/docs/product/ai-world) — turn on the AI features that power the AI achievements. - [The Ring — Inboxes](/docs/product/ring/overview) — connect channels for *First Ring* and *Omnichannel Rookie*. - [Studio](/docs/product/studio) — build the automation for *Automation Boost*. - [CRM](/docs/product/crm) — create a custom object type for *CRM Builder*. --- # Knowledge Base Source: https://docs.teloring.com/docs/product/knowledge-base Markdown: https://docs.teloring.com/markdown/docs/product/knowledge-base.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z The **Knowledge Base** is where you teach Teloring's AI about *your* business. You upload files and websites, Teloring reads and indexes them, and then anyone (a person or the AI) can ask a question in plain language and get an answer built **only** from the content you provided — never from the open internet and never from the AI's general knowledge. Think of it as a private, searchable library for your account. A support team can load product manuals, price lists, policies, and help articles; an agent (or the AI Copilot) then asks "What's the return window for damaged items?" and gets the exact answer, with a reference back to the document it came from. Open the **Knowledge Base** from the **Tools** section of the sidebar (the 📖 book icon, next to AI World). ![The Knowledge Base page with a knowledge base selected — left panel with the list, main panel with stats, upload, sources, and the question box](pathname:///img/screenshots/product/knowledge-base/kb-overview.png) ## Key facts | Fact | Meaning | | --- | --- | | Answers come only from your content | The AI is instructed to use **only** the files and pages you uploaded. If the answer isn't in your content, it says so — it never makes something up from the web. | | Account-isolated | A knowledge base and everything in it belongs to one account. Business A can never see Business B's content. | | Multiple knowledge bases | You can create as many separate knowledge bases as you like — e.g. one for *Support*, one for *Sales*, one for *HR* — and each is searched independently. | | Powered by AI | Every uploaded document is read, split into small pieces, and turned into a searchable form so the AI can find the most relevant parts of *your* content for each question. | | Files **and** websites | Upload documents (PDF, Word, Excel, text, CSV, images) or point Teloring at a web page — optionally crawling its inner pages too. | | Processing happens in the background | After you upload, Teloring keeps working while you carry on. Each source shows a live status (Processing → Ready) and the page updates itself automatically. | | Requires the AI feature to be on | The Knowledge Base is unlocked by the **Knowledge Base** switch in [AI World](/docs/product/ai-world#-knowledge-base). While it's off, the page shows a "feature disabled" message. | | Feeds the AI Copilot | Once a knowledge base has content, agents can point the [AI Copilot](/docs/getting-started/conversations#ai-copilot) at it to answer customer questions during a live conversation. | ## Who uses the Knowledge Base | Role | Typical use | | --- | --- | | Admins | Turn the feature on in AI World, create knowledge bases, and decide what content goes in. | | Team managers | Keep the content accurate and up to date — upload new policies, rescan changed websites, remove outdated files. | | Agents | Ask questions to find answers quickly, and let the AI Copilot draw on the knowledge base while chatting with customers. | | The AI | The AI Copilot and AI agents read the knowledge base to ground their answers in your approved content. | ## Before you start: turn the feature on The Knowledge Base page only works when the **Knowledge Base** capability is enabled in [AI World](/docs/product/ai-world#-knowledge-base). - If it's **on**, the page works normally. - If it's **off**, you'll see a "Knowledge Base is Disabled" card with a button that takes you to the AI World settings. ![The "Knowledge Base is Disabled" message shown when the feature is turned off in AI World](pathname:///img/screenshots/product/knowledge-base/kb-disabled.png) :::note Only account **administrators** can turn the feature on in AI World. If the page is locked, ask an admin to enable it. ::: ## How the page is laid out The page has two areas: | Area | What it holds | | --- | --- | | **Left panel** | Create a new knowledge base, and the list of all your knowledge bases with a count badge. | | **Main panel** | Everything for the knowledge base you've selected: statistics, upload, the sources table, and the question box. | When you first open the page — before you've picked a knowledge base — the main panel shows a "Select a Knowledge Base" prompt. Click any knowledge base in the left list (or create one) to fill in the main panel. ## Knowledge bases (left panel) A **knowledge base** is one library of content. Most businesses keep a few — for example, separate libraries for different departments or products — so that a question is answered only from the relevant set of documents. ### Create a knowledge base In the **Create New** card: 1. Type a **Knowledge Base Name** (required, up to 200 characters) — e.g. `Support Docs`. 2. Optionally add a **Description** — a short note about what it contains. 3. Click **Create Knowledge Base**. The new knowledge base is added to your list and selected automatically, ready for you to upload content. ### Your knowledge bases list The **Your Knowledge Bases** card lists every knowledge base in the account, with a count badge showing how many there are. | Element | What it does | | --- | --- | | A row | Click it to select that knowledge base and load its content into the main panel. The selected one is highlighted. | | Name & description | Shows the name, plus the description if you added one. | | 🗑️ Delete (trash icon) | Appears when you hover over a row. Deletes the knowledge base **and all of its content**. | :::warning Deleting a knowledge base removes **all** its sources and everything Teloring learned from them, permanently. There is no undo. You'll be asked to confirm first. ::: ## Adding content Everything you add lives inside the **currently selected** knowledge base. Select one first, then use the **Upload File** card. ### Upload a file | Method | How | | --- | --- | | Click | Click the dashed upload area and pick a file. | | Drag & drop | Drag a file from your computer onto the dashed area. | ![The upload card — the drag-and-drop area, the website URL row, and the "crawl inner pages" option](pathname:///img/screenshots/product/knowledge-base/kb-upload.png) **Supported file types:** PDF, Word (`.docx`), Excel (`.xlsx`), plain text (`.txt`), CSV, and images (`.jpg`, `.png`, `.gif`, `.webp`). | Rule | Detail | | --- | --- | | Maximum size | 50 MB per file. | | Text documents | The text is read and indexed so it can be searched. | | Scanned PDFs (no selectable text) | Each page is read as an image so the AI can still understand it. | | Images | The picture itself is understood by the AI, so you can ask questions about what it shows. | ### Add a website URL To bring in a web page instead of a file: 1. Paste the full address (starting with `http://` or `https://`) into the **Enter website URL** box. 2. Optionally tick **Also crawl inner pages from this website** (see below). 3. Click **Add Website URL**. Teloring visits the page, extracts its readable text, and indexes it. #### Crawl inner pages When you tick **Also crawl inner pages from this website**, Teloring doesn't just read the one page — it discovers other pages on the **same website** and reads those too (via the site's sitemap and the links on the page), **up to 20 pages**. All of them are stored under a single source, and the source name shows how many extra pages were included (for example `https://example.com (+7 pages)`). Use this to load a whole help centre or product section in one step, instead of adding each page by hand. ### While content is processing Uploading is instant, but reading and indexing happens **in the background** so you don't have to wait. After you upload: - A status message appears (*"Processing in background… Source status will update automatically."*). - The new source shows up in the sources table as **Processing**. - The page checks for updates on its own every few seconds and switches the status to **Ready** (or **Failed**) when it's done — no need to refresh. ## Sources A **source** is one thing you added: a file or a website. The **Sources** table lists everything in the selected knowledge base. ![The sources table showing files and websites with their type, status, chunk count, date, and per-row actions](pathname:///img/screenshots/product/knowledge-base/kb-sources.png) | Column | What it shows | | --- | --- | | **Name** | The file name, or the website address. Long names are shortened; hover to see the full name. | | **Type** | The kind of source — `pdf`, `docx`, `xlsx`, `txt`, `csv`, `url`, or an image type. | | **Status** | **Ready** (indexed and searchable), **Processing** (still being read — shown with a spinner), or **Failed** (something went wrong). | | **Chunks** | How many searchable pieces this source was split into (see [How it works](#how-it-works)). A rough measure of how much content it holds. | | **Date** | When the source was added. | | **Actions** | Per-row buttons (below). | ### Row actions | Action | Appears on | What it does | | --- | --- | --- | | 🔄 **Rescan** | Website (URL) sources that aren't currently processing | Re-reads the website from scratch: removes the old content and fetches the current version. Use it after the website changes. | | ✕ **Delete** | Every source | Removes the source and everything Teloring learned from it. You'll be asked to confirm. | :::tip Websites change over time. When a page you've added is updated, use **Rescan** so the knowledge base reflects the latest content. Files don't change on their own, so there's no rescan for uploaded files — delete and re-upload if the document itself changed. ::: ## Statistics The **Statistics** row gives a quick health-check of the selected knowledge base. | Stat | Meaning | | --- | --- | | **Total Sources** | How many files and websites are in this knowledge base. | | **Total Chunks** | The total number of searchable pieces across all sources. | | **Text Chunks** | Pieces that came from text (documents and web pages). | | **Image Chunks** | Pieces that came from images or scanned PDF pages. This stays at 0 for a text-only knowledge base. | The **Delete Knowledge Base** button sits in the top-right of this card — it removes the whole knowledge base (same as the trash icon in the left list). ## Asking a question The **Ask a Question** card is where you (or the AI) query the knowledge base. ![The question box with the AI model picker, and an answer card showing the answer text plus the sources it used with match scores](pathname:///img/screenshots/product/knowledge-base/kb-ask.png) 1. Choose an **AI Model** (see the table below). 2. Type your question in plain language — the same way you'd ask a colleague. 3. Click **Ask** (or press **Enter**; use **Shift + Enter** for a new line). ### Choosing an AI model The model decides how the answer is written and how much it costs to run. All three answer only from your content — they differ in speed, depth, and cost. | Model | Best for | | --- | --- | | **Haiku (Fast & Cheap)** | Quick, straightforward look-ups where you just need the fact. | | **Sonnet (Balanced)** | The default — a good balance of quality and cost for most questions. | | **Opus (Most Powerful)** | Complex questions that need careful reasoning across several documents. | ### The answer When the AI has an answer, it appears in a highlighted card with: | Part | What it shows | | --- | --- | | **Answer text** | The answer, written in the **same language** as your question (ask in Hebrew, get Hebrew back; ask in English, get English back). | | **Model & chunks used** | Which model answered, and how many pieces of your content it read to do so. | | **Sources Used** | A chip for each document the answer drew from, with a **match score** (how closely that piece matched the question), and a page number when the source has pages. | ### When there's no answer If none of your content is relevant to the question, the AI does **not** guess. It replies **"No relevant information found."** This is deliberate: it means the answer genuinely isn't in your knowledge base, so you can trust that any real answer came from your own documents. (For automated uses, this "not found" case is returned as a clean signal that an AI agent can act on.) ## How it works You don't need to know the internals to use the page, but a short explanation helps both people and AI understand what to expect. 1. **Read** — Teloring opens each file or web page and pulls out its text (or reads it as an image, for scanned PDFs and pictures). 2. **Split** — the text is broken into small overlapping **chunks** so that each piece is a bite-sized, self-contained passage. 3. **Index** — every chunk is turned into a mathematical "fingerprint" (an AI embedding) that captures its meaning, and stored. 4. **Search** — when you ask a question, Teloring turns the question into the same kind of fingerprint and finds the chunks whose meaning is closest. Pieces that aren't close enough are ignored, so weak matches don't pollute the answer. 5. **Answer** — the most relevant chunks are handed to the AI model you picked, which writes a plain-language answer grounded only in those pieces — and tells you which sources it used. Because search is based on *meaning* rather than exact words, a question like "how long do I have to send something back?" can still find a policy that says "returns are accepted within 30 days." ## Where else the knowledge base is used The Knowledge Base page is where you **build and test** your content, but the real payoff is that the same content powers AI elsewhere in Teloring: | Where | How it uses the knowledge base | | --- | --- | | [AI Copilot](/docs/getting-started/conversations#ai-copilot) | During a live conversation, an agent can point the Copilot at a knowledge base and ask a question — the Copilot answers from your content without leaving the conversation. This needs **AI Copilot** to be on in [AI World](/docs/product/ai-world). | | AI agents | Automated AI answering can draw on a knowledge base to respond to customers with your approved information. | Keeping your knowledge bases accurate directly improves the quality of these AI answers. ## Element reference A quick map of every control on the page. ### Left panel | Element | Use | | --- | --- | | **Knowledge Base Name** field | Name for a new knowledge base (required, ≤ 200 characters). | | **Description** field | Optional note about the knowledge base. | | **Create Knowledge Base** button | Creates the knowledge base and selects it. | | Knowledge base row | Selects that knowledge base. | | Count badge | Number of knowledge bases in the account. | | 🗑️ per-row delete | Deletes that knowledge base and all its content (with confirmation). | ### Main panel — Statistics | Element | Use | | --- | --- | | **Total Sources / Total Chunks / Text Chunks / Image Chunks** | Read-only counts describing the selected knowledge base. | | **Delete Knowledge Base** button | Deletes the selected knowledge base and all its content (with confirmation). | ### Main panel — Upload | Element | Use | | --- | --- | | Upload area (dashed box) | Click or drag a file to add a document or image. | | **Enter website URL** field | The web address to read. | | **Add Website URL** button | Reads and indexes the page. | | **Also crawl inner pages** checkbox | Also reads linked pages on the same site, up to 20. | | Status line | Shows uploading / processing / complete / failed. | ### Main panel — Sources | Element | Use | | --- | --- | | Sources table | Lists every file and website, with type, status, chunk count, and date. | | 🔄 Rescan (URL sources) | Re-reads a website to pick up changes. | | ✕ Delete | Removes a source and its content (with confirmation). | ### Main panel — Ask a Question | Element | Use | | --- | --- | | **AI Model** dropdown | Choose Haiku, Sonnet, or Opus. | | Question box | Type your question (Enter to send, Shift+Enter for a new line). | | **Ask** button | Sends the question. | | Answer card | Shows the answer, the model and pieces used, and the sources with match scores. | ## Good practices | Recommendation | Why it helps | | --- | --- | | Split content into focused knowledge bases | A *Support* knowledge base and a *Sales* knowledge base give cleaner answers than one giant mixed library. | | Give each knowledge base a clear name and description | Makes it obvious which one to pick — and helps the AI Copilot choose the right one. | | Upload the source of truth, not summaries | The AI can only answer from what you give it, so load the real manuals, policies, and price lists. | | Rescan websites after they change | Keeps answers current. Otherwise the AI answers from the old version. | | Test with real questions | Ask the questions your customers actually ask, and confirm the answers and sources look right before relying on the AI Copilot. | | Remove outdated sources | Old documents can produce old answers — delete what's no longer true. | ## Troubleshooting | Problem | What to check | | --- | --- | | The page shows "Knowledge Base is Disabled" | The **Knowledge Base** switch is off in [AI World](/docs/product/ai-world#-knowledge-base). Ask an admin to turn it on. | | A source is stuck on **Processing** | Large files and multi-page website crawls take longer. The page updates itself; give it a little time. If it turns to **Failed**, try again. | | A source shows **Failed** | The file may be corrupt, password-protected, empty, or the website may have blocked access or had no readable text. Check the file/URL and re-add it. | | The answer is "No relevant information found" | The content genuinely isn't in this knowledge base. Add the relevant document, pick the right knowledge base, or rephrase the question. | | Answers seem out of date | The underlying document or website changed. **Rescan** the website, or delete and re-upload the file. | | A website added almost nothing | The page may load its content dynamically (via scripts), which can't always be read. Try adding a more content-rich URL, or upload the information as a file instead. | | The AI Copilot can't answer from the knowledge base | Confirm both **AI Copilot** and **Knowledge Base** are on in [AI World](/docs/product/ai-world), and that a knowledge base with content is selected for the conversation. | ## Frequently asked questions **Will the AI ever answer from the internet or its own knowledge?** No. It's instructed to use only the content you uploaded to the selected knowledge base. If the answer isn't there, it says "No relevant information found." **Can other businesses see my content?** No. Every knowledge base belongs to a single account and is fully isolated. Your files never cross to another business. **What languages are supported?** You can upload content and ask questions in Hebrew or English. The answer comes back in the same language you asked in. **How many knowledge bases or sources can I have?** You can create multiple knowledge bases and add many sources to each. Individual files are limited to 50 MB, and website crawling reads up to 20 inner pages per URL. **Do I have to wait for a file to finish processing?** No. Uploads process in the background and the page updates the status on its own. You can keep working and come back when it says **Ready**. **What's the difference between a source and a chunk?** A **source** is one thing you added (a file or website). A **chunk** is a small piece that source was split into for searching. One source usually becomes many chunks. --- # Files Warehouse Source: https://docs.teloring.com/docs/product/files-warehouse Markdown: https://docs.teloring.com/markdown/docs/product/files-warehouse.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z The **Files Warehouse** is the account-wide inventory of file records that supported Teloring features register while your team works. It brings together registered customer attachments, files sent by agents, call recordings, signed documents, Studio voice prompts, form images, and other stored assets in one place. Use it to answer questions such as: - How much storage is our account using? - Which files arrived from customers? - Which files did our team send? - Which conversation did a file come from? - Can I download a stored file? - Which old files should we permanently remove? Open **Files Warehouse** from the **Tools** section of the Teloring sidebar. ![The complete Files Warehouse page with account totals, filters, mixed file types, conversation links, and download controls](pathname:///img/screenshots/product/files-warehouse/warehouse-overview.png) :::info The Files Warehouse is a **catalog and management page**. Files arrive here automatically from other parts of Teloring. The page does not upload, preview, rename, organize into folders, or share files. ::: ## Key facts | Fact | Meaning | | --- | --- | | Account-wide | The page shows stored files for the whole Teloring account, not only files belonging to the signed-in agent. | | Automatic inventory | A file is added when a supported Teloring feature stores it. You do not add files from this page. | | Newest first | Files are listed by their stored date, with the newest files at the top. | | 25 files per page | Use **Previous** and **Next** below the table to move through the inventory. | | Search and filters work together | A file must match the file-name search, direction, and category currently selected. | | Summary totals are account totals | **Total Storage** and **Total Files** describe the whole account. They do not change when you filter the table. | | Conversation links depend on context | A link appears only when Teloring recorded a customer conversation ID with the file. | | Internal-chat downloads are protected | Private agent-to-agent chat attachments cannot be downloaded from the warehouse. Open the internal chat where the file was shared instead. | | Deletion is permanent | Deleting a file removes the stored object. There is no recycle bin or undo. | | Account isolation | A user can only list and manage the file records belonging to their own account. | ## Who uses the Files Warehouse | Role | Typical use | | --- | --- | | Agents | Find an attachment, return to its customer conversation, or download a permitted file. | | Team managers | Review the kinds of files moving through the account and remove selected files that are no longer needed. | | Administrators | Monitor total storage and, when necessary, delete every stored file in the account. | :::warning This is shared account storage. Removing a file can make it unavailable in the conversation, recording, form, signature process, or other feature that originally used it. Delete only files you are certain the business no longer needs. ::: ## How files get into the warehouse There is no **Upload** button on this page. Files are registered automatically when supported Teloring features save them. Common examples include: | Source | Example | | --- | --- | | Customer conversations | An image, video, audio message, document, or email attachment received through a supported file-registration path. | | Agent replies | A supported file attached to an outgoing conversation or email. | | Voice | A recorded inbound or outbound call. | | Documents Signature | A completed or declined PDF produced by the signature process. | | Studio | A WAV file uploaded as a voice prompt for an automation. | | Forms | A logo, background, or question image uploaded in the form builder. | | Account settings | A stored business logo or similar workspace asset. | | Internal chat | A private attachment shared from one agent to another. | Not every Cloud Storage object is a warehouse item. Temporary uploads, generated exports, inline content, and files used only during a short-lived process may be stored elsewhere and may not appear here. ## Page layout The page has four main areas: | Area | What it contains | | --- | --- | | Header | The page name, explanation, **Total Storage**, and **Total Files**. | | Filters | File-name search, direction, category, and **Clear Filters**. | | Selection bar | Appears after you select at least one row and provides bulk-selection and deletion actions. | | Files table | One row per stored file, followed by pagination controls when results are available. | ## Storage summary Two cards at the top-right summarize the complete warehouse inventory for the account. | Card | What it means | | --- | --- | | **Total Storage** | The sum of the recorded file sizes. Teloring automatically displays it in bytes, KB, MB, or GB. | | **Total Files** | The number of file records stored for the account. | These numbers are not a storage quota and do not show how much space remains. They also remain account-wide when the table is searched or filtered. For example, filtering to **Images** changes the table but not the two cards. :::note The total is based on the file sizes recorded in Teloring. A legacy record with no stored size can count as a file without adding to the displayed storage amount. ::: ## Search and filters ![The Files Warehouse with a partial file-name search, Incoming direction, Image category, and the resulting filtered rows](pathname:///img/screenshots/product/files-warehouse/warehouse-filters.png) All three filters can be used together. | Control | What it does | | --- | --- | | **Search files by name…** | Finds file names containing the text you type. Matching is not case-sensitive. The search runs shortly after you stop typing. | | **All Directions** | Shows every direction. Change it to **Incoming**, **Outgoing**, or **Internal Chat** to narrow the table. | | **All Categories** | Shows every category. Change it to **Image**, **Video**, **Document**, or **Audio** to narrow the table. | | **Clear Filters** | Clears the search and both dropdowns, returns to page 1, and clears the current file selection. | A file must match every active control. For example, searching for `invoice`, choosing **Incoming**, and choosing **Document** shows only incoming documents whose stored file name contains `invoice`. ### Direction Direction describes how the file relates to the account. | Direction | Meaning | | --- | --- | | **Incoming** ↓ | The file came into the business, such as a customer attachment or an inbound call recording. | | **Outgoing** ↑ | The file went out from the business or was prepared for outgoing use, such as an agent attachment, signed PDF, Studio prompt, or outbound recording. | | **Internal Chat** ↔ | The file is internal to the workspace. This includes private agent-to-agent attachments and can include assets created for internal Teloring features. | Direction does not tell you which inbox or agent handled the file. Use the conversation link, when available, to open its customer context. ### Category Category describes the broad kind of content. | Category | Typical content | | --- | --- | | **Image** | JPEG, PNG, GIF, WebP, or another stored image. | | **Video** | MP4 or another stored video. | | **Document** | PDF, Office document, spreadsheet, text file, CSV, or email attachment. | | **Audio** | Voice recording, audio message, or Studio WAV prompt. | Some provider-specific or older records can have another category, such as a push-to-talk recording. Those files remain visible under **All Categories**, even though there is no separate dropdown choice for them. ## The files table Each row represents one warehouse record. | Column | What it shows | | --- | --- | | Selection checkbox | Adds or removes this file from the current bulk selection. | | **Date** | When the file record was created. The browser formats the date and time using the user's locale. | | **File Name** | The stored original name, with an icon for its category. Long names are shortened; hover over the name to see it in full. | | **Size** | The recorded size in bytes, KB, MB, or GB. A dash means no positive size was recorded. | | **Direction** | **Incoming**, **Outgoing**, **Internal Chat**, or the raw value on a legacy record. | | **Category** | The stored category, such as image, video, document, or audio. | | **Conversation** | A `#conversation-id` link when customer-conversation context is available; otherwise a dash. | | **Download** | A download button for permitted files, or a lock for a protected internal-chat attachment. | The table is read-only apart from selection, download, conversation navigation, and deletion. Its column headings are labels, not sorting buttons. ## Download a file 1. Find the file by its name, direction, or category. 2. Click the download icon at the right end of the row. 3. Teloring creates a private, temporary download link and asks the browser to download the file. The generated link is valid for about one hour. Creating a link does not make the warehouse or storage bucket public. :::note Your browser can open some file types in a new tab instead of immediately saving them. Use the browser's **Download** or **Save as** action if that happens. ::: ### Locked internal-chat files A lock icon means the file came from a private internal chat. It cannot be downloaded from the account-wide Files Warehouse. This restriction prevents an agent from using a shared inventory page to retrieve an attachment from an agent-to-agent conversation they may not participate in. Open the original internal chat to view the attachment with its proper participant access. ## Open the related conversation When the **Conversation** column contains a link: 1. Click the `#conversation-id`. 2. Teloring opens the Conversations workspace. 3. When a message ID was stored with the file, Teloring also loads and highlights that specific message. This is the fastest way to understand who sent a customer file, why it was sent, and what happened around it. A dash in the column can be correct. For example, a business logo, Studio prompt, form image, or internal-chat attachment does not belong to a customer conversation. Older file records and some integration-created attachments can also lack conversation context. ## Select files You can select one file, the current page, or the whole account inventory. ![The Files Warehouse with several checked rows and the selection bar showing the selected count, Select all on this page, Select all files, and Delete Selected](pathname:///img/screenshots/product/files-warehouse/warehouse-selection.png) | Selection method | How it works | | --- | --- | | One or more rows | Tick the checkbox at the start of each row. | | Current page | Tick the checkbox in the table header, or click **Select all on this page** in the selection bar. This selects the visible rows on the current 25-file page. | | Whole account | First select the current page, then click **Select all _N_ files** when that option appears. This switches to account-wide selection. | The selection bar shows the number currently selected. Row selections remain selected while you move between result pages and while you change filters. :::warning **Select all _N_ files** means every warehouse file in the account—not only the rows matching the current search or filters. If you intend to remove only filtered results, select those rows individually instead. ::: To discard a selection, uncheck the selected rows. If selected rows are hidden by a different filter or page, click **Clear Filters** or reload the Files Warehouse page to reset the selection. ## Delete files 1. Select the required rows. 2. Click **Delete Selected** in the selection bar. 3. Read the confirmation carefully. 4. Click **Delete Selected** in the confirmation window. ![The permanent-delete confirmation displayed after selected files are chosen in the Files Warehouse](pathname:///img/screenshots/product/files-warehouse/warehouse-delete-confirmation.png) After deletion, Teloring reloads the table and recalculates the two account totals. | Deletion mode | Permission and scope | | --- | --- | | Selected rows | Deletes the explicitly selected warehouse files. Remember that a selection can include rows carried over from another page or filter. | | Whole account | **Administrator only.** Deletes every file record and stored object in the account, including files not shown by the current filters. | :::danger Deletion cannot be undone. It removes the stored file, not just the row in this table. Existing messages and features can retain a reference to the deleted file, but the content itself may stop opening, playing, or downloading. ::: Bulk deletions are recorded in the account audit log with the number of deleted files, deleted bytes, and whether the operation targeted the whole account. ## Pagination The Files Warehouse displays 25 rows at a time. | Control | Use | | --- | --- | | Result summary | Shows the current row range, such as `1–25`. | | **Previous** | Opens the preceding page. It is disabled on page 1. | | **Next** | Opens the next page. It is disabled when Teloring has reached the end of the currently returned results. | Changing a filter or search returns you to page 1. Clicking **Clear Filters** also clears your selection. ## Complete element reference ### Header and filters | Element | Use | | --- | --- | | **Total Storage** | Read-only total of recorded bytes across the account. | | **Total Files** | Read-only count of warehouse records across the account. | | Search box | Case-insensitive, partial file-name search. | | Direction dropdown | Filters to Incoming, Outgoing, Internal Chat, or all directions. | | Category dropdown | Filters to Image, Video, Document, Audio, or all categories. | | **Clear Filters** | Resets the search, filters, page number, and selection. | ### Table | Element | Use | | --- | --- | | Header checkbox | Selects or clears all rows on the current page. | | Row checkbox | Selects or clears one file. | | Category icon | Visual cue for image, video, document, audio, or another file type. | | Full-name tooltip | Hover over a shortened file name to read the stored name. | | Direction badge | Shows how the file relates to the account. | | Category badge | Shows the stored content category. | | Conversation link | Opens the related customer conversation and, when known, the specific message. | | Download button | Requests a temporary signed URL and downloads the file. | | Lock icon | Explains that a private internal-chat file cannot be downloaded here. | ### Selection and deletion | Element | Use | | --- | --- | | Selected count | Number of rows selected, or the total account file count in account-wide mode. | | **Select all on this page** | Selects all visible rows on the current page. | | **Select all _N_ files** | Switches from current-page selection to every warehouse file in the account. | | **Delete Selected** | Opens the permanent-delete confirmation. | | Modal close (✕) | Closes the confirmation without deleting. | | **Cancel** | Closes the confirmation without deleting. | | Confirmation **Delete Selected** | Starts the permanent deletion and is disabled while the request runs. | ## Good practices | Recommendation | Why it helps | | --- | --- | | Search before selecting | Reduces the chance of choosing a similarly named file by mistake. | | Use the conversation link before deleting | Confirms the file's customer and business context. | | Prefer individual selection for filtered cleanup | Account-wide selection ignores the active filters. | | Treat recordings and signed PDFs as business records | Your retention, legal, or compliance policy may require you to keep them. | | Keep original file names meaningful | File-name search is the warehouse's only text search. | | Recheck the selected count | Selections can persist when you change pages or filters. | | Limit account-wide deletion to planned maintenance | It removes files created by many different Teloring features. | ## Troubleshooting | Problem | What to check | | --- | --- | | No files are shown | Click **Clear Filters**. If the account has no registered files, the table correctly shows **No files found**. | | The summary cards do not match the filtered rows | Expected: the cards always describe the whole account, while filters affect only the table. | | A known file is missing from search | Confirm the stored file name, clear the category and direction filters, and search with a shorter part of the name. Temporary or non-indexed storage objects do not appear in the warehouse. | | There is no conversation link | The file may be a workspace asset, an internal-chat file, or an older/integration-created record without stored conversation context. | | The download column shows a lock | The item is a protected internal-chat attachment. Open it from the original internal conversation. | | Download opens a browser tab | Use the browser's save action. Some browsers preview supported content instead of saving immediately. | | Download says the file is unavailable | The warehouse record can remain when the underlying object was removed or could not be read. Ask an administrator to check the file source. | | **Select all _N_ files** deletion is rejected | Deleting the whole account inventory requires an administrator role. | | The table is empty after deleting the last rows on a page | Click **Clear Filters** to return to page 1 and reload the inventory. | ## Frequently asked questions **Can I upload a file from the Files Warehouse?** No. Upload or create the file in the Teloring feature that uses it, such as a conversation, form, Studio flow, account setting, or signature process. **Does the search read the contents of documents?** No. It searches the stored file name only. Use the [Knowledge Base](/docs/product/knowledge-base) when you want Teloring's AI to read and answer questions from document contents. **Why did my filters not change Total Storage or Total Files?** The cards always show account-wide totals. Filters apply only to the table. **Can I sort by date, size, or name?** No. The current page is fixed to newest first; the column headings are not interactive. **Why does a file have no conversation?** Some files belong to other parts of Teloring, and some older or integration-created records do not have conversation context. A dash does not necessarily mean the file is broken. **Can I download an internal-chat attachment here?** No. Open the internal chat where it was shared so Teloring can apply that chat's participant access. **Does deleting a row only hide it from the warehouse?** No. It removes the stored file itself and can make the content unavailable anywhere that still refers to it. **Can another Teloring business see our files?** No. The warehouse endpoints and file lookups are scoped to the signed-in user's account. --- # Agents and AI Agents Source: https://docs.teloring.com/docs/product/agents Markdown: https://docs.teloring.com/markdown/docs/product/agents.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z The **Agents** page is the account directory for the people and the autonomous AI profiles that work on customer conversations in Teloring. Use it to: - Invite human team members and manage their access. - Choose each person's role, language, login security, and voice access. - Let people reset their own password or move their own sign-in email — safely, through their inbox. - Resend invitations, deactivate access, or delete a profile. - Create AI Agents and control how they speak, what they know, what they collect, and how they hand a conversation back to a human. Open **Admin → Agents, Teams & Roles → Agents** from the Teloring sidebar. :::tip Grouping agents Once your agents exist, group them into **[Teams](./teams.md)** — *Sales*, *Support*, *Billing* — so a conversation can be routed to a whole team instead of one person. Teams is the second page under **Agents, Teams & Roles**. The **Department** field on an agent profile is *not* a team. It is a free-text label for display and search only. ::: :::info Account isolation Everything on this page belongs only to the current Teloring account. An agent or AI Agent created here is never visible in another account. ::: ## Human agents and AI Agents at a glance Both types live in the same table, but they work very differently. | | Human agent | AI Agent | | --- | --- | --- | | What it is | A person who signs in to Teloring. | An autonomous conversation profile. No person behind it. | | Sign-in | Email + password, with optional email 2FA. | None. No email, no password. | | What you configure | Identity, role, language, 2FA, department, notes, voice. | Identity, writing style, knowledge, rules, goals, outcomes, working hours. | | Conversation assignment | Picked in the **Assigned to** control. | Same control, marked with a robot icon. | | Once assigned | The person answers in the workspace. | Teloring opens an AI session and the AI answers incoming messages. | | Turn it off | **Deactivate** (reversible). | Set the profile **Status** to **Inactive**. | | Delete it | Yes, an admin can delete the profile. | Not from this page — no delete action exists yet. | | Can join a [Team](./teams.md) | Yes | Yes | | Counts as "online" | Yes, while signed in to Teloring. | **Always online.** An AI Agent is software, so it never goes offline. | :::info Two different meanings of "online" This distinction matters once you use Teams, and it is deliberate: - **Team auto-assignment** treats an AI Agent as **always online**, so an AI member can pick up work at 3 a.m. Use a team's *Only real agents* rule when you do not want that. - **Presence features** — the Team Chat green dot, the live-chat "agents online" count, and Studio's **Agent availability** condition — ask *"is a person there?"* and never count AI Agents. ::: ## Who can do what Any signed-in member can open the page and read the directory. Everything that changes something is enforced on the server. | Action | Permission it needs | | --- | --- | | View the directory and search it | **Agents → Read** | | Create a human agent or an AI Agent | **Agents → Create** | | Edit an agent or an AI Agent profile | **Agents → Update** | | Change per-agent voice access | **Agents → Update** | | Resend an invitation | **Agents → Update** | | Activate or deactivate a human agent | **Agents → Update** | | Delete an agent profile | **Agents → Delete** | | Change account voice settings | **My Ring → Update** | | Reset **their own** password | None — always allowed | | Reset **somebody else's** password | **Agents → Update** | | Change **their own** sign-in email | None — always allowed | | Change **somebody else's** sign-in email | **Agents → Update** | | Assign a conversation to a human or AI Agent | **Can assign conversations** on that inbox | | Create, edit, or delete a [Team](./teams.md) | **Teams → Create / Update / Delete** | See **[Roles and Permissions](./roles/overview.md)** for how these are granted. Two rules apply to everyone, whatever their role: - You cannot deactivate or delete **your own** profile here. - Nobody — not even an admin — types a password or a new email address on someone else's behalf. Both always travel through a one-time link sent to the agent's own inbox. ## Page overview ![Agents page with human and AI Agent rows](pathname:///img/screenshots/product/agents/agents-overview.png) | Element | What it does | | --- | --- | | **Add AI Agent** | Asks for a name, then creates the AI profile and its directory row. | | **Add Agent** | Opens the human-agent invitation form. | | **Total Agents** | Every row in the account: active people, pending invitations, inactive profiles, and AI Agents. | | **Active Agents** | Rows whose internal active flag is on. This includes **pending** humans and active AI Agents, so it can be higher than the number of green **Active** labels. Read the Status column for the exact onboarding state. | | **Voice channel** | Account-wide switch for Teloring browser calling. It must be on before voice can be enabled for any individual person. | | Search | Filters the loaded table by **name, email, phone, or department**. It does not search role, status, 2FA, or creation date. | | Agents table | The directory and its per-row actions. | Changes are account-wide, and the table reloads after each successful operation. ## Understand the table | Column | Meaning | | --- | --- | | Name | Display name, optional description, a **You** badge on your own row, and an **AI** badge on AI rows. The colored circle is the first letter, tinted from the name. | | Email | Sign-in address. AI rows show **No login — AI agent**. | | Phone | Optional, informational only on this page. | | Department | Free-text label such as Support or Sales. Display and search only — not a [Team](./teams.md). AI Agents are always filed under `AI`. | | Role | The [role](./roles/overview.md) this person holds — one of your account's own roles. AI rows show **AI Agent**, which is a label, not a role. | | 2FA | Whether that person's own 2FA switch is on. AI rows show a dash. | | Status | **Active**, **Pending**, or **Inactive**. | | Created | Creation date and time, in your browser's format. | | Actions | See [Row actions](#row-actions). | ### What each status means | Status | Meaning | Can they sign in or be assigned work? | | --- | --- | --- | | **Active** human | Registered and enabled. | Yes. | | **Pending** human | Invited, but has not chosen a password yet. | Sign-in is blocked. The profile can still appear in assignment pickers, so avoid assigning work to a Pending row. | | **Inactive** human | An admin deactivated the profile. | New sign-ins are blocked. | | **Active** AI Agent | Ready to be assigned. | Yes. | | **Inactive** AI Agent | Profile status is disabled. | New assignments are rejected. | :::warning Deactivating does not kick someone out Deactivation blocks new sign-ins, but it does **not** end a browser session that is already open. When access must stop immediately, also revoke that person's sessions in **Settings → Security & Login → Active sessions**. (Deleting a profile *does* revoke sessions.) ::: ## Row actions The icons at the end of each row change with the row's type, its status, and your role. ![Row action icons on a human agent row](pathname:///img/screenshots/product/agents/agent-row-actions.png) | Icon | Appears on | What it does | | --- | --- | --- | | **Edit** (pencil) | Every row | Human → the agent form. AI → the AI profile editor. Saving needs **Agents → Update**. | | **Resend confirmation email** (envelope) | **Agents → Update**, on a **Pending** person | Sends a fresh 1-hour invitation and stops the previous invitation link from working. | | **Reset password** (padlock) | Your own row always; anyone else's with **Agents → Update** | Emails a one-time link so a new password can be chosen. See [Passwords](#passwords). | | **Change email** (envelope with arrow) | Your own row always; anyone else's with **Agents → Update** | Starts a sign-in-address change, confirmed from the **current** inbox. See [Change a sign-in email](#change-a-sign-in-email). | | **Deactivate / Activate** | **Agents → Update**, on someone else | Turns the profile off or back on. Reversible. | | **Delete agent** (bin) | **Agents → Delete**, on someone else | Permanently removes the profile after typing `DELETE`. | Reset password and Change email are the two actions that never need a permission — everybody gets them for their **own** row. Extending either to somebody else is **Agents → Update**. :::note Password reset does not appear on a **Pending** row — there is no password to reset yet. Use **Resend confirmation email** instead. ::: --- ## Human agents ### Invite a person 1. Open **Admin → Agents**. 2. Click **Add Agent**. 3. Fill in the name and email (both required). 4. Choose the role and default language. 5. Optionally add phone, department, description, 2FA, and comments. 6. Click **Create Agent**. ![Add Agent form](pathname:///img/screenshots/product/agents/add-human-agent.png) Teloring creates a **Pending** profile and emails a one-time password-setup link. - The link is valid for **1 hour** and can be used **once**. - Until the person chooses a password their row stays **Pending** and sign-in is blocked. - No password is set from this form. Nobody in the account ever sees or chooses another person's password. - Sending a new invitation cancels the person's earlier unused **invitation** links. - If the email fails to send, the profile is still created. Fix the address or the mail problem and use **Resend confirmation email**. #### Field reference | Field | Required | What it controls | | --- | --- | --- | | Agent Name | Yes | The name shown across Teloring: assignments, messages, audit entries, Team Chat. | | Email | Yes | The sign-in address. It must be unique across all of Teloring. In Edit it is read-only — move it with **Change email**. | | Phone | No | Internal contact number. Local or international format. | | Role | No | One of your account's [roles](./roles/overview.md). The list is your own, and the role's description appears underneath so you can confirm the choice. Defaults to the account's **Agent** role. | | Department | No | Free-text label, used for display and search only. It does **not** create a team, a queue, or a permission group. To group agents for routing, use **[Teams](./teams.md)**. | | Default Language | No | English or Hebrew. Sets the person's workspace language and the language of their invitation, reset, and 2FA emails. | | Description | No | One line about the person's responsibility, shown under their name. | | Two-Factor Authentication | No | When on, sign-in also requires an emailed code. | | 2FA Method | No | Leave on **Email**. See [What is not finished yet](#what-is-not-finished-yet). | | Comments | No | Internal notes. Never shown to customers, but any member who can open the profile can read them. | | Voice for this agent | Edit only | Turns on this person's browser softphone, once account voice is on. | #### Choosing a role The **Role** list contains your account's own roles. Every account starts with five — **Owner**, **Team Leader**, **Marketing**, **Agent** and **Viewer** — and you can rename, re-scope, duplicate or delete any of them except Owner. Picking a role decides everything the person can reach: which pages, which inboxes, and what they may do in each. Read the description under the picker if you are unsure, or open **Admin → Agents, Teams & Roles → Roles & Permissions** to see the full grid. | If the person is… | Start with | | --- | --- | | A front-line agent answering customers | **Agent** | | A support manager who is not the account owner | **Team Leader** | | Working on campaigns, automations and reports | **Marketing** | | A stakeholder who only wants dashboards | **Viewer** | | A co-owner of the workspace | **Owner** | | Anything else | Duplicate the closest role and adjust it | See **[Roles and Permissions](./roles/overview.md)**. :::warning Owner is full access **Owner** can reach everything, including billing and account deletion, and its permissions cannot be narrowed. Give it only to people who genuinely own the workspace — but give it to at least **two** of them, so nobody is ever locked out. ::: ### Edit a person Click the pencil on a human row. You can change name, phone, role, department, default language, description, 2FA, comments, and voice access. The email field is read-only here on purpose — see below. ### Passwords Passwords are only ever chosen by the person themselves, from a one-time emailed link. There are three ways one gets issued. | Path | Who starts it | Effect on the current password | | --- | --- | --- | | **Invitation** (new profile / resend) | Admin | No password exists yet. | | **Reset password — my own row** | Anyone, for themselves | **Keeps working** until the new one is chosen, so a lost or slow email cannot lock you out. | | **Reset password — someone else** | Admin | **Stops working immediately.** Use this when credentials may be compromised. | | **Forgot your password?** on the sign-in page | Anyone, without signing in | Same as a self-reset. The page answers identically whether or not the address exists, so it cannot be used to discover who has an account. | Every one of those links: - lasts **1 hour** and works **once**; - is stored only as a hash — the real value exists only inside the email; - cancels the person's other unused links **of the same kind** (so a new password link no longer silently cancels a pending email-change confirmation); - stops working if the profile is deactivated or its address changes in the meantime. Password reset requests are rate limited per IP, and repeated requests for the same address are throttled, so one inbox cannot be flooded. #### Password rules A new password must: - be at least **8 characters** (and at most 72 bytes); - contain an **uppercase** letter; - contain a **lowercase** letter; - contain a **digit**; - contain one **special character** — anything visible that is not a letter or a digit. Spaces do not count. The set-password page lists the same rules and checks them as you type. ### Change a sign-in email The sign-in address is an identity, so moving it is deliberately a two-step, inbox-confirmed operation. 1. Open the person's row (or the Edit form) and click **Change email**. 2. Confirm. Teloring emails a confirmation link **to the address currently on file** — never to a new one. 3. The recipient opens the link and types the new address there, once. 4. Only then does the sign-in address move. Teloring also notifies the old address that it is no longer the sign-in email. ![Change email confirmation dialog](pathname:///img/screenshots/product/agents/change-email-modal.png) Why it works this way: control of the existing inbox is what authorises the move. An admin — or someone who hijacked a dashboard session — cannot take over an agent's identity without being able to read the inbox that agent already uses. The link lasts **1 hour**, is single use, and nothing changes until it is opened. ### Two-factor authentication Per-person 2FA is separate from the account-wide **Enforce 2FA for all members** switch in Settings. A code is required when **either** is true: - the person's own **Two-Factor Authentication** switch is on; - the account-wide enforcement setting is on. The code is emailed, expires after **5 minutes**, is stored only as a hash, and is attempt-throttled. Teloring can also ask for a code when someone signs in from a browser it has not seen before, depending on your account's new-device setting. :::note Keep the method on **Email**. The **WhatsApp** option can be saved, but every code is still delivered by email. ::: ### Voice Voice works at two levels, and the account level comes first. #### 1. Account voice The **Voice channel** card switches Teloring browser calling on or off for the whole account. - Needs **My Ring → Update**. - It must be on before any individual can get voice credentials. - Turning it off stops account voice sessions from starting. - The card is a single switch. The account's concurrent-call limit exists in the backend but is not editable here. #### 2. Per-person voice Open a person's profile and use **Voice for this agent**. When you enable it, Teloring: - generates a private SIP extension and password; - encrypts the password at rest; - provisions the extension on the Teloring voice server; - allows that person's call window to start voice sessions. If provisioning fails, the operation reports an error and the switch reverts. **Reset voice credentials** rotates the SIP password, ends the current voice session, and updates the provisioned extension. Use it if credentials may have leaked or the softphone can no longer register. :::note These controls are for **human browser softphones**. AI Agents never receive SIP credentials. ::: ### Deactivate or delete? | Choose | When | What survives | | --- | --- | --- | | **Deactivate** | Leave of absence, suspension, or a reversible offboarding step. | Everything. The profile can be switched back on. | | **Delete agent** | Permanent removal, after access and ownership have been reviewed. | Conversations, messages, audit entries, and names already copied into records. | Deleting a profile also revokes that person's dashboard sessions, outstanding password-setup links, trusted devices, and personal API tokens. Before you delete: 1. Reassign any open conversations they still own. 2. Check Studio flows or processes that name that agent. 3. **Turn voice off first** — deleting the profile does not deprovision the voice extension. 4. Accept that history stays, without a live profile behind it. --- ## AI Agents An AI Agent talks to the customer directly. Do not confuse it with **AI Copilot**: - **AI Agent** owns the conversation and answers the customer. - **AI Copilot** only advises a human in the right-hand panel. - They never run on the same conversation at the same time. ### Create an AI Agent 1. Open **Admin → Agents**. 2. Click **Add AI Agent**. 3. Type a name when prompted, and confirm. 4. Find the new row and click its pencil to open the profile editor. 5. Complete the profile **before** you point real customers at it. Creating the row does not attach it to any inbox or conversation. ### Put an AI Agent to work 1. Open an active conversation. 2. Open **Assigned to**. 3. Pick the AI Agent (robot icon). 4. Teloring starts an AI session from a **snapshot** of the profile. 5. The conversation moves to the **AI Agent** queue, unless a Studio flow still owns it. 6. The AI sends its greeting when appropriate and answers incoming messages from then on. Because each session uses a snapshot, editing a profile changes **future** sessions only. A conversation already running keeps the settings it started with. :::warning Setting a profile to **Inactive** blocks new assignments but does **not** stop a session that is already running. To stop one immediately, reassign that conversation to a human or back to the waiting line. ::: ### The profile editor Eight tabs, one **Save AI Profile** button that saves all of them together. ![AI Agent Identity tab and the eight editor tabs](pathname:///img/screenshots/product/agents/ai-agent-identity.png) #### Identity | Field | What it controls | | --- | --- | | Name | The sender name customers see, and the directory name. | | Job title | Goes into the AI's instructions, e.g. *Customer Care Specialist*. | | Gender | Tells the AI which self-reference forms to use in gendered languages. | | Status | **Active** allows new assignments; **Inactive** blocks them. Saving also updates the directory row. | | About / Bio | Explains the AI's role and the business it represents. Part of the instructions. | | Internal note | For your team only. Never sent to the model or the customer. | Use the bio to describe responsibility and context — not to re-type a whole Knowledge Base. #### Voice & Language “Voice” here means **writing style**. It has nothing to do with phone calls. ![AI Agent Voice and Language tab](pathname:///img/screenshots/product/agents/ai-agent-voice.png) | Field | What it controls | | --- | --- | | Tone preset | Friendly, professional, casual, formal, playful, empathetic, or concise. | | Response length | Short, medium, or long guidance — not a hard character limit. | | Allowed languages | Which languages the AI should answer in. Hold **Ctrl** (Windows) or **Command** (macOS) to pick several. Select none to let it follow the customer. | | AI disclosure | **Always**, **If asked**, or **Never**. “Never” tells the AI not to describe itself as automated — check that against the rules that apply to your business. | | Signature | Appended to AI messages when not already present. | | Greeting message | The first message, sent on assignment, if the conversation has not already been greeted by an AI. | Greeting variables: | Variable | Becomes | | --- | --- | | `{{customer_name}}` | The customer or contact name, or “there” if unknown. | | `{{agent_name}}` | The AI Agent's name. | | `{{conversation_id}}` | The current conversation ID. | :::note Hebrew, Arabic, and English are the languages Teloring can reliably detect server-side. Russian, Spanish, and French shape the prompt but are not enforced. ::: #### Knowledge ![AI Agent Knowledge tab](pathname:///img/screenshots/product/agents/ai-agent-knowledge.png) | Field | What it controls | | --- | --- | | Knowledge base | Which account Knowledge Base is searched before every AI turn. | | Grounding mode | How strictly the AI must stay inside that Knowledge Base. | | Confidence threshold | How similar a passage must be to be retrieved. Low is broadest, High is strictest. | | Show citations | Asks the model to cite grounded information. Guidance, not a guaranteed format. | | Grounding mode | Use it for | | --- | --- | | **Strict KB only** | Regulated or tightly controlled answers. A Knowledge Base must be selected before you can save. | | **KB + general language** | The Knowledge Base is the source of truth, but the AI may phrase things naturally. A good default. | | **Open assistant** | Broader answers, still preferring Knowledge Base context when it exists. | Build and test the [Knowledge Base](./knowledge-base.md) before switching to strict mode. #### Rules ![AI Agent Rules tab](pathname:///img/screenshots/product/agents/ai-agent-rules.png) | Field | What it controls | | --- | --- | | Forbidden topics | Comma-separated topics the AI must not discuss. If a generated answer contains one of these exact phrases, Teloring replaces it with a refusal/handoff sentence. | | Do not promise | Comma-separated commitments the AI must not make, such as unapproved discounts or delivery dates. | | Behavioral instructions | Free-text operating rules. Keep them short and non-contradictory. | | Max turns | **Enforced.** Maximum customer turns before the session ends on a limit. | | Max duration minutes | **Enforced.** Maximum session age, checked when a message is processed. | | Max consecutive AI messages | Guidance only — see [What is not finished yet](#what-is-not-finished-yet). | Put factual material in the Knowledge Base, collection requirements in Goal, and only true behavioural rules here. :::warning The forbidden-topic filter replaces an unsafe answer, but replacing text does not move the conversation. Keep the **Forbidden topic** escalation reason enabled with a real routing action. ::: #### Goal Goal decides whether the AI only answers, or also gathers information into your CRM. ![AI Agent Goal tab with a CRM field target](pathname:///img/screenshots/product/agents/ai-agent-goal.png) | Mode | Meaning | Use it? | | --- | --- | --- | | **Give info** | Answer and help. No proactive collection. | Yes — for information and support profiles. | | **Get info** | Intended for collection only. | **No.** It does not trigger collection (see below). | | **Both** | Answer the customer *and* collect one missing required field at a time. | Yes — this is the working path for any collection. | :::warning Choose “Both” for collection **Get info** does not reach the runtime's collection mode, so a profile set to it never asks for your fields. Use **Both** whenever the AI must collect data. ::: ##### Add a field to collect 1. Set the mode to **Both**. 2. Click **Add Field**. 3. **Drag** a CRM field from the right-hand picker onto the card's **Target field** box. The target box is read-only — dragging is how it gets filled, and it also fills the label, internal slug, data type, and choice values. 4. Adjust the customer-facing label if you want. 5. Check the data type. 6. Optionally write a sample question. 7. Set the toggles. 8. Repeat for each field. | Property | Meaning | | --- | --- | | Label | The human name, used to phrase a natural question. | | Data type | Text, number, email, phone, date, single select, multi select, boolean, or file. | | Target field | Where the answer is saved in the CRM. | | Sample question | Optional. Leave it empty and the AI writes its own question from the label and type. | | Allowed values | For select types, the accepted values. | | Mandatory | Counts towards “all mandatory fields collected”. | | Re-ask if known | Whether the AI may ask again when the value already seems known. Guidance. | | Overwrite if present | Off = never replace a non-empty CRM value. On = a new answer may replace it. | Supported destinations: - `customer.` - `contact.` - `conversation.custom_fields.` :::warning Custom object targets do not save The picker also lists your custom objects (deals, tasks, and so on) as `object..`. The AI runtime does not write those. Stick to Customer, Contact, and Conversation targets. ::: Answers are validated (email, phone, number, boolean, and choice values) before saving, and customer/conversation writes fire the usual Studio change events. :::note Conversation targets are custom fields The three Conversation targets write under `conversation.custom_fields`. The **Conversation priority** target, for example, does **not** change the real priority control in the conversation header. ::: ##### Two picker quirks to work around - Type the label **after** dragging the target. Typing first can freeze the hidden slug after one character. - With several field cards open, drag the CRM field onto the exact card you mean; a click can land on the first card instead. #### On Success A session can end successfully when the customer confirms it is resolved, or when every mandatory field has been collected and the customer then goes quiet until the follow-up timer. ![AI Agent On Success tab](pathname:///img/screenshots/product/agents/ai-agent-on-success.png) | Setting | Meaning | | --- | --- | | All mandatory fields collected | Lets completed collection become a quiet success after the follow-up timeout. | | Customer confirmed resolved | Lets a clear “all good” or “thanks” close the session. | | Closing message sample | Guidance for tone and intent. The real closing text is generated from the conversation and the customer's language. | | Action | What happens after the closing message. | | Action | Result | | --- | --- | | **End and resolve** | Resolves the conversation and clears the assignment. | | **No action** | Ends the AI session and changes nothing else. Be careful: the conversation can stay assigned to the AI with no live session. | | **Send back to waiting line** | Clears the assignment so a human can pick it up. | | **Assign to human agent** | Assigns the chosen active person. If that person is no longer valid, it goes to the waiting line instead. | #### On Fail ![AI Agent On Fail tab](pathname:///img/screenshots/product/agents/ai-agent-on-fail.png) ##### The customer went quiet | Setting | Meaning | | --- | --- | | Follow-up after minutes | After this much silence, Teloring generates and sends a follow-up. 1–1,440 minutes. | | Follow-up message sample | Guidance for that follow-up. | | Give up after additional minutes | Grace period after the follow-up. 1–1,440 minutes. | | No-response closing sample | Guidance for the closing sent before the action runs. | | Action | Resolve, do nothing, return to the waiting line, or assign to a human. | If every mandatory field was already collected, reaching the follow-up time counts as a **quiet success** instead of abandonment. ##### The customer refused or got stuck The AI can report that the customer will not provide the information, or that collection is going in circles. Choose the action for that outcome. ##### Escalation reasons Six reasons can be configured: **asked for agent**, **angry or frustrated**, **upsell opportunity**, **churn risk**, **forbidden topic**, and **low confidence**. For each one, set whether it is enabled, an optional handoff message sample, and the routing action (with a target person if relevant). :::warning An off switch does not stop detection Turning a reason off disables its **handoff handler**, not the AI's ability to reach that outcome. A disabled reason can end the session with no routing at all. Keep the reasons you care about enabled, each with an explicit action. ::: #### Channels & Hours The tab is named Channels & Hours, but today it only exposes **working hours** and **after-hours behaviour**. There is no per-inbox control here. ![AI Agent Channels and Hours tab](pathname:///img/screenshots/product/agents/ai-agent-hours.png) | Setting | Meaning | | --- | --- | | Timezone | An IANA timezone such as `Asia/Jerusalem` or `Europe/London`. An invalid value falls back to UTC. | | Day switch | Marks that weekday as an operating day. | | Start and end | One operating interval for that day, inclusive of both ends. | Two behaviours worth knowing: - **If every day is switched off, the AI Agent is treated as available 24/7.** It does not mean “closed all week”. - Only one same-day interval is supported. An overnight range such as `22:00–06:00` is not treated as an overnight shift. | After-hours behaviour | Result | | --- | --- | | Do not respond | Skips the immediate AI reply outside working hours. | | Respond normally | Runs the normal AI turn anyway. | | Respond with after-hours message | Sends your fixed after-hours text instead of a generated answer. | :::warning The scheduled follow-up job does not re-check working hours. A profile set to **Do not respond** can still send a follow-up later, outside hours. Do not rely on it as a guarantee of total silence. ::: ### What happens during an AI session 1. Someone assigns an open conversation to an active AI Agent. 2. Teloring checks the profile is active and snapshots it into a session. 3. The AI greets the customer when appropriate. 4. Incoming customer messages go to the AI Agent instead of AI Copilot. 5. For each turn Teloring searches the Knowledge Base, builds the instructions, and runs the model. 6. The AI answers, saves a configured field, or reports a terminal outcome. 7. Teloring sends the generated follow-up, closing, or handoff text the profile calls for. 8. The configured action resolves, unassigns, assigns a human, or does nothing. AI messages carry an AI Agent badge. Model requests, retrieval details, responses, provider failures, and fallbacks are recorded for Teloring administrators to review in internal tooling. ### Recommended setups **A support AI Agent** 1. Write a narrow job title and bio. 2. Select only languages your content and team actually support. 3. Connect a tested Knowledge Base. 4. Start on **KB + general language**. 5. Add forbidden commitments and a few short behavioural rules. 6. Keep the mode on **Give info** (or **Both** if it must collect). 7. Send success to **End and resolve**. 8. Send failure and escalation to the waiting line or a monitored person. 9. Set working hours and test after-hours behaviour. 10. Run a full test conversation before going live. **A lead-collection AI Agent** 1. Mode **Both**. 2. Add only the fields the business truly needs. 3. Use Customer, Contact, or Conversation targets. 4. Mark the critical ones Mandatory. 5. Turn **Overwrite if present** off for fields that must not replace verified data. 6. Route completed collection to a human, or resolve it — whichever matches your process. --- ## Grouping agents into Teams Both human agents and AI Agents can be grouped into **[Teams](./teams.md)** — the second page under **Agents, Teams & Roles**. A team lets you assign a conversation to a group instead of one person, and it changes who may pull a waiting conversation with **Get next**: | | Effect on this page | | --- | --- | | Membership | Set on the **Teams** page, not in the agent form. An agent can be in many teams. | | Human vs AI members | Both are allowed. A team's **Only real agents** rule excludes AI Agents and removes any already in it. | | Auto-assignment | A team can hand a conversation to a random **online** member. AI Agents count as always online. | | Deactivating an agent | They are silently dropped from teams the next time a team is saved. | | Deleting an agent | They are removed from every team automatically. | **Department is not a team.** It is a free-text label on the agent profile, used for display and search only. Team membership is set on the Teams page. Read the full guide: **[Teams](./teams.md)**. --- ## What is not finished yet These are real gaps, not things you are doing wrong. Plan around them. Every item below was re-verified against the current build. | Item | What actually happens | Do this instead | | --- | --- | --- | | **2FA method: WhatsApp** | Saved, but every code is emailed. | Leave it on Email. | | **“2FA is not active yet”** hint under the 2FA switch | Outdated text. Email 2FA works. | Ignore the hint. | | AI **Get info** goal mode | Never reaches the runtime's collection mode, so nothing is collected. | Use **Both**. | | AI **custom object** goal targets (`object..`) | Offered in the picker; the runtime does not write them. | Use Customer, Contact, or Conversation. | | Conversation **priority / topic / notes** targets | Write to `conversation.custom_fields`, not the real conversation controls. | Use them only as custom data. | | Goal data type **file** | Stores text. Nothing is uploaded or registered as a CRM file. | Collect a link, or use a form or attachment instead. | | **Max consecutive AI messages** | Goes into the prompt only. Unlike max turns and max duration, nothing enforces it. | Treat it as a hint. | | Escalation reason **off** switch | Disables the handoff handler, not the detection. The session can end with no routing. | Keep needed reasons on, each with an action. | | Escalation **“other”** fallback | Not in the editor, and hardcoded to no action. | Configure the six visible reasons and avoid no-action paths. | | **Allowed inboxes** for an AI Agent | The runtime honours the setting, but the editor has no control for it and **clears it on every save**, so it can never be used. | Control where an AI runs by only assigning it there. | | After-hours **Do not respond** | Stops immediate replies; scheduled follow-ups still go out. | Do not treat it as full silence. | | **Add AI Agent** name box | Still a plain browser prompt, unlike every other dialog on the page. | Nothing to do — it works. | | **Active Agents** statistic | Counts pending humans and active AI Agents too. | Read the Status column for real onboarding state. | | **Pending** humans in assignment pickers | They are technically active, so they can be picked before they finish registering. | Do not assign work to a Pending row. | | **Deactivate** and open sessions | Blocks new sign-ins only; an open session keeps working. | Also revoke sessions in Settings → Security & Login. | | Deleting a **voice-enabled** person | The voice extension is not deprovisioned. | Turn voice off first, then delete. | | **Voice channel** card | On/off only; the concurrent-call limit is backend-only. | Ask Teloring support to change the limit. | | Management buttons for non-admins | Some can still render; the server rejects the change. | Ask an admin to do it. | | **AI Agent delete** | There is no delete action for an AI Agent row. | Set the profile **Status** to **Inactive**. | Team-specific limitations are listed in the [Teams guide](./teams.md#limitations-and-what-to-watch-for). ## Troubleshooting ### Someone is stuck on Pending - Check they opened the newest email — invitations last **1 hour**. - Click **Resend confirmation email** to issue a fresh link (the old one stops working). - Check spam filtering and that the address is spelled correctly. ### Someone cannot sign in after a password reset If an **admin** reset it, the old password stopped working right away — they must complete the newest link, which lasts 1 hour. If they reset it **themselves**, the old password still works until they finish. Either way, sending a new link cancels the previous one, so make sure they are using the latest email. ### A new password is rejected It must meet all five rules: 8+ characters, upper, lower, digit, and one special character. The set-password page shows which rule is failing. ### The email-change link does not arrive It goes to the address **currently on file**, not to the new one. Confirm that inbox is reachable. If it is not, an admin can create the correct profile and deactivate the old one. ### An AI Agent does not appear in Assigned to - Confirm its **Status** is Active. - Reload the conversation after saving the profile. - Confirm the conversation is still open. ### An AI Agent ignores changes I just saved The running conversation uses the snapshot from when its session started. Reassign it, or start a new conversation, to pick up the new profile. ### The AI is not collecting a field - Use **Both**, not **Get info**. - Mark the field **Mandatory** if it must be asked. - Check the target starts with Customer, Contact, or Conversation — not a custom object. - Confirm the conversation is assigned to the AI and the session is still live. ### The AI cannot answer from the Knowledge Base - Confirm a Knowledge Base is selected. - Confirm it has processed sources. - Lower the confidence threshold for broader recall. - Ask the same question on the Knowledge Base page to compare. - In strict mode, missing context is *meant* to produce a refusal or a limited answer. ### Voice cannot be enabled for someone - Turn the account **Voice channel** on first. - Confirm the profile is active. - If provisioning reports an error, the voice server needs attention before retrying. ## Related guides - [Teams](./teams.md) — group agents and route conversations to a whole team. - [Conversations](../getting-started/conversations.md) — assignment and the AI Agent queue. - [AI World](./ai-world.md) — account-wide AI Copilot and AI feature switches. - [Knowledge Base](./knowledge-base.md) — build and test grounded sources. - [Settings](./settings.md) — account-wide 2FA, security, and session revocation. - [Voice inbox](./ring/voice.md) — voice channels and calling behaviour. --- # Teams Source: https://docs.teloring.com/docs/product/teams Markdown: https://docs.teloring.com/markdown/docs/product/teams.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z A **team** is a named group of agents — *Sales*, *Support*, *Billing*, *Hebrew speakers*. Once a team exists, you can assign a conversation to the **whole team** instead of picking one person. That solves the everyday problem with per-person assignment: to route a conversation you had to know who is working, who is free, and who handles that topic. With teams you route by *responsibility* — "this is a Sales conversation" — and let Teloring or the team itself work out who actually takes it. Teams are **account-wide**. Every agent sees the same teams; there is no per-agent team list. Open **Admin → Agents, Teams & Roles → Teams** in the sidebar. :::info Account isolation Teams belong only to the current Teloring account. A team created here is never visible in another account, and a team can only contain agents from this account. ::: ## Key facts | Fact | Meaning | | --- | --- | | A team is a group of agents | Human agents and AI Agents can both be members. | | Account-wide | Not personal. Everyone works from the same team list. | | A conversation has one team | The **Assigned team** field holds one team, or none. | | A team is not a permission | Team membership does not grant or restrict access to anything. It only affects conversation routing. | | A team is not a department | The **Department** field on an agent's profile is a free-text label for display and search. It does not create a team. | | Optional auto-assignment | A team can hand a conversation straight to a random **online** member. | | It controls "Get next" | An agent can only pull a waiting conversation that has **no team**, or a team **they belong to**. | | Studio can route to a team | The **Change Conversation** action can hand over to a team, and the **Conversation Changed** trigger can fire on team assignment. | | Reportable | Analytics has a **Teams** data source, and Conversations can be grouped by **Assigned Team**. | | Managed by permission | Seeing teams needs **Teams → Read**; creating, editing and deleting need **Teams → Create / Update / Delete**. See [Roles and Permissions](./roles/overview.md). | ## Who can do what | Action | Permission it needs | | --- | --- | | See the Teams page and the team list | **Teams → Read** | | Create a team | **Teams → Create** | | Edit a team | **Teams → Update** | | Delete a team | **Teams → Delete** | | Assign a conversation to a team | **Can assign conversations** on that inbox | | Filter conversations by team | None — filters only narrow what you can already see | | Route to a team from Studio | **Studio → Update** | Everything that changes a team is enforced on the server. A role without the permission does not see the **Add team** button, and the API rejects the change even if the button is reached another way. The default roles give full team management to **Owner** and **Team Leader**, and read-only visibility to **Marketing**, **Agent** and **Viewer**. --- ## The Teams page ![Teams page with the team list and rule badges](pathname:///img/screenshots/product/teams/teams-overview.png) | Element | What it does | | --- | --- | | **Add team** | Opens the team form. Needs **Teams → Create**. | | **Teams** (stat) | How many teams exist in the account. | | **Team memberships** (stat) | The total number of agent-to-team links. An agent in three teams counts three times, so this is usually higher than your agent count. | | **Auto-assigning teams** (stat) | How many teams have the auto-assign rule switched on. | | Search | Filters the list by **team name or description**. | | Team list | One row per team, with its members and rules. | ### Understand the list | Column | Meaning | | --- | --- | | **Team** | The team name, with a coloured initials badge, and the team's ID underneath (`#3`). The ID is what Studio and the API use. | | **Description** | Your own description, or `—`. Hover to read a long one in full. | | **Agents** | How many agents are in the team. | | **Members** | Up to five member initials circles, then `+N`. AI Agents show a 🤖 icon. Hover one for the name. | | **Rules** | Two badges showing whether each rule is on (`✓`, green) or off (`✕`, grey). | | **Actions** | ✏️ Edit and 🗑️ Delete, shown when your role grants **Teams → Update** and **Teams → Delete**. | --- ## Create a team 1. Open **Admin → Agents, Teams & Roles → Teams**. 2. Click **Add team**. 3. Type a **Team name**. This is what agents pick in the conversation, so make it obvious: *Sales*, not *Group 2*. 4. Optionally write a **Description** — what this team handles. 5. Tick the agents who belong to the team. 6. Set the two **Rules** (see below). 7. Click **Create team**. ![Create team form with the agent picker and the two rule switches](pathname:///img/screenshots/product/teams/create-team.png) ### Field reference | Field | Required | Limit | What it controls | | --- | --- | --- | --- | | **Team name** | Yes | 100 characters | The name shown everywhere a team is chosen. Must be unique in the account — Teloring compares names case-insensitively, so `Sales` and `sales` collide. | | **Description** | No | 500 characters | Free text, shown in the list and as a tooltip on the team picker in a conversation. | | **Agents in this team** | No | 500 agents | The members. A team with no members is allowed but cannot auto-assign and nobody can pull its conversations — see [Limitations](#limitations-and-what-to-watch-for). | | **Auto-assign to an online agent from this team** | No | — | See [Rule 1](#rule-1--auto-assign-to-an-online-agent). | | **Only real agents (no AI agents)** | No | — | See [Rule 2](#rule-2--only-real-agents). | An account can hold up to **200 teams**. ### The agent picker - Type in the search box to filter by **name or email**. - Agents you have already ticked float to the top, so a long roster stays manageable. - Each row shows whether the agent is **Human** or **AI**. - Only **active** agents appear. Deactivated agents are silently dropped when you save. - The counter above the list shows how many are selected. An agent can belong to **many teams** at once. Somebody in both *Sales* and *Support* can pull waiting conversations from either. --- ## The two rules ### Rule 1 — Auto-assign to an online agent > *When the team is selected, auto-assign to an online agent from this team.* **Off (default).** Assigning the team leaves the conversation with no owner. It sits in **Waiting in line** until a member of that team picks it up. **On.** The moment the team is assigned, Teloring picks one **online** member at random and assigns the conversation to them. It goes straight into that person's **Mine** queue. | Situation | What happens | | --- | --- | | Several members online | One is chosen **at random**. | | One member online | That member gets it. | | No member online | Nobody is assigned. The conversation waits in line for the team. | | The team has an AI Agent member and the rule is on | The AI Agent can be chosen, because AI Agents are always online. | **Why random, not round-robin?** Teloring runs across many servers at once. Random selection needs no shared counter between them, so it spreads work evenly without one server having to wait for another. Over a working day the distribution evens out. :::info "Online" means signed in right now An agent counts as online while they have Teloring open — exactly the green dot in Team Chat. It is not a status they set manually. Close the browser tab and they stop being online. **AI Agents are always online.** They are software, so they never go offline and can be auto-assigned at any hour, including nights and weekends. Use [Rule 2](#rule-2--only-real-agents) if you do not want that. ::: ### Rule 2 — Only real agents > *When the team is selected, only include real agents and not AI agents.* **Off (default).** AI Agents can be members and can be auto-assigned. **On.** This team is humans-only: - AI Agents disappear from the agent picker. - Any AI Agent already in the team is **removed when you save** — the rule is enforced, not just displayed. - Auto-assignment will never choose an AI Agent from this team. Use it for teams that must reach a person: complaints, escalations, VIP accounts, anything with a legal or contractual review. --- ## Assign a conversation to a team There are three ways. ### From the conversation header 1. Open the conversation. 2. Open the **Assigned team** picker (the two-people icon, next to **Assigned to**). 3. Choose a team, or **No team**. ![Assigned team picker in the conversation header](pathname:///img/screenshots/product/teams/conversation-team-picker.png) A `⚡` next to a team name means that team auto-assigns to an online member, so you know before you click whether somebody will receive it immediately. Teloring then tells you what happened: | Message | Meaning | | --- | --- | | *Assigned to Dana from Sales* | The team auto-assigned an online member. | | *Waiting in line for Sales* | The team owns it, but nobody was assigned. A Sales member must pick it up. | :::note The picker is hidden when you have no teams If the account has no teams yet, the **Assigned team** control does not appear at all. Create your first team and reload the conversation. ::: ### From the conversation list Right-click any conversation card → **Assign team** → pick a team or **No team**. Handy for sorting a backlog quickly. ### From Studio Use the **Change Conversation** action with **Human intervention** on and **Hand over to → A team**. See [Studio actions](./studio/actions.md). ### What assignment changes Assigning a team always does three things: 1. Sets the conversation's **Assigned team**. 2. **Releases Studio.** If a Studio flow owned the conversation, it stops owning it. A conversation is handled by Studio *or* by people — never both. 3. Either assigns an online member (Rule 1 on, somebody online) or leaves it waiting for the team. Conversation cards show a `👥 team name` chip so you can see the owner while scanning the list. --- ## How teams change who gets what This is the part worth reading carefully, because it changes how work is distributed. ### "Get next conversation" When an agent clicks **Get next** in the conversation list, Teloring offers only conversations they are allowed to take: | The waiting conversation has… | Can this agent take it? | | --- | --- | | **No team** | Yes — anyone can. | | **A team they belong to** | Yes. | | **A team they do not belong to** | **No.** It is left for that team. | So an agent in *Support* can pull untagged conversations **and** *Support* conversations, but never a *Sales* one. An agent in **no team** can only pull conversations that have no team. Among whatever they are allowed to take, the existing fairness rules are unchanged: 1. **Priority first** — Urgent, then High, then Medium, then Low. 2. **Then oldest first** (FIFO), so a waiting customer is not overtaken by a newer one at the same priority. **Example.** Two conversations are waiting, both on *Support*. One arrived an hour ago at Medium. One arrived twenty minutes ago at High. A Support agent clicking **Get next** receives the **twenty-minute-old High** one, because priority beats age. If everything waiting belongs to other teams, **Get next** says *No conversations waiting in line for your teams* instead of giving them somebody else's work. ### Queue tabs are not filtered by team **Waiting in line** still shows and counts **every** waiting conversation, including other teams'. That is deliberate: teams control *fair distribution*, not visibility. Anyone can still see the whole queue, open another team's conversation, and take it manually if they need to — a supervisor covering a gap, for example. Only **Get next** respects team boundaries. To see just your team's queue, use the **Assigned team** filter described below. ### "Mine" never changes **Mine** always means *assigned to me as an agent*. A conversation that belongs to your team but has no owner stays in **Waiting in line** — it does not appear in anyone's **Mine** until somebody actually takes it. --- ## Teams and the agent field together A conversation can hold a team **and** an agent. Teloring keeps the two consistent, so you never end up with *Sales* owned by somebody outside Sales. | What you do | What Teloring does | | --- | --- | | Assign a team, nobody owns it yet | Auto-assigns an online member (Rule 1 on) or leaves it waiting. | | Assign an agent who **is** in the team | Both are kept. | | Assign an agent who is **not** in the team | The **team is cleared**. You will see *Team Sales was removed — the new agent is not a member*. | | Move an owned conversation to a team the owner is not in | The **agent is cleared** and it waits in line for the new team. | | **Send back in line** | The **team is kept**. It means "somebody else on this team should take this", so the team keeps first refusal. | | Delete the team | Every conversation still on it goes back to the general waiting line. | :::tip Why the team is cleared If a conversation could sit on *Sales* while a Support agent owned it, nobody could tell who was responsible, and Sales would never see it in **Get next** again. Clearing one of the two keeps the answer to "whose is this?" unambiguous. ::: --- ## Filter conversations by team The conversation filter panel now has two new sections. ![Conversation filter panel with the assigned agent and assigned team sections](pathname:///img/screenshots/product/teams/conversation-filters.png) | Filter | What it offers | | --- | --- | | **Assigned agent** | Every agent, plus an explicit **Unassigned** chip. Has its own search box for long rosters. | | **Assigned team** | Every team, plus an explicit **No team** chip. | Both are multi-select and combine with the other filters. Selecting two teams shows conversations in **either**. Useful combinations: - **Assigned team = Sales** + **Assigned agent = Unassigned** → the Sales queue nobody has taken. - **Assigned team = No team** → conversations nobody has routed yet. - **Assigned team = Sales** + the **Resolved** tab → what Sales closed. --- ## Teams in Studio ### Route to a team In the **Change Conversation** action, switch on **Human intervention** and set **Hand over to** → **A team**, then choose the team. The flow then behaves exactly like a manual team assignment: Studio releases the conversation, and the team either auto-assigns an online member or holds it in the waiting line for its members. These flow variables become available: | Variable | Contains | | --- | --- | | `conversation.handover_team_id` | The team ID the flow handed over to. | | `conversation.handover_team_name` | The team's name. | | `conversation.handover_agent_id` | The member who was auto-assigned, or empty if it waits in line. | :::warning Pick the team in the block If **Hand over to** is set to **A team** but no team is chosen, the handover falls back to the plain waiting line. The flow editor flags the block with a warning while you are editing, so fix it before publishing. If the chosen team is later **deleted**, the block **fails** rather than parking the conversation on a team that no longer exists. Check your flows after deleting a team. ::: ### Trigger on team assignment The **Conversation Changed** trigger has a **Team Assignment** filter: | Setting | Fires when | | --- | --- | | **Any team** (default) | Any change. The team is ignored. | | **Team assigned (any)** | The conversation now has a team. | | **Team removed** | The conversation no longer has a team. | | **Specific team assigned** | The conversation's team is one you selected. | Flows built before Teams existed keep working unchanged — they default to **Any team**. Team changes also set `change.type` to `team_assigned` or `team_unassigned`, separately from the agent-level `assigned` / `unassigned`, so a flow can react to "handed to Sales" without firing on every individual assignment. :::note Selecting no team with "Specific team assigned" **Specific team assigned** with nothing selected never fires. An empty selection means "no team matches" — it is not treated as "every team", so an unfinished trigger cannot fire on assignments you never asked for. ::: See [Studio triggers](./studio/triggers.md) and [Studio actions](./studio/actions.md). --- ## Teams in Analytics Two separate things, and picking the right one matters. ### Report on the work a team handled Use the **Conversations** data source and group by **Assigned Team**. That is where volume, resolution time, priority, and channel live. Examples: - Open conversations by team. - Average resolution time by team. - Conversations Sales resolved this month. - Count of distinct teams involved this week. Team IDs are shown as **team names** in charts, tables, and filter pickers. Conversations with no team group under `(none)`. ### Report on the teams themselves Use the **Teams** data source. It answers questions about your team setup, not about conversations: | Field | Use | | --- | --- | | **Team** | Count teams, or group by team. | | **Team Name** | Group or filter by name. | | **Agents in Team** | Average, sum, min, or max team size. | | **Auto-assign to Online Agent** | Split teams by whether the rule is on. | | **Human Agents Only** | Split teams by whether the rule is on. | | **Created By**, **Created At**, **Updated At** | Who set a team up and when. | See [Analytics](./analytics.md). --- ## Edit or delete a team ### Edit Click ✏️ on the row. You can change the name, description, members, and both rules. Editing a team takes effect **immediately** for future routing: - Adding a member lets them pull that team's waiting conversations right away. - Removing a member stops them pulling new ones, but **does not** take away conversations they already own. - Switching **Only real agents** on removes AI members when you save. ### Delete Click 🗑️ and confirm. Deleting a team: - removes the team; - **clears the team from every conversation that still has it**, so those conversations return to the general waiting line and anyone can pick them up; - reports how many conversations were detached. It does **not** delete agents, conversations, or messages. :::warning Check Studio before deleting A **Change Conversation** block that hands over to a deleted team will **fail** at runtime, and a **Conversation Changed** trigger filtered on it will stop matching. Search your live flows for the team before you delete it. ::: --- ## Recommended setups **By topic — the common case** 1. Create *Sales*, *Support*, and *Billing*. 2. Put each person in the team or teams that match their job. 3. Leave **Auto-assign** off at first, so people pull work with **Get next** at their own pace. 4. Route incoming conversations to a team, manually or from Studio. 5. Turn **Auto-assign** on later for the team that needs the fastest first response. **Fast first response** 1. Create *Front line* with everyone who answers first. 2. Turn **Auto-assign to an online agent** on. 3. Route new conversations there from Studio. 4. Whoever is online gets it immediately; when nobody is online it waits for the team. **Escalation that must reach a person** 1. Create *Escalations* with your senior agents. 2. Turn **Only real agents** on. 3. Leave **Auto-assign** off, so a human deliberately accepts the escalation. 4. In Studio, route the *angry or frustrated* and *asked for agent* escalation reasons to this team. **AI first, humans second** 1. Create *AI front line* containing only your AI Agent, with **Auto-assign** on. 2. Create *Human backup* with your people. 3. Route new conversations to *AI front line* — the AI is always online, so it always answers. 4. In the AI Agent profile, send failure and escalation outcomes to a human. --- ## Limitations and what to watch for These are real product limits today, not mistakes on your side. | Item | What actually happens | Do this instead | | --- | --- | --- | | **Queue badge counts** | **Waiting in line** counts every waiting conversation, including other teams'. The number can be higher than what **Get next** will actually give you. | Use the **Assigned team** filter to see your own team's queue. | | **No team queue tab** | There is no sidebar tab for "my team's conversations". A team conversation with no owner sits in **Waiting in line**. | Filter by **Assigned team**, or pin the filter combination you use. | | **One team per conversation** | A conversation cannot belong to two teams at once. Choosing a second team replaces the first. | Use a single team plus labels for anything cross-cutting. | | **No team-level working hours** | A team has no schedule of its own. | Use Studio's **Business Hours** condition before routing to a team, or working hours in an AI Agent profile. | | **No team priority or skill weighting** | Auto-assign is purely random among online members. There is no "give it to the least busy" or "prefer the specialist". | Keep teams small and focused, or assign manually where it matters. | | **An empty team** | You can save a team with no members. Assigning it means nobody can auto-receive it, and nobody can pull it with **Get next**. It sits in the queue until somebody opens it manually or you fix the team. | Always add at least one member. | | **Team membership is not permission** | Being in a team does not restrict what an agent can see or open. | Use [channel permissions](./roles/channel-permissions.md) for visibility. Teams control routing only. | | **Created by / updated by** | Recorded on the team for the audit log, but not shown on the Teams page. | Check **Admin → Audit Log** for `team.created`, `team.updated`, and `team.deleted`. | --- ## Troubleshooting ### "Get next" says nothing is waiting, but the queue shows conversations Everything waiting belongs to teams you are not in. The message *No conversations waiting in line for your teams* confirms it. Ask an admin to add you to the team, or open the conversation from the list and assign it to yourself manually. ### I assigned a team and nobody received it Expected when either the team's **Auto-assign** rule is off, or no member was online. Check: 1. Open the team and confirm **Auto-assign to an online agent** is on. 2. Confirm at least one member is online — the green dot in Team Chat. 3. If the team is **humans-only** and its only member is an AI Agent, nobody is eligible. ### The team disappeared when I assigned an agent That agent is not a member of the team. Teloring cleared the team so the conversation has one clear owner. Either add that agent to the team, or pick an agent who is already in it. ### The agent disappeared when I assigned a team The previous owner is not a member of the new team, so the conversation went back to the waiting line for the new team. Assign a member of the new team if it needs an owner immediately. ### An AI Agent keeps getting auto-assigned at night AI Agents are always online, so they are always eligible. Turn **Only real agents** on for that team, or remove the AI Agent from it. ### I cannot create a team Your role does not grant **Teams → Create**, so the **Add team** button is hidden. Ask somebody with **Roles & permissions → Update** to add it — see [Roles and Permissions](./roles/overview.md). ### "A team with this name already exists" Names are unique per account and compared case-insensitively — `Sales` and `sales` collide. Pick a different name, or edit the existing team. ### A Studio flow stopped routing If the flow handed over to a team that was deleted, the block now fails. Open the flow, pick a current team, and publish again. --- ## Related guides - [Agents and AI Agents](./agents.md) — create the people and AI profiles that become team members. - [Conversations](../getting-started/conversations.md) — assignment, queues, **Get next**, and filters. - [Studio actions](./studio/actions.md) — the **Change Conversation** team handover. - [Studio triggers](./studio/triggers.md) — the **Conversation Changed** team filter. - [Analytics](./analytics.md) — the **Teams** data source and the **Assigned Team** grouping. - [Roles and Permissions](./roles/overview.md) — access control, which teams deliberately do *not* provide. --- # Notifications Source: https://docs.teloring.com/docs/product/notifications Markdown: https://docs.teloring.com/markdown/docs/product/notifications.md Section: Product Guides Last modified: 2026-08-20T20:49:57.000Z Notifications tell you when something you care about happens in Teloring — a conversation lands on your name, a customer replies, or an automation you built decides you need to know. Two questions decide everything: - **WHAT** do you want to be told about? - **HOW** should Teloring tell you? You answer both in your own profile, and the two combine: every delivery method you switch on applies to every notification type you switch on. Open **your name at the bottom-left of the sidebar → My Profile → Notifications**, or go straight to `/dashboard/profile#notifications`. :::info Everything starts switched off A brand-new agent receives no notifications at all. Nothing is sent until you turn it on yourself. This is deliberate — Teloring never decides on your behalf that something is worth interrupting you for. ::: ## Key facts | Fact | Meaning | | --- | --- | | Personal, not account-wide | Your settings are yours alone. Turning email alerts on does not turn them on for a colleague, and an admin cannot set them for you. | | Opt-in | Every switch defaults to off. | | Four delivery methods | Sound, Email, Browser push, Notification bell. | | Three notification types | Conversation assigned to me, New message, Studio notifications. | | One master switch | Turn everything off in one click without losing your choices. | | Studio covers everything else | The two built-in types are shortcuts. Anything else you can imagine is built with a Studio block. | | Works across all inboxes | WhatsApp, Email, SMS, Telegram, LINE, Live Chat, Messenger, Facebook, Instagram, TikTok, Voice, and the API. | | Account isolated | Notifications never cross between Teloring accounts. | ## Who can do what | Action | Who can | | --- | --- | | Change **my own** notification settings | Everyone. No permission needed. | | Change **someone else's** notification settings | **Nobody.** There is no such screen and no such API call. | | Read **someone else's** notification bell | **Nobody.** | | Build a Studio flow that notifies other agents | Anyone with **Studio → Create** — see [Roles and Permissions](./roles/overview.md). | Your identity comes from your signed-in session, never from the page. There is no screen — and no API call — that lets one agent read or change another agent's notifications. --- ## The settings screen ![The Notifications panel on the profile page, showing the master switch, the four delivery methods, and the three notification types](pathname:///img/screenshots/product/notifications/notifications-settings.png) The panel sits on the right-hand side of **My Profile**, next to your photo and display name. It has three parts: | Part | Purpose | | --- | --- | | **Enable notifications** | The master switch at the top. | | **How do you want to get them?** | The four delivery methods. | | **What do you want to be notified about?** | The three notification types. | Changes are **not** live until you press **Save**. The confirmation appears next to the button. ### The master switch **Enable notifications** is an on/off switch for the whole feature. - **Off** — you receive nothing, whatever else is selected. The rest of the panel greys out. - **On** — your selected methods and types take effect. Switching it off keeps your choices. Switch it back on and everything is exactly as you left it — useful for a focused afternoon, a holiday, or a noisy launch day. :::tip Turning the master switch off also removes this browser's push registration, so a backgrounded tab stops buzzing too — not just the in-app parts. ::: --- ## HOW — the four delivery methods Pick one or more. They are not exclusive; most agents run the bell plus one attention-getter. ![The four delivery methods — Sound, Email, Browser push, Notification bell — each with its own switch](pathname:///img/screenshots/product/notifications/notifications-how.png) | Method | You get | Best for | | --- | --- | --- | | **Sound** | A short sound in the browser. No text. | Knowing *something* happened while you work in another tab. | | **Email** | A message to your sign-in address. | A record you can search, forward, or read on your phone. | | **Browser push** | A desktop notification, even when Teloring is not the active tab. | Not missing anything while you work in other apps. | | **Notification bell** | An entry in the bell menu, with an unread count. | Catching up on what you missed. | ### Sound Plays a short audio cue in your browser. Nothing is displayed — this is purely "look up, something happened". Choose from ten sounds and press **Play** to hear one before committing. Selecting a sound from the dropdown also plays it immediately. | Sound | Character | Length | | --- | --- | --- | | **Chime** *(default)* | Three-note glassy arpeggio. Warm and unobtrusive. | 1.5s | | **Bell** | A struck bell with a long tail. | 2.2s | | **Ding** | The classic bright "you have a message". | 1.1s | | **Ping** | Very short, high blip. The least intrusive option. | 0.5s | | **Pop** | Soft percussive pop. | 0.4s | | **Marimba** | Woody two-note. Carries well in a busy room. | 1.4s | | **Alert** | Two-tone descending. Reads as "attention needed". | 1.3s | | **Bubble** | Rising water-drop blip. Light and playful. | 0.6s | | **Knock** | Soft double knock. Low and quiet — good for open offices. | 0.5s | | **Digital** | Retro three-step blip. Cuts through noise without being harsh. | 0.6s | :::note Why the first sound sometimes does not play Browsers block audio until you have clicked somewhere on the page. If you load Teloring and leave it untouched, the first sound may be silent. Any click anywhere unlocks it for the rest of the session. ::: ### Email Sends the notification to your sign-in address from **do-not-reply@teloring.com**. ![An example Teloring notification email](pathname:///img/screenshots/product/notifications/notifications-email.png) | Element | What it contains | | --- | --- | | **Subject** | The conversation ID in brackets, then what happened — `[#4821] New message in your conversation`. | | **Heading** | The notification type in words. | | **Message box** | The notification text, plus any extra detail. | | **Conversation** | The conversation ID again, as a searchable line. | | **Button** | Opens the conversation (or page) the notification points at. | | **Footer** | A reminder of where to switch these emails off. | Three things worth knowing: - **The email is written in *your* profile language**, not the language of whoever triggered it. Set it under **Admin → Agents**. - **The conversation ID appears in the subject** for every type that belongs to a conversation. Search your mailbox for `#4821` to pull up every alert about that one conversation, and most mail clients will thread them together. - **New-message emails are rate-limited to one per conversation every 10 minutes.** See [Email flood protection](#email-flood-protection). ### Browser push A desktop notification from your operating system, shown even when Teloring is in a background tab or another window is in front. Supported in **Chrome**, **Edge**, **Firefox**, and **Safari 16.4 and later**. ![A Teloring browser push notification on the desktop](pathname:///img/screenshots/product/notifications/notifications-push.png) Turning it on takes two steps, because your browser must agree as well as Teloring: 1. Press **Enable in this browser**. Your browser asks for permission — choose **Allow**. 2. Switch the **Browser push** toggle on and press **Save**. The status chip next to the button tells you where you stand: | Chip | Meaning | What to do | | --- | --- | --- | | **Not enabled in this browser** | This browser has not registered yet. | Press **Enable in this browser**. | | **Enabled in this browser** | Registered and ready. | Nothing. **Send a test push** appears next to it. | | **Blocked by the browser** | You (or someone) chose *Block* at the permission prompt. | Allow notifications for this site in your browser settings, then reload the page. Teloring cannot re-ask once you have blocked it. | | **This browser does not support push notifications** | Older browser, or a private/incognito window. | Use a supported browser in a normal window. | | **Browser push is not configured on this server** | The platform has no push keys installed. | Contact your Teloring administrator. | :::caution Push is registered per browser, per device Enabling it on your office laptop does **not** enable it on your home machine or on a different browser. Repeat the **Enable in this browser** step everywhere you work. Teloring remembers up to **10** browsers per agent; beyond that the oldest is dropped. ::: #### If a test push says it was sent but nothing appears Teloring can hand the notification to your browser, but it cannot force your operating system to display it. When the confirmation says the push was sent and you still see nothing, the block is outside Teloring: | Check | Where | | --- | --- | | Notifications allowed for your browser | **macOS:** System Settings → Notifications → *your browser*
**Windows:** Settings → System → Notifications | | Do Not Disturb / Focus is off | macOS Control Centre, or the Windows notification panel | | Notifications allowed for the site | Browser settings → Site settings → Notifications → `console.teloring.com` | ### Notification bell Adds the notification to the bell in the top bar, with a count of what you have not seen. This is the only method that keeps a history — see [The notification bell](#the-notification-bell) below. --- ## WHAT — the three notification types ![The three notification types with their switches](pathname:///img/screenshots/product/notifications/notifications-what.png) | Type | Fires when | | --- | --- | | **A conversation is assigned to me** | A conversation's assigned agent becomes you. | | **New message in a conversation I'm assigned to** | A customer sends a message into a conversation you already own. | | **Studio notifications** | A Studio flow sends you one deliberately. | ### A conversation is assigned to me Fires whenever a conversation lands on your name — **no matter who or what put it there**: - a colleague assigning it to you by hand; - a bulk action on the conversation list; - a **team** auto-assigning to an online member; - a **Studio** flow handing over to you; - an **AI Agent** handing the conversation to a human. **It does not fire when you assign a conversation to yourself.** You are already looking at it; a notification for your own click is noise. The notification tells you the customer's name, which channel it came in on, and who assigned it. Clicking it opens the conversation. ### New message in a conversation I'm assigned to Fires when a **customer** sends a message into a conversation whose assigned agent is you. Works on every inbox type: WhatsApp, Email, SMS, Telegram, LINE, Live Chat, Messenger, Facebook, Instagram, TikTok, and the API. It deliberately does **not** fire when: | Situation | Why not | | --- | --- | | The conversation is unassigned | Nobody owns it yet — there is no "me" to notify. Use a Studio flow if you want to be told about the waiting line. | | The conversation belongs to a colleague | You are not the assignee. | | The conversation is handled by an **AI Agent** | An AI Agent occupies the assignee slot but has no inbox to notify. | | An agent sends a message | These alerts are about what *customers* do. | The notification includes the start of the customer's message, so you can judge urgency without opening it. :::tip Busy inboxes On a high-volume inbox this type can fire often. Many agents run it on **sound + bell** only and leave email off. Email has its own [flood protection](#email-flood-protection) for exactly this reason. ::: ### Studio notifications Fires when a Studio flow runs the **Send Teloring Notification** action and names you as a recipient. This one switch covers *everything* the first two do not. Because the message text and the trigger are yours to design, there is no limit to what it can tell you: - a contact was created with status *Lead*; - an analytics threshold was crossed; - a conversation has been waiting too long; - a form was submitted; - a customer replied outside business hours; - an external system called your webhook. See [Build your own notifications with Studio](#build-your-own-notifications-with-studio). :::note Advanced setups The first two types exist so you get something useful without touching Studio. Once you are comfortable in Studio, it is common to switch both of them **off** and drive everything from flows instead — that way you control the exact wording, timing, and audience. ::: --- ## How WHAT and HOW combine The two lists multiply. Every method you switch on applies to every type you switch on. **A worked example.** You switch on all four methods, and only the **Studio notifications** type. In Studio you build *"for every new contact created"* → **Send Teloring Notification** with the text `New contact {{contact.name}} created!` A contact called Yossi Levi is created. You get all four at once: | Method | What happens | | --- | --- | | **Sound** | Your chosen sound plays. There is no text — a sound is just a cue. | | **Email** | An email arrives with *New contact Yossi Levi created!* | | **Browser push** | A desktop notification shows the same line. | | **Bell** | The bell badge increases by one; the entry reads *New contact Yossi Levi created!* | Had you enabled only the bell, only the bell entry would appear. The flow decides *what* to say and *who* to tell — **each recipient's own profile decides how it reaches them**. --- ## The notification bell The bell lives in the top bar, to the left of **Sign Out**, on every page. ![The notification bell with an unread badge](pathname:///img/screenshots/product/notifications/notification-bell.png) ### The badge The number on the bell is how many notifications have arrived **since you last opened the list**. It updates live — you do not need to refresh. When something arrives the bell gives a short shake. ### Opening the list ![The notification bell menu, with unread entries highlighted](pathname:///img/screenshots/product/notifications/notification-bell-open.png) | Element | What it does | | --- | --- | | **Notifications** | The panel title. | | **Settings** | Jumps to the Notifications section of your profile. | | The list | Your most recent **100** notifications, newest first. | | An entry | Icon by type, the notification text, any extra detail, and how long ago it arrived. | | Highlighted entries | Everything that was new at the moment you opened the list. | **Opening the list marks everything as read.** That is intentional, and it is worth understanding: 1. The badge shows `10`. 2. You open the list. You see the last 100 notifications, and those 10 are highlighted in bold so you can tell what is new. 3. The badge clears immediately. 4. Change page or refresh, and the bell has no badge — but opening it still shows the same 100 entries, now all plain. Nothing is deleted by reading it. The history stays; only the "new" marker is cleared. This keeps the bell from becoming a chore that has to be managed. ### Clicking an entry An entry that points somewhere is a link — usually to the conversation involved. Entries without a target (a Studio notification set to *Nothing — text only*) are plain text. Notification links always stay inside Teloring. A flow cannot make a notification link to an external site. --- ## Send yourself a test Two buttons let you check your setup without waiting for a real event. | Button | Where | What it does | | --- | --- | --- | | **Send a test push** | Next to the Browser push status chip | Sends a push to this browser only. Appears once this browser is registered. | | **Send myself a test** | Next to **Save** | Sends a full notification through your **current saved settings** — every method you have enabled. | **Save first.** Both buttons test what is saved on the server, not what is currently on screen. If you flip a switch and test without saving, you are testing the old settings. **Send myself a test** needs at least one delivery method and at least one type switched on, otherwise there is nothing to send. --- ## Build your own notifications with Studio The **Send Teloring Notification** action is a THEN block in the **Tools** group of the Studio block picker. ![The Send Teloring Notification block in the Studio properties panel](pathname:///img/screenshots/product/studio/action-notify-agents.png) In short: | Property | What it does | | --- | --- | | **Send to** | Specific agents · the agent assigned to this conversation · everyone in a team. | | **Message** | The text agents see. Supports every `{{variable}}` from earlier blocks. | | **Extra details** | An optional second line. | | **Clicking the notification opens** | The conversation · nothing · a specific Teloring page. | Full reference, outputs, and behaviour: **[Studio → Actions → Send Teloring Notification](./studio/actions.md#send-teloring-notification)**. :::info Recipients still control delivery A flow can decide *who* gets notified and *what* it says. It can never decide *how loudly*. An agent who has notifications switched off, or who has **Studio notifications** switched off, receives nothing from any flow. ::: --- ## Limits and behaviour | Behaviour | Value | | --- | --- | | Notifications kept in the bell list | The most recent **100** | | Notification history retained | **30 days**, then deleted automatically | | New-message emails per conversation | At most **1 every 10 minutes** | | Assignment and Studio emails | Not rate-limited | | Browsers registered for push per agent | Up to **10**; the oldest is dropped after that | | Duplicate protection | The same event cannot notify you twice within 60 seconds | | Notification text length | Message up to 160 characters, details up to 600 | ### Email flood protection A busy agent can receive hundreds of customer messages a day. One email each would bury your inbox, so Teloring sends at most **one new-message email per conversation every 10 minutes**. - It applies **only** to the *New message* type. Assignment and Studio notifications are never held back — they are low-volume and under your control. - It is **per conversation**. Messages in three different conversations still produce three emails. - **Nothing else is affected.** The sound, the push, and the bell entry all still fire for every message. Only the email is skipped. The active window is shown on the settings screen so a missing email never looks like a fault. --- ## Privacy and isolation | Guarantee | How | | --- | --- | | Notifications are private to you | Each notification is delivered on your own private channel and stored under your own agent record. | | Settings are private to you | Only your signed-in session can read or change them. | | No cross-account leakage | An agent in one Teloring account can never receive, or read, a notification belonging to another account. | | Links stay inside Teloring | Notification targets are restricted to Teloring pages. An external or script link is rejected. | | Text is always escaped | Notification text is displayed as text everywhere, including in email. | | Deactivated agents stop receiving | Disabling an agent stops their notifications immediately. | --- ## Troubleshooting | Symptom | Likely cause | Fix | | --- | --- | --- | | Nothing arrives at all | The master switch is off, or you have no type selected. | Check **Enable notifications**, then at least one method **and** one type. | | I saved but nothing changed | The change was not saved. | Press **Save** and wait for the confirmation next to the button. | | No sound, but the bell works | The browser has not been interacted with yet, or the tab is muted. | Click anywhere on the page. Check the tab is not muted (right-click the tab). | | No push, everything else works | This browser is not registered, or the OS is blocking it. | Check the status chip. If it says *Enabled*, see [If a test push says it was sent](#if-a-test-push-says-it-was-sent-but-nothing-appears). | | Push worked, then stopped | The browser dropped the registration — this happens after clearing site data. | Press **Enable in this browser** again. | | Push works on one machine, not another | Push is per browser, per device. | Run **Enable in this browser** on the other machine. | | No email for new messages, but the bell fires | The 10-minute-per-conversation limit. | Expected. See [Email flood protection](#email-flood-protection). | | No email at all | Your profile email is wrong, or the mail is filtered. | Check your address under **My Profile**, then your spam folder for `do-not-reply@teloring.com`. | | Badge does not clear | The list was never opened, or the page is stale. | Open the bell. | | Not notified about a new message | The conversation is not assigned to you. | Only the assignee is notified. Use a Studio flow to be told about unassigned conversations. | | Not notified when I took a conversation myself | By design. | Self-assignment never notifies. | | A Studio flow notified nobody | No recipient resolved, or the recipients have the type off. | Check the block's `notification.recipients` and `notification.delivered` outputs. | --- ## Related - [Studio → Actions → Send Teloring Notification](./studio/actions.md#send-teloring-notification) — build your own notification triggers - [Conversations](../getting-started/conversations.md) — assignment and the waiting line - [Teams](./teams.md) — team routing, which drives assignment notifications - [Agents](./agents.md) — profile language, which sets your email language - [Analytics](./analytics.md) — threshold alerts you can wire into a notification flow --- # Teloring API Source: https://docs.teloring.com/api/ Markdown: https://docs.teloring.com/markdown/api/index.md Section: API Reference Last modified: 2026-08-20T20:49:57.000Z Everything an agent can do in the console, your systems can do over HTTPS: conversations across every channel, the CRM behind them, the automations, the knowledge bases, the numbers — and, when you need it, a way to drop one of your own users straight into a specific chat. ``` https://api.teloring.com/v1 ``` ## Five minutes to your first call **1. Create a credential.** In the console, go to **Settings → API** and press **New credential**. Give it a name, choose an expiry (or leave it unlimited), and tick the scopes it needs. Each scope unlocks a whole feature area — grant only what you will use. **2. Copy the client secret.** It is shown once, at creation, and never again. If you lose it, revoke the credential and create another; the client id stays visible forever, so you can always tell which credential is which. **3. Get a token.** ```bash curl -X POST https://api.teloring.com/v1/oauth/token \ -H "Content-Type: application/json" \ -d '{ "client_id": "tlc_811fc5491673d78d047a1085da2e22b7", "client_secret": "tls_9f3c8a21b6d54e7f90a1c2b3d4e5f60718293a4b5c6d7e8f" }' ``` ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "token_type": "Bearer", "expires_in": 3600, "expires_at": "2026-08-20T11:24:31+00:00", "scopes": ["conversations", "messages", "customers"], "account_id": "42" } ``` **4. Call something.** ```bash curl https://api.teloring.com/v1/conversations?status=open \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` **5. Send a message.** ```bash curl -X POST https://api.teloring.com/v1/conversations/387/messages \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"type": "text", "content": "Thanks — we are on it."}' ``` That is the whole shape of the API. Everything else is more endpoints. ## The things worth knowing up front **There is no account id in any path.** Your token already identifies the account. That is not a convenience — it is what makes reaching another business's data unrepresentable rather than merely forbidden. **Scopes are checked on every request, against live data.** Remove a scope in the console and the very next call fails, without waiting for the token to expire. **This is a server-side API.** No CORS headers are sent, deliberately: a token in browser JavaScript is a token in your page source. Call it from your backend. **Some calls cost money.** Creating an agent takes a seat and may charge the card on file; WhatsApp templates, outbound SMS and signing links cost credits. Every such endpoint says so, in bold, at the top of its description. **Everything you write is audited.** Each mutation is recorded with the credential that made it, so "what changed this?" always has an answer. See [Audit log](/api/list-audit-log). **IP restrictions apply.** If the account limits access by IP under Settings → Security & login, that limit covers the API too — see [IP restrictions](./guide-authentication#ip-restrictions). ## Where to go next | | | | --- | --- | | [Authentication](./guide-authentication) | Tokens, rotation, and what each failure means | | [Scopes](./guide-scopes) | What every scope unlocks, and how to choose | | [Pagination, filtering & errors](./guide-conventions) | The conventions every endpoint follows | | [SSO login](./guide-sso) | Signing your users into the console, standalone or in an iframe | | [Postman collection](./guide-postman) | Import all 115 endpoints and start clicking | Then browse the endpoint reference in the sidebar — every operation has its parameters, request body, response schema and a runnable example. --- # Teloring API Source: https://docs.teloring.com/api/teloring-api Markdown: https://docs.teloring.com/markdown/api/teloring-api.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import ApiLogo from "@theme/ApiLogo"; import Heading from "@theme/Heading"; import SchemaTabs from "@theme/SchemaTabs"; import TabItem from "@theme/TabItem"; import Export from "@theme/ApiExplorer/Export"; The Teloring REST API gives your own systems the same reach an agent has in the console: conversations across every channel, the CRM behind them, the automations, the knowledge bases, the numbers, and — when you need it — a way to drop one of your users straight into a specific chat. ## Base URL ``` https://api.teloring.com/v1 ``` Every path in this reference is relative to that. There is no account id in any path: your access token already identifies the account, which is what makes it impossible for a credential to reach somebody else's data. ## Getting started in four steps 1. In the console, go to **Settings → API** and create a credential. Choose its scopes — each one unlocks a whole feature area — and copy the **client secret**. It is shown once and never again. 2. Exchange the client id and secret for an access token: `POST /v1/oauth/token`. Tokens last one hour. 3. Send the token as `Authorization: Bearer ` on every request. 4. Call `GET /v1/oauth/introspect` if anything is unexpected — it tells you which account you are on and exactly which scopes you hold. ## What you should know before you build - **Server-side only.** There are no CORS headers on this API by design. A token in browser JavaScript is a token in your page source. - **Scopes are checked live.** Removing a scope in the console takes effect on the very next request, not when the token expires. - **Some calls cost money.** Creating an agent takes a seat and may charge the card on file. WhatsApp templates, outbound SMS and signing links cost credits. Each of those endpoints says so. - **Rate limit:** 600 requests per minute per credential; 20 per minute per IP on the token endpoint. Cache your token — you need one per hour, not one per request. - **IP restrictions apply here too.** If the account has an IP allow-list set under Settings → Security & login, it governs API calls exactly as it governs sign-in. Calling from an address that is not on it answers `403` with `code: ip_not_allowed` — add your server's outbound IP there. ## Errors Every failure answers in the same shape, with a machine-readable `code` and a `request_id` to quote if you need help: ```json { "error": { "type": "invalid_request_error", "code": "missing_parameter", "message": "'inbox_id' is required.", "param": "inbox_id", "request_id": "req_5f2a91c0e8b74d3a9c1e" } } ```
`Authorization: Bearer `, where the token came from `POST /v1/oauth/token`. Tokens last one hour. A `401` with `code: invalid_token` means fetch a new one.
Security Scheme Type: http
HTTP Authorization Scheme: bearer
Bearer format: JWT

Contact

Teloring support: URL: [https://docs.teloring.com](https://docs.teloring.com)
--- # Authentication Source: https://docs.teloring.com/api/guide-authentication Markdown: https://docs.teloring.com/markdown/api/guide-authentication.md Section: API Reference Last modified: 2026-08-20T20:49:57.000Z Teloring uses **OAuth 2.0 client credentials**. You hold a long-lived client id and secret; you exchange them for a short-lived access token; you send that token on every request. ``` client id + secret ──POST /v1/oauth/token──▶ access token (1 hour) │ Authorization: Bearer ────┘ ``` The split is the point. A leaked access token expires by itself within the hour. A leaked secret is revoked in one click, without you redeploying anything. ## Creating a credential **Settings → API → New credential.** You choose four things: | | | | --- | --- | | **Name** | For you. It shows up in the audit log next to everything this credential does, so name it after the integration, not after a person. | | **Expiration** | A date, or unlimited. A date is worth setting for anything temporary — a migration script, a contractor's integration. | | **Scopes** | Which feature areas it may reach. See [Scopes](./guide-scopes). | | **SSO settings** | Only if you ticked the `sso` scope: which agents it may sign in as, and which sites may embed the session. | You get back a **client id** (`tlc_…`, visible forever) and a **client secret** (`tls_…`, shown once). :::warning The secret is shown once It is stored only as a bcrypt hash. Nobody — not an Owner, not Teloring support — can retrieve it afterwards. Lost it? Revoke the credential and create another. ::: ## Getting a token `POST /v1/oauth/token` accepts your credentials three ways. Use whichever your HTTP client makes easiest; they are equivalent.
JSON body ```bash curl -X POST https://api.teloring.com/v1/oauth/token \ -H "Content-Type: application/json" \ -d '{"client_id": "tlc_…", "client_secret": "tls_…"}' ```
Form-encoded (what most OAuth libraries send) ```bash curl -X POST https://api.teloring.com/v1/oauth/token \ -d grant_type=client_credentials \ -d client_id=tlc_… \ -d client_secret=tls_… ```
HTTP Basic (RFC 6749 §2.3.1) ```bash curl -X POST https://api.teloring.com/v1/oauth/token \ -u "tlc_…:tls_…" \ -d grant_type=client_credentials ``` If both a Basic header and body parameters are present, the header wins — a body parameter cannot downgrade it.
### Cache the token One token per hour is the expected pattern. The token endpoint is rate limited to **20 requests per minute per IP**, and ten consecutive failures against one client id lock that client out for fifteen minutes. A minimal client, in the shape most people end up writing: ```python import time, requests class Teloring: BASE = "https://api.teloring.com/v1" def __init__(self, client_id, client_secret): self._id, self._secret = client_id, client_secret self._token, self._expires_at = None, 0 def _auth_header(self): # Refresh a minute early so a request never races the expiry. if not self._token or time.time() > self._expires_at - 60: response = requests.post( f"{self.BASE}/oauth/token", json={"client_id": self._id, "client_secret": self._secret}, timeout=10, ) response.raise_for_status() payload = response.json() self._token = payload["access_token"] self._expires_at = time.time() + payload["expires_in"] return {"Authorization": f"Bearer {self._token}"} def get(self, path, **params): response = requests.get(f"{self.BASE}{path}", headers=self._auth_header(), params=params, timeout=30) if response.status_code == 401: # revoked or edited mid-flight self._token = None response = requests.get(f"{self.BASE}{path}", headers=self._auth_header(), params=params, timeout=30) response.raise_for_status() return response.json() ``` The `401` retry matters more than it looks. Editing a credential's scopes, or revoking it, invalidates outstanding tokens **immediately** — so a token can stop working before its stated expiry, and the correct response is to fetch a new one once, not to crash. ## Using the token ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9… ``` Not sure what a token can do? `GET /v1/oauth/introspect` tells you the account, the credential, and exactly which scopes it holds. It is the fastest way to explain a surprising `403`. ## When authentication fails | Status | `code` | What happened | What to do | | --- | --- | --- | --- | | 400 | `invalid_request` | A credential field was missing | Send both `client_id` and `client_secret` | | 400 | `unsupported_grant_type` | `grant_type` was not `client_credentials` | Only that grant is supported | | 401 | `invalid_client` | Unknown client id, wrong secret, revoked credential, or one past its expiry date | Check the pair; check the credential in Settings → API | | 401 | `missing_token` | No `Authorization: Bearer` header | Add the header | | 401 | `invalid_token` | Token expired, tampered with, or its credential was revoked or edited | Fetch a new token | | 402 | `plan_limit_exceeded` | The account's plan does not include API access | Upgrade the plan | | 403 | `ip_not_allowed` | The account restricts access by IP and yours is not on the list | Add your server's outbound IP under Settings → Security & login | | 429 | `too_many_failed_attempts` | Ten consecutive failures on one client id | Wait fifteen minutes; check the secret | | 429 | `rate_limit_exceeded` | Too many token requests from this IP | Cache the token | :::note One message for every credential failure Unknown client id, wrong secret, revoked and expired all answer the same `401 invalid_client`. Distinguishing them would let somebody enumerate which client ids exist. Our logs record the real reason — quote the `request_id` from the response if you need us to look. ::: ## IP restrictions If the account has an IP allow-list under **Settings → Security & login**, it applies to the API as well as to sign-in. That list is described in the console as "who may access the system", and an integration holding a credential *is* access to the system. When one is set: - `POST /v1/oauth/token` refuses a call from an address that is not on the list and issues no token at all. - Every authenticated request is checked again, not just the token exchange. A token already in hand stops working the moment it is used from a disallowed address — a one-hour window during which a stolen token still worked would be a weaker promise than the one Settings makes. Both answer `403`: ```json { "error": { "type": "permission_error", "code": "ip_not_allowed", "message": "This IP address is not on the account's allow-list. Add it under Settings → Security & login, or call the API from an allowed address.", "details": { "client_ip": "203.0.113.55" }, "request_id": "req_5f2a91c0e8b74d3a9c1e" } } ``` The address we compare is your server's **outbound** IP as it reaches us, which is often not the address of the machine running your code — a NAT gateway, a load balancer or an egress proxy usually sits in between. `details.client_ip` in the error tells you exactly what we saw, so add that. Both single addresses and CIDR ranges are accepted in the console: ``` 198.51.100.7 192.0.2.0/24 ``` An account with an empty list is unrestricted, which is the default. :::caution Serverless and dynamic IPs If your integration runs somewhere with a changing outbound address (most serverless platforms, some CI runners), either give it a static egress IP or leave the allow-list empty. A partially-correct list produces intermittent `403`s that are miserable to debug. ::: ## Rotating a secret There is no in-place rotation, on purpose: a credential that can change its own secret is a credential whose secret can be changed by whoever holds it. The zero-downtime rotation is two credentials: 1. Create a second credential with the same scopes. 2. Deploy the new client id and secret to your integration. 3. Watch **Last used** on the old credential in Settings → API until it stops moving. 4. Revoke the old one. ## Keeping the secret safe - Store it in a secrets manager or an environment variable — never in source control, never in a frontend bundle, never in a URL. - Give each integration its own credential with its own scopes. One shared secret across five systems means a leak anywhere is a leak everywhere, and the audit log cannot tell you which system did what. - Set an expiry on anything temporary. - Revoke immediately if you suspect exposure. Revocation kills outstanding access tokens as well as the secret. --- # Scopes Source: https://docs.teloring.com/api/guide-scopes Markdown: https://docs.teloring.com/markdown/api/guide-scopes.md Section: API Reference Last modified: 2026-08-20T20:49:57.000Z A scope is a **whole feature area**, not a verb. Granting `conversations` allows every conversation operation — read, create, update, hold, resolve, delete — because an integration that can read conversations but not resolve them is usually just an integration that will be granted the second half next week. Choose scopes the other way round instead: grant the areas an integration genuinely touches, and leave the rest off. A credential that only syncs customers into a data warehouse should hold `customers` and nothing else. ## The catalog | Scope | Unlocks | | --- | --- | | `conversations` | List, create, update, hold, resolve and delete conversations; read the queue counts; list inboxes; read and write conversation custom attributes | | `messages` | Read a conversation's messages; send text, media, notes and WhatsApp templates; delete a message; list WhatsApp templates | | `customers` | Read, create, update, search and delete customers; list a customer's contacts | | `customer_objects` | Read the object types and manage their records — deals, service calls, tasks and your own | | `analytics` | Read dashboards and run their graphs | | `studio` | Read flows, their blocks and each block's settings | | `ai_world` | Read every AI capability and switch one on or off | | `knowledge_base` | Manage knowledge bases, their sources and the indexed chunks | | `quick_replies` | Read, create, update and delete saved replies | | `forms` | Read forms and their submissions; delete a form | | `documents_signature` | Read documents, upload a PDF, create and revoke signing links | | `account` | Read and update the account's general and invoicing details | | `business_hours` | Manage schedules; read holiday calendars | | `conversation_attributes` | Read the conversation-attribute schema | | `agents_teams` | Manage agents, AI agents and teams; read roles | | `audit_log` | Read the account's audit trail | | `billing` | Read credit balances, the usage price list, transactions and invoices | | `files` | List files with their storage usage; delete files | | `profile` | Read and update any agent's display name, timezone, picture and notification settings | | `notifications` | Read an agent's notification feed and unread count | | `sso` | Create single-use links that sign a chosen agent into the console | ## The four that deserve a second thought **`agents_teams` can spend money.** Creating a human or AI agent takes a seat, and a seat the plan does not have free is a real charge on the card. Grant this only to an integration that genuinely provisions people, and read the warning on [Create a human agent](/api/create-agent). **`documents_signature` can spend credits.** Every signing link costs. The endpoint is safe to retry — a repeat for the same document and contact returns the existing link and charges nothing — but a loop that creates links for a list of contacts spends real money. **`profile` reaches every agent in the account,** addressed by id in the path. It is the right scope for syncing display names or timezones from an HR system, and the wrong one for almost anything else. **`sso` grants nothing on its own.** See below. ## Scopes that carry extra configuration ### `sso` Ticking the scope is step one of two. The credential must also name: - **the agents** it may sign in as — a multi-select in Settings → API. An empty list means the credential can impersonate nobody, which is the safe default when somebody ticks the scope and saves. - **the origins** allowed to embed the resulting session in an iframe, if you plan to embed it. As many as you need, one per line, scheme and host only: ``` https://app.example.com https://portal.example.co.il https://crm.example.com:8443 ``` Removing an agent from that list invalidates every SSO link already issued for them. See [SSO login](./guide-sso). ## Changing scopes later Scopes are editable on an existing credential — that is deliberate, so an integration that grows a feature does not force you to rotate a secret your client has already deployed. The client id and the secret never change. Everything else does: 1. **Settings → API**, press **Edit** on the credential. 2. Tick or untick scopes; adjust the SSO agents and origins. 3. Save. Editing a credential **invalidates its outstanding access tokens.** The next call answers `401 invalid_token`, and the client fetches a new token carrying the new scopes. That is why the client sketch in [Authentication](./guide-authentication) retries once on a `401` — with that in place, a scope change is invisible to a running integration. ## When a scope is missing ```json { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This credential does not hold the 'conversations' scope. Edit the credential in Settings → API to grant it.", "details": { "required_scope": ["conversations"], "granted_scopes": ["customers", "billing"] }, "request_id": "req_5f2a91c0e8b74d3a9c1e" } } ``` The error names what was needed and what you hold, so it is usually self-diagnosing. `GET /v1/oauth/introspect` answers the same question for a token you already have. ## Scopes are not the only gate Two other things can refuse an otherwise well-scoped request, and it is worth knowing which is which: - **`402 plan_limit_exceeded`** — the account's plan does not include the feature, or a ceiling is full. `GET /v1/billing/plan` lists every limit and feature flag. - **`403 feature_disabled`** — an account-level switch is off. The knowledge base endpoints answer this when the Knowledge Base capability is switched off in AI World, so you can tell "turned off" from "nothing indexed yet". --- # Pagination, filtering & errors Source: https://docs.teloring.com/api/guide-conventions Markdown: https://docs.teloring.com/markdown/api/guide-conventions.md Section: API Reference Last modified: 2026-08-20T20:49:57.000Z Learn these once and every endpoint behaves the way you expect. ## Responses **A single resource is returned as itself.** No envelope, nothing to unwrap: ```json { "object": "conversation", "id": "387", "status": "open", "…": "…" } ``` Every resource carries an `object` field naming its type, which is what lets you write one dispatcher over mixed results. **A collection is `data` plus `meta`:** ```json { "data": [ { "object": "conversation", "id": "387" } ], "meta": { "page": 1, "per_page": 25, "count": 25, "total": 155, "total_pages": 7, "has_more": true } } ``` **A delete answers uniformly**, so one handler covers all of them: ```json { "id": "387", "object": "conversation", "deleted": true } ``` Some deletes add a field describing the cascade — `unlinked_contacts` on a customer, `detached_conversations` on a team, `freed_bytes` on a bulk file delete. Read them; they are how you find out a delete did more than you expected. ## Pagination | Parameter | Default | Range | | --- | --- | --- | | `page` | 1 | ≥ 1 | | `per_page` | 25 | 1–100 | `per_page=500` is a `400`, not a silent clamp. A client asking for 500 rows a page has a design assumption worth correcting now rather than discovering in production. **Loop on `has_more`, not on `total`.** `total` is omitted where counting the full result set would cost a second scan; `has_more` is always present. ```python page = 1 while True: result = client.get("/conversations", status="open", page=page, per_page=100) for conversation in result["data"]: handle(conversation) if not result["meta"]["has_more"]: break page += 1 ``` :::tip Polling for changes Do not re-walk a whole collection on a timer. `GET /v1/conversations` takes `updated_after`, so a poll can ask only for what moved: ``` GET /v1/conversations?status=open&updated_after=2026-08-20T09:00:00Z ``` ::: ## Filtering **Repeated values within one filter are OR.** Both forms work, so use whichever your HTTP client produces: ``` ?label=vip&label=urgent ?label=vip,urgent ``` **Different filters are AND.** This finds open, urgent conversations in two inboxes that nobody owns: ``` ?status=open&priority=urgent&inbox_id=3,7&assignee_id=unassigned ``` **Two filters take sentinel values:** `assignee_id=unassigned` for the waiting line, and `team_id=none` for conversations no team owns. **Timestamps are ISO-8601.** `2026-08-20T09:00:00Z` or with an offset. A value that will not parse is a `400` naming the parameter rather than a silently ignored filter. **Unknown enum values are rejected,** and the error lists the accepted ones — `?status=nope` tells you it wants `open`, `pending`, `on_hold` or `resolved`. A filter you mistyped never silently returns everything. ## Errors One shape, everywhere: ```json { "error": { "type": "invalid_request_error", "code": "missing_parameter", "message": "'inbox_id' is required.", "param": "inbox_id", "request_id": "req_5f2a91c0e8b74d3a9c1e" } } ``` Branch on **`code`** — it is stable across releases. `type` groups failures the way you would handle them; `message` is written for a human reading a log. ### Status codes | Status | `type` | Means | | --- | --- | --- | | 400 | `invalid_request_error` | Something about the request is wrong. Fix it; retrying will not help. | | 401 | `authentication_error` | No token, or the token is no longer valid. Fetch a new one and retry once. | | 402 | `plan_limit_error` | Valid and authorised, but a plan ceiling or a locked feature stopped it. | | 403 | `permission_error` | The credential lacks the scope, an account switch is off, or the caller's IP is not on the account's allow-list. | | 404 | `not_found_error` | No such resource in this account. | | 409 | `conflict_error` | Valid, but conflicts with current state — a closed WhatsApp window, a duplicate team name. | | 413 | `invalid_request_error` | The upload is too large. | | 429 | `rate_limit_error` | Slow down. | | 5xx | `api_error` | Our problem. Retry with backoff and quote the `request_id`. | ### Validation detail Where several fields failed at once, the specifics arrive in `details`: ```json { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more attribute values were rejected.", "details": { "errors": [ "reason_for_contact: 'refund' is not one of the allowed options", "order_number: required" ] } } } ``` ### `request_id` Every response carries one, in the body on errors and in the `X-Request-Id` header always. Quote it when reporting a problem — it is how we find the exact request in our logs. You may also supply your own, and it will be echoed back and used in our logs, which makes correlating with your side trivial: ``` X-Request-Id: my-job-4192-attempt-1 ``` ## Rate limits | | Limit | | --- | --- | | Authenticated requests | 600 per minute, per credential | | `POST /v1/oauth/token` | 20 per minute, per IP | Over the limit is a `429`. Back off exponentially — and if you are hitting the token limit, the fix is to cache the token rather than to retry harder. ## Retries and idempotency Most write endpoints are not idempotent: `POST /v1/customers` twice makes two customers. Where a retry is genuinely safe, it is because the endpoint was built that way and says so: - **`POST /v1/signature/links`** returns the existing link for the same document and contact instead of creating a second one, and does not charge again. `created` in the response says which happened. - **`POST /v1/agents`** rolls the agent back if the seat charge is declined, so a `402` means nothing was created. - **`PATCH`** endpoints are naturally idempotent — sending the same body twice leaves the same state. For everything else, retry a `429` or a `5xx`; do not blind-retry a `400`. ## Timestamps and ids All timestamps are **ISO-8601 in UTC**, and a field that has no value is `null` rather than `""` — so you can tell "never resolved" from "resolved at an unknown time". Ids are **opaque strings**. Some look like numbers (`"387"`), some like hashes (`"kIlBtSS5yQTGeghZmlQ3"`). Store them as strings; never parse or generate one. ## What this API will not do Worth knowing before you plan around it: - **No webhooks in this version.** Poll with `updated_after`. Studio can already call your endpoint on conversation events if you need push today. - **No visual editors.** Studio flows, form layouts and signature field placement are coordinates on a canvas, and a JSON body of pixel offsets is not a contract anybody should have to write. Those stay in the console; this API reads them. - **No browser access.** No CORS headers, deliberately. --- # SSO login Source: https://docs.teloring.com/api/guide-sso Markdown: https://docs.teloring.com/markdown/api/guide-sso.md Section: API Reference Last modified: 2026-08-20T20:49:57.000Z Your users already work in your product. SSO login lets them reach Teloring from inside it, without a second password: your backend asks for a link, your user opens it, and they land in the console signed in as a specific agent. Two shapes, for two different jobs: **Full system** — the whole console, exactly as if they had signed in. Use it for a "Open in Teloring" button. **Specific conversation** — one contact's chat and nothing else. No navigation, no conversation list, no dashboard. Use it when your user is looking at a customer in *your* system and wants to message them: open it in an iframe, send the message, close the iframe. ## Before it will work The `sso` scope alone grants nothing. In **Settings → API**, on the credential, you must also set: **Which agents it may sign in as.** A multi-select. An agent not on the list answers `403 agent_not_allowed`, and the error lists who is allowed. An empty list means the credential can impersonate nobody — the safe default when somebody ticks the scope and saves without choosing. **Which origins may embed it,** if you plan to use an iframe. As many as you need, one per line, scheme and host only: ``` https://app.example.com https://portal.example.co.il https://crm.example.com:8443 ``` Both are editable later without rotating the secret. ## Full system ```bash curl -X POST https://api.teloring.com/v1/sso/login \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"agent_id": "agent_12", "mode": "full"}' ``` ```json { "object": "sso_login", "url": "https://console.teloring.com/sso/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "mode": "full", "agent_id": "agent_12", "agent_name": "Dana Levi", "embed": false, "expires_at": "2026-08-20T10:34:31+00:00", "expires_in": 600, "single_use": true } ``` Redirect the browser to `url`. They land on the dashboard, signed in as Dana. ## Specific conversation Identify the contact by `phone` or `email`. Add `inbox_id` when you know which channel to use. ```bash curl -X POST https://api.teloring.com/v1/sso/login \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "agent_12", "mode": "conversation", "contact": { "phone": "+972501234567" }, "inbox_id": "3", "embed": true }' ``` What your user sees depends on what exists, and the API tells you in advance under `target`: | Situation | What opens | | --- | --- | | A conversation with that contact is already open | That conversation, ready to reply | | No conversation, and you passed `inbox_id` | The composer, contact **and** inbox already chosen — only the message is left (or the template, on WhatsApp outside the 24-hour window) | | No conversation, and no `inbox_id` | The composer with the contact chosen; your user picks the inbox | The contact must already exist. An unknown phone or email answers `404 contact_not_found` — create the contact, or start the conversation with `POST /v1/conversations`, which will create it for you. ## Embedding in your own product Set `embed: true` and open the URL in an iframe: ```html ``` Three things happen because you asked for an embed: - The pages are served with `Content-Security-Policy: frame-ancestors` naming **only** the origins you configured. Any other site framing the same URL gets nothing. - The session cookie is issued `SameSite=None; Secure; Partitioned`. Partitioned matters: the cookie lives in *your* site's cookie partition, so it cannot be replayed from anywhere else — which is also what keeps cross-site request forgery closed on an embedded session. - In `conversation` mode, the embedded page posts a message to the parent window when the agent sends something, so you can close the iframe without polling: ```js window.addEventListener('message', (event) => { if (event.origin !== 'https://console.teloring.com') return; if (event.data?.source === 'teloring' && event.data.type === 'message_sent') { closeTeloringPanel(); // your code } }); ``` Requesting `embed: true` with no origins configured answers `400 no_embed_origins` rather than quietly handing you a page no browser will frame. ## How the link is protected A URL that bypasses the login screen is a credential, so it is treated like one. **Ten minutes, one use.** The link expires after ten minutes and is redeemable exactly once. A second attempt — a copied URL, a duplicated tab, a prefetching proxy — answers `409`. Mint one per use; never cache them. **Re-checked at redemption.** The link carries no permissions of its own. When it is opened, the credential is re-read (still active? still holds `sso`? still allows this agent?) and the agent is re-read (still exists? still active?). So removing an agent from the allowlist, or revoking the credential, kills every link already issued — within the ten-minute window, not after it. **Fails closed.** If the one-time-use store is unreachable, redemption is refused rather than allowed. A login-bypass link that silently becomes replayable is worse than one that briefly stops working. **Audited.** Every link minted and every redemption is written to the audit log with the credential, the agent and the mode, so `agent.sso_login` in the audit trail always names who let it happen. ## Handling a link that will not open If the link is expired, already used, or its credential or agent no longer qualifies, the user sees a small Teloring error page — **not** a redirect to the sign-in form. That is deliberate: inside your iframe, a Teloring login form is both useless and confusing to somebody who has no Teloring account of their own. That page says one of four things, and they split into two groups: | What the user sees | HTTP | Cause | Does a new link fix it? | | --- | --- | --- | --- | | You have already opened this link | `409` | The link was redeemed once already — a refresh, a back button, or a second click | Yes | | This sign-in link has expired | `401` | More than 10 minutes passed between minting and opening | Yes | | This sign-in link is no longer authorised | `403` | The credential was revoked, lost the `sso` scope, or the agent was removed from its allow-list | No | | This sign-in link no longer works | `403` | The agent it signs in as was deactivated | No | The first two are the everyday ones, and the page tells the user to go back and open it again — so they resolve themselves as soon as your product mints a new link. The last two are configuration changes on the Teloring side, so the page sends the user to whoever administers the account instead of round a retry loop that cannot succeed. Your integration's job is simply to mint a fresh link. Because they are cheap and single-use, the right pattern is to request one at the moment the user clicks, never to store one. A refresh of your own page should mint a new link rather than reload the iframe's existing URL — that URL is spent, and reloading it is the single most common way to land on the "already opened" page. ## A complete example ```python def open_teloring_chat(agent_id, customer_phone, inbox_id=None): """Return an iframe URL for messaging this customer. Call it per click.""" payload = { "agent_id": agent_id, "mode": "conversation", "contact": {"phone": customer_phone}, "embed": True, } if inbox_id: payload["inbox_id"] = inbox_id response = requests.post( "https://api.teloring.com/v1/sso/login", headers=client._auth_header(), json=payload, timeout=10, ) if response.status_code == 404: # No such contact yet — create the conversation, which creates the # contact, then try again. return None response.raise_for_status() return response.json()["url"] ``` ## Security notes for your side - **Mint links server-side only.** Your `sso` credential must never reach the browser: anyone holding it can sign in as any allow-listed agent. - **Authorise on your side first.** Teloring checks that the *credential* may impersonate the agent. It cannot check that *this particular user of yours* should be allowed to — that is your call, and you must make it before minting. - **Map your users to agents deliberately.** A shared agent id means your audit log says "the API" where it should say a person. - **Keep the origin list tight.** Every origin you add is a site that may frame a signed-in Teloring session. --- # Postman collection Source: https://docs.teloring.com/api/guide-postman Markdown: https://docs.teloring.com/markdown/api/guide-postman.md Section: API Reference Last modified: 2026-08-20T20:49:57.000Z Every endpoint in this API, in one importable collection — with the token dance already wired up. Download the collection Direct link, if you prefer to import by URL: ``` https://docs.teloring.com/teloring-api.postman_collection.json ``` ## Setting it up **1. Import.** In Postman: **Import → File** (or **Link**, pasting the URL above). You get a collection called *Teloring API v1.0.0* with one folder per feature area. **2. Fill in two variables.** Open the collection, go to the **Variables** tab, and paste the `client_id` and `client_secret` from **Settings → API** into the *Current value* column. | Variable | Set it to | | --- | --- | | `base_url` | Already set to `https://api.teloring.com/v1` | | `client_id` | Your client id, `tlc_…` | | `client_secret` | Your client secret, `tls_…` | | `access_token` | Leave empty — step 3 fills it in | :::tip Use *Current value*, not *Initial value* Postman shares *Initial value* when you share a collection. Secrets belong in *Current value*, which stays on your machine. ::: **3. Get a token.** Run **Authentication → Get an access token** and press **Send**. Its test script writes the token into the `access_token` variable, and the collection console logs the scopes it came back with. **4. Send anything.** Every other request inherits bearer auth from the collection, so it just works. Tokens last an hour — when requests start answering `401`, run step 3 again. ## Finding your way around The folders match the sidebar of this reference, so an endpoint you read about here is where you would expect it in Postman. - **Path parameters** are Postman variables: a request to `/conversations/:conversation_id` shows a *Path Variables* table under the URL. Fill in the value there. - **Query parameters** are pre-listed and **disabled**. Tick the ones you want — a fresh request sends none of them, which is the sensible default. - **Request bodies** are pre-filled from this reference's examples, so nothing is an empty box. Edit them in place. - **Descriptions** come from the same source as these pages, so the documentation travels with the request. ## A first run, end to end Try these five in order. It is the shortest path from "imported" to "sent a message". 1. **Authentication → Get an access token** — the token lands in the variable. 2. **Authentication → Inspect the current token** — confirms the account and the scopes you actually hold. 3. **Conversations → List inboxes** — note an `id` from the response. 4. **Conversations → Create a conversation** — put that inbox id in `inbox_id` and a real phone number in `contact.phone`. 5. **Messages → Send a message** — put the new conversation's id in the `conversation_id` path variable. ## Keeping it current The collection is **generated from the OpenAPI specification behind this reference**, on every docs build. It cannot describe an endpoint differently from these pages, and it cannot fall behind when endpoints are added. Re-download it after a Teloring release to pick up new endpoints. Postman's **Import → Link** keeps the URL, so a re-import is one click. ## Using the raw specification instead Prefer to generate a client, or import into Insomnia, Bruno, or an API gateway? The OpenAPI 3.1 document is the same source: ``` https://docs.teloring.com/api/openapi.yaml ``` It works with the usual generators — for example: ```bash openapi-generator-cli generate \ -i https://docs.teloring.com/api/openapi.yaml \ -g python \ -o ./teloring-client ``` --- # Account Source: https://docs.teloring.com/api/account Markdown: https://docs.teloring.com/markdown/api/account.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Who this business is, and when it is open. **Scopes:** `account`, `business_hours`, `conversation_attributes` An Israeli account's `billing_country` is locked once billing starts: it determined the VAT on invoices already issued. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Add a source Source: https://docs.teloring.com/api/add-knowledge-base-source Markdown: https://docs.teloring.com/markdown/api/add-knowledge-base-source.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Add a source — a URL, or an uploaded file. **URL:** `application/json` with `{"url": "https://…"}`. Set `crawl_inner: true` to follow links within the same site. URLs are validated against private address ranges before the worker fetches them. **File:** `multipart/form-data` with a `file` part. PDFs, Office documents, plain text and images are supported. Returns `202` immediately with the source in `processing`. Poll `GET /v1/knowledge-bases/{kb_id}/sources` for the outcome — a large PDF takes minutes, not seconds. Request --- # Agents & teams Source: https://docs.teloring.com/api/agents-teams Markdown: https://docs.teloring.com/markdown/api/agents-teams.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z The people — and the AI — who answer conversations. **Scope:** `agents_teams` ⚠️ **Creating an agent can charge the card on file.** A human or AI agent occupies a seat; if the plan has none free, a prorated charge is taken. A `402` with `code: seat_charge_failed` means nothing was created and a retry is safe. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # AI World Source: https://docs.teloring.com/api/ai-world Markdown: https://docs.teloring.com/markdown/api/ai-world.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Which AI capabilities are switched on for the account. **Scope:** `ai_world` Each item is a plain on/off. Most of them consume AI credits when they run, so treat enabling one as a deliberate act. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Analytics Source: https://docs.teloring.com/api/analytics Markdown: https://docs.teloring.com/markdown/api/analytics.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Dashboards and the graphs on them. **Scope:** `analytics` Graph values are computed on demand, not stored. Fetching them is opt-in (`?include=values`) because it is genuinely expensive — cache the result rather than polling. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Audit log Source: https://docs.teloring.com/api/audit-log Markdown: https://docs.teloring.com/markdown/api/audit-log.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Who did what, including what this API did. **Scope:** `audit_log` Read-only by design. Every write made through this API is recorded with `details.via = "public_api"` and the credential's client id, so an API-driven change is never anonymous. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Authentication Source: https://docs.teloring.com/api/authentication Markdown: https://docs.teloring.com/markdown/api/authentication.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Turning a client id and secret into a one-hour access token. This is the only unauthenticated endpoint in the API, and the only one that reads your client secret. Cache the token you get back and re-request it when it expires or when a call answers `401`. If the account restricts access by IP (Settings → Security & login), that restriction is enforced here as well — a call from an address that is not on the list is refused before any token is issued. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Billing Source: https://docs.teloring.com/api/billing Markdown: https://docs.teloring.com/markdown/api/billing.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Credits, the price list they are spent against, and invoices. Read-only. **Scope:** `billing` Nothing here can spend money or change a plan. Two balances exist and are not interchangeable: `monthly` (included, resets each period, does not roll over) and `topup` (bought, spent only once monthly runs out). ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Delete many files Source: https://docs.teloring.com/api/bulk-delete-files Markdown: https://docs.teloring.com/markdown/api/bulk-delete-files.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete up to 100 files in one call. Partial success is normal and is reported rather than hidden: `deleted` lists the ids that went and `failed` the ones that did not, with a reason. A file id that does not exist counts as failed — an integration deleting the wrong ids should find out. Request --- # Move the conversation to a different customer Source: https://docs.teloring.com/api/change-conversation-customer Markdown: https://docs.teloring.com/markdown/api/change-conversation-customer.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Re-parent this conversation's contact under a different customer. A contact cannot belong to two customers at once, so this moves **all** of that contact's conversations, not just this one. The response reports how many, under `conversations_moved`. Request --- # Queue counts Source: https://docs.teloring.com/api/conversation-counts Markdown: https://docs.teloring.com/markdown/api/conversation-counts.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The numbers behind the inbox sidebar badges, in one call. `assigned` counts open conversations with a human owner — the console shows a per-agent "Mine" badge, which has no meaning for a machine credential. --- # Conversations Source: https://docs.teloring.com/api/conversations Markdown: https://docs.teloring.com/markdown/api/conversations.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z The threads between a contact and the business, across every channel. **Scope:** `conversations` A conversation belongs to an **inbox** (the channel it arrived on) and a **contact** (the person on the other end). Its `status` moves between `open`, `pending`, `on_hold` and `resolved`; `on_hold` additionally carries a deadline and is set through its own endpoint. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Get an access token Source: https://docs.teloring.com/api/create-access-token Markdown: https://docs.teloring.com/markdown/api/create-access-token.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Exchange a client id and secret for a bearer token that lasts one hour. Credentials may be sent three ways — pick whichever your HTTP client makes easiest. All three are equivalent: - a JSON body (shown below), - a form-encoded body, which is what most OAuth libraries send, - HTTP Basic, with the client id as the username. Basic wins if both are present, so a body parameter cannot downgrade a header. **Cache the token.** One call an hour is the expected pattern; the token endpoint is rate limited to 20 requests per minute per IP, and ten consecutive failures against one client id lock it out for fifteen minutes. Every credential failure — unknown client id, wrong secret, revoked credential, expired credential — answers the same `401 invalid_client`. Telling you which one it was would tell an attacker which client ids exist. Two things are checked before a token is issued: that the account's plan includes API access, and that the calling IP passes the account's IP allow-list if one is set. A blocked address answers `403 ip_not_allowed` and gets no token at all. The first time an account reaches this endpoint, the **API Explorer** achievement becomes collectable in the console. Nothing to do — it unlocks on its own. Request --- # Create a human agent Source: https://docs.teloring.com/api/create-agent Markdown: https://docs.teloring.com/markdown/api/create-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a human agent. ⚠️ **This may charge the card on file.** An agent occupies a seat; if the plan has none free, a prorated charge is taken for the rest of the billing period, exactly as in the console. Two consequences to design around: - A `402` with `code: seat_charge_failed` means the card was declined and **nothing was created** — the agent is rolled back before the response is written, so a retry is safe. - A `201` may carry a `seat_charge` object saying what was charged. Log it: "why did my invoice go up" is a question an automated provisioning integration will eventually have to answer. Omit `password` and the new agent is emailed a one-time link to set their own — the right choice for a real person. Supply one and the account works immediately, which suits a service account a machine will drive. `role_id` comes from `GET /v1/roles`. Omitted, the account's default Agent role is applied, which is a working least-privilege role rather than no permissions. Request --- # Create an AI agent Source: https://docs.teloring.com/api/create-ai-agent Markdown: https://docs.teloring.com/markdown/api/create-ai-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create an AI agent. ⚠️ **This may charge the card on file** — an AI agent costs a seat exactly as a human one does, with the same `402` / `code: seat_charge_failed` behaviour and the same rollback. Every field the console's AI agent editor offers is accepted and passed through: persona, instructions, model, language, the knowledge bases it may answer from, the inboxes it works in and its hand-off rules. Unknown fields are rejected rather than silently dropped. Request --- # Create a schedule Source: https://docs.teloring.com/api/create-business-hours Markdown: https://docs.teloring.com/markdown/api/create-business-hours.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a named schedule. `days` maps weekday names to opening periods. A day with no periods is closed. Times are read in the schedule's own `timezone`, falling back to the account's. Request --- # Create a conversation Source: https://docs.teloring.com/api/create-conversation Markdown: https://docs.teloring.com/markdown/api/create-conversation.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Open a conversation in an inbox. `inbox_id` is enough on its own — the channel type is read from the inbox, so you never have to keep the two in sync. Get the ids from `GET /v1/inboxes`. Identify the contact either by `contact_id`, or by a `contact` object carrying a `phone` or an `email`. The second form is what an integration usually wants: an unknown phone number creates the contact rather than failing. Pass a `message` object to send the first message in the same call — the same body `POST /v1/conversations/{id}/messages` takes, including `{"type": "template", …}` for WhatsApp. The created message comes back under `initial_message`. **Which inboxes can start a conversation?** Live chat, the API inbox, Instagram DM, Facebook Messenger and TikTok are inbound-only: the customer must write first, because there is no way to address them until they do. Request --- # Create a customer Source: https://docs.teloring.com/api/create-customer Markdown: https://docs.teloring.com/markdown/api/create-customer.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a customer. Counts against the plan's customer limit — a full account answers `402` with `code: plan_limit_exceeded` rather than silently discarding the record. Creating a customer fires the Studio *customer changed* trigger and writes a journey event, exactly as the console does, so automations react to API-created records the same way. Request --- # Create a record Source: https://docs.teloring.com/api/create-customer-object-record Markdown: https://docs.teloring.com/markdown/api/create-customer-object-record.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a record under a customer. Field values go in `data`, keyed by the `fields[].key` values from `GET /v1/objects/{object_id}`. They are validated against the object's schema: a missing required field, or a select value outside the list, is a `400` naming the field — with the per-field detail under `error.details.errors` — rather than a record with bad data in it. Creating a record writes a journey event on the customer and fires the Studio *customer record changed* trigger. Request --- # Create a knowledge base Source: https://docs.teloring.com/api/create-knowledge-base Markdown: https://docs.teloring.com/markdown/api/create-knowledge-base.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create an empty knowledge base. Counts against the plan's knowledge-base limit. Request --- # Create a quick reply Source: https://docs.teloring.com/api/create-quick-reply Markdown: https://docs.teloring.com/markdown/api/create-quick-reply.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a quick reply. `scope` defaults to `account` — a shared snippet is almost always what an integration means. For a personal one, pass `scope: "personal"` **and** the `agent_id` it belongs to; without an owner a personal reply would be invisible to everybody. Bodies may contain merge variables such as `{{contact.name}}`. They are stored verbatim and resolved when an agent inserts the reply. Request --- # Create a signing link Source: https://docs.teloring.com/api/create-signing-link Markdown: https://docs.teloring.com/markdown/api/create-signing-link.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a signing link for an **active** document. **Costs credits.** Both `customer_id` and `contact_id` are required. The customer is the business the document belongs to; the contact is the person who will sign it — and a signed document that cannot say who signed it is not worth much. **Safe to retry.** Calling this twice for the same document and contact returns the existing link instead of creating a second one, and does not charge again. `created` in the response tells you which happened, and the status code follows it (`201` for a new link, `200` for an existing one). Request --- # Create a single-use sign-in link Source: https://docs.teloring.com/api/create-sso-link Markdown: https://docs.teloring.com/markdown/api/create-sso-link.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Mint a link that signs one of your agents straight into the console — no login screen, no password. ### Before it will work The `sso` scope alone grants nothing. In **Settings → API**, the credential must also name: - **the agents** it may sign in as. An agent not on that list answers `403` with `code: agent_not_allowed`, and the error lists who *is* allowed. - **the origins** allowed to embed the session, if you plan to open the link in an iframe. Requesting `embed: true` with none configured answers `400` with `code: no_embed_origins`. ### The two modes **`full`** opens the whole console, exactly as if the agent had signed in. **`conversation`** opens one contact's chat and nothing else — no navigation, no conversation list. Supply the contact by `phone` or `email`. If a conversation with them is already open it is opened; if not, the composer opens with the contact pre-selected. Add `inbox_id` and the inbox is chosen too, leaving only the message to write. This is the mode built for an iframe: open it, send a message, close it. ### The link itself Valid for **ten minutes** and redeemable **once** — a URL that bypasses the login screen is a credential, and a credential in a URL ends up in browser history and referrer headers. Mint one per use; do not cache it. Revocation is immediate: at redemption the credential and the agent are re-checked against live data, so removing an agent from the allowlist kills every link already issued for them. ### Embedding With `embed: true` the resulting pages are served with `frame-ancestors` naming only your configured origins, and the session cookie is issued `SameSite=None; Secure; Partitioned` so it lives in your site's own cookie partition and cannot be replayed from anywhere else. In `conversation` mode the embedded page posts a message to the parent window when the agent sends something, so you can close the iframe without polling: ```js window.addEventListener('message', (event) => { if (event.origin !== 'https://console.teloring.com') return; if (event.data?.source === 'teloring' && event.data.type === 'message_sent') { closeMyIframe(); } }); ``` Request --- # Create a team Source: https://docs.teloring.com/api/create-team Markdown: https://docs.teloring.com/markdown/api/create-team.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Create a team. `auto_assign_online: true` makes assigning the team immediately hand the conversation to a random online member — AI agents count as always online. `humans_only: true` keeps AI agents out of the team entirely. Teams are a plan capability: a plan without agent groups answers `402`. Names are unique per account, compared case-insensitively, so a duplicate answers `409`. Request --- # Customer objects Source: https://docs.teloring.com/api/customer-objects Markdown: https://docs.teloring.com/markdown/api/customer-objects.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z The mini-CRM: object types and the records filed under each customer. **Scope:** `customer_objects` An **object** is a type — Contacts, Deals, Service Calls, Tasks, plus whatever was defined in the field editor. A **record** is one instance, and every record belongs to exactly one customer. Records can be read per-customer, or account-wide across every customer. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Customers Source: https://docs.teloring.com/api/customers Markdown: https://docs.teloring.com/markdown/api/customers.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z The business records contacts belong to. **Scope:** `customers` A **contact** is a channel identity — this phone number on WhatsApp, this email address. A **customer** is the company or household those identities belong to. One customer owns many contacts; a conversation belongs to a contact, and through it to a customer. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Deactivate an agent Source: https://docs.teloring.com/api/delete-agent Markdown: https://docs.teloring.com/markdown/api/delete-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Deactivate an agent. They can no longer sign in and stop receiving assignments, but their name and history stay intact — a message has to keep showing who sent it. The seat is released at the next billing cycle. Any SSO permission naming this agent is removed at the same time, which invalidates every SSO link already issued for them. Request --- # Remove a profile picture Source: https://docs.teloring.com/api/delete-agent-avatar Markdown: https://docs.teloring.com/markdown/api/delete-agent-avatar.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Removes the picture; the console falls back to the agent's initials. Request --- # Delete an AI agent Source: https://docs.teloring.com/api/delete-ai-agent Markdown: https://docs.teloring.com/markdown/api/delete-ai-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Deletes the AI profile and deactivates the agent record fronting it. Conversations it handled keep their history; the seat is released at the next billing cycle. Request --- # Delete a schedule Source: https://docs.teloring.com/api/delete-business-hours Markdown: https://docs.teloring.com/markdown/api/delete-business-hours.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete a schedule. System schedules cannot be deleted. Studio flows branching on this schedule keep their configuration but stop resolving it, so check your flows before deleting one that is in use. Request --- # Delete a conversation (email inboxes only) Source: https://docs.teloring.com/api/delete-conversation Markdown: https://docs.teloring.com/markdown/api/delete-conversation.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Permanently delete a conversation, its messages, notes and stored attachments. **Email inboxes only.** Every other channel keeps an immutable history on purpose: a WhatsApp or SMS thread is a record of what was actually sent to a customer. Email is deletable because an inbox routinely receives mail that should never have been filed at all. A non-email conversation answers `403` with `code: delete_not_permitted`. This cannot be undone. Request --- # Delete a customer Source: https://docs.teloring.com/api/delete-customer Markdown: https://docs.teloring.com/markdown/api/delete-customer.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete a customer. Contacts and conversations are **unlinked**, not deleted: the message history is a record of what was said to a real person and survives the customer record it happened to be filed under. Object records stored under the customer (deals, service calls…) go with it. The response reports how many contacts and conversations were unlinked. Request --- # Delete a record Source: https://docs.teloring.com/api/delete-customer-object-record Markdown: https://docs.teloring.com/markdown/api/delete-customer-object-record.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Deletes the record and removes any cross-object links pointing at it. Request --- # Delete a file Source: https://docs.teloring.com/api/delete-file Markdown: https://docs.teloring.com/markdown/api/delete-file.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete one file. The stored object goes with it and cannot be recovered. A message that referenced this file keeps its text but loses the attachment — check `conversation_id` on the file first if that matters. Request --- # Delete a form Source: https://docs.teloring.com/api/delete-form Markdown: https://docs.teloring.com/markdown/api/delete-form.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete a form. Its public link stops working immediately. Submissions already received are **kept** — they are records of what somebody actually told the business, and deleting the form they arrived through does not make them untrue. Pull them with `GET /v1/form-submissions?form_id=…` first if you need them elsewhere. Request --- # Delete a knowledge base Source: https://docs.teloring.com/api/delete-knowledge-base Markdown: https://docs.teloring.com/markdown/api/delete-knowledge-base.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete a knowledge base and every source and chunk inside it. Irreversible. Any AI agent configured to answer from it keeps its configuration but stops retrieving anything — check `knowledge_base_ids` on your AI agents first. Request --- # Delete a source Source: https://docs.teloring.com/api/delete-knowledge-base-source Markdown: https://docs.teloring.com/markdown/api/delete-knowledge-base-source.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Deletes one source and every chunk derived from it. Request --- # Delete a message Source: https://docs.teloring.com/api/delete-message Markdown: https://docs.teloring.com/markdown/api/delete-message.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Remove one message from a conversation. There is no equivalent in the console — this is API-only, and it is genuinely destructive. It deletes **our** record of the message, not the copy the customer already received on WhatsApp, SMS or email. Use it to redact something that should never have been stored, not to "unsend". The conversation's message count is corrected and attachments are detached from the Files Warehouse index. Every delete is written to the audit log with the credential that made it. Request --- # Delete a quick reply Source: https://docs.teloring.com/api/delete-quick-reply Markdown: https://docs.teloring.com/markdown/api/delete-quick-reply.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Delete a quick reply Request --- # Revoke a signing link Source: https://docs.teloring.com/api/delete-signing-link Markdown: https://docs.teloring.com/markdown/api/delete-signing-link.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Revoke a pending signing link. Only `pending` links can be revoked. Once somebody has signed, the link is part of the audit trail of a completed document and cannot be removed — that answers `400` with `code: link_not_pending`. Request --- # Delete a team Source: https://docs.teloring.com/api/delete-team Markdown: https://docs.teloring.com/markdown/api/delete-team.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Conversations still assigned to the team are detached and return to the general waiting line rather than becoming unreachable. The response says how many. Request --- # Document signature Source: https://docs.teloring.com/api/document-signature Markdown: https://docs.teloring.com/markdown/api/document-signature.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Documents sent out for signature, and the links people sign them through. **Scope:** `documents_signature` A **document** is an uploaded PDF; it becomes signable once signature fields are placed in the console's editor. A **signing link** is one recipient's invitation to sign one document, and **costs credits**. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Get an invoice download URL Source: https://docs.teloring.com/api/download-invoice Markdown: https://docs.teloring.com/markdown/api/download-invoice.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; A short-lived signed URL for one invoice PDF. Minted per call and valid for about an hour, so it is safe to hand to a browser but should never be stored. Fetch a fresh one each time you need the file. Request --- # Files Source: https://docs.teloring.com/api/files Markdown: https://docs.teloring.com/markdown/api/files.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Every file that passed through the account, and how much space it uses. **Scope:** `files` Deleting is destructive: the stored object is removed and a message that referenced it shows a broken attachment afterwards. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Forms Source: https://docs.teloring.com/api/forms Markdown: https://docs.teloring.com/markdown/api/forms.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Forms and their submissions. Read and delete. **Scope:** `forms` Building a form is a visual act with no honest JSON equivalent, so it stays in the console. Pulling submissions into another system is what this API is for. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Get account details Source: https://docs.teloring.com/api/get-account Markdown: https://docs.teloring.com/markdown/api/get-account.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Everything on Settings → General, plus the read-only facts: the account id, the plan it is on, when it was created and who owns it. Worth calling once at the start of an integration. `plan` decides whether the rest of this API will work at all — `GET /v1/billing/plan` has the detail. **Scope:** `account` --- # Get an agent Source: https://docs.teloring.com/api/get-agent Markdown: https://docs.teloring.com/markdown/api/get-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get an agent Request --- # Get an agent's profile Source: https://docs.teloring.com/api/get-agent-profile Markdown: https://docs.teloring.com/markdown/api/get-agent-profile.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One agent's personal settings: display name, timezone, language and picture. Request --- # Get an AI agent Source: https://docs.teloring.com/api/get-ai-agent Markdown: https://docs.teloring.com/markdown/api/get-ai-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get an AI agent Request --- # Get one capability Source: https://docs.teloring.com/api/get-ai-feature Markdown: https://docs.teloring.com/markdown/api/get-ai-feature.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get one capability Request --- # Get a conversation Source: https://docs.teloring.com/api/get-conversation Markdown: https://docs.teloring.com/markdown/api/get-conversation.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Everything stored about one conversation, including its custom attributes. Request --- # Read a conversation's custom attributes Source: https://docs.teloring.com/api/get-conversation-custom-attributes Markdown: https://docs.teloring.com/markdown/api/get-conversation-custom-attributes.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The attribute values stored on this conversation, with their definitions resolved. Request --- # Get credit balances Source: https://docs.teloring.com/api/get-credits Markdown: https://docs.teloring.com/markdown/api/get-credits.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The account's current credit balances. `monthly_balance` is what remains of this period's included credits and does not roll over; `topup_balance` is the total across every unexpired package. Spending draws down the monthly balance first. --- # Get a customer Source: https://docs.teloring.com/api/get-customer Markdown: https://docs.teloring.com/markdown/api/get-customer.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One customer. Pass `include=contacts` to get its channel identities in the same call. Request --- # Get an object type Source: https://docs.teloring.com/api/get-customer-object Markdown: https://docs.teloring.com/markdown/api/get-customer-object.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One object type and its full field schema. Request --- # Get a record Source: https://docs.teloring.com/api/get-customer-object-record Markdown: https://docs.teloring.com/markdown/api/get-customer-object-record.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get a record Request --- # Get a dashboard Source: https://docs.teloring.com/api/get-dashboard Markdown: https://docs.teloring.com/markdown/api/get-dashboard.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; A dashboard with its graphs, and optionally their current values. Without `include=values` this is a cheap metadata read. With it, every graph is executed and gains a `value` object holding the same series and totals the console renders — up to 30 graphs per call, with `values_truncated_after` in the response if the dashboard has more. Running the graphs is genuinely expensive. Cache the result rather than polling it, and prefer a schedule measured in minutes over one measured in seconds. One caveat: a graph filtered to "my conversations" resolves `$AGENT_ID` against the caller, and a machine credential is nobody in particular — such a graph legitimately comes back empty here. Request --- # Get a file Source: https://docs.teloring.com/api/get-file Markdown: https://docs.teloring.com/markdown/api/get-file.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One file's metadata with a short-lived signed `download_url`. The URL expires within the hour and is minted per request — fetch a fresh one rather than storing it. Request --- # Get storage statistics Source: https://docs.teloring.com/api/get-file-stats Markdown: https://docs.teloring.com/markdown/api/get-file-stats.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Total files and bytes stored, against the plan's storage quota, broken down by category. The quota comes back with the usage because a number with nothing to measure it against is why an upload starts failing "for no reason". `quota_bytes: null` means the plan has no ceiling. --- # Get a form Source: https://docs.teloring.com/api/get-form Markdown: https://docs.teloring.com/markdown/api/get-form.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One form, including its field definitions. `fields[].id` is the key each answer is stored under in a submission — fetch this once and cache it if you are mapping submissions into another system. Request --- # Get a submission Source: https://docs.teloring.com/api/get-form-submission Markdown: https://docs.teloring.com/markdown/api/get-form-submission.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get a submission Request --- # Get a knowledge base Source: https://docs.teloring.com/api/get-knowledge-base Markdown: https://docs.teloring.com/markdown/api/get-knowledge-base.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One knowledge base with its indexing statistics. Request --- # Get a message Source: https://docs.teloring.com/api/get-message Markdown: https://docs.teloring.com/markdown/api/get-message.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get a message Request --- # Get notification settings Source: https://docs.teloring.com/api/get-notification-settings Markdown: https://docs.teloring.com/markdown/api/get-notification-settings.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; How this agent is notified, plus the values each setting accepts. `channels` are the delivery routes (sound, email, push, bell) and `events` are what can trigger one. `available_channels`, `available_events` and `available_sounds` list what this build supports, so you never have to hardcode them. Request --- # Get the current plan Source: https://docs.teloring.com/api/get-plan Markdown: https://docs.teloring.com/markdown/api/get-plan.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The plan this account is on: its ceilings and which features it includes. Worth reading once at the start of an integration. A `402` from anywhere else in this API is explained by exactly one of these numbers or flags. --- # Get a quick reply Source: https://docs.teloring.com/api/get-quick-reply Markdown: https://docs.teloring.com/markdown/api/get-quick-reply.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Get a quick reply Request --- # Get a flow with its blocks Source: https://docs.teloring.com/api/get-studio-flow Markdown: https://docs.teloring.com/markdown/api/get-studio-flow.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One flow, with every block and trigger it contains and the settings inside each. `blocks[].settings` is block-specific by design — a *send WhatsApp template* block and a *branch on business hours* block have nothing in common. Use `GET /v1/studio/blocks` as the dictionary. `connections` describes the wiring: which block's output leads to which block's input, and through which handle. On a branching block the handle is what tells you *which* branch, so do not ignore it. Request --- # Get a team Source: https://docs.teloring.com/api/get-team Markdown: https://docs.teloring.com/markdown/api/get-team.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; One team, with its members resolved. Request --- # Get the unread count Source: https://docs.teloring.com/api/get-unread-count Markdown: https://docs.teloring.com/markdown/api/get-unread-count.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Just the badge number — the cheap call to poll. Request --- # Put a conversation on hold Source: https://docs.teloring.com/api/hold-conversation Markdown: https://docs.teloring.com/markdown/api/hold-conversation.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Park a conversation until a deadline. It leaves the active queues and comes back by itself when the timer expires — or sooner, if the customer writes in. The assignment is deliberately left alone: on hold means "come back to me later", so the conversation returns to the same agent. `until` is read in the **account's** timezone (Settings → General), never the caller's, because a deadline is business logic rather than a display preference. Request --- # Inspect the current token Source: https://docs.teloring.com/api/introspect-token Markdown: https://docs.teloring.com/markdown/api/introspect-token.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; What this token can do: which account it belongs to and exactly which scopes it holds. Call it first when something is unexpected. Between the account id and the scope list it explains almost every surprising `403`, and it costs nothing. --- # Knowledge base Source: https://docs.teloring.com/api/knowledge-base Markdown: https://docs.teloring.com/markdown/api/knowledge-base.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z The documents the AI is allowed to answer from. **Scope:** `knowledge_base` A knowledge base holds **sources** (a file, or a crawled URL), and each source is split into **chunks** — the passages the retriever matches a question against. Ingestion is asynchronous: add a source, then poll until its status reads `ready`. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # List agents Source: https://docs.teloring.com/api/list-agents Markdown: https://docs.teloring.com/markdown/api/list-agents.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every agent in the account, human and AI, with their role. The `id` here is what goes in `assignee_id` on a conversation and in the SSO agent allowlist. Request --- # List AI agents Source: https://docs.teloring.com/api/list-ai-agents Markdown: https://docs.teloring.com/markdown/api/list-ai-agents.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; AI agent profiles, with every setting they carry. `agent_id` is the agent record each one fronts — that is what you assign a conversation to. --- # List AI capabilities Source: https://docs.teloring.com/api/list-ai-features Markdown: https://docs.teloring.com/markdown/api/list-ai-features.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every AI capability and whether it is switched on for this account. --- # List submissions Source: https://docs.teloring.com/api/list-all-form-submissions Markdown: https://docs.teloring.com/markdown/api/list-all-form-submissions.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Submissions across every form, newest first. Each submission carries the answers twice: `answers` is the flat `{field_id: value}` map most integrations want, and `answers_detail` keeps each answer's label and type so you can render a submission without also fetching the form. Request --- # List audit actions Source: https://docs.teloring.com/api/list-audit-actions Markdown: https://docs.teloring.com/markdown/api/list-audit-actions.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The distinct action names present in this account's log, with counts — so you can build a filter list without hardcoding names that vary by which features the account uses. --- # Read the audit log Source: https://docs.teloring.com/api/list-audit-log Markdown: https://docs.teloring.com/markdown/api/list-audit-log.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Audit entries, newest first. `action` accepts a full action (`agent.login`) or a prefix (`agent`), which matches everything in that family. Use `from` and `to` to page through a long history: one call scans a bounded window, so an unfiltered request over a busy year will not return everything — `meta.scan_truncated` tells you when that happened. Anything done through this API carries `details.via = "public_api"` plus the credential's `client_id` and name, and its `agent_id` reads `api:`. Request --- # List business-hours schedules Source: https://docs.teloring.com/api/list-business-hours Markdown: https://docs.teloring.com/markdown/api/list-business-hours.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every named schedule, with the holidays that will next close it. Schedules are what Studio branches on and what reports use to separate "slow reply" from "out of hours". **Scope:** `business_hours` --- # Get the conversation-attribute schema Source: https://docs.teloring.com/api/list-conversation-attributes Markdown: https://docs.teloring.com/markdown/api/list-conversation-attributes.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The account's conversation-attribute schema: the custom fields a conversation can carry. `api_id` is the key you use when writing values at `PATCH /v1/conversations/{id}/custom-attributes`, and `type` decides what a value may be — the write endpoint enforces it. Read-only on purpose. This is a *schema*, and reshaping it from a machine credential would silently invalidate values on conversations that already carry them. **Scope:** `conversation_attributes` --- # List conversations Source: https://docs.teloring.com/api/list-conversations Markdown: https://docs.teloring.com/markdown/api/list-conversations.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Conversations in one status bucket, filtered and paginated. `status` defaults to `open`, which also folds in `missed` — a missed call is an open conversation nobody has picked up, not a separate queue. Filters combine with AND; repeated values within one filter combine with OR, and may be sent either repeated (`?label=vip&label=urgent`) or comma-separated (`?label=vip,urgent`). Two filters take sentinel values: `assignee_id=unassigned` finds the waiting line, and `team_id=none` finds conversations no team owns. Fetching a large `status=resolved` set? Add `created_after` / `created_before`. Open buckets stay small; the resolved archive does not. Request --- # List credit transactions Source: https://docs.teloring.com/api/list-credit-transactions Markdown: https://docs.teloring.com/markdown/api/list-credit-transactions.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Credit movements, newest first — every spend, top-up and refund, with where the credits came from. Request --- # List a customer's contacts Source: https://docs.teloring.com/api/list-customer-contacts Markdown: https://docs.teloring.com/markdown/api/list-customer-contacts.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The channel identities linked to this customer — what you pass as `contact_id` when starting a conversation. Request --- # List one customer's records Source: https://docs.teloring.com/api/list-customer-object-records Markdown: https://docs.teloring.com/markdown/api/list-customer-object-records.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Records of one object type belonging to one customer. Request --- # List object types Source: https://docs.teloring.com/api/list-customer-objects Markdown: https://docs.teloring.com/markdown/api/list-customer-objects.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every object type in the account, with its field definitions. **Start here.** Each object's `id` is what you pass as `object_id` everywhere else, and `fields[].key` is what goes in a record's `data`. The account's own custom objects appear alongside the seeded ones (Contacts, Deals, Service Calls, Tasks, Notes). Request --- # List customers Source: https://docs.teloring.com/api/list-customers Markdown: https://docs.teloring.com/markdown/api/list-customers.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Customers in the account, filtered and paginated. `search` is a case-insensitive substring match over name, phone, email, industry and address. When you have an exact identifier, `GET /v1/customers/search` is the better call. Request --- # List a dashboard's graphs Source: https://docs.teloring.com/api/list-dashboard-graphs Markdown: https://docs.teloring.com/markdown/api/list-dashboard-graphs.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The graphs on one dashboard. `?include=values` computes each one. Request --- # List dashboards Source: https://docs.teloring.com/api/list-dashboards Markdown: https://docs.teloring.com/markdown/api/list-dashboards.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every dashboard in the account. `is_default: true` marks the dashboard Teloring seeds for a new account. It is an ordinary dashboard — it can be renamed and rearranged — the flag exists so an integration can find "the main one" without matching on a name that might be in Hebrew. --- # List files Source: https://docs.teloring.com/api/list-files Markdown: https://docs.teloring.com/markdown/api/list-files.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Files in the warehouse, newest first — attachments customers sent in, files agents sent out, and uploads from forms and knowledge bases. Request --- # List a form's submissions Source: https://docs.teloring.com/api/list-form-submissions Markdown: https://docs.teloring.com/markdown/api/list-form-submissions.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; List a form's submissions Request --- # List forms Source: https://docs.teloring.com/api/list-forms Markdown: https://docs.teloring.com/markdown/api/list-forms.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every form in the account, with its submission count and public URL. Request --- # List holiday calendars Source: https://docs.teloring.com/api/list-holidays Markdown: https://docs.teloring.com/markdown/api/list-holidays.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Holiday calendars available to schedules, with their dates for a year. Both kinds are returned: the calendars Teloring maintains (Jewish Israeli holidays, Christian holidays) and any the account added itself. **Scope:** `business_hours` Request --- # List inboxes Source: https://docs.teloring.com/api/list-inboxes Markdown: https://docs.teloring.com/markdown/api/list-inboxes.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every inbox in the account, with the id you pass as `inbox_id`. Provider secrets — access tokens, webhook signing keys, mailbox passwords — are never included. No endpoint on this API returns them. **Scope:** `conversations` or `messages`. Request --- # List invoices Source: https://docs.teloring.com/api/list-invoices Markdown: https://docs.teloring.com/markdown/api/list-invoices.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Issued tax invoices, newest first. Only issued documents appear. An invoice still being generated, or parked after a provider rejection, is ours to resolve — it is not a row you should see and wonder about. The PDF is not linked here: download URLs are minted per request and expire. Request --- # List indexed chunks Source: https://docs.teloring.com/api/list-knowledge-base-chunks Markdown: https://docs.teloring.com/markdown/api/list-knowledge-base-chunks.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The indexed passages in a knowledge base — literally what the AI can see. This is the endpoint that lets you audit a knowledge base: if the assistant is answering oddly, the answer is usually visible here. Filter to one source with `source_id`, or pass `include_content=false` for metadata only, which is much cheaper when walking a large base. Embedding vectors are never returned: a thousand floats per chunk, meaningless outside the model that produced them, and they would dwarf every other field. Request --- # List sources Source: https://docs.teloring.com/api/list-knowledge-base-sources Markdown: https://docs.teloring.com/markdown/api/list-knowledge-base-sources.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The sources in a knowledge base, with their ingestion status. `processing` means the worker is still chunking and embedding; `ready` means it can be retrieved from; `failed` means ingestion could not complete. Poll this after adding a source. Request --- # List knowledge bases Source: https://docs.teloring.com/api/list-knowledge-bases Markdown: https://docs.teloring.com/markdown/api/list-knowledge-bases.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every knowledge base in the account. Requires the Knowledge Base AI capability to be switched on. When it is off the endpoint answers `403` with `code: feature_disabled` — deliberately, so a client can tell "switched off" from "nothing indexed yet". --- # List messages Source: https://docs.teloring.com/api/list-messages Markdown: https://docs.teloring.com/markdown/api/list-messages.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Messages in a conversation, oldest first by default. Private notes are included. Pass `include_private=false` to get only what the customer actually saw — usually what you want when syncing a transcript somewhere else. Request --- # List an agent's notifications Source: https://docs.teloring.com/api/list-notifications Markdown: https://docs.teloring.com/markdown/api/list-notifications.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The notifications in one agent's bell, newest first. Reading this **never marks anything as read**. In the console, opening the bell is a human deciding they have seen something; a background job polling for new items must not clear that badge out from under the person it belongs to. `meta.unread_count` carries the badge number alongside the page. Request --- # List records across all customers Source: https://docs.teloring.com/api/list-object-records Markdown: https://docs.teloring.com/markdown/api/list-object-records.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every record of one object type, across every customer. This is how you ask "all deals that closed this month" without walking the customer list. Filter on a field's value with `field.=`, for example `?field.stage=Won&field.owner=agent_12`. Comparison is case-insensitive string equality, so select lists and free-text fields behave the same way; use `created_after` / `created_before` for date ranges. This query is served by a Firestore collection-group index. If that index is still building, the endpoint answers `503` with `code: index_required` rather than returning a partial list — fall back to the per-customer endpoint in the meantime. Request --- # List quick replies Source: https://docs.teloring.com/api/list-quick-replies Markdown: https://docs.teloring.com/markdown/api/list-quick-replies.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Quick replies in the account. By default this returns the shared (`account`) replies **plus** every agent's personal ones — the full library, which is what a credential managing it wants. Narrow with `scope`, or with `agent_id` for one agent's personal replies. Request --- # List categories Source: https://docs.teloring.com/api/list-quick-reply-categories Markdown: https://docs.teloring.com/markdown/api/list-quick-reply-categories.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The categories quick replies can be filed under. --- # List roles Source: https://docs.teloring.com/api/list-roles Markdown: https://docs.teloring.com/markdown/api/list-roles.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The roles defined in this account, for use as `role_id` when creating or updating an agent. Read-only. Roles decide what a *person* can reach in the console, and editing that matrix from a machine credential is the kind of privilege change that should leave a human's fingerprints on it. --- # List documents Source: https://docs.teloring.com/api/list-signature-documents Markdown: https://docs.teloring.com/markdown/api/list-signature-documents.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every document in the signature library. `status=active` are the ones with signature fields placed, and therefore the only ones a signing link can be created for. `status=draft` still need a pass through the console's editor. Request --- # List signed documents Source: https://docs.teloring.com/api/list-signed-documents Markdown: https://docs.teloring.com/markdown/api/list-signed-documents.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Completed and declined signings, newest first. A declined signing carries the reason the signer gave. Request --- # List signing links Source: https://docs.teloring.com/api/list-signing-links Markdown: https://docs.teloring.com/markdown/api/list-signing-links.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Signing links. `status=pending` is the waiting-to-sign list. Request --- # List block and trigger types Source: https://docs.teloring.com/api/list-studio-block-types Markdown: https://docs.teloring.com/markdown/api/list-studio-block-types.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; The catalog of every block and trigger Studio offers, with each one's settings schema. This describes the platform rather than the account, so it is identical for everybody — fetch it once and cache it. --- # List flows Source: https://docs.teloring.com/api/list-studio-flows Markdown: https://docs.teloring.com/markdown/api/list-studio-flows.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every flow in the account, most recently edited first. `live` flows are running against incoming conversations right now; `draft` have never been published, and `paused` were stopped deliberately. `has_unpublished_changes` tells you a live flow has edits that are not yet in effect. Request --- # List teams Source: https://docs.teloring.com/api/list-teams Markdown: https://docs.teloring.com/markdown/api/list-teams.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Every team in the account. `?include=members` adds each team's roster. Request --- # Get the usage price list Source: https://docs.teloring.com/api/list-usage-pricing Markdown: https://docs.teloring.com/markdown/api/list-usage-pricing.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; What each metered action costs in credits: an outbound SMS, a WhatsApp template by category, a signing link. Use it to estimate a campaign before running it. Each row's `id` is the same `usage_item_id` that appears on a credit transaction, so costs reconcile after the fact. Request --- # List WhatsApp templates Source: https://docs.teloring.com/api/list-whats-app-templates Markdown: https://docs.teloring.com/markdown/api/list-whats-app-templates.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Approved WhatsApp templates for one inbox, with how many body variables each expects. Call it before sending a template: `name` and `body_variable_count` are what you need to build the send. Only templates with `status: approved` can be sent. A non-WhatsApp inbox returns an empty list rather than an error, so a client can call this uniformly. Request --- # Messages Source: https://docs.teloring.com/api/messages Markdown: https://docs.teloring.com/markdown/api/messages.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Reading and sending inside a conversation. **Scope:** `messages` Channels are not interchangeable here. WhatsApp closes a 24-hour window after the customer's last message, after which only approved templates may be sent; TikTok has a 48-hour window and a per-window message cap; voice conversations accept private notes only. Each rule is enforced before the send, with a specific error `code`, rather than surfaced as a provider failure afterwards. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Notifications Source: https://docs.teloring.com/api/notifications Markdown: https://docs.teloring.com/markdown/api/notifications.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z An agent's bell feed. **Scope:** `notifications` Read-only, and deliberately non-destructive: reading the feed here does not clear the badge a human has not looked at yet. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Profile Source: https://docs.teloring.com/api/profile Markdown: https://docs.teloring.com/markdown/api/profile.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z One agent's personal settings and notification preferences. **Scope:** `profile` Email and password cannot be changed here. Both are identity rather than profile: an email change must be confirmed from the address itself, and a password can only be set by the person who owns it. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Quick replies Source: https://docs.teloring.com/api/quick-replies Markdown: https://docs.teloring.com/markdown/api/quick-replies.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Saved snippets agents insert into a conversation. **Scope:** `quick_replies` `account` replies are shared with everyone; `personal` ones belong to a single agent and are addressed by `agent_id`. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Release a hold Source: https://docs.teloring.com/api/release-conversation-hold Markdown: https://docs.teloring.com/markdown/api/release-conversation-hold.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Release a hold early and return the conversation to its queue. Request --- # Search customers Source: https://docs.teloring.com/api/search-customers Markdown: https://docs.teloring.com/markdown/api/search-customers.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Find customers by an exact identifier, or by free text. Prefer `phone` or `email`: those are exact, index-backed matches and the natural way to answer "do I already have this company?" before creating a duplicate. `q` falls back to the same substring search the list endpoint uses. At least one of the three is required. Request --- # Send a message Source: https://docs.teloring.com/api/send-message Markdown: https://docs.teloring.com/markdown/api/send-message.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Send a message, an internal note, or a WhatsApp template. `type` selects the shape of the request: | `type` | What it sends | Required | | --- | --- | --- | | `text` *(default)* | A plain text message | `content` | | `media` | A file by URL | `content` (an https URL), `content_type` | | `note` | An internal note, never delivered to the customer | `content` | | `template` | An approved WhatsApp template | `template.name` | ### The WhatsApp 24-hour window WhatsApp only accepts free-form messages within 24 hours of the customer's last message. Outside it, this endpoint answers `409` with `code: whatsapp_window_closed` **before** contacting the provider, and the error carries `details.last_customer_message_at` so you can show the operator why. Send a template instead — that is what templates are for. ### Other channel rules - **TikTok** — 48-hour window plus a per-window message cap; text and image only. - **Voice** — private notes only. - **SMS** — costs credits per segment. Insufficient credits answers `402`. - **Templates** — cost credits by category (`utility`, `marketing`, `authentication`). Pass the right one: it decides the price. Request --- # Switch a capability on or off Source: https://docs.teloring.com/api/set-ai-feature Markdown: https://docs.teloring.com/markdown/api/set-ai-feature.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Turn one AI capability on or off. Most of these consume AI credits every time they run — check `GET /v1/billing/usage-pricing` before enabling one across a busy account. The response carries `changed`, which is `false` when the capability was already in the requested state. Note that switching a feature on does nothing if the account's plan does not include AI World at all: the plan gate is checked where the feature runs, so `GET /v1/billing/plan` is where that shows up. Request --- # SSO Source: https://docs.teloring.com/api/sso Markdown: https://docs.teloring.com/markdown/api/sso.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z Signing one of your agents straight into the console from your own system. **Scope:** `sso` The most powerful thing in this API, and the most tightly controlled. The scope alone grants nothing: the credential must also name the agents it may impersonate, and (for iframe embedding) the origins allowed to frame the session. Links expire in ten minutes and work exactly once. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Studio Source: https://docs.teloring.com/api/studio Markdown: https://docs.teloring.com/markdown/api/studio.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z The automations built on the Studio canvas. Read-only. **Scope:** `studio` A flow is a graph of blocks at coordinates, wired through named handles. This API lets you see which flows exist, whether they are live, and how every block is configured. Editing a flow is a visual act and stays in the console. ```mdx-code-block import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; ``` --- # Update account details Source: https://docs.teloring.com/api/update-account Markdown: https://docs.teloring.com/markdown/api/update-account.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Update the account's general and invoicing details. **`billing_country` is guarded.** An Israeli account cannot be moved: the country already determined the VAT on invoices that have been issued. Attempting it answers `400` with `code: country_locked`. `billing_country_locked` on the GET tells you in advance. Invoice fields — `business_tax_id`, `business_address`, `business_city`, `business_contact_name` — are audited separately from the rest, because they are printed on legal documents. Request --- # Update an agent Source: https://docs.teloring.com/api/update-agent Markdown: https://docs.teloring.com/markdown/api/update-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Update an agent's profile, role or activation state. **Email and password cannot be changed here** — both answer `400` with `code: field_not_editable`. They are identity rather than profile: an email change re-keys the global login index and must be confirmed from the address itself, and a password can only be set by the person who owns it. The account's last Owner cannot be moved off Owner or deactivated. That answers `400` with `code: last_owner` — an account must never be able to lock itself out of its own product. Request --- # Update an agent's profile Source: https://docs.teloring.com/api/update-agent-profile Markdown: https://docs.teloring.com/markdown/api/update-agent-profile.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Update display name, timezone, language or contact details. `timezone` is an IANA name such as `Asia/Jerusalem`, and it is validated — a typo is a `400` rather than a profile that silently renders every timestamp in UTC. Email, password and `role_id` are rejected here with `code: field_not_editable`. The first two are identity, not profile; roles belong to `PATCH /v1/agents/{agent_id}` under the `agents_teams` scope. Request --- # Update an AI agent Source: https://docs.teloring.com/api/update-ai-agent Markdown: https://docs.teloring.com/markdown/api/update-ai-agent.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Only the fields you send change. Request --- # Update a schedule Source: https://docs.teloring.com/api/update-business-hours Markdown: https://docs.teloring.com/markdown/api/update-business-hours.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; System schedules cannot be edited — those answer `403` with `code: system_schedule`. Request --- # Update a conversation Source: https://docs.teloring.com/api/update-conversation Markdown: https://docs.teloring.com/markdown/api/update-conversation.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Change assignment, routing, priority, flag, labels, subject or status. Only the fields you send are touched. `status` accepts `open`, `pending` and `resolved`. Moving **to** `on_hold` is not allowed here, because a hold carries a deadline — use `POST /v1/conversations/{id}/hold`. Moving **out** of on-hold by setting another status works and clears the deadline. Two assignments have side effects worth knowing about: - Assigning a **team** whose auto-assign rule is on immediately hands the conversation to a random online member. - Assigning an **AI agent** starts an AI session; the response carries an `assignment` object with its `ai_session_id`. Assigning a human to a conversation an AI is handling ends that session silently — the human takeover the console does. Request --- # Set custom attribute values Source: https://docs.teloring.com/api/update-conversation-custom-attributes Markdown: https://docs.teloring.com/markdown/api/update-conversation-custom-attributes.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; A partial merge: attributes you do not mention keep their value. Send `null` for one to clear it. Values are validated against the account's schema (`GET /v1/conversation-attributes`), so an unknown attribute id, or a value outside a select list, is a `400` naming the field rather than bad data stored quietly. Writing an attribute does **not** move the conversation up the queue — filing information is bookkeeping, not a customer interaction. Request --- # Update a customer Source: https://docs.teloring.com/api/update-customer Markdown: https://docs.teloring.com/markdown/api/update-customer.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Only the fields you send change. Changing `lifecycle_stage` writes a journey event. Request --- # Update a record Source: https://docs.teloring.com/api/update-customer-object-record Markdown: https://docs.teloring.com/markdown/api/update-customer-object-record.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Only the fields present in `data` change. Status transitions write journey events — a deal moving to `Won` or `Lost`, a service call being resolved. Request --- # Update notification settings Source: https://docs.teloring.com/api/update-notification-settings Markdown: https://docs.teloring.com/markdown/api/update-notification-settings.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Replace an agent's notification settings. Turning the `push` channel off — or the master `enabled` switch — also deletes that agent's stored browser push subscriptions, so the pushes actually stop rather than the toggle merely looking off. Request --- # Update a quick reply Source: https://docs.teloring.com/api/update-quick-reply Markdown: https://docs.teloring.com/markdown/api/update-quick-reply.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Only the fields you send change. Request --- # Update a team Source: https://docs.teloring.com/api/update-team Markdown: https://docs.teloring.com/markdown/api/update-team.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Only the fields you send change. Sending `agent_ids` replaces the whole roster. Request --- # Set a profile picture Source: https://docs.teloring.com/api/upload-agent-avatar Markdown: https://docs.teloring.com/markdown/api/upload-agent-avatar.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; `multipart/form-data` with an `avatar` part — PNG, JPEG, GIF or WebP, up to 5 MB. The upload is validated by decoding the image, not by trusting its `Content-Type`: a file that merely claims to be a PNG is rejected. The returned `avatar_url` is an authenticated proxy path, never a public Cloud Storage URL — a person's face should not be permanently addressable by anybody who once saw the link. Request --- # Upload a PDF Source: https://docs.teloring.com/api/upload-signature-document Markdown: https://docs.teloring.com/markdown/api/upload-signature-document.md Section: API Reference Last modified: 2026-08-20T20:52:05.000Z import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; import ParamsDetails from "@theme/ParamsDetails"; import RequestSchema from "@theme/RequestSchema"; import StatusCodes from "@theme/StatusCodes"; import OperationTabs from "@theme/OperationTabs"; import TabItem from "@theme/TabItem"; import Heading from "@theme/Heading"; import Translate from "@docusaurus/Translate"; Upload a PDF into the signature library. `multipart/form-data` with a `file` part. The document arrives as a **draft**. It cannot be sent for signature until somebody places the signature fields in the console's editor — a signature field is a coordinate on a page, and a JSON body of pixel offsets is not a contract anybody should have to write. That is why this returns `status: "draft"` rather than something immediately usable. Request