Administration & Settings

Administration & Settings: overview

Overview The Administration & Settings area brings together everything that governs your Conversa Labs account: who has access, with which permissions, in which teams, with which business hours, integrations, audit logs, branding and notification preferences. It is the control panel of your operation. Think of this category as the place where you set the rules of the game — before you start handling conversations. Each product module (CRM, Payments, Calendar, Follow-ups and others) has its own settings, documented in the matching categories of this Help Center; here you find what is shared across all of them. Prerequisites - An active Conversa Labs account. - A user with the Administrator role (most screens in this category are admin-only). - Some features are optional and depend on your plan or a specific enablement: custom roles and audit logs, for example, are premium features and may not appear if they are not enabled for your account. Step by step 1. Open the account Settings from the left sidebar. 2. Start with the Account tab: company name, language, time zone and branding. 3. Invite your Agents and organize them into Teams. 4. Define roles and permissions (default roles or, if available, custom roles). 5. Configure business hours, labels and custom attributes. 6. Connect the integrations you need (Slack, webhooks, API and more). 7. Review audit, notifications and, where applicable, whitelabel and Custom Scripts. Settings & options - Account: identity, language, time zone and basic branding. - Agents and teams: who handles conversations and how work is distributed. - Roles and governance (RBAC): what each person can see and do. - Business hours, labels and attributes: the structure that organizes conversations and contacts. - Integrations: connections to external tools and the API. - Audit, whitelabel, scripts and notifications: governance, branding and advanced customization. Use cases - Standardize permissions for a growing team. - Make sure each agent only sees what concerns them. - Connect the platform to Slack, an external CRM or your own automation via webhooks/API. - Track who did what with audit logs. Tips, limits & best practices - Configure account, teams and permissions before inviting many agents. - Prefer roles over per-user tweaks: easier to maintain and audit. - Periodically review integrations and API tokens that are no longer in use. Troubleshooting - I can't see a settings tab: it may require the administrator role or a premium feature that is not enabled — talk to the account owner. - A change had no effect: confirm you saved and that the feature depends on an enablement (flag/plan). See also - Account, agents and teams - Custom roles and governance (RBAC) - Business hours, labels and attributes - Integrations - Audit logs

Account, agents and teams

Overview These are the three foundations of your operation: the account (identity and general preferences), the agents (the people who handle conversations) and the teams (groups of agents that organize the queue and conversation assignment). Setting them up well from the start avoids rework as the team grows. - The account defines company name, default language, time zone and branding. - Agents are the users with access, each with a role (permissions). - Teams group agents by function, product or shift and help route conversations. Prerequisites - The Administrator role to edit the account, invite agents and create teams. - The email addresses of the people you'll invite. - An idea of how you want to organize the team (by channel, product, shift, etc.). - Optionally, a square PNG, JPEG, GIF, or WebP icon for each team. Step by step 1. Account: in Settings, open the account tab and adjust name, language and time zone. 2. Agents: open the agents area and use the invite option. Enter the email and role; the person receives an email invitation to set a password. 3. Teams: create a team, give it a clear name, upload an optional icon, decide whether it allows auto-assignment and add the member agents. Without an image, Conversa Labs generates an icon from the team's initials. 4. Connect teams to your inboxes and assignment rules as needed. 5. Review the agent list and remove/deactivate anyone no longer on the team. Settings & options - Language and time zone: affect business hours, reports and automated messages. - Agent role: defines permissions (see the roles and governance article). - Availability: each agent can appear as online/busy/offline, influencing assignment. - Team with auto-assignment: distributes new conversations among available members. - Team icon: identifies the team in settings, the sidebar, assignment selectors, bulk actions, access scopes, integrations, and reports. You can upload, replace, or remove it at any time; removing it restores the generated initials. - Auto-Resolve: resolves conversations with no activity after the configured time (minutes, hours or days), optionally sending a closing message and applying a label. By default, conversations awaiting an agent's reply are protected and never auto-resolved; the option "Also resolve conversations awaiting an agent's reply — not recommended" is an explicit opt-in to include them. See the dedicated Auto-Resolve article. Use cases - Separate Support, Sales and Billing into distinct teams. - Route conversations from a specific WhatsApp number to the responsible team. - Scale the team by adding agents to an existing team, without reconfiguring everything. Tips, limits & best practices - Use self-explanatory team names — they appear in filters and reports. - Prefer a square image that stays clear at small sizes. Files may be up to 15 MB; PNG, JPEG, GIF, and WebP are supported. - Set the right role at invite time so you don't grant overly broad access. - Deactivate agents who left instead of leaving them active and unused. Troubleshooting - The invitation didn't arrive: ask them to check spam and confirm the email; resend the invitation if needed. - Conversations aren't being distributed: check that the team has auto-assignment on and that agents are available (online). - The icon wasn't accepted: confirm the file format and 15 MB limit. If an image cannot load, the interface keeps the team initials visible so its identity is never lost. - I can't invite agents: the plan limit may have been reached or your role lacks permission — talk to the administrator. See also - Custom roles and governance (RBAC) - Business hours, labels and attributes - Notifications and preferences - Administration overview

Account timezone

Overview The account timezone is the single time reference for your workspace. It decides two things at once: - How a time is saved. When someone picks "21/07/2026 15:59" as a task due date, that time is interpreted in the account timezone. - How a time is displayed. The same commitment shows the same time on the dashboard, on the board card, in the notification email, in the generated PDF and in the CSV export. In practice, the team sees one clock. An agent in São Paulo, another in Lisbon and an automated email all show 15:59 for the same commitment — because the authority is the account, not the computer of whoever is looking. What stays on the reader's own clock: conversation and message timestamps and activity trails ("5 minutes ago", "yesterday at 14:20"). Time there is relative to the reader by design, and that does not change. Prerequisites - Administrator profile, to edit account settings. - Knowing which timezone represents your operation — usually where the team sits, or where most of your customers are. Step by step 1. Open Settings → Account. 2. Find the Timezone field. 3. Pick your timezone from the list (for example, (GMT-03:00) Brasilia). 4. Save. From then on, every business date and time created or edited uses that timezone. Platform operators can also view and adjust an account's timezone from the Super Admin console, under Accounts → edit account. The value is the same in both places. Settings & options | Where | What it does | |---|---| | Settings → Account → Timezone | Sets the timezone for the whole account | | Event timezone (Calendar) | An event may carry its own timezone, which takes priority over the account's | | Super Admin → Accounts | Lets the operator view and correct an account's timezone | If the field has never been filled in, Conversa Labs uses the timezone provided during initial signup. If there is none, it falls back to UTC — and in that case it is worth setting the correct value. Use cases - Distributed team. Agents in different cities and countries agree on deadlines without doing mental conversions. - Campaign delivery. A campaign scheduled for 09:00 goes out at 09:00 in the account timezone, no matter who scheduled it. - Contracts and documents. The date printed on the PDF matches the one on screen. - Exported reports. The date column in the CSV matches the dashboard. Tips, limits & best practices - Existing records are not converted. Dates saved before the timezone was set stay as they were, so older and newer records may carry different interpretations. When reviewing an important older commitment, check the time and reschedule it if needed. - Changing the timezone moves nothing. Changing it changes how everything is displayed, not the instant that was stored. A commitment still happens at the same moment; only the number on screen changes. - Daylight saving time is handled for you. In timezones that observe it, a time that simply does not exist (the hour the clock skips) is adjusted to just after the jump, and a repeated hour resolves to the first occurrence. The field tells you when it makes that adjustment. - Dates without a time have no timezone. A date-only field (just the day) is never converted — and should not shift a day when the timezone changes. Troubleshooting The time shown is a few hours off from what I typed. Check the timezone under Settings → Account. If the record was created before the timezone was set, it predates the correction: reopen the item and save the intended time again. Each teammate sees a different time. That points to a screen still tied to the browser clock. Note where it happened (which page and which field) and send it to support, with an example of the expected and the displayed time. The email shows one time and the dashboard shows another. Confirm both refer to the same record and the same field. If the difference persists, send support the email you received along with a link to the record. I cannot find my timezone in the list. The list covers the world's standard timezones. If yours is missing, pick one with the same offset and the same daylight saving rule, and let support know. See also - Account, agents and teams - Business hours, labels and attributes

Account language and dashboard language

Overview There are two languages on the platform, and they are independent. Mixing them up is the most common reason a customer receives an email in a language nobody chose, while the operator swears the platform is fully set to their own language. | Language | Where it is set | Who it affects | |---|---|---| | Dashboard language | In your profile (Preferred Language) | Only you. It is the language of the menus, buttons and screens you work in | | Account language | In Settings → Account (Site language) | Your customers. It is the language of everything the platform generates and sends out | The dashboard language is a personal preference: each agent can pick their own, and one agent's choice never affects another's — nor what the customer receives. The account language is different — it is the authority for every piece of content generated for the person on the other side: - Automated emails — conversation transcript, appointment notification, task reminder, password reset, invitation. - Bot and AI assistant replies — the language the automated agent answers in by default. - Help center and public pages — portal, booking page, public contract signing page, affiliate portal. - Ready-made templates — the task, pipeline, product and sequence templates the platform ships already translated. - Satisfaction surveys and automated messages in general. What changed Accounts used to be born in English and nobody noticed. The reason is subtle: the operator almost always has their own language picked in their profile, so they read the dashboard in their own language — while every message generated for the customer went out in English, because those read the account language. Worse: "English because nobody ever chose" and "English because someone chose it deliberately" were byte-for-byte the same stored value. There was no way to tell them apart. Now there is a choice marker, written the moment the language is saved on an already-existing account. From then on: - No marker (the language was never saved): the account follows the dashboard language of the account's first administrator. It is the only real signal the platform has about which language that operation works in. - With a marker (someone saved it): exactly what was chosen applies, forever. Nothing infers anything on top of it. And in the account settings, a highlighted notice appears whenever the two languages diverge — with a shortcut to adopt your dashboard language for customers as well. Prerequisites - Administrator profile, to edit account settings. - Knowing which language your customers should be served in. That is usually the language of your market, not the language of your team. Step by step 1. Check your dashboard language. Open your Profile (avatar in the corner) → Preferred Language. This is the language only you see. If it is set to Use account default, your dashboard follows the account language and no divergence is possible. 2. Check the account language. Open Settings → Account and find the Site language field. Right below it there is a note explaining that this is the language your customers receive. 3. Look for the notice, if any. If your dashboard language and the account language differ, a notice appears just below the field, telling you which language your customers are currently receiving. It offers a shortcut to adopt your dashboard language for customers too. 4. Choose and save. Select the correct language and click Save Changes. Saving is what makes the choice definitive. Even if you re-pick exactly the language already shown on screen, the act of saving writes the marker and locks the decision. From then on, no inference overrides your choice. Settings & options | Where | What it does | |---|---| | Profile → Preferred Language | Language of your dashboard. Does not affect customers or other agents | | Profile → Preferred Language → Use account default | Your dashboard follows the account language | | Settings → Account → Site language | Language of everything the platform generates for the customer | | Divergence notice (Settings → Account) | Appears when the two languages differ, with a shortcut to align them | | Super Admin → Accounts | Platform operators can also view and adjust an account's language | When the notice does not appear: when the two languages already match, or when you never picked your own language in your profile (you are on Use account default). In that second case there is no divergence to point out — you read exactly what your customers receive. Use cases - A Brazilian operation born in English. You serve customers in Portuguese, your dashboard is in Portuguese, but transcript emails were arriving in English. Just open Settings → Account, pick Portuguese (Brazil) and save. - A bilingual team. You prefer to work with the dashboard in English, but your customers are Brazilian. Leave your profile in English and the account in Portuguese. The divergence notice will show up — and in this case it is purely informational, because the setup is deliberately correct. - An operation that really does serve in English. Open Settings → Account, re-pick English and save. That writes the marker and protects the choice from any future inference. - A new account. On the first visit, set the account language together with the name and the timezone. It is a two-minute setting that prevents months of messages in the wrong language. Tips, limits & best practices - An account has a single language. If you serve customers in different languages, the account language is the default for what the platform generates on its own. Whatever an agent types by hand in the conversation is still free, in any language. - Changing the language does not rewrite the past. Emails already sent and messages already delivered stay exactly as they went out. The change applies from the moment you save onwards. - Content you wrote is not translated. Canned responses, macros, templates you created and articles you published remain exactly in the language they were written in. The account language governs only the text the platform generates. - The inference uses the account's first administrator, and only when that administrator has picked a dashboard language among those the platform offers. If they are on Use account default, or their language is not one of the available ones, the stored value stays as it is. - HONEST LIMIT — legacy accounts that chose English on purpose. If your account uses English intentionally but nobody ever saved that choice on the settings screen, it is now treated as "never set" — and it may start following the administrator's dashboard language. If English is intentional, open Settings → Account, re-pick English and save. A single save locks the choice permanently. It is worth doing even if nothing looks wrong. - Verify after changing. The fastest way to confirm is to trigger a test email (for example, send a conversation transcript to yourself) and check the language. Troubleshooting My customers received emails in English and I never asked for that. This is exactly the problem described above. Open Settings → Account, pick the correct language in the Site language field and save. From then on all new content goes out in the right language. I do not see the divergence notice. Either the two languages already match, or your profile is on Use account default — in which case you read the dashboard in the same language your customers receive, so there is nothing to warn about. I changed my dashboard language and the customers' language changed too. Is that expected? It only happens while the account language has never been saved. Without that save, the account follows the administrator. Open Settings → Account, pick the language customers should receive and save — from then on the two are independent. I want English, but after the update the account started sending in Portuguese. That means the English choice was never saved and the account administrator reads the dashboard in Portuguese. Re-pick English in Settings → Account and save. The choice is then locked. One specific email arrived in the old language. Check whether it was generated before the change — content already sent is not rewritten. If it is text someone on the team wrote (a macro, a canned response, your own template), it does not follow the account language: it has to be edited. The help center is still in another language. Published articles have their own language, set when they were published. The account language does not translate existing articles. See also - Account timezone - Account, agents and teams - Profile, security and account

Roles & Access and governance (RBAC)

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

Business hours, labels and custom attributes

Overview Three simple settings that make the operation much more organized: - Business hours: define when your team is available per inbox, enabling automatic off-hours messages. - Labels: colored tags to classify conversations (and contacts) by subject, priority or status. - Custom attributes: tailored fields to store business-specific information on conversations and contacts. Prerequisites - The Administrator role to create/edit these settings. - The account time zone set correctly (it affects business hours). - An idea of the taxonomy that makes sense for the team (which labels and which fields). Step by step 1. Business hours: in the inbox settings, enable business hours, choose the days and time ranges and set the off-hours message. 2. Labels: in the labels area, create each label with a name, description and color; apply them to conversations from the conversation side panel. 3. Custom attributes: in the attributes area, create a field with a name, type (text, number, list, date, etc.) and whether it applies to a conversation or a contact. 4. Use labels and attributes in filters, views and automations for productivity. Settings & options - Hours per inbox: each channel can have its own schedule. - Off-hours message: automatic reply when no one is available. - Label colors: help visually identify the type of conversation. - Attribute types: text, number, link, dropdown list, date, checkbox and more. Use cases - Auto-reply outside business hours and set a return expectation. - Tag conversations as urgent, refund or lead and filter by them. - Store an order number or contracted plan as a contact attribute. Tips, limits & best practices - Keep a lean, standardized set of labels — too many tags become clutter. - Combine labels with automations to tag conversations automatically. - Use attributes for what you'll actually filter on or use in reports. Troubleshooting - The off-hours message doesn't fire: check that business hours are enabled on the inbox and the account time zone is correct. - The label doesn't appear for the team: confirm it was saved and the agent has access to the inbox. - An attribute doesn't show on the conversation/contact: check that it was created for the right type (conversation vs. contact). See also - Account, agents and teams - Integrations - Administration overview - Notifications and preferences

Integrations: providers, credentials, OAuth, webhooks and API

Overview Integrations connect Conversa Labs to the rest of your ecosystem. From the integrations area you enable ready-made connections and create your own extension points: - Slack: mirror conversations in a Slack channel and reply from there. - Dialogflow: connect a Dialogflow bot for automated replies. - Notion and Linear: bring conversation context into your productivity and engineering tools. - Shopify: pull order/customer data from your store into support. - Credential-based providers: connect translation, video, CRM, AI, voice and search with your own keys or service accounts. - Webhooks: receive platform events at your own endpoint, in real time. - Dashboard Apps: embed your own web app in the conversation or account sidebar, with native audience, order and compatibility controls when enabled. - API: automate and integrate via access tokens. Prerequisites - The Administrator role to configure integrations. - Credentials/accounts for the tools you'll connect (for example, a Slack workspace, a Dialogflow project, a Shopify store). - For webhooks/API: an accessible endpoint and/or an access token generated in the account. Step by step 1. Open the Integrations area in Settings. 2. Pick the integration. On credential forms, the shortcuts above the fields include the provider's name: - Get provider credentials opens the official key or service-account page; - Open provider console opens the API or console that must be enabled, when applicable; - View provider setup documentation opens the corresponding official guide. 3. Fill in the fields with data from the same project/account and finish creating the connection. 4. For webhooks, register your endpoint URL and select the events of interest; validate receipt in your system. 5. For the API, generate an access token (profile/agent) and use it in authenticated calls. 6. Test the integration with a real conversation before going to production. Settings & options - Authorization-based connections (Slack, Shopify, etc.): follow the external tool's login. - Key/project-based connections (Dialogflow, Google Translate, Dyte, LeadSquared, and AI, voice, or search providers): require the provider's credentials. - Webhooks per event: you choose which events to receive. - API tokens: treat them like passwords; revoke them if leaked or unused. Use cases - Notify a Slack channel when a new conversation arrives. - Automatic triage with a Dialogflow bot before reaching an agent. - Create a Linear issue from a customer-reported bug. - Show Shopify order data right on the conversation screen. - Sync events with your CRM or ERP via webhooks. Tips, limits & best practices - Start with one integration, validate the flow, then add others. - For webhooks, implement idempotency and respond fast (process in the background). - Store tokens in your system's environment variables — never in public source code. - Review integrations and tokens periodically; remove what's no longer used. Troubleshooting - The integration won't connect: check credentials/permissions and try re-authorizing. - The webhook isn't arriving: verify the URL is public, returns success (2xx) and is subscribed to the right events. - API 401 error: the token is wrong, expired or revoked — generate a new one. - I don't see the integration I want: it may depend on the plan or a specific enablement. See also - Dashboard Apps: native surfaces, audience and security - Custom Scripts: inject JS/CSS - Custom roles and governance (RBAC) - Audit logs - Administration overview

Dashboard Apps: native surfaces, audience and security

Overview Dashboard Apps embed an external web application inside Conversa Labs. With native surfaces enabled, an authorized manager can install each app in the conversation or the account sidebar, control who can see it, and migrate from the legacy integration without interrupting existing apps. The feature switch is deliberately off by default. While it is off, existing Dashboard Apps continue to use the legacy conversation experience; native installation screens and APIs are unavailable. Prerequisites - An account Administrator, or a custom role with integration_manage permission. - The dashboard_apps_native_surfaces feature enabled for the account exclusively by Super Admin. - An app URL reachable from every agent's browser. Use HTTPS in production. - Permission for the app URL to be embedded: its CSP frame-ancestors policy must allow the exact Conversa Labs origin, and it must not send a conflicting X-Frame-Options header. Step by step 1. Open Settings → Integrations → Dashboard Apps and select Add a new dashboard app. 2. Enter a recognizable name and the exact HTTP(S) URL. Query strings and fragments are preserved; use them only for non-sensitive static parameters such as tenant, language, or route. 3. In the same guided form, choose where the app should appear: - Conversation displays it with the selected conversation context. - Sidebar displays it at account level. Choose one of the native categories — Support, Contacts & CRM, Applications, Commercial, Productivity, Automation, Growth, or Analytics & Settings —, select an icon, and review the direct-item preview before saving. 4. Choose the compatibility mode: - Legacy keeps the previous iframe messaging behavior while you migrate. - V2 uses the versioned Dashboard App SDK bridge and requires a distinct origin. - Dual temporarily supports legacy and V2 during a controlled migration. 5. Under Data and identity, review what each V2/dual installation may receive. The complete default includes current-user email, signed identity and, in conversations, contact email and phone. Disable only what the app does not need; session/API tokens are never granted. New native apps preselect V2 and show these grants before creation. Legacy/dual displays its broader legacy-context warning. 6. Save. The app and selected surfaces are created together, enabled and initially visible to the whole account. 7. On the app card, edit each surface to enable or disable it and change its category, icon, readable position, capabilities, or audience. Positions use First and After..., with no manual numbers. Use Add location later when you want to include a location that is not configured yet. 8. Under Audience, All makes it available to eligible account members. Selected can restrict it to administrator/agent roles, teams and individual users; matching any selected criterion grants visibility. 9. A sidebar app becomes a direct item in the selected category. The Applications group sits immediately below Contacts & CRM and appears only when at least one visible app is assigned to it. Position is normalized per category; conversation positions are normalized among app tabs. 10. Select Test on the configured location. The preview uses the real URL, query string, hash, sandbox, and bridge. Under V2 the result confirms the handshake. Under Legacy validation is visual and the dialog says so. Under Dual the dialog lists each bridge separately — read that breakdown: agents keep working through the legacy lane even when V2 fails, so the overall status can read ready while the migration is blocked. 11. Also test with one administrator and one regular agent before expanding the audience. Settings & options - One app can have at most one installation on each surface. - An installation exposes surface, compatibility_mode, enabled, position, sidebar_category, sidebar_icon, capabilities, and audience. Category and icon exist only on sidebar resources, use closed enums, and are selected through the visual picker. - Core account, current-user, permissions, appearance and installation capabilities are required. Conversation, contact and message capabilities exist only on the conversation surface. Email/phone and identity:assertion are explicit grants configurable per installation. - Audience is an access boundary, not merely a visual filter. A user who is outside it must not receive that installation through the interface or API. - Administrators and custom roles with integration_manage can manage installations and inspect audience details. Their management list can include visible: false rows because they are disabled or outside the manager's own audience, but those rows never mount in conversation, sidebar or a deep link. Other agents see only enabled installations that match their role, team or user identity. - Reordering is optimistic: if another administrator changed the installation first, reload the list before trying again. Use cases - Show CRM or order context beside a conversation. - Put an account-wide operations panel in the sidebar. - Integrate CRM and ERP with email, WhatsApp, SMS and other inbox conversations through the same omnichannel context; the app receives allowed IDs/context, never channel-provider credentials. - Roll out a new internal app to one team before enabling it for everyone. - Move a legacy conversation app to the V2 bridge with Dual, validate it, then select V2. Tips, limits & best practices - Use HTTPS and a separate app origin. V2 rejects same-origin embedding because origin isolation is part of its trust boundary. - Never put API tokens, passwords or personal data in the URL. Query strings and fragments are useful for static parameters but can appear in browser history and the app server logs. The host preserves existing parameters and, in V2/dual, adds only cl_* names for dashboard origin, IDs, surface, protocol and locale. Every cl_* name is reserved: the host removes static values in that namespace and writes back only the permitted launch parameters. - Native creation requires exactly one HTTP(S) frame. When the feature is enabled, Super Admin prepares legacy apps with one frame and reports only truly incompatible definitions. - Grant the smallest practical audience and review team/user membership periodically. - Treat data delivered by the SDK as read-only context. Perform business changes through an authenticated backend and the REST API, where authorization and audit controls apply. - When an app backend or n8n must verify who opened the app, use the two-minute signed identity and public introspection. It proves account/user/installation identity but never authorizes REST/MCP. - The app can ask the host to resize its frame or open a link, but the V2 bridge is not a general proxy for arbitrary API calls. - Plain HTTP may be useful for local development, but browsers block mixed content when Conversa Labs itself runs over HTTPS. An HTTP warning does not bypass that browser protection. Troubleshooting - Native settings do not appear: confirm the feature is enabled for this account. The legacy Dashboard Apps integration remains available while the flag is off. - The feature cannot be enabled: only Super Admin can activate it. The operator prepares compatible apps; correct reported IDs so each app has exactly one HTTP(S) frame. - The frame is blank or says it was refused: use Test to reproduce the real configuration, then inspect the app response for CSP frame-ancestors and X-Frame-Options; allow the exact Conversa Labs origin. X-Frame-Options: SAMEORIGIN blocks every dashboard on a different origin, including localhost; Legacy removes the SDK requirement but does not bypass this browser policy. - HTTP works locally but not in production: serve the app over HTTPS. A secure page cannot embed active HTTP content in modern browsers. - V2 reports an unsafe origin: host the app on a different origin from Conversa Labs; changing only the path is not enough. - An agent cannot see the app: confirm it is enabled, installed on the expected surface, and that the agent matches at least one configured role, team or user selector. - The Applications group is missing: assign at least one enabled, visible app to the Applications category. The empty group is hidden automatically. - The order changed after saving: another administrator may have reordered the surface. Reload and submit the current version again. - The SDK handshake times out: the dashboard re-sends the invitation for up to 10 seconds from frame load, so a timeout means the app did not answer within that window. Start with the app — it must call the SDK's connect() as soon as its page loads. Then verify the dashboard origin passed to the SDK, embedding headers, protocol version and that no proxy strips browser messaging behavior. Under Dual, use the per-bridge breakdown in Test to see the V2 error; to see it raw, switch the installation to V2 temporarily. - Email or phone is missing: confirm V2/dual and the current_user:email, contact:email and contact:phone capabilities. Contact data exists only on the conversation surface. - Identity returns capability_denied: enable identity:assertion and confirm the installation is active, visible to the user and the feature remains enabled. See also - Integrations: providers, credentials, OAuth, webhooks and API - Dashboard Apps SDK, REST API and MCP - Custom roles and governance (RBAC) - Audit logs

Audit logs

Overview Audit logs record the relevant actions taken in the account: configuration changes, agent and team management, permission changes and other administrative actions. They answer the question “who did what and when”, which is essential for security, compliance and incident investigation. Prerequisites - The Administrator role to access the logs. - Audit logs is a premium/optional feature and may not be enabled on your account. If the area doesn't appear, talk to the account owner or support. Step by step 1. In Settings, open the audit area (audit logs). 2. View the chronological list of events: actor (who), action (what), target and date/time. 3. Use the available filters to narrow the scope (by period, by action type, etc.). 4. Open a record to see the action details. 5. For external analysis, consider exporting/integrating via the API where applicable. Settings & options - Chronological view: events from newest to oldest. - Filters: help locate a specific action among many records. - Retention: history is available according to your plan's policy. - Native trail (Governance & LGPD): besides the premium logs, the account can enable the native audit trail, read from the Audit tab of Settings → Governance & LGPD — sign-ins, settings changes, role/routing template applies, agent and inbox changes, contact deletions and data subject requests, with admin-configurable retention. Use cases - Investigate when and by whom a setting was changed. - Confirm an agent's permission changes after a complaint. - Meet your company's compliance and security requirements. Tips, limits & best practices - Combine audit with well-defined roles: less broad access means fewer surprises in the log. - Review logs periodically, not only after incidents. - Logs are read-only — they record history and should not be edited. Troubleshooting - I can't see the audit area: the premium feature is not enabled for the account. - I can't find a specific action: adjust the filters (period/type) and confirm the action is one that's recorded in audit. - I need more history: retention depends on the plan — talk to the account owner. See also - Governance & LGPD - Custom roles and governance (RBAC) - Account, agents and teams - Integrations - Administration overview

Governance & LGPD

Overview The Governance & LGPD module gathers, inside the account Settings, everything the operation needs to serve LGPD/GDPR day to day: the contacts' consent registry, data subject requests (export or anonymize/erase a contact's data), central message retention, the DPO data (Data Protection Officer) and the native audit trail. It also hosts Presentation Mode, which blurs sensitive data for demos and screen recordings. Prerequisites - Administrator profile (or a custom role holding the governance permissions — governance management, data export, data erasure and audit viewing). - The Governance & LGPD feature enabled on the account. The Audit tab additionally requires the Audit Trail (Native) feature. If the area is missing, talk to the account owner. Step by step 1. Open Settings → Governance & LGPD. 2. On the LGPD tab, fill in the DPO name and email and, if desired, enable automatically request and register inbound consent. Configure the global message, per-channel overrides, privacy-policy URL, and accepted affirmative/negative replies. 3. Set the message retention (days): messages of resolved conversations older than the limit are redacted automatically every day (0 disables it). Conversation retention (days) removes resolved, inactive conversations in small batches; linked contracts and active legal holds always suspend removal. The canonical audit ledger is preserved. Commerce payload retention (days) removes buyer-identifying data from old events while preserving aggregate revenue values. 4. Set the audit trail retention (days) — older events are pruned. 5. To serve a data subject: search the contact in the Data subject requests section and choose Export data (generates a JSON bundle with the contact's profile — including masked tax ID, country, address and billing address —, company memberships and relationships, consent history, conversations, messages and attachment manifest, and emails a notification; it does not include CRM deals, payments, tasks, contracts or bookings) or Anonymize (scrubs the identifying data — name, email, phone, identifier, attributes, fiscal document, address and the company memberships/relationships — preserving the conversation history). 6. Track progress in the Request history list, which refreshes automatically while requests are pending or processing. If loading fails, use Try again. When the bundle is ready, use Download bundle: the platform checks your permission again and issues a temporary link. Settings & options - Manual/API consent: from the contact panel, read the history and append a declaration — purpose (data processing, marketing, cookies, custom), channel, granted or denied, and a note. The API also accepts structured evidence. History is immutable. A global (all) declaration is the current default; only channel declarations newer by event time/id are also current overrides. Older channel declarations remain visible but not current. - Automatic inbound consent: on the first inbound interaction for a contact/channel with no applicable data_processing declaration, the platform persists and sends the prompt through that channel's normal pipeline. The prompt is processed in the background, alongside bots, listeners, and automations — the inbound message never waits on it. A configured affirmative or negative reply appends a declaration with channel, response message, prompt message, and evidence. Automatic evidence stores technical IDs, the normalized matched token, and a SHA-256 digest — never the raw reply text. - Consent prompt wording, per language: the automatic prompt ships with built-in text, but you can write your own — and now per language. The text is chosen by the contact's language (falling back to the account language and finally to the wording you already had). A single text configured earlier keeps applying to every language: there is nothing to migrate. There is also a per-channel text, which wins over the general one. An {x} picker inserts the five accepted placeholders — {{contact_name}}, {{privacy_policy_url}}, {{dpo_email}}, {{affirmative_token}} and {{negative_token}}; anything else is stripped on send, and the platform refuses the save telling you which placeholder does not exist (in any of the languages). An empty field shows the built-in text that really goes out, and Restore default deletes your version of that language for real (the removal reaches the server, it does not just vanish from the screen). - Prompt preview and test: the preview renders the text per channel, with a real contact's name and the tokens the matcher accepts; the test really sends it to a conversation you pick. You validate the wording without waiting for the next inbound. - Legal holds: the Legal holds tab lists the conversations retention must never remove — not by age, not by inactivity. Search the conversation by contact, number or inbox, give the reason (a court order, say) and place it. A hold is released, never deleted: the record keeps who placed it, who released it and when, because that is precisely the evidence a legal hold exists to produce. Only administrators and roles with manage data governance place or release holds; export/erase holders can read the list to understand why a conversation survived a sweep. - Consent badge: the contact panel shows the state in force — Granted, Denied, or Pending. With more than one channel the badge shows the worst state, so a refusal can never hide behind a grant on another channel; hover it for the channel-by-channel reading. A channel the contact never declared on simply does not appear — absence is not pendency. - Unrecognized reply: if the contact answers with something that cannot be read as a decision, the platform stops asking and flags the conversation with Consent pending. Settle it with the contact and record the declaration by hand from the panel. - Campaigns: contacts who explicitly refused are removed from the audience. The preview reports how many were excluded, and the note appears only when a refusal actually shrank the list. Someone who was never asked, or whose grant expired, still receives it — asking for consent is the prompt's job, not the campaign's. - Deliberate boundary: this mode requests and records; it does not quarantine the inbound message, pause automations until a decision, or ever block outbound. The UI therefore makes no technical-blocking promise. If the operation's legal policy requires all processing to stop, enforce that restriction in the operational flow in addition to this registry. - Safe customization: the prompt can be global or channel-specific and supports only contact_name, privacy_policy_url, dpo_email, affirmative_token, and negative_token, each wrapped in double braces. Replies are matched case-insensitively and ignore accents and edge punctuation. An affirmative token cannot also be negative; the API rejects ambiguous configurations and legacy ambiguity never records a decision. Unsupported placeholders and Liquid tags are rejected; legacy values are stripped before sending so they cannot expose data. - Anonymize with message redaction: optionally the anonymization also redacts the contact's inbound message content and purges attachments. - Mandatory confirmation: anonymization/erasure requires typing the contact id — a guard against accidental destructive actions. Use cases - Serve a formal data-subject request (LGPD art. 18) with an auditable receipt. - Periodically sanitize the base with central message retention. - Prove the marketing legal basis with the per-contact consent history. Tips, limits & best practices - The export runs in the background; the requester receives an email that returns them to the authenticated Governance area. Only Administrators and roles with data export can issue the temporary bundle link; governance management or data erasure alone do not grant file access. - Anonymization does not delete the conversation — it deletes the identity. For full removal, use erasure (contact deletion), aware that the conversation history is removed with it. - Every governance action leaves an event in the audit trail (when enabled). - Prompt, grant, and denial have distinct audit actions; retries are idempotent and the contact row lock prevents two concurrent prompts. - Companies in DSR: a contact's export and anonymization already include their Companies memberships and relationships (names, roles, dates and notes). What stays separate is fiscal-document masking (Presentation Mode/RBAC) and the governance of the Company as an entity — see the Companies & relationships article. Troubleshooting - The area is missing: the feature is not enabled on the account or your profile lacks the permission. - A request shows "Failed": check the error detail on the list and retry; the failure event is also recorded in the audit trail. - The prompt was not sent: check the Governance & LGPD feature, inbound consent control, and whether a global or channel declaration already exists. Any prior state (granted or denied) prevents another prompt. A prompt marked failed by the delivery provider is retried on the next inbound message, once per contact/channel. - A reply was not recognized: check the configured tokens; the message must match one complete token. Add required variants as comma-separated values. See also - Presentation Mode - Audit logs - Custom roles and governance (RBAC) - Companies and relationships

Presentation Mode (data blurring)

Overview Presentation Mode blurs the dashboard's sensitive data — avatars, contact names, phones and emails, message content, media previews, deal values and agent names — so you can record tutorials, run demos and share your screen without exposing PII. The administrator picks which categories blur; each agent switches the mode on and off whenever needed. Prerequisites - The Governance & LGPD feature enabled on the account. - The "Offer presentation mode to the agents" switch turned on by the administrator in the hub — the button is not pinned to the sidebar; it only shows while that switch is on. - To configure the categories: Administrator profile. - To toggle it: any agent on the account. Step by step 1. (Administrator) Open Settings → Governance & LGPD → Presentation mode, turn on the "Offer presentation mode to the agents" switch and the categories that should blur. The preview beside it reflects the choices in real time. 2. (Any agent) Click the Presentation mode button (crossed-eye icon) at the sidebar footer — or use the Cmd/Ctrl+Shift+P shortcut. 3. Record the screen or run the demo normally: conversations, contacts, Companies, CRM, payments, tasks, WhatsApp Web panels, Captain and library show blurred. 4. Click again (or repeat the shortcut) to switch it off — everything is restored instantly. Settings & options - Categories (account-wide): avatars, contact names, phones, emails, fiscal documents (CPF/CNPJ) and addresses, message content, media previews, deal/payment values and agent names. The phones and emails switch covers the contact's fiscal documents and addresses in the same category. - Per-agent state: the on/off is individual and persists across page reloads. - No hover-to-reveal: nothing is exposed by accident during a recording. Use cases - Record an internal tutorial or onboarding video without leaking customer data. - Present the CRM pipeline to third parties hiding the deal values. - Provide screen-shared support preserving the contacts' privacy. Tips, limits & best practices - The blur is visual (in the browser of whoever enabled it) — it never changes the data nor affects other agents. - Enable only the categories you need: blurring everything makes feature demos harder. - Category changes made by the administrator leave an event in the audit trail. Troubleshooting - The button is missing: the Governance & LGPD feature is not enabled on the account, or the administrator hasn't turned on the "Offer presentation mode to the agents" switch in the hub. - Nothing blurs when switched on: no category is active — ask the administrator to configure them in the Governance hub. See also - Governance & LGPD - Audit logs

Dynamic variables {{ }}

Overview Dynamic variables let you write one message that arrives personalised for every person. Instead of "Hello!", you write Hello {{ contact.first_name }}! and each contact receives their own name. A variable is always written between double braces and resolved on the server, at send time — never in the browser. If the data does not exist, the variable becomes empty text and the rest of the message goes out normally. Every variable uses the same vocabulary on every surface: what works in the reply composer works identically in an email, a campaign, a follow-up, a flow and a contract. Prerequisites - None. The basic variables (contact, account, inbox, agent) work from day one. - A module's variables (charge, booking, contract, order…) only carry a value once that module is in use in the account. With no data they resolve to empty — they never break the message. Step by step 1. Open any text field that accepts variables (composer, macro, canned response, campaign, follow-up, contract, booking reminder…). 2. Type {{ — the variable list appears automatically. 3. Or click the {x} Insert variable button when it is available in the field header. 4. Search by name (for example "amount" or "due") and click to insert. 5. Check the value before sending. Inside a conversation, every variable in the list shows what it will produce for that contact — the real name, the real charge amount, the real booking date. What you see there is exactly what the customer will receive. 6. Send a test before firing at your whole base. Settings and options The available groups | Group | What it is for | Example | |---|---|---| | Contact | Who is on the other side | {{ contact.first_name }} | | Conversation | The current conversation | {{ conversation.display_id }} | | Account / Brand | Your company | {{ account.name }} · {{ brand.name }} | | Agent | Who is answering | {{ agent.available_name }} | | Date and time | The clock, in the account timezone | {{ now.date }} · {{ now.weekday }} | | CRM deal | The deal linked to the contact | {{ crm.title }} · {{ crm.value_formatted }} | | Organization | The contact's company | {{ organization.legal_name }} | | Charge | The most recent charge | {{ payment.pay_url }} · {{ payment.due_date_formatted }} | | Subscription | The recurring plan | {{ subscription.next_due_date_formatted }} | | Order | The most recent order | {{ order.amount_formatted }} | | Booking | The contact's appointment | {{ booking.date_formatted }} · {{ booking.manage_url }} | | Contract | The open contract | {{ contract.sign_url }} | | Task | The task linked to the contact | {{ task.due_at_formatted }} | | Cart and checkout | Sales recovery | {{ commerce.pay_url }} | | Product | The product being quoted | {{ product.price_formatted }} | | Group | WhatsApp group / launch cohort | {{ group.invite_url }} | | Team · SLA · Availability | Operations | {{ team.name }} · {{ wfm.online }} | | Satisfaction · Engagement | Relationship | {{ csat.rating }} · {{ engagement.tier }} | | Salesperson · Goal · Commission · Affiliate | Sales | {{ seller.name }} · {{ affiliate.referral_code }} | | Ad · Lead | Paid acquisition | {{ lead.headline }} | | Article | Help Center | {{ article.url }} | | Account Brain | AI signals | {{ brain.risk_band }} | The picker only shows the groups that work on that screen. A campaign, for instance, has no conversation, so conversation variables are not offered there. Formatted values Every money and date value exists in two forms: - Raw — the value as stored: {{ crm.value_amount }} → 1500.0 - Formatted — ready for the customer to read: {{ crm.value_formatted }} → $1,500.00 The same applies to dates: {{ payment.due_date }} → 2026-08-08 and {{ payment.due_date_formatted }} → 08/08/2026, always in your account's currency, language and timezone. If a value has no formatted sibling, you can format it inline with a filter: {{ payment.amount | money: 'USD' }} → $1,500.00 {{ booking.starts_at | datetime }} → 08/08/2026 02:30 PM Custom fields The custom fields you created also become variables, in the form {{ contact.custom_attribute.key }}. This works for custom fields on contacts, conversations, organizations, deals, products, tasks, groups, charges, bookings, follow-ups and contracts. Use cases - Overdue charge: Hi {{ contact.first_name }}, your invoice of {{ payment.amount_formatted }} was due on {{ payment.due_date_formatted }}. Pay here: {{ payment.pay_url }} - Booking reminder: Your appointment is on {{ booking.date_formatted }} at {{ booking.time_formatted }} with {{ booking.host }}. Need to reschedule? {{ booking.manage_url }} - Contract: {{ contact.first_name }}, your contract "{{ contract.title }}" is ready: {{ contract.sign_url }} - Group invite: Welcome! Join {{ group.name }}: {{ group.invite_url }} Tips, limits and best practices - Always send a test. It is the fastest way to see whether the variable brought the value you expected. - Missing data becomes empty. Write the sentence so it still reads correctly without the value — avoid "Your order of has arrived". - In campaigns, take extra care. If a variable used in the approved template does not resolve for a recipient, that recipient is skipped. Prefer variables you are certain exist. - Tax ID: in messages the tax ID only ever appears masked ({{ contact.masked_tax_id }}). The full document is exclusive to contracts, which the person signs themselves. - Do not invent variables. If it is not in the picker it does not exist, and it will render empty. - Where the value does not show. Outside a conversation (macro, canned response, campaign, contract template) there is no contact yet, so the list shows only the variable name. That is the correct behaviour: the variable has no owner there yet. - If your role hides a field, the value shows hidden too. An agent who sees a***@example.com on the contact record sees a***@example.com in the variable list — it is the sent message that carries the real value. Troubleshooting | Symptom | Likely cause | What to do | |---|---|---| | The message arrived with a literal {{ ... }} | The variable was typed into a field that does not resolve variables | Use the picker — it only appears where variables work | | The variable came out empty | The data does not exist for that contact | Check the record; rewrite the sentence to work without the value | | The value rendered as 1500.0 | You used the raw form | Switch to {{ ...value_formatted }} | | The date is off by one day | The account timezone is not what you expected | Adjust the timezone in Account settings | | The campaign skipped recipients | A variable in the approved template had no value | Review the template and use safer variables | | The "undefined variables" warning appears on a variable that works | The variable genuinely has no value for this contact | Look at the value next to it in the list: if it is blank, the data is not on record | See also - Account, agents and teams

Whitelabel (your own brand)

Overview Whitelabel lets you replace the default brand with your brand: installation name, logos, accent colors, icons and your own domain. The result is a platform that looks entirely yours to your team and your end customers. Whitelabel configuration is done at the platform operator/administration level (it's not a per-customer-account preference), because it affects the look of the whole installation. Prerequisites - Operator/super administration access to the platform (or a request to whoever runs the installation). - Ready brand assets: light and dark logo, icon/favicon, color palette. - For a custom domain, access to that domain's DNS. Step by step 1. Access the platform administration panel (super admin). 2. Open the brand/whitelabel configuration. 3. Set the installation name shown across texts and titles. 4. Upload the logos (light/dark) and the icon/favicon. 5. Adjust the accent colors to match your visual identity. 6. Configure the custom domain (and certificate), pointing DNS per the instructions. 7. Save and verify in an incognito tab, checking logo, colors and page title. Settings & options - Installation name: replaces product references in the interface and emails. - Logos and icon: appear on login, in the sidebar and in the browser tab. - Colors: align the interface with your identity. - Custom domain: uses your URL instead of the default domain. Use cases - An agency delivering the platform as its own product to clients. - A company that wants its support hub with the corporate identity. - Standardizing emails and login screens with the company brand. Tips, limits & best practices - Use logos with a transparent background and versions for light and dark themes. - Test on small screens: the icon and name also appear on mobile. - After changing the domain, confirm that links (including this Help Center) remain valid. Troubleshooting - I can't find the whitelabel options: they live in platform administration — ask the installation owner for access. - The logo didn't update: clear the browser cache and reload; confirm the upload was correct. - The custom domain won't open: review the DNS pointing and certificate per the instructions. See also - Custom Scripts: inject JS/CSS - Administration overview - Account, agents and teams - Guided Tours

Custom Scripts: inject JS/CSS into dashboard, portal and widget

Overview Custom Scripts let you inject custom JavaScript and CSS into three surfaces of the platform: - Dashboard: the panel used by your support team. - Portal: the public Help Center site. - Widget: the chat embedded on your website. This lets you add behaviors (e.g., track events, show a notice) or styling tweaks (e.g., hide/highlight elements) without changing the platform's code. It's a powerful feature, which is why it lives in platform administration. Prerequisites - Operator/super administration access to the platform. - JavaScript/CSS knowledge (the script runs in the browser of whoever uses the chosen surface). - An environment to test before publishing (ideally outside production). Step by step 1. Access the platform administration panel and open the Custom Scripts area. 2. Create a new script with: surface (dashboard, portal or widget), type (JS or CSS) and when it should run (run on). 3. Paste your code. In JS scripts, use the context object (ctx) provided by the platform to interact safely with the surface. 4. Teardown: scripts that add elements/listeners should remove them when requested, to avoid accumulating side effects in SPA navigation. 5. Save, enable and test on the matching surface before rolling out to everyone. Settings & options - Surface: choose which environment the script runs in (dashboard, portal or widget). - Type: JavaScript (behavior) or CSS (style). - When to run (run on): controls the execution moment/context. - Active/Inactive: turn a script on or off without deleting it. Use cases - Add a temporary notice/banner on the team dashboard. - Hide or restyle a portal element to match your brand. - Fire an analytics event when the widget opens. Tips, limits & best practices - Keep scripts small and idempotent; always implement the teardown. - Avoid heavy external dependencies — they affect the surface's performance. - Version your code outside the platform and document what each script does. - Because it's code injection, treat it as high impact: review before publishing. Troubleshooting - The script doesn't run: check the chosen surface, that it's active, and the run-on moment. - Something broke on screen: disable the script and use the browser console to see errors. - The effect duplicates on navigation: the teardown is missing — remove added elements/listeners. - I can't find the Custom Scripts area: it's in platform administration — ask the installation owner for access. See also - Whitelabel (your own brand) - Integrations - Administration overview - Guided Tours

Notifications and preferences

Overview Notifications tell you what needs attention: new conversations, assignments, mentions, replies and module events. Each agent controls their own preferences, choosing where they want to be alerted: - In-dashboard: the notification bell inside the platform. - Email: summaries and alerts in your inbox. - Push: alerts in the browser and/or the mobile app. Prerequisites - Being signed in with your user (preferences are per agent). - For browser push: allow notifications when the browser asks. - For mobile push: have the app installed and an active session. Step by step 1. Open your profile and go to the notifications/preferences area. 2. Choose the events you want to be alerted about (e.g., new assigned conversation, mention, reply). 3. Select the notification channels for each event (dashboard, email, push). 4. If you'll use browser push, authorize notifications in the browser prompt. 5. Save and test by generating a conversation/mention to validate. Settings & options - Per event: toggle each alert type individually. - Per channel: dashboard, email and push independently. - Default for a new member: no email alert comes turned on. A new agent only gets the push for conversations assigned to them; to receive emails, tick the events you want in the Email column and save. - Sound/visual: audible alerts and unread counters in the dashboard. - Per-agent preferences: each person tunes their own, without affecting the team. Use cases - Receive push only for conversations assigned to you. - Use email for an end-of-day summary and the dashboard for real time. - Make sure mentions always alert, even with the rest muted. Tips, limits & best practices - Avoid turning everything on: too many notifications become noise and get ignored. - Prioritize assignments and mentions — usually what matters most. - If push doesn't arrive, start by checking browser/system permissions. Troubleshooting - I don't get browser push: check the site's notification permission and that it isn't blocked at the operating system level. - I don't get emails: check spam, your profile email and that the event is enabled. - I get too many notifications: reduce events/channels in your preferences. - Preferences won't save: reload the page and try again; confirm you're signed in. See also - Account, agents and teams - Business hours, labels and attributes - Guided Tours - Administration overview

Maestro & AI: configuration and integration health

Overview Maestro is the platform's AI engine: it powers the account Brain, the copilot, the agents and generative onboarding. The integration is managed by the operator in the admin console — no redeploy needed to change configuration. Prerequisites - Access to the operator console (Super Admin). - The Maestro service's internal URL and the admin key provided at deployment. Step by step 1. Open the operator console → Maestro settings. 2. Fill in the API URL (internal address) and, if applicable, the Public URL (used for agent webhooks). 3. Enter the admin key — it is masked and never displayed again. 4. Choose the onboarding mode for new accounts: off, guided (wizard) or automatic. 5. Set the default vertical template applied when signup carries no segment. 6. Save and use "Test connection" to validate. Settings & options - Maestro enabled: master switch. When off, every AI surface answers with a clear "disabled by the operator" state instead of connection errors. - Allow account keys (BYOK): controls whether accounts may use their own AI keys (see "AI tokens per account"). - Panel configuration takes precedence over environment variables; environments provisioned via variables keep working. Human-attendance pause When a conversation is assumed or assigned to a person, its pause state is stored durably and remains valid after restarting the API, workers or cache. Resume releases the agent only after a valid confirmation; an unknown state is treated as paused. Each agent also controls what to retain from inbound messages received during the pause: discard (default), keep only the latest, or keep a bounded set by count and age. Resuming never replays those messages by itself. Replay is a separate, explicit operator-confirmed action. To process a retained queue safely: 1. Remove the human assignee from the conversation if one is still assigned. 2. In the conversation's Maestro panel, select Resume and wait for confirmation. This action releases only new messages. 3. The Messages received during the pause card appears only after Resume is confirmed. 4. Select Process retained messages, review the impact and choose Confirm processing. Each attempt uses a unique retry-safe identifier: if the network response is lost, trying again does not process the same queue twice. Without confirmation, with an unknown state or while a human remains assigned, the platform keeps the queue blocked. Use cases - Rotate the admin key after a credential rotation without restarting services. - Enable automatic onboarding only after validating the guided flow on pilot accounts. Tips, limits & best practices - Rotate the admin key periodically and after any suspected exposure. - Keep the internal URL reachable only on the private network; expose only the public URL. Troubleshooting The diagnostics panel shows one of five states: - OK: service reachable and authenticated. - Authentication failed: the admin key doesn't match the service's — update one of the sides. - Unreachable: the URL doesn't respond (DNS, network, stopped service). The detail shows why. - Disabled: the "Maestro enabled" master switch is off. - Not configured: the admin key is missing. While the service is Unreachable or returns an invalid state, automatic replies, effectful tools and Follow-ups configured to honor human attendance remain blocked until the state is known again. If generative onboarding is active and Maestro is unavailable, accounts keep being provisioned with the vertical templates — nothing gets blocked. See also - AI tokens per account (BYOK) - Usage and consumption limits - AI onboarding

AI tokens per account (BYOK)

Overview Each account can use its own keys for AI providers (OpenAI, Anthropic, Google, Groq, xAI, DeepSeek, OpenRouter, Cohere, ElevenLabs) — known as BYOK (bring your own key). When the account provides no keys, the operator's global keys apply. Tavily shows up on the same screen, but it is there for a different reason: it is not a chat provider. No model ever runs on that key and it never appears in the bot's model chain — it is the key that unlocks the web search and page reading tools. Without it those two tools are unavailable; everything else in AI keeps working normally. Prerequisites - BYOK governance enabled by the operator (installation switch) and the capability active on the account. - Account administrator profile to register keys. Step by step 1. In the account: Settings → Integrations → open the desired provider. 2. Use Get provider credentials to create the key and View provider setup documentation to check the official guide; both shortcuts appear above the form. 3. Enter the key. It is then used by that account's AI features (Brain, copilot, agents, dictation). 4. To fall back to the global keys, disable the provider integration. Settings & options - Operator governance: the operator can turn BYOK off for the whole installation or for a specific account. With BYOK off: - the account's keys remain stored but stop being used; - new key writes are refused; - every AI feature falls back to the global keys. - Precedence: account key (BYOK on) → installation global key. Use cases - An enterprise customer that requires its own billing with the AI provider. - An operator who centralizes AI consumption on global keys to resell by package. Tips, limits & best practices - Never share keys between different customers' accounts. - Prefer keys with a spending limit configured at the provider. - Rotate compromised keys immediately — the change applies on the next request. Troubleshooting - "I can't save the key": BYOK is disabled by the operator for this account or the installation. - AI failing with quota errors: check the balance/limit of the key in use (account or global) at the provider's dashboard. See also - Maestro & AI: configuration and integration health - DeepSeek as a model provider for your bot - Web search: the bot looking things up on the public internet - Usage and consumption limits

Usage and consumption limits

Overview The platform measures the account's monthly consumption across five metrics: messages, conversations, contacts, AI requests and AI tokens. Totals are available to the account, to the operator and via API — the foundation for consumption-based plans and limit alerts. Prerequisites - Metering enabled on the account by the operator (usage metering capability). - Monthly limits are optional and defined by the operator per account. Step by step 1. In the account: follow the month's totals and recent history in the account usage area. 2. As operator: check any account's consumption in the admin console or via the platform API (GET /platform/api/v1/accounts/{id}/usage). 3. Limits: the operator sets monthly ceilings per metric (e.g. messages per month) on the account's limits. Settings & options - Metrics: messages, conversations, contacts, ai_requests, ai_tokens — aggregated per calendar month. - Monthly limits: configured per metric (<metric>_monthly). Without a limit, metering only accumulates. - Alerts: crossing 80% and 100% of a limit sends an installation webhook event — once per metric, per month. Use cases - Sell plans with a monthly message allowance and get an automatic alert at the ceiling. - Track AI cost per account before defining consumption-based pricing. Tips, limits & best practices - Metering is fail-safe: it never blocks the message flow — even if the counter storage fails, support keeps working. - The 80%/100% alerts are informational: this version has no automatic consumption blocking. - No retroactive counting: measurement starts when metering is enabled. Troubleshooting - Usage doesn't show in the account: the metering capability is off for the account. - Alert didn't arrive: confirm the installation events webhook URL and that the metric's monthly limit is configured. See also - Maestro & AI: configuration and integration health - AI tokens per account (BYOK) - Super Admin: accounts, plans and license

Guided Tours

Overview Guided Tours are interactive tutorials inside the platform itself. They highlight interface elements step by step (with a spotlight) and can include short videos to explain each feature, speeding up team onboarding without leaving the screen. Tours are modular and role-aware: each person sees the tour suited to their context, and progress is remembered per user (you resume where you left off). Prerequisites - Guided Tours is an optional feature and must be enabled for your account. If you don't see tours, they may not be active — talk to an administrator. - To attach or replace the video for each step, you need platform administration (super admin) access. The sequence and highlighted controls follow the installed product version. - Being signed in: tour progress is saved on your user. Step by step For the user (take a tour): 1. Open Guided tours in the sidebar footer (or search for a tour in the command bar). 2. Choose Start, Resume or Replay. A first-visit tour can also open automatically when autoplay is enabled for the account. 3. Follow the highlighted steps on screen; go forward, back or skip as needed. Multi-page tours navigate to the correct screen or tab for you. 4. Watch the short videos where available. 5. On completion, the tour is marked as seen for your user. For the administrator (manage content): 1. Enable the guided tours feature for the account. 2. In the platform administration panel, manage the per-step videos by their media key. 3. Publish and validate the experience from an agent's point of view. Settings & options - Role-aware: the displayed tour adapts to the user's context. - Permission-aware: management-only steps, such as gateway settings and reconciliation, appear only to people who can open those screens, including matching custom roles. - Per-user progress: each person resumes where they left off. - Steps with video: the administrator can attach short videos to each step. - Per-account opt-in: the feature is enabled by the account, not on by default. Catalog, Payments, Orders and Sales recovery each have their own tour. Together they cover the native lists, import/synchronization ledgers, plans, offers, subscriptions, reports, gateway connections, messages and reconciliation surfaces available to the current user. In the Catalog tour, the variants step opens the detail of a product already available to the current user and highlights the native variants panel. It does not create a product or contact an external provider. When no accessible product is loaded, the tour remains on the product list and shows the same guidance in a centered card. Use cases - Speed up onboarding of new agents without in-person training. - Introduce a new module to the team with a focused tour. - Reduce repeated questions by showing "where to click" right on screen. Tips, limits & best practices - Keep tours short and focused — a few steps per tour work best. - Use brief videos; they complement, not replace, the highlighted steps. - Re-present a tour after major interface changes. Troubleshooting - I don't see any tour: the feature may not be enabled for the account — talk to an administrator. - The tour doesn't resume where I left off: confirm you're signed in with the same user. - A step's video doesn't appear: the administrator needs to attach the video to that step in the platform panel. See also - Notifications and preferences - Account, agents and teams - Whitelabel (your own brand) - Administration overview

Team Management overview

Overview The Conversa Labs Team Management module gives your team a complete, contact-center-grade view of agent availability. On top of the platform's native presence (Online / Busy / Offline) you define your own work and break statuses — Lunch, Coffee, Meeting, On-site service and anything else — grouped into three sections: - Availability — the presence statuses (Online, Busy, Offline). - Timed breaks — breaks with a configured limit and a live countdown (e.g. Coffee 10 min). - Open breaks — breaks without a limit (Meeting, Training, External work…). Each status maps to a native availability, so when an agent goes on a break the platform automatically stops routing new conversations to them — no change to your routing rules. Every status change is recorded on an append-only timeline that powers the change history, adherence, time per status and the login/logout (sessions) report. Prerequisites - The Team Management module is optional and must be enabled for your account. If you can't find the Team Management area, ask an administrator to turn it on. - The monitoring board, per-agent detail and settings are available to administrators (and to custom roles granted the Team Management permissions). Any monitored agent can set their own status. Step by step Set your status (any agent) 1. Open the profile menu in the sidebar. 2. Pick a status from the grouped switcher (Availability / Timed breaks / Open breaks). Timed breaks show their limit next to the name. 3. If the status requires a reason, add a short note and confirm. 4. While you are on a break, a full-screen timer and/or a floating widget show the elapsed time, the configured limit and how much you have consumed. Use Go online to return. Monitor the team (supervisor) 1. Open Team Management from the sidebar. 2. Use the period filter (Today / This week / This month / This year / Custom). 3. The header shows live counts; the table shows each agent's live status, teams, inboxes, conversations, performance, CSAT and login/logout. 4. Click Details on any agent to open their performance page. Read a single agent (supervisor) The per-agent page shows the stat cards, the status timeline (adherence, total changes, average time per status, most frequent status) and the full change history with duration, expected limit and result (OK / Over / Ongoing). Settings & options - Status catalog — create, rename, recolor, reorder, set the section, the native availability, the time limit and the flags (productive, counts against adherence, requires a reason, full-screen takeover, floating widget). System statuses (Online/Busy/Offline) can be renamed and recolored but not deleted. - When the limit is exceeded (per timed break) — choose any combination of: flag it on the board, notify the agent, notify supervisors, return the agent to Online automatically, plus a grace period and a repeat-reminder interval. - Monitored agents — choose who appears on the board: all agents with exceptions, only selected agents, or by team / inbox. Optionally set an expected daily journey per agent. - Schedules — reusable weekly templates; generate planned shifts over a date range. - Queues — group agents and inboxes with a distribution policy on top of the native router. - General — adherence target, timezone and the day the week starts on. Use cases - Enforce coffee and lunch limits with a live countdown and an automatic return to Online. - Give supervisors a single screen to see who is available, on a break or offline right now. - Measure adherence and time per status to balance workload across a 25+ agent operation. - Reconstruct login/logout sessions per agent and period. Tips, limits and best practices - Breaks park the agent in Busy/Offline, so auto-assignment stops sending new conversations — keep "On-site service" or "Active chats" mapped to Online if those agents should keep receiving work. - The client-side timer is for the agent's experience; the server enforces the over-limit policy every minute, so limits are honored even if the browser is closed. - Keep the catalog short and meaningful — too many statuses make adherence harder to read. Troubleshooting - I don't see the module — it isn't enabled for the account, or you aren't an administrator. - An agent isn't on the board — check the enrollment mode and the agent's Monitored toggle. - A break didn't auto-return — confirm the timed break has an "auto-return" over-limit policy. See also - Reports & Analytics - Contacts & CRM

Agent statuses and breaks (Team Management)

Overview In the Conversa Labs Team Management module, every agent works on top of a status catalog that you customize. On top of the platform's native presence (Online / Busy / Offline) you create your own work and break statuses, organized into three sections: - Availability — the presence statuses (Online, Busy, Offline). - Timed breaks — breaks with a configured limit and a live countdown (e.g. Coffee 10 min). - Open breaks — breaks without a limit (Meeting, Training, External work…). Each status maps to a native availability. When an agent goes on a break, the platform parks them in Busy/Offline and auto-assignment stops routing new conversations to them — no change to your routing rules. While on a break, a full-screen timer and/or a floating widget show the elapsed time against the limit. If the time runs out, the over-limit policy decides what happens (flag, notify, return to Online…). Prerequisites - The Team Management module must be enabled for the account. With the module on, the grouped status switcher replaces the native availability picker (Online/Busy/Offline) for every agent. - The status catalog and the over-limit policy are for administrators (and custom roles granted the Team Management permissions). Any agent can change their own status from the grouped switcher. Step by step Build the status catalog (admin) 1. Open Team Management and go to the Status catalog tab. 2. The account starts with just the native Online / Busy / Offline trio. Use Templates to apply a ready status pack (lunch, coffee, meeting…), or Add status in any section to create your own. 3. For each status set the Section (Availability / Timed break / Open break), the Availability it maps to, color, icon, and the behavior flags. 4. Reorder within a section with the up/down arrows, edit with the pencil, and delete custom statuses with the trash. System statuses (Online/Busy/Offline) can be renamed and recolored but not deleted. Configure a timed break (admin) 1. Add or edit a status in the Timed breaks section. 2. Set the Time limit (minutes) — this drives the live countdown. 3. Choose the over-limit policy: flag it on the board, notify the agent, notify supervisors, return the agent to Online automatically, plus a grace period and a repeat-reminder interval. A per-status policy overrides the account default. 4. Optionally turn on Requires a reason, Full-screen takeover and Show floating widget. Switch your status during the day (any agent) 1. Open the profile menu in the sidebar and use Set your status. 2. Pick a status from the grouped switcher (Availability / Timed breaks / Open breaks). Timed breaks show their limit next to the name. 3. If the status requires a reason, add a short note and confirm. 4. The native availability is parked automatically (Busy/Offline), so auto-assignment stops sending new conversations. Use the break timer (any agent) 1. On a full-screen break, a full-screen timer takes over the whole app: current status, configured limit, an elapsed stopwatch with a progress ring, percent consumed and a Within limit / Over limit badge. It has no minimize and no close — the only way out is Go online. 2. On other breaks, a floating widget in the corner shows the status and elapsed time, with a quick Go online button. 3. The elapsed time comes from the server: reloading, reopening, duplicating or hiding the tab does not reset the timer, and the limit is enforced server-side even if the browser is closed. Settings & options Fields on each status: | Field | What it does | |---|---| | Name / Description | Identifies the status | | Section | Availability, Timed break or Open break | | Availability | The native presence it maps to (Online/Busy/Offline); drives auto-assignment | | Color / Icon | Appearance in the switcher, board and timer | | Time limit (minutes) | Timed breaks only; empty = no limit | | Counts as productive | Marks the time as productive in reports | | Counts against adherence | Includes the status in the adherence calculation | | Requires a reason | Opens a note dialog before applying the status | | Full-screen takeover | Shows the full-screen timer (no close) during the break | | Show floating widget | Shows the corner widget for breaks that aren't full-screen | | Active | Makes the status available or hidden in the switcher | Over-limit policy (per timed break, on top of the account default): - Flag it on the board — highlights the over-limit agent on monitoring. - Notify the agent — alerts the person on the break. - Notify supervisors — alerts supervision. - Return to Online automatically — ends the break and brings the agent back. - Grace period (seconds) — waits before applying the policy. - Repeat reminder every (seconds) — reminder frequency while over the limit. Catalog sections (families): | Section | Has a limit? | Examples | |---|---|---| | Availability | No | Online, Busy, Offline | | Timed breaks | Yes, with a countdown | Coffee 10 min, Lunch 60 min | | Open breaks | No | Meeting, Training, External work | Use cases - Enforce coffee and lunch with a live countdown and an automatic return to Online. - Let agents step away for a meeting (open break) without a timer. - Require a reason for certain breaks for auditing. - Keep "On-site service" mapped to Online so those agents keep receiving conversations even when "away from the chat". Tips, limits and best practices - Breaks park the agent in Busy/Offline, so auto-assignment stops — map to Online any status that should keep receiving work. - Time limit and over-limit policy apply only to timed breaks; open breaks have no countdown. - The full-screen takeover only exits with Go online — use it for breaks that must be strictly honored. - The client-side timer is the agent's experience; the server enforces the policy every minute, so an agent can't "shave time" by reloading, reopening or hiding the tab. - Keep the catalog short and meaningful — too many statuses make adherence harder to read. Troubleshooting - I still see the plain Online/Busy/Offline picker — the Team Management module isn't enabled for the account. - A timed break didn't auto-return — confirm the over-limit policy has "Return to Online automatically". - The full-screen timer won't close — that's by design; click Go online. If you expected a corner widget, turn off "Full-screen takeover" on the status. - I can't delete a status — it's a system status; you can rename and recolor it, but not delete. - The timer reset after I reloaded — it doesn't; the elapsed time derives from the server start time. See also - Team Management overview - Real-time monitoring board - Monitored agents (enrollment) - Schedules - Queues

Real-time monitoring board (Team Management)

Overview The Monitoring board is the Monitoring tab of the Conversa Labs Team Management area — a single screen for a supervisor to see, in real time, who is available, on a break or offline right now, and how each agent is performing over the selected period. It combines three blocks: - Live counts at the top — how many agents are Online, Busy, On break and Offline. - Roll-up cards — total agents, total conversations, average performance (response / resolution time) and average CSAT. - Per-agent table — live status, teams, inboxes, conversations, performance, CSAT and login/logout sessions, with a link to each agent's detail page. The board reads the pre-aggregated data in a single pass and overlays each agent's live status via ActionCable — so when someone changes status, their row updates instantly, with no reload and no polling. Prerequisites - The Team Management module must be enabled for the account. - The board is read-only and meant for administrators (and custom roles granted the Team Management permissions). It has no management action — it is for observation only. - An agent only appears in the table if they are part of the monitored agents set (defined by the enrollment mode). See the Agent enrollment article to choose who is monitored. Step by step Open the board 1. Open Team Management from the sidebar. 2. Go to the Monitoring tab. Read the live counts 1. At the top, read the four counters: Online (teal), Busy (amber), On break (violet) and Offline (slate). 2. Just below, the roll-up cards show: Agents (total monitored), Conversations (sum across all agents), Performance (average response time) and CSAT (average; shows — when there are no responses yet). Choose the period 1. Use the period filter: Today / This week / This month / This year / Custom. 2. In Custom, enter the start and end dates. 3. The period affects the time-bound metrics — performance, CSAT and sessions. Live status, teams and inboxes always reflect the current state. Read the per-agent table Each row shows: - Agent — avatar and name. - Status — the live status (with the colored dot). On breaks, a count-up timer shows how long the agent has been on that break; presence statuses (Online/Busy/Offline) show no timer. - Teams and Inboxes — the count; hover to see the names. - Conversations — the total, with the (open/resolved) split. - Performance — the average response time (or — when there is no data). - CSAT — the score as a percentage (or —). - Sessions — the number of logins in the period · the time of the last login. Open an agent's detail 1. Click Details on the agent's row. 2. You land on the agent performance page, with the status timeline, adherence and the full change history. Settings & options - Period filter — Today / This week / This month / This year / Custom. The week start and timezone come from the Team Management settings (General tab). - Refresh — the Refresh button re-pulls the aggregated numbers on demand; live status already arrives on its own over ActionCable. - Live status — overlaid on the aggregated board in real time; the dot and label reflect the agent's current status, colored from the status catalog. - Conversations — reflect the current state (open / resolved / pending), not the period window. - Sessions — derived live from the status timeline: each Online stretch counts as one login, and the board shows the count in the period and the time of the last login. Filter by team Next to the period filter, the Filter by team selector narrows the board (summary and rows) to the monitored agents that belong to the chosen team. The filter is applied server-side and lives on the URL (?team=), so a per-team view can be bookmarked/shared. It never widens the monitored set — it only trims the view. Use cases - Keep a single supervision screen to see, right now, who is available, on a break or offline. - Spot long breaks from the count-up timer without opening each agent. - Compare conversation load and response time across agents over the same period. - Quickly check logins and last access per agent before redistributing work. Tips, limits and best practices - The count-up timer appears only on breaks — presence (Online/Busy/Offline) has no timer, so a row with no timer is normal. - If an agent is missing, the cause is usually enrollment (monitoring mode), not the board. - For the Today period, performance and CSAT may use a live calculation before the aggregation job runs — the numbers stay consistent with the agent's page. - The board is observation only: to change a status, a limit or who is monitored, use the Team Management settings. Troubleshooting - An agent is missing — check the enrollment mode and the agent's Monitored toggle in Agent enrollment. - Status doesn't update live — confirm the real-time connection (ActionCable); use Refresh to re-pull the aggregates. - Performance/CSAT show — — there are no responses/ratings in the selected period; change the period or wait for data. - No timer on an Online agent — expected: the count-up is for breaks only. See also - Team Management overview - Agent statuses and breaks - Monitored agent enrollment - Schedules - Queues - Reports & Analytics

Per-agent performance & adherence (Team Management)

Overview The per-agent performance page in the Conversa Labs Team Management module brings everything you need to assess an agent into a single screen: a live header (avatar, role, teams, inboxes and the current status with a ticking clock), a period filter, the productivity cards (Conversations, Response time, Resolution time, Adherence, CSAT, Messages, Sessions), the status timeline (adherence, total changes, average time per status and most frequent status) and the full change history with duration, expected limit and result (OK / Over / Ongoing). The numbers come from the platform's native reporting (response/resolution-time rollups, CSAT, messages) combined with the agent's own append-only status timeline. Adherence is derived from the timed breaks finished within their limit — explained in detail below. Prerequisites - The Team Management module must be enabled for the account. If you can't find Team Management, ask an administrator to turn it on. - The detail page is available to administrators (and custom roles granted the Team Management permissions). - For the timeline, history and adherence to show content, the agent must have recorded status changes in the selected period. Step by step Open an agent's page 1. Open Team Management from the sidebar. 2. In the table, click Details on the agent's row. 3. Use the Back button or the breadcrumb (Team Management › agent name) to return to the board. Opening another agent reloads the data automatically. Read the header The header shows the avatar and name, the role, the teams and inboxes counts, and a current status chip with a colored dot and the elapsed time, which ticks live in the browser. Choose a period Use the period filter (Today / This week / This month / This year / Custom). The default is This month. Every card, the timeline and the history are recomputed for the chosen window. Read the cards | Card | What it shows | |---|---| | Conversations | Total conversations assigned to the agent (open + resolved). | | Response time | Average reply time over the period. | | Resolution time | Average time to resolve. | | Adherence | % of timed breaks finished within their limit (see below). | | CSAT | Satisfaction: positive ratings (4–5) over the total responses. | | Messages | Outgoing messages the agent sent in the period. | | Sessions | Number of login/logout sessions reconstructed from the timeline. | The page also shows the Teams and Inboxes counts alongside the other cards. Read the status timeline Below the cards, four tiles summarize the period: Adherence (the same % as the card), Total changes (how many status switches), Average per status and Most frequent status. A bar per status then shows the total time and the number of times in each status, with the width proportional to the longest-running status. Read the change history The table lists the most recent changes (up to 100) with the columns Status, Started, Duration, Expected (the configured limit, or — if none) and Result: - OK — the timed break ended within its limit. - Over — the timed break exceeded its limit. - Ongoing — it is the current status, still open. - — — not evaluated (e.g. a status with no time limit). Settings & options How adherence is computed Adherence counts only timed breaks that are flagged "counts against adherence" in the Status catalog and that have already ended (so the within/over-limit verdict exists). The formula is: Adherence % = timed breaks finished within their limit ÷ all evaluated counting timed breaks × 100. Key consequences: - The current status (still open) and open breaks (no limit) are not counted — they appear as Ongoing or — in the history. - Availability statuses (Online/Busy/Offline) do not affect adherence. - The time limits and the "counts against adherence" flag come from the Status catalog (see the Status & breaks article). Keeping them consistent is what makes the % meaningful. - The account's adherence target is set under General in the Team Management settings. - Each window's figures are computed on the server; if the detailed calculation fails, the page falls back to the persisted daily adherence rollup, so the detail never breaks. Other readings - Sessions are derived from the logged-in (Online/Busy) ↔ logged-out (Offline) transitions — there is no separate login log. - CSAT treats ratings 4–5 as positive and 1–2 as negative; the score is positives over the total. Use cases - Coach an agent using their adherence and the breaks that ran over the limit. - Reconstruct a day: time per status, status changes and login/logout sessions. - Compare response time, resolution time and CSAT for the same agent across periods. - Spot the most frequent status to right-size the catalog. Tips, limits and best practices - The current-status clock ticks live in the browser; the period totals are recomputed on the server each time you change the window. - The history shows the most recent 100 changes for the chosen window. - Open breaks (no limit) and the in-progress status show — / Ongoing and do not count toward adherence. - Adherence reflects only the timed breaks flagged "counts against adherence" — review those flags in the catalog so the % is meaningful. Troubleshooting - The cards show zeros — there was no activity in the period, or the agent produced no reporting events in the window; widen the period. - Adherence looks like 0% or 100% for no reason — check in the Status catalog which statuses have a time limit and the "counts against adherence" flag; open breaks don't count. - The timeline / history are empty — the agent had no recorded status changes in the period. - I opened another agent and see old data — the page reloads when you navigate between agents; refresh the screen if needed. See also - Monitoring board (Team Management) - Status & breaks (Team Management) - Agent enrollment (Team Management) - Schedules (Team Management) - Queues (Team Management) - Team Management overview

Schedules and planned shifts (Team Management)

Overview Schedules are reusable weekly templates that describe the expected journey of your operation inside the Conversa Labs Team Management module. Each schedule has a name, a timezone and an active flag. From a schedule you generate planned shifts over a date range: the platform materializes the recurring weekly blocks into concrete, dated shifts. Those planned shifts become the expected baseline — the "when the agent should be working" — that schedule adherence compares against the live status timeline. In other words, the schedule defines the plan, generation turns the plan into dated shifts, and adherence measures how closely the real presence matched that plan. In this version, the Schedules screen manages the template (name, timezone, active) and triggers shift generation. The per-weekday recurrence block map is authored via the API for now (the model and the generation job already consume it). A visual weekly editor is a future iteration. Prerequisites - The Team Management module is optional and must be enabled for your account. If you can't find the Team Management area, ask an administrator to turn it on. - The Schedules tab lives in the Team Management settings and is available to administrators (and to custom roles granted the Team Management permissions). - The per-weekday recurrence blocks (the repeating hours) are authored via the API in this version — the screen manages the template (name / timezone / active) and shift generation. Step by step Create a schedule 1. Open Team Management → Settings → Schedules. 2. Click Add. 3. Enter a Name (e.g. "Business hours Mon–Fri"). 4. Choose a Timezone — shifts are generated in this timezone, so use the team's working timezone. 5. Leave Active on (or turn it off to keep the schedule as a draft). 6. Click Save. Generate shifts from a schedule 1. On the schedule row, click Generate shifts (calendar icon). 2. Pick a start date (from) and an end date (to) for the range. 3. Click Generate shifts. Generation runs in the background; planned shifts are materialized for the whole range from the schedule's recurring blocks. Edit, deactivate or delete - Use the pencil to edit the name, timezone or active flag. - Turn Active off to show the INACTIVE badge: the schedule is kept but no longer used as a reference. - Use the trash to delete the schedule. Settings & options | Field / action | What it does | |---|---| | Name | Identifies the schedule in the list. Required to save. | | Timezone | The timezone used to generate shifts. Align it to the working timezone so adherence matches. | | Active | Keeps the schedule in use. Off shows the INACTIVE badge (draft). | | Generate shifts | Materializes planned shifts between a start date and an end date. | | Per-weekday recurrence blocks | The weekly hour map, authored via the API in this version. | Monitored scope on generation Shift generation materializes shifts only for monitored agents. If an agent assigned to a template leaves monitoring, already-generated shifts are preserved — only future generations skip them — and the schedules list shows an amber warning with how many of the template's agents are outside monitoring. Use cases - Model a standard weekday journey and generate a whole month of shifts at once. - Keep a separate schedule for weekend coverage with a different set of blocks. - Prepare the expected baseline that feeds each agent's schedule adherence. - Park a deactivated schedule as a draft until you validate the hours before generating. Tips, limits and best practices - Generation is asynchronous (it runs in the background) — shifts appear shortly after you confirm. - The Generate shifts button only enables once both dates (start and end) are filled in. - Generate one range at a time and avoid overlapping ranges to prevent duplicate planned shifts. - Set the schedule's timezone to the team's working timezone — that's how adherence compares expected against actual correctly. - The adherence target is configured in the General tab of the Team Management settings, not on the schedule. Troubleshooting - I don't see the Schedules tab — the module isn't enabled for the account, or you aren't an administrator. - The Generate shifts button is disabled — fill in both the start date and the end date. - I can't save the schedule — the Name field is required. - Generated shifts don't affect adherence — check that the per-weekday recurrence blocks were authored via the API, that the timezone is correct, and that agents are monitored with an expected journey set. See also - Team Management overview — the big-picture view of the module. - Monitoring board — the team's live status that adherence uses as the actual baseline. - Statuses & breaks — the status catalog with timers and limits behind the timeline. - Queues — group agents and inboxes with a distribution policy. - Monitored agents (enrollment) — who appears on the board and the expected daily journey.

Service queues (Team Management)

Overview A Queue is a named grouping of agents + inboxes + a distribution policy, layered over the platform's native router. It does not replace your assignment rules: it adds a layer of organization and monitoring on top of them, so you can think about your operation in terms of "Support L1", "WhatsApp Sales" or "Billing" instead of loose inboxes. Each queue stores only three pieces of configuration — name, description and distribution policy — plus two sets of memberships: the members (agents) and the inboxes. The three available policies are: - Round robin — distributes conversations in a cycle across members, one after another. - Load balanced — favors whoever currently has the lightest workload. - Manual — no automatic distribution; the queue is used to group and monitor. The queue stores only the identifiers of agents and inboxes; the names are resolved from the account roster (agent settings and inboxes), so the configuration stays lean and always consistent with your account. Prerequisites - The Team Management module must be enabled for the account. See the Team Management overview article. - Creating, editing and deleting queues and managing their memberships is for administrators (and custom roles granted the Team Management permissions). Without the manage permission, the tab opens in read-only mode: you see the queues, but the edit/delete buttons and the chips are disabled. - Have your agents set up and your inboxes created before building a queue — those are what appear as selectable chips. Step by step Create a queue 1. Open Team Management from the sidebar and go to the Queues tab. 2. Click Add (the button with the "+" icon). 3. Fill in the Name (required) and, optionally, the Description. 4. Choose the Distribution policy: Round robin, Load balanced or Manual. 5. Use the Active toggle to keep the queue enabled (on) or paused (off). 6. Click Save. The new queue appears in the list with its policy and the member and inbox counts. Manage agents and inboxes (chips) 1. In the list, click the queue name (or the arrow) to expand its panel. 2. In the Members section, click each agent's chip to add (chip lit) or remove (chip dimmed). The change is applied instantly, with no save needed. 3. In the Inboxes section, do the same: click the inbox chips to include or remove them from the queue. 4. The counts in the queue header (members · inboxes) update as you toggle the chips on and off. Edit or delete a queue 1. On the queue row, use the pencil icon to reopen the form and change the name, description, policy or the Active state. 2. Use the trash icon to delete. Confirm in the confirmation dialog. Settings & options - Name — the queue label (required). Use names that describe the operation ("Support L1", "WhatsApp Sales"). - Description — optional free text for team context. - Distribution policy — Round robin, Load balanced or Manual (see the Overview above). - Active — a toggle to enable or pause the queue without deleting it. - Members — agent chips from the account roster; click to toggle membership. - Inboxes — inbox chips from the account; click to link or unlink them. Monitored agents only Only agents inside the monitored scope can be added to a queue — the server rejects new additions outside monitoring with a clear message. Anyone already in the queue who later left monitoring stays visible (and removable); use the Show all agents toggle to reveal the full roster when needed. Use cases - Organize a large operation into named fronts (Support, Sales, Billing) over the same inboxes. - Use Round robin to split volume evenly across the agents on a shift. - Use Load balanced when handling times vary a lot and you want to favor whoever is freer. - Use Manual just to group and follow a team on the monitoring board, without touching automatic distribution. - Pause a queue (turn Active off) during a campaign or after hours, without losing its configuration. Tips, limits and best practices - The queue is a layer on top of the native router — it organizes and monitors, but it does not erase the assignment rules already set on the inboxes. - The Members chips come from the agent roster and the Inboxes chips from your inboxes; if an agent or inbox doesn't appear, set it up first. - Chip changes are immediate — there is no "save" button in that section. Reopen the queue to check the counts. - Keep few, well-named queues: too many queues make the monitoring board harder to read. Troubleshooting - I don't see the Queues tab — the Team Management module isn't enabled for the account, or you aren't an administrator. - The edit/delete buttons and the chips are greyed out — you are in read-only mode (without the Team Management manage permission). - An agent or inbox doesn't appear as a chip — confirm the agent was set up and the inbox was created in the account; the chip list comes from that roster. - I saved and nothing changed — the Name is required; the save button stays disabled while it is empty. See also - Team Management overview - Real-time monitoring board - Agent statuses and breaks - Schedules and planned shifts - Monitored agents (enrollment)

Who is monitored: enrollment modes and general settings (Team Management)

Overview The Monitored agents tab of the Team Management module decides who appears on the board and who is included in the adherence, time-per-status and login/logout calculations. You set one account-wide enrollment policy — three modes — and adjust exceptions and the expected daily journey agent by agent. The enrollment mode is the account-wide rule; each agent's Monitored toggle is the exception (or opt-in) that the server combines with the mode to build the board roster. When the mode is By team or inbox, enrollment comes from the agent's membership in the selected teams and inboxes — the Monitored toggle is not consulted in that mode. The General page rounds out the configuration with the adherence target, timezone and the day the week starts on — values that power the board's period filter and the adherence calculation. Prerequisites - The Team Management module must be enabled for the account. If you can't find the Team Management area, ask an administrator to turn it on. - The Monitored agents tab and the General tab are for administrators (and custom roles granted the Team Management permissions). Without that permission the controls appear read-only. - To use the By team or inbox mode you must already have teams and/or inboxes with agents assigned. Step by step Set the enrollment mode 1. Open the Team Management settings and select the Monitored agents tab. 2. In the Mode selector, pick one of the three modes (see the table under Settings & options). The change is saved automatically. 3. If you choose By team or inbox, two chip groups appear — Teams and Inboxes. Click to select/deselect, then click Save. Adjust per agent (Monitored + expected journey) 1. In the agents table, use each row's Monitored toggle: - In All agents with exceptions mode, turn it off to exclude someone from the board. - In Only selected agents mode, turn it on to include someone on the board. - In By team or inbox mode, the toggle has no effect — membership decides. 2. In the Expected daily journey column, enter the number of hours/day expected from the agent. The value is saved when you leave the field and becomes that person's adherence denominator. 3. Leave the field empty (or 0) when the agent has no fixed journey. Configure General 1. Open the General tab. 2. Set the adherence target (in %), the timezone and the day the week starts on for the account. 3. Save. These values define how the board resolves periods (Today / This week / …) and the basis of the adherence calculation. Settings & options The three enrollment modes | Mode | Who is monitored | Per-agent Monitored toggle | | --- | --- | --- | | All agents with exceptions | Every agent, by default | Turn off to exclude someone | | Only selected agents | Nobody, by default | Turn on to include someone | | By team or inbox | Anyone in a selected team or inbox | Ignored — membership decides | - All agents with exceptions is the default for operations that want to see the whole team and remove only a few profiles from the board (managers, bots, back office). - Only selected agents starts from zero: only the agents you explicitly turn on are included — ideal for a pilot with a small group before expanding. - By team or inbox keeps the board in sync with your structure: when you add an agent to a monitored team/inbox they become monitored automatically. An agent is included if they belong to any selected team or inbox. Expected daily journey - It is entered in hours and stored internally in seconds. - It serves as the adherence denominator: the agent's productive time is compared against this journey. - It is individual — part-time agents can have shorter journeys than full-time ones. General - Adherence target (%) — the goal used on the per-agent page and in the adherence reading. - Timezone — used to resolve the day/week boundaries of the board's periods. - Week start — the day "This week" begins on (affects the period filter). Apply by team In the All agents with exceptions and Only selected agents modes, the Apply by team card enrolls or removes every agent of a team from monitoring in a single action (it uses the team's member list at click time). Agents outside monitoring don't appear on the board, can't join new queues and stop receiving newly generated shifts. Use cases - Monitor the whole team and simply remove managers and automation accounts from the board (All agents with exceptions). - Run a Team Management pilot with 5 agents before rolling it out to everyone (Only selected agents). - Keep the board aligned with the operation with no manual upkeep: whoever joins the Sales team shows up monitored (By team or inbox). - Calibrate adherence per shift by setting journeys of 4h, 6h or 8h per agent. Tips, limits and best practices - The mode is saved instantly; the team/inbox chips only take effect after you click Save. - In By team or inbox mode the Monitored toggle has no effect — if an agent needs individual handling, use All agents with exceptions or Only selected agents. - Set the expected journey before you hold people to adherence: without it the comparison basis is empty. - Set the timezone and week start early — changing them later shifts how historical periods are read. Troubleshooting - An agent isn't on the board — check the mode: in Only selected agents they must have Monitored turned on; in By team or inbox they must belong to a selected team/inbox. - I picked teams/inboxes and nothing changed — confirm you clicked Save after choosing the chips. - An agent's adherence looks off — check the expected daily journey: empty or too low skews the percentage. - Per-period totals don't add up — review the timezone and week start on the General tab. See also - The Team Management overview, to understand the module as a whole. - The Monitoring board, which reads this list of monitored agents in real time. - Statuses & breaks, for the status catalog and the over-limit policy. - Schedules, to model weekly shifts and generate the planned-shift sheet. - Queues, to group agents and inboxes with a distribution policy.

Automatic conversation resolution

Overview Auto resolve closes conversations with no activity after the period you define, keeping the queue clean without manual work. The platform protects by default conversations that are still awaiting an agent's reply: a conversation whose last visible message is from the customer is never auto-resolved — preventing an unanswered request from silently vanishing from the queue. The setting lives under Settings → Account settings → Auto resolve. Prerequisites - Administrator role to change account settings. - Minimum inactivity period: 10 minutes; maximum: 999 days. Step by step 1. Go to Settings → Account settings. 2. Turn on the Auto resolve switch. 3. Set the inactivity period (minutes, hours or days). 4. Optional: write the closing message sent to the customer on resolution. 5. Optional: pick a label applied to auto-resolved conversations. 6. Optional: enable "Also resolve conversations awaiting an agent's reply — not recommended" only if you want to turn the default protection off. 7. Save. Settings & options - Inactivity period — counted from the conversation's last activity. Once elapsed, the open conversation is resolved on the next check cycle. - Closing message — sent to the customer at auto-resolution time (for example: "We closed this conversation due to inactivity; reply to reopen"). - Post-resolution label — makes it easy to filter and measure the automatically closed volume. - Awaiting-reply protection (default) — conversations whose last visible message is from the customer are excluded from auto-resolution, even when inactive. The team keeps seeing the pending request in the queue. - Also resolve conversations awaiting a reply — not recommended — an explicit option that turns the protection off. Use it only if your operation prefers closing everything by inactivity, regardless of who spoke last. Use cases - High-volume support: automatically close conversations where the customer stopped replying after the solution, keeping resolution metrics realistic. - Sales teams: combine with the automatic label (e.g. "no-reply") to feed follow-up cadences. Tips, limits & best practices - Resolution runs on periodic cycles and processes conversations in batches — on accounts with many eligible conversations, closing may be spread across a few cycles. - Combine with the inbox Conversation routing: with "Reopen the same conversation" enabled, a customer who replies after resolution reopens the SAME conversation, keeping the history. - The closing message also restarts the messaging window on windowed channels (such as WhatsApp) — write it with that in mind. Troubleshooting - "An inactive conversation was not resolved" — check whether its last visible message is from the customer with no team reply: in that case the default protection keeps it open, by design. Reply or resolve it manually (or enable the opt-in, not recommended). - "Unattended conversations were being closed" — confirm the "Also resolve conversations awaiting a reply" option is off; with it off the default protection applies to all conversations. - "The customer replied after resolution and a new conversation opened" — the inbox is set to "Create new conversations"; switch it to "Reopen the same conversation" for a single thread. See also - Conversation routing: reopen the same conversation or create new ones - Business hours, labels and attributes

Your profile and personal account security (password, 2FA, sessions, token)

Overview The Profile page gathers your personal details and the security of your user account. It is different from the Account settings (company administration, agents and teams): here you adjust only what belongs to you. In one place you can: - Update your name, photo, interface language and font size. - Set your message signature. - Change your password. - Enable two-factor authentication (2FA/MFA) with an authenticator app. - Review and end sessions open on other devices. - Generate and regenerate your personal API token. - Adjust sound alerts and notification preferences. Prerequisites - Be signed in with your user (every option is per agent and does not affect the team). - For 2FA: have an authenticator app (TOTP) installed on your phone — for example Google Authenticator, Authy or 1Password. - Some options may be hidden when the operator locks profile editing (installs with managed login/SSO). In that case, talk to your administrator. Step by step 1. Open your user menu and go to Profile. 2. In basic details, adjust name, display name and email; upload or remove the photo. Changing the email ends your session for security — you will sign in again. 3. In interface, choose the language and the font size. 4. In message signature, write the text appended to your replies and save. 5. In password, enter your current password, set the new one (at least 6 characters) and confirm it. 6. In security (2FA), enable two-factor authentication (see the section below). 7. In active sessions, review the devices and end any you do not recognize. 8. In access token, copy or regenerate your personal API token. Settings & options Profile details - Name / display name / email and photo. The display name is what appears in conversations. Language and font - Interface language: changes only for your user. - Font size: tunes how the dashboard reads. Message signature - A rich-text editor appended to your replies. - Pasted images inside the signature are removed on save (the platform warns you) — use text and formatting. Password - Requires your current password to confirm the change. - New password with at least 6 characters; the confirmation must match. Two-factor authentication (2FA/MFA) - Adds a temporary code (from the authenticator app) on top of your password at sign-in. - Enable: the platform shows a QR Code; scan it in your authenticator app (or use the manual entry option with the secret key), type the 6-digit code and confirm. - Recovery codes: once finished, the platform shows a list of codes — download them as a .txt file or copy and store them safely. Each code works once and is used when you do not have the app at hand. - Regenerate codes: creates a new list (invalidating the previous one) and requires a valid code. - Disable: requires your password and a valid code (from the app or a recovery code). - 2FA may not appear if the operator did not enable the feature on the install. Active sessions - Lists each session with device, browser, approximate location and last activity. - The current session is flagged and cannot be ended from this list. - Ending a session disconnects that device immediately. API access token - A personal token to use the API on your behalf. - Copy (with show/hide) and Regenerate. - When you regenerate, the previous token stops working immediately — update wherever it is used. - API usage details live under Integrations. Sound alerts - Audio preferences for notifications. The remaining notification options are in the Notifications article. Use cases - Protect the account: enable 2FA and keep the recovery codes. - Lost my phone: end the open sessions and change the password. - A token leaked: regenerate the access token to invalidate the old one. - Standardize support: set a consistent message signature. Tips, limits & best practices - Enable 2FA whenever possible — it is the most effective protection against unauthorized access. - Keep the recovery codes off your phone (password manager, vault). - Treat the API token like a password: never share it or put it in public code. - Review active sessions from time to time and end anything you do not recognize. - Remember: changing the email ends your current session. Troubleshooting - Lost my 2FA app: sign in with a recovery code; then, on the security page, regenerate the codes or disable and re-enable 2FA. - I don't see the 2FA section: the feature may not be enabled by the operator on your install. - I can't change the password: confirm the current password, use 6+ characters and check that the confirmation matches. If the password fields are missing, profile editing may be locked by the administrator. - Token leaked or stopped working: regenerate the token and update the integrations using it. - I don't recognize a session: end that session and then change the password. See also - Notifications and preferences - Login, profile and 2FA - Integrations: Slack, Dialogflow, webhooks, API - Account, agents and teams

Single sign-on (SSO) with SAML

Overview Single sign-on (SSO) with SAML lets agents sign in to Conversa Labs using your company's identity provider (IdP) — such as Okta, Azure AD / Microsoft Entra, or Google Workspace. Instead of each person keeping a separate password on the platform, authentication is delegated to the IdP: your corporate directory controls who can sign in and who loses access. It is a premium feature (gated by plan and by installation type — Cloud or Enterprise) and lives under Settings > Security. Prerequisites - An Administrator profile to configure SSO. - A plan with the SAML feature enabled for the account (premium/optional). If it isn't active, the Security area shows an unavailability notice or an upgrade screen. - A Cloud or Enterprise installation type (SAML SSO does not appear on other types). - The SAML login method allowed for the account (part of the platform configuration). - A SAML 2.0–compatible IdP (Okta, Azure AD / Entra, Google Workspace, or equivalent) where you can register Conversa Labs as a service application. Step by step 1. Open Settings > Security. 2. Turn on SAML SSO using the section toggle (the feature ships as Beta). 3. Fill in the fields with your IdP data: - SSO URL — the IdP sign-on URL. - IdP Entity ID — your provider's identifier (Entity ID / Issuer). - Certificate — the IdP's public X.509 certificate (paste its contents into the field). 4. Save. The platform validates the data and then shows the service-side values (see Service provider (SP) values below). 5. In your IdP, register Conversa Labs as an application using the SP Entity ID shown, and grant access to the agents who should use it. Login flow (how agents sign in via the IdP) With SSO active, the login screen offers sign-in via SAML. When an agent picks that option, they are taken to the IdP, authenticate there (with the company's policies and second factor), and return to the platform already authenticated. On a new agent's first sign-in, the account is provisioned automatically from the attributes the IdP sends. Settings & options - Enable toggle — turns SAML SSO on or off. Turning it off (or clearing the fields and saving) removes the SAML configuration from the account. - SSO URL, IdP Entity ID, and Certificate — the three required fields that describe your identity provider. Attribute and role mapping To provision the agent correctly, the IdP must send the attributes the platform expects: - email - first_name - last_name The collapsible Attribute mapping section on the Security screen lists these attributes. Configure your IdP to send them in the SAML assertion. Associating roles/functions (which role the agent gets on sign-in) is handled by the account's access governance — combine SSO with well-defined roles to control what each person can see and do. Service provider (SP) values After you save, the platform shows the service provider (SP) values that you give to your IdP: - SP Entity ID — the identifier for Conversa Labs as an application in your IdP. - Fingerprint — the certificate fingerprint, useful for verification. Use cases - Centralize access: the company controls sign-ins and offboarding through the corporate directory. - Strengthen security: enforce the IdP's own password policies and second factor (MFA). - Fast onboarding/offboarding: grant or revoke an agent's access directly in the IdP, without touching accounts one by one on the platform. Tips, limits & best practices - Keep the IdP certificate up to date — certificates expire and break sign-in when they lapse. - Combine SSO with well-defined roles (RBAC) and with audit logs for full governance. - Test with one agent before requiring SAML for the whole team. Availability and paywall - SAML SSO is premium: if it isn't in your plan, the Security area shows an upgrade screen (on Cloud, with a path to billing) instead of the form. - Available only on Cloud and Enterprise installations, and only when the SAML login method is allowed for the account. Troubleshooting - Sign-in fails or loops: check the SSO URL, IdP Entity ID, and Certificate — a value that differs between the platform and the IdP prevents authentication. - Missing role attribute / agent without permission: confirm the IdP sends email, first_name, and last_name, and review the role assigned in access governance. - Expired certificate: generate a new certificate in the IdP and update the Certificate field. - User not provisioned: the account is created on first sign-in only if the expected attributes arrive — confirm the attribute mapping in the IdP. - I don't see the SAML configuration: the premium feature may not be enabled, or the installation isn't Cloud/Enterprise, or the SAML login method isn't allowed for the account. See also - Custom roles and governance (RBAC) - Audit logs - Login, profile and two-factor authentication (2FA) - Administration overview