Administration & Settings

Administration & Settings: overview

Overview The Administration & Settings area brings together everything that governs your ConversaLabs 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 ConversaLabs 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. If you'd rather not use an image, a team can be identified by an emoji or a colored icon picked inside ConversaLabs, with nothing to upload. 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 and choose its visual identity — upload an image or open the Icon and emoji picker (the smiley button next to the image buttons) and pick an emoji or a colored icon. Then decide whether it allows auto-assignment and add the member agents. With no image and no icon, ConversaLabs 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. - Emoji or colored icon: the Icon and emoji picker opens a panel with two tabs. Icons holds a curated set of 163 icons, a Search icons field that matches both the icon name and its keywords, a button that toggles between Outline icons and Filled icons, and a palette of 10 colors: Slate, Red, Orange, Amber, Green, Teal, Blue (the default), Indigo, Violet and Pink. Emojis has search by name plus a Frequently used section with the 16 most recently picked emojis, kept in your own browser. An emoji already carries its own color, so picking one clears the selected color — the color is only stored when the value is an icon. The panel's eraser button removes the icon and the color in one go. - Icon takes precedence over the image: when a team has an emoji or icon, it is displayed instead of the uploaded image — in the team list, the team selector in the conversation panel, the team filter, when you mention the team with @ in the composer, and in macro and automation menus. The image is still stored; to show it again, remove the icon with the eraser button. - 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. - An emoji or colored icon is the quickest route when there's no logo ready: it stays sharp at any size and needs no upload. - Use different colors for teams that usually appear side by side in the same list — the color is what tells two similar icons apart at a glance. - Team names are normalized on save: control characters are stripped, surrounding whitespace is trimmed and the name is stored in lowercase — the capitalization you see in some lists is only presentation. - 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 uploaded an image but the team still shows the emoji: the emoji or icon takes precedence over the image. Open the Icon and emoji picker and use the eraser button to remove it — the image comes back. - I picked an emoji and the color disappeared: that's expected. The color only applies to icons; an emoji already has colors of its own. - I can't invite agents: the plan limit may have been reached or your role lacks permission — talk to the administrator. Inboxes for team-scoped roles A team-scoped role can navigate inboxes the user belongs to. Conversations remain restricted to that role’s teams and permissions. Seeing an inbox in navigation does not grant access to its settings. After switching accounts or starting impersonation, wait for the current user’s inboxes to load. 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, ConversaLabs 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 - Getting started - 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 notification emails sent to the agent themselves (conversation created, assigned, mention, new message and missed SLA) also follow that agent's dashboard language; without that choice, they use the account language. 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 - Getting started - 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 ConversaLabs installation and does not depend on a legacy enterprise edition'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. Custom Roles (legacy Enterprise) is now a hard gate The premium Custom Roles feature — the old Enterprise implementation, distinct from the native module described above — is now blocked end to end by the custom_roles feature, which ships turned off on every account. What changes in practice: - The Custom Roles API is refused without the feature. It answers 401 with "You are not authorized to do this action". The check runs before the profile check, so not even an Administrator can list, open, create, edit, or delete a custom role while the feature is off. - Assigning a custom role to an agent is silently ignored. If the feature is off and the request carries a custom role, the assignment is simply not written — with no error. Clearing the assignment (sending an empty value) still works on purpose, so an account that lost the feature can still remove a stale assignment left behind. - Nobody who already used it loses anything. On upgrade, a data routine turns the feature on automatically for every account that already has custom roles created. It only turns it on where use is demonstrated, re-reads the state before writing (running it twice changes nothing), and turns nothing off on the way back — a feature enabled by hand by an operator is indistinguishable from one it enabled. - A new account still starts without the feature, which is the default behavior. The native Roles & Access module does not depend on this feature. It is governed by Granular permissions, which ships enabled. If your account only uses native roles, none of this changes for you. Settings & options - Role templates: start from a governance-gallery template when it matches the person's responsibility, then review every permission before saving; a template never replaces a least-privilege review. - Scope: prefer specific teams or inboxes when the work does not need the whole account. Review scope whenever an Agent changes team or responsibility. - Fields: use Masked to support service without revealing a value and Hidden when the person must not read it at all. Record the personal-data rule's rationale in your privacy policy. 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. Tips, limits & best practices - Grant the smallest permission combination that lets the work be completed, and validate the role with a test Agent before assigning it in production. - Review roles, scope, and field rules regularly and after a change in team, process, or privacy obligation. - Do not treat a hidden button as a security control: retain server-side authorization and investigate denied attempts through the audit history. 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. - I opened /settings/custom-roles and landed on Roles & Access: that is the expected behavior. In this installation the old address redirects to Roles & Access; there is no Custom Roles screen in the dashboard any more. The custom_roles API still exists and is refused with 401 while the feature is off — even for an Administrator. - I assigned a custom role and the agent still doesn't have it: with the feature off the assignment is discarded without an error. Confirm the feature or use a native role. - I need to remove an old custom role and the account lost the feature: clearing the assignment is still allowed with the feature off — send an empty value. 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

Help Center portal settings

Overview The portal is the public site of your Help Center: the home page, the categories, the articles and the search your customers reach without logging in. Everything that defines how that site looks and behaves lives in Help Center → (portal) → Settings, at the .../portals/<slug>/settings route of the dashboard. The screen has four vertical tabs: | Tab | What it controls | |---|---| | General | Name, identifier (slug), page title, header text, color, logo, home page link and portal deletion | | Domain | Custom domain, CNAME record, certificate status and e-mailing the instructions | | Appearance | Layout (Classic or Documentation) and social network links | | Integrations | Live chat widget and the analytics providers | There is one more setting that does not live on that screen: the recommended content, chosen per locale on the portal's Locales page. Prerequisites - The Help Center feature (help_center) must be enabled on the account — it ships enabled by default. With the feature off, the public portal pages stop serving content and show an inactive-help-center notice instead. - A portal already created on the account. - To edit the analytics section you must be an account administrator. The restriction is enforced on both ends: the cards only render for administrators, and the API drops analytics fields sent by anyone who is not an administrator — even when their role may edit the other portal settings. The reason is stated in the code itself: analytics injects tracking scripts into every public page. - For a custom domain, access to the domain's DNS panel. Step by step 1. Open Help Center in the sidebar and select the portal you want to configure. 2. Click Settings. The General tab opens first. 3. In General, adjust name, identifier, page title, header text, color and logo. The save button only enables once something changes. 4. In Domain, click Add (or Edit) and enter the custom domain. On save the platform opens the DNS dialog with the record ready to copy, in the form your-domain CNAME <installation host>. You can e-mail those instructions to whoever manages the DNS. 5. In Appearance, pick the layout and, on the Documentation layout, add the social links. 6. In Integrations, pick the live chat widget and fill in the analytics identifiers you want to use. Click Save Changes. 7. For recommended content, go back to the Help Center, open Locales, click the menu of the locale you want and choose Select recommended content. Settings & options Recommended content per locale The Recommended content dialog lets you pin, for each locale, which categories and which articles are featured on the home page: - Up to 3 categories and up to 6 articles. The counter shows how many slots are left. - Order matters: drag the items into the sequence visitors should see. The home page honors exactly that order. - Article search runs on the server and only considers published articles of that locale. - Saving with both lists empty removes the selection for that locale, and the portal falls back to the automatic defaults. How the home page decides what to show: | Block | With a recommendation | Without one — Classic layout | Without one — Documentation layout | |---|---|---|---| | Topic pills at the top | Your recommended categories, in your order | No pills at all: Classic builds no automatic list | The first 3 visible categories that already have a published article, by position | | Featured articles block | Your recommended articles, in your order | The 6 most viewed articles inside visible categories, and the block only appears when there are at least 6 | The 6 most viewed articles of the locale, even if there are fewer than 6 | Two rules avoid surprises: a recommended category does not need published articles to show up, unlike the automatic list, which only considers categories with at least one published article. Visibility, though, is not negotiable — categories and articles restricted to operators never surface on the public portal, and items deleted after the pick simply drop out of the list. Layout Two options, stored on the portal: - Classic — a welcoming home page with search and featured topics. - Documentation (marked beta) — side-by-side navigation that keeps every guide one click away. Any value other than these two is treated as Classic. There is also an internal "plain" variant (?show_plain_layout=true), used by the article preview inside the dashboard — it is not a configuration option. Social links The social links section appears only when the layout is Documentation, because it is that layout's footer that renders the icons. There are eight networks, and you type only the handle — the platform builds the full address: | Network | Prefix applied | |---|---| | Facebook | facebook.com/ | | X | x.com/ | | Instagram | instagram.com/ | | LinkedIn | linkedin.com/ | | YouTube | youtube.com/ | | TikTok | tiktok.com/ | | GitHub | github.com/ | | WhatsApp | wa.me/ | Removing a link clears the stored handle. The footer disappears entirely when no network is filled in and the platform signature is turned off — either by the account's whitelabel or by the signature removal configured for the whole installation. Custom domain - The domain is unique across the whole installation: two portals cannot point to the same address. - The field only accepts a bare domain such as help.yourcompany.com. Pasting a full address, with https:// or with a path, is refused in the dialog itself with a format error. - The DNS dialog shows the CNAME record ready to go, with a copy button. - E-mailing the instructions requires a valid address and a domain already configured on the portal — without that, the action is refused with a message explaining why. - The certificate status (Live / Pending / Error) and the refresh-status button only appear on cloud-hosted accounts. On self-hosted installations the certificate is your infrastructure's responsibility. Live chat The Live chat with ConversaLabs card connects a website widget inbox to the portal, so the visitor can talk to the team while reading the articles. The list only shows website widget inboxes; picking No widget disconnects the portal from any widget. Analytics providers Seven providers, each with its identifier and a format validated before saving: | Provider | Field | Accepted format | Example | |---|---|---|---| | Google Tag Manager | gtm_container_id | GTM- followed by uppercase letters and digits | GTM-XXXXXXX | | Google Analytics 4 | ga4_measurement_id | G- followed by uppercase letters and digits | G-XXXXXXXXXX | | Hotjar | hotjar_site_id | digits only | 1234567 | | Plausible | plausible_domain | a domain (letters, digits, dot and hyphen) | example.com | | Amplitude | amplitude_api_key | letters and digits | 0123456789abcdef0123456789abcdef | | Microsoft Clarity | clarity_project_id | letters and digits | abcd1234ef | | Meta Pixel | meta_pixel_id | digits only | 123456789012345 | How this is injected into the portal: - The script block goes into the <head> of every public portal page — except the internal article preview (plain layout), precisely so the preview does not count as a visit. - Google Tag Manager and Meta Pixel also get their noscript version (iframe and image pixel) right at the start of the <body>, for browsers with JavaScript disabled. - The Meta Pixel fires PageView on every internal portal navigation, not only on the first load. - Leaving a field blank disables that provider: empty values are dropped on submit. Use cases - Product launch: pin the new product's category to the top pills and the 6 getting-started articles as recommended, in the target audience's locale. - Multilingual Help Center: choose different recommendations per locale — the Spanish audience sees the Spanish guides featured, with no effect on Portuguese. - Technical knowledge base: use the Documentation layout, with side navigation and social links in the footer. - Your own brand: publish the Help Center at help.yourcompany.com with a custom domain and logo. - Content measurement: connect GA4 to measure traffic and Microsoft Clarity to see heatmaps of which articles stall the visitor. - Advertising: use the Meta Pixel to measure conversions and build audiences from people who read the Help Center. Tips, limits & best practices - The 3 categories and 6 articles limits are hard. If you try to store more than that through the API, only the first items of the list are considered. - Prefer one Google Tag Manager container over several loose scripts: you can swap tags without going back to the dashboard. - Do not run GTM and GA4 for the same property at once — that double-counts visits. - Treat analytics identifiers as high-impact configuration: they add third-party scripts to public pages, which affects performance and privacy. Review your cookie policy before turning on heatmaps and session recordings. - Revisit your recommendations after archiving or deleting articles: the item disappears from the portal, but the list keeps a slot occupied until you edit it. - Two people can save different tabs at the same time without wiping each other's work — the platform locks the record while saving and merges onto the latest version. - The portal's default locale cannot be marked as a draft. Troubleshooting "Invalid analytics configuration" — the request carried an analytics field that does not exist or a value that is not text. Use only the seven fields in the table above. A message says an analytics field is invalid — the value does not match the expected format. Check the prefix (GTM-, G-) and the character type: Hotjar and Meta Pixel accept digits only. The dashboard also flags the field in red and blocks the save button before submitting. The Save button is disabled — either nothing has changed since the last save, or some field has an invalid format, or a save is still in flight. I cannot see the analytics cards — they are exclusive to account administrators. Events do not show up when I open the article preview from the dashboard — that is the expected behavior: the internal preview does not load analytics scripts, so your metrics are not polluted by your own team's traffic. A recommended article does not appear on the home page — check that it is published, that it is public (not operator-only), that it belongs to the same locale as the recommendation, and that it was not deleted after the pick. The featured articles block does not appear on the Classic layout — without recommended content, that block needs at least 6 published articles inside visible categories of the locale; below that it stays hidden. Picking recommended articles shows the block at any count. I set up the social links and the footer still has no icons — social links are only rendered on the Documentation layout. The certificate status does not appear — it is only shown on cloud accounts; on a self-hosted installation, check the certificate in your own infrastructure. The DNS instructions are not sent — confirm the portal already has a custom domain saved and that the e-mail address you entered is valid. See also - Integrations - Custom Scripts: injecting JS/CSS into the dashboard, portal and widget - Whitelabel - Website channel (widget)

Integrations: providers, credentials, OAuth, webhooks and API

Overview Integrations connect ConversaLabs 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. - Video and voice calls (Cloudflare RealtimeKit): the agent starts a call with the customer inside the conversation itself. This integration used to be called Dyte and now runs on Cloudflare RealtimeKit — the credentials changed. - 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 or a native role with Manage integrations permission to configure account connections. - 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. - For video/voice calls: a Cloudflare account with a RealtimeKit app created and an API token with Realtime Admin permission. Connecting and disconnecting this integration takes the same access as any other: Administrator or a native role with Manage integrations. - To verify Slack webhook signatures: your Slack app's Signing Secret, applied at the installation level (not per account) — see below. 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. Set up video calls with Cloudflare RealtimeKit 1. In Cloudflare, create (or locate) the RealtimeKit app and note its app ID. 2. Note your Cloudflare account ID as well, and create an API token with Realtime Admin permission for that account. 3. In ConversaLabs, open Integrations and pick the video integration. Fill in the three fields: - Cloudflare Account ID - RealtimeKit App ID - Cloudflare API Token On this integration, the shortcuts above the fields still point at the previous provider's pages (dev.dyte.io and docs.dyte.io). Ignore them: all three values come from the Cloudflare dashboard. 4. Save. The platform validates the credentials right away: it checks that the token is active and that the RealtimeKit App ID exists in that Cloudflare account. If something doesn't match, the connection isn't created and the error message points at the exact field to review. 5. Open a conversation and start the call. The platform posts an invitation message in the conversation; participants use Click here to join and end with Leave the room. If you were already using the old integration (Dyte): it stays registered but can no longer open calls. Trying to start a meeting returns "Cloudflare RealtimeKit credentials are required. Delete the existing Dyte integration and create it again with Cloudflare RealtimeKit credentials." — and that is exactly the path: delete the old connection and create a new one with the three fields above. This integration's screen offers only Connect and Disconnect, so there is no form for swapping the old fields (organization ID and API key) in place. Turn on Slack webhook signature verification 1. In your Slack app's dashboard, copy the Signing Secret. 2. Apply the value at the installation level, in one of these ways: - in Super Admin, under the Slack configuration group, in the Slack Signing Secret field; or - in the server's SLACK_SIGNING_SECRET environment variable. 3. Send an event from Slack again and confirm the conversation still arrives normally. While the secret is not configured, the platform does not reject the webhook: it only writes a warning to the log and processes the event — existing installations keep working unchanged. Verification only kicks in once you fill in the secret, and that is what protects the endpoint against forged calls. Settings & options - Authorization-based connections (Slack, Shopify, etc.): follow the external tool's login. - Key/project-based connections (Dialogflow, Google Translate, Cloudflare RealtimeKit, 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. Cloudflare RealtimeKit fields | Form field | Required | What it is | Visible after saving | |---|---|---|---| | Cloudflare Account ID | Yes | Your Cloudflare account ID | Yes | | RealtimeKit App ID | Yes | The RealtimeKit app ID inside that account | Yes | | Cloudflare API Token | Yes | API token with Realtime Admin permission | No | All three fields are required, and the form accepts no field beyond them. The "Visible after saving" column applies to administrators; the API token is never returned by the platform to anyone. Because the integration only has Connect and Disconnect, changing any of the three values means disconnecting and connecting again. Where the Slack Signing Secret lives The secret belongs to the installation, not to an account. The platform looks for the value in this order: 1. the Slack Signing Secret installation setting (Super Admin); 2. the SLACK_SIGNING_SECRET environment variable. If the panel field exists but is blank, the environment variable is still used — so an installation that already set the secret through the environment stays protected after the upgrade. Verification uses the signature Slack sends in the X-Slack-Signature and X-Slack-Request-Timestamp headers, with HMAC-SHA256 over the raw request body. A webhook is rejected with 401 when one of those headers is missing, when the request timestamp is more than 5 minutes away from the server clock, or when the signature doesn't match. 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. - Settle a complex case on the spot by opening a video call with the customer, without pulling them out of the channel they were already in. - Harden the Slack webhook endpoint against forged calls by turning on the signing secret. 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. - Give the Cloudflare token the smallest scope that still includes Realtime Admin: that is the permission both validation and the calls require. - Confirm the three RealtimeKit fields belong to the same Cloudflare account. An App ID that is valid in another account is rejected with the app-not-found message. - The Slack signature's 5-minute window depends on the server clock: keep time sync (NTP) healthy, or legitimate webhooks start being rejected. - When you rotate the Signing Secret in Slack, update the value on the platform in the same window — between the rotation and the update, events are rejected. 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. - Shopify needs attention: follow the dedicated guide before reconnecting the store. - "Cloudflare API token is invalid or inactive": the token failed Cloudflare's own check. Create a new token with Realtime Admin permissions. - "Cloudflare Account ID is invalid, or the API token does not have Realtime Admin access to this account": the token is valid but doesn't reach that account. Review the account ID and the token's scope. - "RealtimeKit App ID was not found in this Cloudflare account": the app doesn't exist in that account. Check that you copied the App ID from the right environment. - "Could not verify Cloudflare RealtimeKit credentials right now": Cloudflare didn't answer in time or returned a temporary error. Try saving again. - The video call won't open and asks for RealtimeKit credentials: the connection is still the old Dyte one. Delete it and create the integration again with the three Cloudflare RealtimeKit fields. - Slack events stopped with 401: the configured secret doesn't match the Slack app's, or the server clock is outside the 5-minute window. Compare the Signing Secret and check the server time. 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 ConversaLabs. 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 ConversaLabs 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 ConversaLabs 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 ConversaLabs 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 ConversaLabs; 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

Shopify: securely connect a store and view orders

Overview The Shopify integration finds a customer using the contact's email address or phone number and shows store orders in the conversation. The lookup happens on demand: ConversaLabs does not persist the Shopify customer record or order response. This connection is separate from a Catalog & Commerce source. Use this integration for support order lookup; use a commerce source for catalog sync, sales events, cards, and automations. Prerequisites - The installation operator must configure SHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET, and the public HTTPS origin for ConversaLabs. In development, HTTP is accepted only for loopback hosts. - The installation operator must register the configured OAuth callback and the verified Shopify privacy webhook endpoint in the Shopify app settings before enabling the feature for accounts. - Shopify integration must be enabled for the account. - You must be an Administrator or have the native Manage integrations permission. - You need store admin access and its permanent your-store.myshopify.com domain. Do not use the storefront's custom domain. Step by step 1. Open Settings → Integrations → Shopify. 2. Select Connect store or Reconnect store. 3. Enter only your-store.myshopify.com, without https://, a path, query, or port. 4. In Shopify, check the store and requested permissions, then authorize in the same browser. 5. Back in ConversaLabs, open a conversation whose contact has an email address or phone number and expand Shopify orders. Reconnecting safely replaces the account credential and can refresh permissions or change stores. Each attempt expires in about ten minutes, is bound to the initiating browser, and can be completed only once. If you cancel, wait too long, or open the callback in another browser, start again from the integration page. Settings & options - The app requests only read_customers and read_orders. - The contact's email/phone is sent to Shopify search; the UI response contains only order ID, date, amount, currency, financial/fulfillment status, and the admin link. - By default, Shopify's API makes the last 60 days of orders available. Longer history requires separate Shopify approval and is not requested by this integration. - The token remains server-side and is never returned to the browser, Swagger, or MCP. - Mandatory privacy webhooks are HMAC-verified. Customer/order data is transient, so customer access and redaction requests acknowledge that there is no local copy to erase. shop/redact deletes the saved connection for that store. Use cases - Check order amount, date, and status without leaving the conversation. - Open the correct Shopify admin order to handle a return, delivery, or refund. - Reconnect the same store after its permissions change. - Replace the store attached to the account without creating duplicate credentials. Tips, limits & best practices On the Shopify integration page, choose Disconnect and confirm. Removal remains available if the feature is disabled so an old credential can never become trapped. Also revoke the app in Shopify admin when ending its use permanently. Always use the permanent .myshopify.com domain, finish each attempt in the browser that started it, and periodically review who has the Manage integrations permission. Troubleshooting - Invalid domain: copy the .myshopify.com domain from Shopify Settings → Domains. - Integration disabled: ask the operator to enable the feature for this account. - Callback error: stay in the same browser, check the system clock, and start again; do not reuse an old link. - No orders: ensure the contact matches an email address or phone number in Shopify and remember the default 60-day window. - Permissions changed: choose Reconnect store and approve again. - Temporary failure: use Try again in the order panel. Provider internals and credentials are never displayed in the error. See also - Integrations: providers, credentials, OAuth, webhooks, and API - E-commerce lifecycle - Custom roles and governance

Import data from another platform (Intercom and Freshdesk)

Overview The Settings → Data area brings your customer history from another support tool into your ConversaLabs account. It has two tabs: Import and Export (exporting is still marked as Coming soon). Two integration sources are supported today: | Source | Credential | Extra field | |---|---|---| | Intercom | Intercom access key | — | | Freshdesk | Freshdesk API key | Domain (acme.freshdesk.com) | Every import runs in the background, on a low-priority queue: you can close the screen and keep working. While it is active, the page refreshes itself every 5 seconds and shows the current stage, how much was imported per type, the errors and everything that was skipped. The Import tab lists the account's imports, newest first, with the total right above the list. It also includes the CSV contact imports started from the Contacts area: those do not come from an integration, and the row icon shows File import on hover. Prerequisites - Administrator role. Every action in this area (list, open, create, retry, abandon and download the log CSVs) requires it. - The Data import capability (the data_import flag) must be enabled for the account. It ships disabled by default; without it, the Data entry does not even appear in the settings menu. - Intercom: an access key for your workspace. The platform calls the public Intercom API (https://api.intercom.io, API version 2.15) with that key. - Freshdesk: your account domain and an API key. The platform calls https://YOUR-DOMAIN/api/v2 authenticating with the key. The domain must end in .freshdesk.com — typing just acme completes it to acme.freshdesk.com. - Only one active integration import per account. While one is pending or processing, the new import button stays disabled. The credential is stored encrypted (when encryption is configured on the installation) and is never returned by the API — neither in the list nor in the import detail. Step by step 1. Open Settings → Data and stay on the Import tab. 2. Click Import. 3. Under Source, pick Intercom or Freshdesk. 4. Adjust the Import name if you want. The default is Intercom import or Freshdesk import. 5. For Freshdesk, fill in the Freshdesk domain (example: acme.freshdesk.com). 6. Paste the Intercom access key or the Freshdesk API key. When you leave the field, validation runs automatically and the field shows Validating access key…, then Access key validated. or the error message. 7. Under Data to import, Contacts and Conversations are ticked already. Untick whatever you do not want to bring over; at least one of the two is required. 8. Click Import. The button only enables when the key is validated, at least one type is ticked and there is no other active import. 9. You are taken straight to the import tracking screen. Settings & options What is imported, and in which order Contacts are imported first, then conversations (and each conversation's messages). If you tick only one of the types, only that stage runs. Contacts - Name, email (normalized to lowercase and validated) and phone in E.164 format — a number without + gets the prefix automatically; anything that does not end up in E.164 is discarded. - Identifier = the source external_id (in Freshdesk, unique_external_id). - A contact with an email or a phone is created with the Lead type. - Custom attributes created: intercom_contact_id and intercom_external_id, or freshdesk_contact_id and freshdesk_unique_external_id. - In Freshdesk the phone comes from mobile (or phone); other emails, custom fields and tags are kept in the contact's source metadata. - Deduplication: the platform looks for an existing contact by identifier, then by email, then by phone. If it finds one, it updates that contact instead of creating another. Conversations and messages - Every imported conversation lands with the Resolved status and its own identifier (intercom:<id> or freshdesk:<id>), which prevents duplicates on a later import. - Conversations are spread across import inboxes created automatically, of the API type, one per source channel, with names like Intercom Import - Email, Intercom Import - WhatsApp or Freshdesk Import - Phone. They are created with auto assignment turned off. - Intercom: Email, Instagram, Facebook, SMS, Twitter, WhatsApp, Phone, Messenger and Unknown. - Freshdesk: Email, Phone, Forum, Twitter, Facebook, Portal, Chat, Mobile, Ecommerce, Bot, WhatsApp, Internal task, Instagram, SMS and Unknown. - Incoming or outgoing: a message is incoming when the source author is a contact, a user or a lead, and outgoing otherwise. An internal note from the source becomes a private note. - Intercom events become activity messages on the timeline, in the account's language: assignment, open, close, snooze, participant added or removed, attribute change, custom action and quick reply. Freshdesk has no equivalent record. - The body is sanitized: HTML is converted to plain text. - Conversation custom attributes: intercom_conversation_id, or freshdesk_ticket_id, freshdesk_subject, freshdesk_status and freshdesk_priority. Tracking The detail screen shows five tiles — Source, Import types, Created, Duration and Started by — plus an Import progress block. The counters follow what you ticked: Contacts shows up when contacts were included; Conversations and Messages show up when conversations were included. The percentage bar only appears when the source reports a total. Intercom returns the contact and conversation totals during validation; Freshdesk does not return totals, so there the progress only shows how many records already came in. The stage is shown in the header: Queued, Importing contacts, Importing conversations, Finalizing import, Completed, Completed with errors, Failed or Abandoned. When it ends, the import is Completed when no error was recorded, and Completed with errors when there was at least one. Errors and skipped records The detail brings two sections: - Errors — run failures and incomplete conversations. - Skip logs — what was skipped or failed on a specific record, with a filter for All, Contacts, Conversations and Messages — each type shows its own count. Each section shows the 5 most recent records on screen plus a Download CSV button with the complete list. The files are named data-import-<id>-error-logs.csv and data-import-<id>-skip-logs.csv, with the columns created_at, kind, source_object_type, source_object_id, error_code, message and details. The kind field tells what happened: | kind | Meaning | |---|---| | skipped | Record intentionally skipped (for example, already imported before) | | failed | Record that errored and did not come in | | incomplete | The source returned fewer conversation parts than the total it reported | | run_error | The whole run failed | Frequent skip reasons: already imported in a previous import (the existing record is reused), the body had no readable text after HTML sanitization, attachments are present but no importable text was found and no body or attachments to import. Resume, retry and abandon - After each processed page the platform saves a cursor, and the next page is queued as a new job. If something interrupts the run, it starts again from the saved point without redoing what already came in. - An import with no update for 15 minutes is flagged as stalled. When that happens the Retry button appears in the detail header and puts the run back in the queue. - The Abandon button is available while the import is pending or processing and ends the run. - Repeating the import from the same source does not duplicate records: every source object has a unique mapping per account, provider and type. Use cases - Migrate the support history from Intercom or Freshdesk when switching tools, without losing customer context. - Bring only the contacts first, validate the base, then run a second import with the conversations. - Keep the old history searchable inside the platform, in separate inboxes, while new support happens in the real channels. - Audit the migration with the error and skip-log CSVs before switching the old tool off. Tips, limits & best practices - One integration import at a time per account. Plan the order if you have several sources. - Attachments are not downloaded. In place of the file, the message gets a marker with the source attachment count — [Intercom attachment skipped: 2] or [Freshdesk attachment skipped: 2]. Attachment metadata is kept on the record. - Source tags and labels do not become platform labels: they are preserved in the source metadata of the contact and of the conversation. - Source agents do not become account users. Agent messages land as outgoing, with no linked sender. - Freshdesk: the ticket sweep is capped at 300 pages of 100 tickets, and tickets are processed in chunks of 10. Intercom paginates 50 contacts and 10 conversations at a time. - Do not delete the Import inboxes created by the migration — the imported conversations live there. - Run the import during a quieter period and review the log CSVs before calling the migration done. - If the credential is rotated or removed after the import was created, the resume actions answer that the credential is unavailable — in that case, create a new import. Troubleshooting - I don't see “Data” in the settings menu. The capability is not enabled for the account, or your role is not Administrator. - “We could not validate this Intercom access key. Check the key and its permissions.” (or “…this Freshdesk API key…”; when the source returns no message, the local text “Could not validate this access key.” is shown instead.) The key is wrong, expired, or missing the read permissions required on the source tool. - “Intercom could not be reached. Please try again.” (or “Freshdesk could not be reached…”) The source answered with a non-authentication error, or did not answer in time. Try again in a few minutes. - “Enter a valid Freshdesk domain, such as acme.freshdesk.com.” The domain you typed is not a valid Freshdesk domain. Use your account subdomain. - “Another data import is already in progress.” There is already a pending or processing import. Wait for it to finish, or abandon it. - The Import button stays disabled. The key is not validated yet, no data type is ticked, or there is an active import. - “This … import is no longer stalled.” The import started progressing again before you clicked Retry — just keep watching it. - It finished as “Completed with errors”. Open the Errors and Skip logs sections and download the CSVs to see exactly which source objects did not come in, and why. - Freshdesk progress shows no percentage. That is expected: the source does not return totals, so only the number of imported records is shown. See also - Contacts: import and segments - Integrations - Account, agents and teams - Audit logs - Administration overview

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. The list offers search by person, filters by event type and date range, and sorting. That is how you narrow thousands of events down to the handful that matter before investigating. 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 Audit Logs in the sidebar. 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. Use the search box in the header to find a person's actions by name or email. It kicks in from 3 characters onwards. 5. Pick an event type from the grouped list (Access, Agents & teams, Configuration, Conversations) or keep All events. 6. Set the date range in the date selector and the sort order (newest or oldest first). 7. Use Clear filters to go back to the full list. 8. Read the event row: it already carries the full description of the action, the time and the source IP address. The row is the whole record — there is no detail screen behind it. 9. For external analysis, read the same history through the API at GET /api/v1/accounts/{account_id}/audit_logs, which accepts exactly the filters of the screen (q, types, since, until, sort and page). Settings & options - Chronological view: events from newest to oldest. - Filters: help locate a specific action among many records. - Search by person: the search box looks for an agent name or email. It starts from 3 characters and waits for a short typing pause before querying, so it doesn't fire on every keystroke. - Event type filter, organized into four groups: | Group | Available types | |---|---| | Access | Sign in / sign out | | Agents & teams | Agents · Teams · Team members · Inbox collaborators | | Configuration | Account settings · Inboxes · Webhooks · Automation rules · Macros | | Conversations | Conversation deletions | - Date range filter: the platform's standard date selector. The chosen range is applied from the start of the first day to the end of the last one. - Sorting: Newest first (default) or Oldest first. - Counter: the header shows the total number of events matching the current filters. - Clear filters: the button appears as soon as a search term, event type, date range or sort order is active. - State in the URL: search, type, period, sort order and page live in the page address. You can reload, use the browser's back/forward buttons and share the already-filtered link with another administrator. - Pagination: 25 events per page. - Columns: the activity described in plain text (who did what), the time and the source IP address. - Export: the screen does not export CSV. To take the events elsewhere, use the API named in step 9. - Retention: history is available according to your plan's policy. The platform does not prune these entries on its own and the screen has no retention field — the trail with a configurable window is the native one described below. - Native trail (Governance & LGPD): besides the premium logs, the account can enable the native audit trail, read from the Audit trail 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. That trail has its own filters (Action, From and Until) and does not offer free-text search. 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. - Reconstruct an agent's day: search by their email and sort from oldest to newest. - Isolate configuration changes in a suspicious window: filter by Configuration and by the incident's period. - Check deletions: filter by Conversations → Conversation deletions. 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. - Search covers who performed the action (name or email), not the text of the event description. To answer “what changed”, combine event type + date range. - Filter before sharing: an already-filtered link saves the other person from repeating the whole investigation. - An unknown event type or sort order in the address is simply ignored, and the date range is only applied when both start and end are present. 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. - Search returns nothing: it needs at least 3 characters and looks for a user's name or email — a fragment of the action description will not find the record. - The list says “There are no items matching this query”: active filters matched no event. Use Clear filters to start over. - I pasted a link and got fewer filters than expected: unsupported values are discarded when the address is read. - I want to export to a spreadsheet: the screen has no export button. Use the API from step 9 and convert the result. - 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. For anonymization and erasure, the request stays Processing until the WhatsApp gateway confirms that the subject was removed from the groups they took part in. The local part is already done at that point, and the notice under the status explains the wait. The platform retries automatically every day, with no action needed from you, and the request only shows Completed after that confirmation. 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 stays "Processing" with a waiting notice: the local part is done and the removal from the WhatsApp groups still has to be confirmed. The platform retries automatically every day; do not create a new request for the same subject. - A request shows "Failed": read the notice under the status. For an export, create a new request. If the removal from the groups was refused, contact support, because that request cannot be reprocessed from the screen yet. 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, the picker shows what the selected variable will produce for that contact — the real name, the real charge amount, the real booking date. When you type {{, the value appears in the preview panel under Value; through the {x} button, it appears as a chip on the token's own row. What you see there is exactly what the customer will receive. 6. Send a test before firing at your whole base. Settings & options The variable picker There are two ways to reach the same list: - Typing {{ inside the editor. The picker opens anchored to the point where you are writing, above or below that line — whichever side of the screen has more room — with the search field already focused: keep typing and the list filters. - Through the {x} Insert button, in the header of the fields that offer it (WhatsApp templates, follow-up steps, booking reminders, flow builder fields). In both cases the search matches the token name and the description — searching for "due" finds the variable even when you do not know its name. The list is never re-sorted. Groups and tokens arrive in the server catalog's own order, which already puts the most-used first (name, first_name, email… before the postal address fields). The custom fields you created join the group of the model they belong to. The preview panel shows two fields for the selected item: | Field | What it carries | |---|---| | Description | What the variable means, in the dashboard language | | Value | What it will produce in this conversation, computed on the server by the same engine that assembles the message at send time | When the token has no value for that contact, the panel says "No value for this conversation" in muted text instead of faking a value it does not have. That is the honest answer — and it is exactly what you need to see before sending. On wide screens the panel sits to the right of the list; on narrow screens it drops below it; and when it fits neither way, the picker shows the list alone, which keeps working the same. Keyboard: ↑ ↓ (or Tab / Shift+Tab, or Ctrl+P / Ctrl+N) move through the list, which wraps from the last item to the first; Enter inserts; Esc closes and hands focus back to the text; Backspace with an empty search erases the {{ that opened the picker. Moving the mouse over a row selects it, clicking inserts, and clicking outside closes. Where {{ does not open. The trigger is only recognised at the start of the line or after a space, and the picker does not open in a private note — picking a variable from the list is a Reply-mode feature. Once closed with Esc, it only reopens when you type {{ afresh. 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. Account Brain signals The {{ brain.* }} variables describe the conversation the message is written in: - {{ brain.risk_score }} and {{ brain.risk_band }} show the risk of that conversation or, when it has no reading yet, of its contact. With neither, they stay blank — they never show the risk of another conversation. - {{ brain.insight_type }}, {{ brain.insight_severity }} and {{ brain.department }} show the insight about that conversation or its contact and, when there is none, the latest insight about the account as a whole (for example, a support indicator). Insights about other conversations and insights flagged as sensitive never appear in variables. The value the picker shows is the one the message gets when it is sent, for anyone who can write in that conversation. In flows that run with no conversation and no contact, the risk is the latest reading of the account and the insight is the latest one about the account as a whole. Date and time in the account timezone {{ now.date }}, {{ now.time }}, {{ now.datetime }} and the other now values use the timezone selected in account settings, including in Flow Builder. The *_formatted tokens also display times in that zone. {{ now.timezone }} and {{ account.timezone }} show which timezone applies. Without a configured timezone or one inherited from onboarding or the legacy setting, the account uses UTC, even if the server uses another timezone. The Liquid filters | date, | datetime and | time_of_day also use the timezone configured for the account, just like {{ now.* }} and the *_formatted tokens. For example, {{ contact.created_at | datetime }} displays the instant on the account clock. With an explicit format such as | date: '%H:%M', an instant with an offset or Z also uses the account timezone. A date-only value keeps its written day; a date-and-time string without an offset keeps its written digits, without a timezone shift. Flow Builder date conditions interpret dates without a timezone, such as 2026-10-06 00:00, in the account timezone. An ISO date with an explicit offset keeps its instant. Review comparisons in published flows that previously depended on UTC. The within-N-days condition still compares a duration of N × 24 hours. 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 & best practices - Always send a test. It is the fastest way to see whether the variable brought the value you expected. - Esc closes, Backspace erases. Esc closes the picker but keeps the {{ in the text — handy when you did mean to type braces. To remove the trigger along with it, use Backspace with the search field empty. - What you type after {{ goes to the search field, not to the message. The picker's search field takes focus as soon as it opens. - 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 | | I typed {{ and the picker did not open | You are in a private note, where the picker does not open — or the {{ did not come at the start of the line or after a space | Switch back to Reply mode to pick the variable from the list; in an internal note, write the value out in full | | The panel says "No value for this conversation" | The token has no data for this contact | Check the record; rewrite the sentence to work without the value, or pick another variable | | The picker opened without the preview panel | There was no room for it on screen | Widen the window or give the editor more height — the list works the same without the preview | See also - Account, agents and teams - Replying, private notes and mentioning colleagues

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 The panel has two independent names: Installation name controls login and page titles; Brand name identifies the brand in emails and the widget. For a consistent identity, use the same spelling in both fields. Spaces are allowed. Custom names are preserved when the platform's default files are updated. Enabling an account's white label feature hides attribution on supported surfaces; it does not fill identity fields or automatically replace logos. Configure each field in the super admin panel and save. Remove Powered by hides attribution across the installation. The panel does not configure DNS, certificates, email senders or the identity of mobile apps already distributed. Colors affect compatible components; compiled legacy styles may need separate changes. Script-based colors and CSS require Custom Scripts to be enabled. Manually entered content and images containing the old brand are not rewritten. Reload pages after saving and check login, emails, the widget and Help Center separately. The ConversaLabs identity is configured through light/dark logos, the symbol, favicons and installation icons. Files uploaded in the whitelabel panel take priority over defaults: updating default files does not replace an existing upload. Check both logo versions, the super administration login and the icon after reloading. - 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. Share card In Public sharing, set a Public description of up to 300 characters (160 is recommended), an optional Share title and, when needed, a Share image URL. When the title is empty, the platform uses the Installation name. When the public description is empty, the platform retains its standard public description, independently of the installable-app setting. The image URL must be public HTTPS; the server does not download or test that image. When it is empty, the card reuses the managed brand icon when one is available. The recommended image reference is 1200 × 630 px. The panel preview confirms the values published in HTML, but it does not confirm when WhatsApp, social networks or other services will refresh their own caches. Validate the published HTML and treat a remote card refresh as a separate step. 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. - Do not put personal data, tokens or management links in the public description, title or URL. 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. Browser icons and upgrades Public survey, payment, contract and widget pages use the same browser icon as the panel. The Help Center keeps its own portal logo when configured; without one, its tab follows the installation icon. The legacy /favicon.ico address redirects to that resolved icon without caching it. A customized installation with no usable icon gets no default product icon. Only HTTP(S) URLs and safe local paths are accepted; unreadable branding configuration does not break these pages. The API viewer allows the icon's exact storage origin, without allowing other external image origins. After an upgrade, existing managed branding scripts receive the content produced by the current brand settings. Disabled scripts stay disabled, deleted scripts are not recreated, and targeting and recorded incidents remain intact. An unchanged script is not saved again. With no configured script-based branding, the upgrade does not touch scripts. Saving in the whitelabel panel remains the explicit way to create or reactivate managed scripts. See also - Custom Scripts: inject JS/CSS - Administration overview - Account, agents and teams - Guided Tours

Help Center: write, review and publish articles

Overview The ConversaLabs Help Center is your account's public content site. Each portal holds categories and articles, and every article exists in one language — translations of the same article are linked to each other. This article covers the writer's work: the editor (and the menu that opens when you type /), the draft changes flow on an article that is already live, the screen that compares the draft against the published version, and the tools in the admin lists — search and drag reordering. The key point is this: on a published article, what you type does not go live right away. It is held as a draft until you publish the changes. On a Draft or Archived article every edit saves straight into the record, because there is nothing published to protect. Prerequisites - Access to the Help Center (Portals) in the account, with permission to create and edit articles. - The article's author must be a user of the account itself. An invalid author is rejected on creation and simply ignored on edit. - For the article to show on the public site it must be Published, have public visibility and sit in a public category of the same portal and the same account. - A published article must have content: an empty body blocks publishing. - Article body limit: 200,000 characters. Step by step Create an article 1. Open the Help Center, pick the portal and the language, then click New article. 2. Type the title. The article is created when you leave the title field and starts as Draft, with you as the author, in the category that was open (or the first category of the language), and already publicly visible. 3. Write the body in the editor. Set the author, the category and the article properties (meta title, meta description and meta tags) in the controls below the title. 4. Click Publish once the text is ready. Use Preview to open the article the way a reader will see it. Write with the slash menu (/) 1. In the article body, type /. The formatting menu opens at the cursor. 2. Keep typing to filter the options by name. 3. Move with arrow down / arrow up (or Ctrl+N / Ctrl+P) and confirm with Enter. You can also click an option. Esc closes the menu. Options available in the article editor: Heading 1, Heading 2, Heading 3, Bold, Italic, Strikethrough, Code, Bullet List, Ordered List, Table, Image, Video and Divider. Link, undo and redo are enabled as well. - Table inserts a 3-column table with one header row and one data row. - Divider inserts a horizontal rule and leaves the cursor right after it. - Image opens your computer's file picker, which accepts PNG, JPEG, JPG, GIF and WebP. Insert a video 1. Type /, then choose Video. 2. Paste the link into the Paste a video link field and confirm with Embed. The button only becomes available once the link is recognised; Cancel or Esc close the box without inserting anything. 3. Supported links: YouTube, Vimeo, Loom, Wistia, Arcade, Bunny, CodePen, GuideJar and .mp4 files. Anything outside that list is rejected with "That doesn't look like a supported video link". 4. The editor stores the address as a link in the text; the public portal is what turns that link into the embedded player. Edit an article that is already published 1. Open the article. The editor saves on its own 500 ms after your last keystroke — the header shows "Saving..." and then "Saved". 2. Because the article is published, the text goes into a draft and the site keeps showing the previous version. The header now shows the Pending changes badge, and the article card in the list shows Unpublished edits. 3. Click the Pending changes badge to open the comparison panel. The badge is a button; hovering it shows the View unpublished changes hint. 4. To go live, click Publish changes. To throw the draft away and keep the text that is live, open the menu next to the button and choose Discard changes. Compare the draft against the live version The Unpublished changes side panel only shows what changed — if only the body changed, the title block does not even appear: - The title is compared word by word; what left is struck through and what came in is highlighted. - The body is compared block by block (paragraph, heading, list, code block). A block only shows as changed when the rendered result changes — reshuffling blank lines produces no difference. - Fenced code blocks (three backticks or three tildes) and lists are treated as a single block, so they never appear cut in half. - A block that came in carries a green marker; a block that left is struck through with a red one. The comparison decides on the rendered HTML in CommonMark — the same dialect the public portal uses — not on the raw text; that is why a spacing-only edit produces no difference. - On very large texts (over 2,000 blocks or words on either side) the detailed comparison is dropped: everything live shows as removed and the whole draft shows as added. - Tables are displayed with the column widths you set in the editor. Settings & options Article status | Status | What it means | Where your typing goes | | --- | --- | --- | | Draft | Does not appear on the public portal. | Straight into the article record. | | Published | Appears on the public portal. | Into the draft changes, until you publish. | | Archived | Leaves the portal; use it to mark obsolete content. | Straight into the article record. | From Published the menu offers Archive and Draft. From Archived, Draft. From Draft, Archive. The Publish button is disabled on an article that is already published and has no pending changes. Changing status with pending changes If you send a published article to Draft or Archive while draft changes exist — from the editor menu or from the card menu in the list — the Unpublished changes confirmation appears with two ways out: - Apply changes: promotes the draft into the article text and applies the new status. - Discard changes: throws the draft away and applies the new status. While either action is in flight, the confirmation does not close on Esc or on a click outside. Article search - The Search articles... field sits in the list header and fires 500 ms after you stop typing. - The term goes into the page address, so the result survives a reload and can be shared. - Search runs on the server across title, description and content, weighted towards the title, and matches the start of a word. - With no match, the list shows "No matching articles". On the categories screen search behaves differently: it filters the categories already loaded by name. Tabs, filters and pagination The All articles, Mine, Draft and Archived tabs carry the count of each group. There is no "Published" tab: to work with what is live, stay on All articles and use each card's status label. There are also category and language filters, and the list pages 25 at a time. Drag reordering The order you set here is the order in which articles appear in the portal category. - Dragging is only available inside a category, with more than one article (or more than one page) and with no active search and no bulk selection. - Press the card and drag. The destination shows as a dashed placeholder. - To take an article to another page, drag to the left or right edge of the list and hold: after roughly 0.6 s the page turns on its own and you keep dragging. While an edge is armed it lights up and shows an arrow — that is a cue that the turn is coming, not a button to click. - Near the top and the bottom the list scrolls on its own while you hold the card. - Esc during a drag cancels the operation and nothing is saved. - The new position shows immediately and, if the server refuses it, the order reverts and the message "Unable to reorder articles. Please try again." appears. - When the server accepts, the list adopts the positions it returned, so the next drag never starts from a stale number. Categories can also be reordered by dragging on the categories screen, and dragging is disabled while a search is active. Bulk actions Select one or more cards to open the action bar: Publish, Draft, Archive, Category (move), Translate and Delete. - A bulk Publish also publishes each article's draft when it has pending changes. - Bulk Draft and Archive skip articles with pending changes and tell you how many were skipped — open each one to publish or discard. If every selected article has unpublished edits, nothing is applied and "These articles have unpublished edits — open each to publish or discard." appears. - The selection clears itself whenever the list changes (page, tab, filter or search), so check what is ticked before firing an action. - Delete asks for confirmation and is permanent. - Translate only appears on Enterprise installations with the Captain Tasks (captain_tasks) feature enabled for the account. - Each card's own menu carries the same status changes and, when a draft is pending, Discard changes too. Use cases - Fix a live article without taking it offline: edit freely, check the comparison panel and only then click Publish changes. - Four-eyes review: the writer leaves the draft ready and says so; the reviewer opens the same article, uses the comparison panel and decides between publishing and discarding. - Reorganize a category: enter the category, drag articles into the order the reader should meet them, and use the edge drag to move an article between pages. - Clean up old content: on All articles (or inside a category), tick the expired articles by their status label and use a bulk Archive. - Find a specific passage: use search — it also looks inside the article body, not only the title. Tips, limits & best practices - Autosave sends title and body together, so editing one field never drops a recent edit to the other. - A save that only touches the draft does not change the article's update date. That date only moves when something is written to the record — publishing the changes, or changing the category or the author. - If the draft becomes identical to what is live, it is cleared on its own and the pending changes badge disappears — that is the case when you undo an edit or only touch spacing. - If you send a published article to Draft and then edit it, the old draft is promoted and cleared, so a future publish cannot resurrect stale text. - Leaving the editor with a pending save does not lose the edit: it is sent on the way out. - Discard changes has no undo. - Each image uploaded from the editor must be under 4 MB. Above that, "Image size should be less than 4MB" appears and the file is not uploaded. - Inside a table cell the / menu hides headings, lists, image, table, divider and video: a markdown table cell only holds inline content, and the rest would be lost on save. - The addresses search, articles and categories are reserved and cannot be used as an article's address. - Two articles sharing the same position do not swap places between visits: the tiebreak is stable. Troubleshooting - The Publish button is disabled. The article is already published and has no pending changes. Edit something, or use the menu beside it to change the status. - "Still saving your latest changes" appeared. An autosave is in flight. Wait a moment and try again — publishing right then would push stale text live. - I published, but the article returns a not-found page on the portal. Confirm that the article's category is public and belongs to the same portal and account. Legacy articles with no visibility set are also refused at publish time until a platform administrator classifies their provenance. - The pending changes badge disappeared after I saved. The draft became identical to the live version — usually because the edit was undone or only touched spacing, which does not change the published result. - The bulk action said it skipped articles. Those articles had unpublished edits. Open each one and choose between publishing and discarding before repeating the action. - I can't drag the cards. Check that you are inside a category, that no search is active, that no article is selected, and that there is more than one article. - Options are missing from the / menu. The cursor is most likely inside a table cell. - The video link was rejected. The provider is not on the supported list. Host the video on one of the accepted services or use an .mp4 file. - The article won't save. Check that the body has not gone past 200,000 characters and that the article has content before trying to publish. See also - Help Center portal settings - Administration overview - Whitelabel (your own brand) - Custom Scripts: inject JS/CSS into dashboard, portal and widget - Dynamic variables

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. Login background and public scripts The login, signup and password-reset request pages run enabled dashboard Custom Scripts that match their route. The managed login background uses ctx.dom.css; ctx.log and cleanup helpers also work. On these public pages, ctx.store, ctx.api and ctx.storage are unavailable, account-scoped scripts are excluded, and execution status is not sent to account APIs. Scripts remain trusted operator JavaScript, not sandboxed code. Use run_on: route_change with /app/login* for login-only styling; its managed resources are removed when leaving that route. Password editing remains excluded, including when reached through SPA navigation. If the initial page is password editing, reload a permitted page to load its scripts. After applying branding, reload the login page; public pages do not subscribe to authenticated hot reload. 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. Execution reports Browser error reports send only the execution status and error message, not the stack trace, raw page URL or run-on metadata. Reproduced storm incidents keep their sanitized page path; managed branding scripts retain their exemption from automatic disabling. Review messages before sharing them: a script can include its own data in an error message. 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 list inside the platform, opened by the Notifications item in the sidebar. - Email: summaries and alerts in your inbox. - Push: alerts in the browser and/or the mobile app. Where notifications show up The same history is served by two screens, and both read the same notification list: - The list opened by the Notifications item in the sidebar (inbox icon), at /app/accounts/<id>/inbox-view. The unread counter next to the item comes from here. - The same list as a table, at /app/accounts/<id>/notifications. There is no sidebar link to it: the Go to Notifications shortcut in the command palette (Ctrl/Cmd + K) opens it, and a bug-report reply links to it with ?bug_report=ID. Neither needs a special permission: both use the standard dashboard access set that every profile (Administrator, Agent, native role, or Enterprise role) already has. 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. - Where preferences live: in your Profile → Settings (/profile/settings). It is the same address for every profile; there is no administrator version of that screen. - One checkbox per event and per channel: each event has an independent checkbox in the Email column and another in the push notification column, stored per agent and per account — if you work in more than one account, you tune preferences in each of them. - The list grows with the modules: besides conversation events (new conversation, assignment, new message in an assigned conversation, mention, and new message in a conversation you follow), there are events from Tasks, CRM, Payments, Calendar, Follow-up, Internal chat, Maestro, Sales, Team management, Message scheduling, and Bug reports. - The three SLA breach rows only show when the SLA feature is enabled on the account; without it they are removed from the list. 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. - I clicked Notifications in the sidebar and did not get the table: that is the expected behavior — the sidebar item opens the list at /inbox-view. For the table screen, use Go to Notifications in the command palette. - A new event showed up turned off for everyone: events are added turned off. Turn on what matters in Profile → Settings; the preference is individual and is not inherited from the team. 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 - Getting started - 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 - Getting started - 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 - Getting started - 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 account and 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. Find the right tour The launcher groups tours into Getting started, Support, Customer relationships, Operations, Growth and sales and Settings. Search by name or category, then scroll the list to choose a tour. Search ignores accents and uppercase letters. Close and reopen the launcher to clear the search. Message scheduling has its own tour: it introduces the list, filters, recurring messages, where to begin scheduling from a conversation, and management settings when you have permission. Administrative areas also have focused tours, including agents, teams, inboxes, automations, integrations, security and profile. The available list depends on your account and access. Settings & options - Account and user isolation: progress belongs to your user in the current account. Switching accounts ends the open tour; progress from another account is not reused. Older unscoped progress is preserved but is not copied automatically to each account. - Active resources only: a module tour and its steps require the module to be enabled and the user to have access. Direct start and replay follow the same rules. If access changes during a tour, unavailable steps are removed or the tour ends. - Optional videos: Super Admin's step catalog includes steps without a video. Operators can filter videos by module, language and activation. An active video does not enable a module for an account; text guidance remains available without video. Media is refreshed for the current account and language when you change context. - 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-account and 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 - Search found nothing: clear the search or try a category name. A disabled module or a screen outside your permissions will not appear, even when a video exists in Super Admin. - Progress differs after switching accounts: this is expected; use the same account and user to resume a saved tour. - 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 ConversaLabs 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 & 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 - Getting started - Reports & Analytics - Contacts & CRM

Agent statuses and breaks (Team Management)

Overview In the ConversaLabs 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 & 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 - Getting started - 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 ConversaLabs 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 & 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 - Getting started - 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 ConversaLabs 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 & 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 - Getting started - 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 ConversaLabs 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 & 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 - Getting started - 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 & 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 - Getting started - 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 & 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 - Getting started - 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. Rule per inbox Each inbox can behave differently from the account. In Settings → Inboxes → (the inbox) → Conversation rules, pick one of the three options under Auto-resolve on inactivity: - Follow the account rule (default) — the inbox uses what is configured on the account. If the account has no auto-resolve rule, conversations in this inbox are not resolved on their own. - Use its own rule — the inbox has its own period, closing message, label and "waiting for a reply" preference. The inbox rule replaces the account rule as a whole and works even when auto-resolve is off on the account. - Never auto-resolve in this inbox — conversations in this inbox stay out of auto-resolve, even with the account rule on. The screen always shows the rule in effect and where it comes from (account or inbox). The Restore the account default button returns the inbox to the account rule. On the account screen, the list Inboxes that do not follow the account rule shows every exception. Example: WhatsApp closing after 30 minutes, e-mail after 2 days, and a groups inbox that never closes on its own. 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. - "I changed the account rule and one inbox did not change" — that inbox has its own rule or has auto-resolve turned off. Open Conversation rules on the inbox and use Restore the account default. 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 ConversaLabs 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 ConversaLabs 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 ConversaLabs as an application using the ACS URL and the SP Entity ID shown on the screen, 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. A user can only belong to one account With SAML active, the platform requires each person to exist in a single account. The rule applies in both directions: - On invitation. Inviting an email that already belongs to another account is refused with "Users associated with another account cannot be added while SAML is enabled". The agent is not created. - On login. If the person belongs to this account and also to another, signing in through the IdP fails with "Authentication failed. Please check your credentials and try again." The reason is identity: a person in several accounts would have a single login record, and the authentication method is stored on that record — it cannot be SAML in one account and a password in another at the same time. For the same reason, when you turn SAML on the platform converts to the SAML method only the users who belong to this account alone; anyone who is also in another account keeps email-and-password sign-in. When you remove the SAML configuration, the way back is symmetric: the method returns to email, except for anyone who still has SAML active on another account. An agent created while SAML is on starts on the SAML method already. Mapping groups to roles (role_mappings) Beyond the three identity attributes, the configuration accepts a map of IdP group → role. Groups are read from the assertion in the groups, Group, or memberOf attributes — the first one present. The first group with a defined mapping wins, and it can point to: - a default role (administrator or agent); or - a custom role — but that branch only applies if the Custom Roles feature is enabled on the account (see Roles & Access and governance). With no map, or no matching group, the agent enters as an Agent. The map has no field of its own on the Security screen — it is written through the API, in the role_mappings field of the SAML settings: { "Administrators": { "role": "administrator" }, "Support": { "custom_role_id": 7 } } Careful: the Security screen form sends an empty role_mappings every time someone saves. If you set the map through the API and someone later saves the configuration from the screen, the map is wiped — reapply it through the API. Service provider (SP) values After you save, the platform shows the service provider (SP) values that you give to your IdP: - ACS URL — the address the IdP posts the SAML response to, shaped as https://<platform address>/omniauth/saml/callback?account_id=<account id>. It is always shown. - SP Entity ID — the identifier for ConversaLabs as an application in your IdP. - Fingerprint — the certificate's SHA-1 fingerprint, useful for verification. Two availability switches The form only appears when both are cleared, and each has its own message: - The saml feature on the account — without it, the API answers 403 with "SAML feature not enabled for this account". - SAML SSO on the installation (ENABLE_SAML_SSO_LOGIN, on by default) — when off, the API answers 403 with "SAML SSO is not enabled for this installation". That switch belongs to the installation operator, not to the account. The installation check runs first: with both off, the message you see is the installation one. 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. - I can't invite someone who already uses the platform in another account: that is SAML's single-account rule. The person must leave the other account before being invited, or you hold the invitation until SAML is turned off. - The agent can't reset their password: expected. A login account on the SAML method gets "This account uses SAML authentication. Password reset is not available. Please contact your administrator." The password is managed in the IdP from then on. - Email-and-password sign-in is refused: also expected. The response is "This account uses SAML authentication. Please sign in through your organization's SAML provider." - The certificate is refused on save: the field requires a valid X.509 certificate in PEM format. Paste the full contents, including the begin and end lines. - I turned SAML on and part of the team still signs in with a password: those are the people who also belong to another account — they are left out of the conversion on purpose. See also - Custom roles and governance (RBAC) - Audit logs - Login, profile and two-factor authentication (2FA) - Administration overview

Reports: local support, replies and history

Overview A report can be handled within the platform. Local support remains available without an external tracker or supplier sharing. Prerequisites Reports must be enabled for the account. Reporters follow their own cases. Account administrators can read account reports; replying as support or reading internal notes requires an explicit support capability granted by the installation operator. Step by step 1. Open your report in My reports and read the public conversation. 2. Reply with the requested information. The platform assigns your authenticated identity as the author. 3. Read the summary when the case reaches an outcome. Reopening preserves the conversation, evidence and earlier history. Settings & options The SuperAdmin queue offers account, owner, service state, authority, priority and delivery filters. Open a report to read the public conversation, permitted attachments and history. Support actions require the corresponding capability; account administrator access alone does not grant it. A private note and a public reply are separate actions. Changing the action clears the draft so private text is not carried into a public reply. In Reports configuration, review local support, the installation tracker and supplier sharing separately. Sharing can be disabled, manual or automatic under the current policy. The effective mode, its source and revision are displayed. The installation defines the ceiling and an account can only restrict it. Disabling pauses new supplier effects; it does not recall data already shared. Re-enabling does not automatically send old reports. Installation Linear uses a Personal API Key configured only by SuperAdmin. The account OAuth integration does not control reports. Choose a team and labels from the server catalogue; verify readiness and webhook status separately. Saving or rotating a credential is distinct from reconciling an existing report destination. Diagnostics do not create an issue or send a reply. An unconfirmed external result requires checking the existing receipt. The operator may configure a neutral public support name, signature, contact URL and terms to replace, as well as explicitly delegate support capabilities for a user in an account. Stored credentials are never shown in read responses. The report Terms of Use and Privacy Policy links are optional installation settings (BUG_REPORT_TERMS_URL and BUG_REPORT_PRIVACY_URL). New installations start with these links empty. An explicitly empty report URL hides that link; only an absent legacy setting inherits the global URL. Updating the software does not rewrite stored installer choices. Configure your own notices in SuperAdmin before enabling their links. The installer is responsible for their content and applicability; configuring a URL does not establish legal compliance. A case can be received, in triage, waiting for the reporter, in progress, resolved, closed or duplicate. Authorized support sets its owner and classification. The operator may configure a public support name, signature and contact link. The operator configures the installation tracker. When it controls status, a requested change remains pending until its remote state is confirmed. Supplier status is a separate projection and does not resolve the local case on its own. Use cases For manual sharing, authorized SuperAdmin support selects the report fields, diagnostics, attachments and optional reporter/account information, enters a reason and reviews the recipient and exact preview. Public conversation, private notes and history are never selectable for this transfer. Confirming the preview queues the authorized attempt; only a confirmed server receipt proves its outcome. Content, permissions, policy or destination changes require a new preview. Expiration disables confirmation. The supplier authenticates the installation and already knows its registered host. Leaving the optional hostname unchecked only omits it from this request; it does not make the installation anonymous. Use a public reply to communicate with the reporter. Support uses internal notes for information that must remain outside that conversation. Notes are not delivered to trackers or suppliers and do not trigger public notifications. Tips, limits & best practices Resolving, closing, marking a duplicate or reopening requires a reason and a summary. A duplicate reference must be a permitted case from the same reporter and account. Editing or withdrawing a local reply preserves its history and does not recall an external copy already delivered. A neutral name does not automatically make text safe. Avoid personal data, secrets and private links. A tracker's publication marker selects a reply; it does not sanitize its content. Troubleshooting If the report changed while you were editing it, refresh before trying again. A change awaiting confirmation is not completed. Failed or uncertain delivery does not authorize creating another issue or blindly resending it. See also Use Reports to check the case status and conversation. Ask the installation operator to review permissions, destinations and sharing. - Account, agents and teams