Contacts & CRM

Contacts and CRM overview

Overview The Contacts & CRM area is where Conversa Labs keeps track of who your audience is and what is happening with each business opportunity. Everything revolves around the contact: the person you talk to. From the contact, the platform connects companies, custom attributes, segments, conversation history and the deals in the CRM. In short, this category brings together four blocks that work as one: - Contacts: the central record of people, with CSV import and organization into segments. - Companies: group contacts that belong to the same organization. - Custom attributes: extra fields you create to store information specific to your business on contacts and conversations. - CRM: pipelines, kanban and deals to track opportunities from first contact to close, with notes, attachments, checklists, line items, value and order history. Prerequisites - An active Conversa Labs account and a user with access to the Contacts area. - For the CRM (pipelines, kanban and deals), the CRM module must be enabled for your account — it is usually on by default. - The Companies module is optional and may depend on your plan; if you do not see it, ask an administrator. - The Orders Registry is an advanced capability that may require activation. Check its dedicated article. Step by step 1. Open the Contacts area from the sidebar. 2. Create a contact manually or import your base via CSV. 3. Organize the base into segments (saved filters) to find groups quickly. 4. Define custom attributes to store the data that matters to your business. 5. Open the CRM and create or pick a pipeline; drag deals across stages on the kanban. 6. In each deal, log notes, attachments, checklists and line items, and track its value. 7. Use the Orders Registry to see the purchase history of each contact. Settings & options - Contacts: standard fields (name, email, phone, identifier, city, country) plus custom attributes. - Segments: saved filters by combined criteria (attributes, labels, date, etc.). - CRM: pipelines with their own stages, per-stage probability and per-deal rules. - Permissions: access to the CRM is controlled by the CRM management permission; administrators decide who can create and move deals. Use cases - Centralize every customer and lead in one record, coming from multiple channels. - Track sales opportunities in a visual funnel, from prospecting to close. - Segment the base for more precise campaigns, follow-ups and reports. - Record each customer's order history for more contextual support. Tips, limits & best practices - Standardize custom attributes before importing large bases — it avoids rework. - Use segments instead of loose labels for groups you query often. - Start with a simple pipeline and refine the stages as the operation matures. - Keep one contact per person: duplicates pollute reports and history. Troubleshooting - I do not see the CRM or Companies: the module may not be enabled for the account or for your role — ask an administrator. - Duplicate contacts after import: check the identifier/email column in the CSV before importing again. - I cannot move a deal: confirm you have the CRM management permission. See also - Contacts: create, import (CSV) and segments - Contact and conversation custom attributes - Companies and contact linking - CRM: pipelines, kanban and deals - Orders Registry in the CRM

Contacts: create, import (CSV) and segments

Overview The contact is the central record of each person you communicate with. Every contact stores identity data (name, email, phone, identifier), additional information and the custom attributes you define. From the contact you open conversations, create CRM deals and follow the history. You can populate your base in three ways: creating contacts manually, importing a CSV file, and letting new conversations create contacts automatically. To find groups quickly, organize the base into segments — saved filters by combined criteria. Prerequisites - An active Conversa Labs account and a user with access to the Contacts area. - To import, a CSV file with a header row as the first line. - Define the custom attributes you want to fill during import beforehand (see the custom attributes article). Step by step Create a contact manually 1. Open the Contacts area from the sidebar. 2. Use the new contact action and fill at least one identity field (name, email or phone). 3. Save. The contact becomes available for conversations and for the CRM. Import via CSV 1. In the Contacts area, open the import contacts option. 2. Download the sample CSV template, if offered, to see the expected columns. 3. Fill the file: one row per contact, with a column header on the first line. 4. Upload the file. The import runs in the background. 5. When it finishes, you get an email notification with the result (success or failure). Create and use segments 1. In the Contacts list, build a filter combining criteria (attributes, labels, dates, etc.). 2. Save the filter as a segment with a clear name. 3. Open the segment whenever you need that group, without rebuilding the filter. Bulk actions 1. In the contact list, use the "Select all" checkbox at the top of the list (or hover a contact's avatar) to pick contacts. 2. With the whole page selected, the "Select all N contacts" button extends the selection to the entire view (every page, including label views). 3. With an active selection, the bar offers the bulk actions: assign/remove labels (with on-the-fly label creation for administrators), change type (visitor, lead or customer), assign/remove owner, block/unblock, export selected (CSV by e-mail, administrators) and delete (administrators). 4. Actions apply to every selected contact; the list refreshes when done. Settings & options - Standard fields: name, email, phone, identifier, city, country, company and blocked status. - Custom attributes: extra columns you create for your business. - Segments: saved per user and reusable; each user has a limit of saved filters. - Deduplication: email, phone and identifier help avoid repeated contacts. Use cases - Upload an existing base from another tool via CSV in minutes. - Create a "leads with no reply in the last 7 days" segment for a follow-up. - Split customers by city or by custom attribute for regional campaigns. Tips, limits & best practices - Make sure the CSV is UTF-8 to preserve accents and special characters. - Use a unique identifier column (or email/phone) to avoid duplicates. - Import a small test batch first before the full base. - Standardize formats (phone in international format, dates in the same pattern). Troubleshooting - The import failed: check the notification email; it is usually a header, encoding or column format error. - Duplicate contacts: verify the identifier/email column is filled and consistent. - Broken accents: save the CSV again as UTF-8 and import once more. - I cannot find a segment: segments are saved per user; confirm you are on the right user. See also - Contacts and CRM overview - Contact and conversation custom attributes - Companies and contact linking

Contact fiscal data and address (tax ID, billing)

Overview Every contact natively stores its fiscal identity — legal type (Individual or Business), tax ID (CPF/CNPJ) and tax country — plus the full postal address (ZIP, street, number, complement, neighborhood, city, state and country). Optionally, a billing address different from the principal one. This data automatically feeds the modules that need it: Payments prefills the payer (document and address) when creating charges and subscriptions, message templates and automations gain variables such as {{contact.address_city}}, and the account AI sees the address for context — The document is shown in full to your team in the panel and the form; it is masked only when an access role says so, for bots/integrations, and in external outputs (webhooks, CSV export and message variables). Prerequisites - Permission to edit contacts. - For automatic charge prefill: an active gateway connection in Payments. Step by step 1. Open the contact (Contacts page or conversation panel) and click Edit. 2. Fill in the Type (Individual or Business), the Tax ID and the tax country (e.g. BR). A saved document is prefilled with its real value: edit it to correct it, or clear the field to remove it. 3. In the Address section, enter the ZIP (CEP): street, neighborhood, city and state are autofilled for Brazilian codes. Complete number and complement. 4. If billing goes to another address, check Different billing address. Use the Copy from address button to bring everything over in one click and tweak only what changes. 5. Save. From then on, charges and subscriptions created for this contact come with the document and address prefilled. Settings & options - Document visibility: the tax ID is validated on save (check digits) and is visible to your team. To hide it from part of the team, use Roles & access and set the tax_id field rule to masked (shows ***.***.***-09) or hidden. The value is always stored encrypted. - Billing address: unchecking the option makes billing use the principal address again. - CSV import: the columns legal_type, tax_id, tax_country, address_zip, address_street, address_number, address_complement, address_neighborhood, address_city, address_state and address_country fill the native fields. - Export: the document always exports masked; the address exports as flattened address_* columns. - Variables: {{contact.masked_tax_id}}, {{contact.legal_type}}, {{contact.tax_country}} and {{contact.address_zip}} … {{contact.address_country}} work in canned responses, macros, automations, follow-ups and the FlowBuilder. Use cases - Issue a Mercado Pago boleto without asking for the address again: the contact already has it. - A business with a head office (principal) billed at another unit (billing address). - Segment by city/country — the address feeds the contact location filters. - Segment by legal type (individual/business), document type, fiscal country and address (ZIP, city, state, country) in the advanced contact filters and segments. - Automate: the "Set contact field (fiscal/address)" action in automations, macros and flows writes legal type, document and address straight onto the native fields — e.g. a flow that asks for the CPF/CNPJ and saves the reply on the contact. - Condition: contact-triggered automations can gate on legal type, document type, fiscal country and address; in flows, the condition node uses the same contact variables. Tips, limits & best practices - Brazilian documents are check-digit validated; an invalid document is not stored in the native field (the charge can still be created with the typed value — the gateway decides). - Accounts that used the payment custom attributes (payment_document, payment_address_*) lose nothing: those values keep being read as a fallback until the automatic migration, and charges now write only to the native fields. - The ZIP autofill covers Brazilian addresses; for other countries, fill in manually. Troubleshooting - "The tax ID was not saved": check the digits — documents with an invalid check digit are rejected to protect billing. - The charge asks for a document even though the contact has one: confirm the document shows filled in on the contact panel; if empty, save it again. - The ZIP did not autofill the address: the CEP service may be unavailable — fill in manually; nothing is overwritten. See also - Contacts: create, import (CSV) and segments - Create a charge and send it in the conversation - Subscriptions and plans

Contact and conversation custom attributes

Overview Custom attributes are fields you create to store information the platform does not ship by default — for example, a tax ID, the subscribed plan, the lead source, an order number or any data relevant to your operation. Each attribute is defined once (with a name, a key and a type) and then appears in the conversation side panel and/or on the contact record. You can use attributes as criteria for segments, in automations, in campaigns and during CSV import. Prerequisites - An active Conversa Labs account. - Administration permission to create and edit attribute definitions. - Decide the type of each field before creating it (text, number, date, list, etc.). Step by step 1. Go to the account Settings and open the custom attributes section. 2. Create a new definition and choose where it applies: contact or conversation. 3. Enter a display name (what the team sees); the system generates a stable key. 4. Select the field type (see the table below). 5. For lists, enter the possible values; save the definition. 6. Open a contact or conversation and fill the new attribute in the side panel. Settings & options The platform offers these attribute types: | Type | What it is for | | --- | --- | | Text | Free text (notes, codes) | | Number | Numeric values | | Currency | Monetary values | | Percent | Percentages | | Link | Clickable URLs | | Date | Dates | | List | Choose from predefined values | | Checkbox | True/false | - Attribute model: contact (applies to the person) or conversation (applies to that interaction). - Unique key: each key is unique per model and cannot conflict with standard fields. - Optional validation: some fields accept a pattern (regex) to enforce the format. - Conversa Labs also uses custom attributes in other modules (CRM, catalog, tasks, calendar and more), each in its own settings area. Use cases - Store the customer's tax ID or document number on the contact. - Mark the lead source (ad, referral, website) as a list. - Record an order number or ticket number on the conversation. - Build segments like "Pro plan customers" using a list attribute. Tips, limits & best practices - Choose the right type from the start — changing the type later may require re-editing data. - Use lists instead of free text for fields with few options (avoids variants like "WhatsApp" and "whats"). - Standardize key naming before importing large bases via CSV. - Contact attributes follow the person; conversation attributes apply only to that interaction. Troubleshooting - I cannot create the attribute: the key may already exist or conflict with a standard field — use another name. - The value does not appear on import: check that the CSV header uses exactly the attribute key. - The field rejects the value: there may be a format validation (regex) set on the definition. See also - Contacts: create, import (CSV) and segments - Companies and contact linking - CRM: pipelines, kanban and deals

Companies and contact linking

Overview The Companies module lets you group contacts that belong to the same organization. Instead of treating each person in isolation, you start to see the corporate account: who the company's contacts are, how many interactions it generated and which deals are in progress. It is especially useful in B2B operations, where several contacts (purchasing, finance, support) talk to you on behalf of the same company. Prerequisites - The Companies module is optional and may depend on your plan. If you do not see it, it may be disabled for your account — ask an administrator. - Administration permission to enable and configure the module. - Have the contacts already created so you can link them to the company. Step by step 1. Confirm with an administrator that the Companies module is enabled for the account. 2. Create a company with at least a name (and, optionally, domain and description). 3. Link contacts to the company, associating the people from the same organization. 4. Open the company to see related contacts and the aggregated context. 5. Use company custom attributes to store specific data (segment, size, etc.). Settings & options - Company fields: name, domain, description and contact count. - Company custom attributes: extra fields created in the attributes area. - Contact linking: a contact can be associated with its company to inherit context. - CRM: a deal can be linked to a company (organization) in addition to the contact, connecting the opportunity to the corporate account. Use cases - Centralize all contacts of a corporate customer in a single view. - Track, in B2B, how many opportunities exist per company, not just per person. - Enrich reports and segments with organization data (size, market segment). Tips, limits & best practices - Use the company domain to standardize and avoid duplicate companies. - Link the right contacts: the module's value is in consolidation by organization. - Combine it with company custom attributes for richer analysis. Troubleshooting - I do not see the Companies module: it may be disabled for the account or for your plan — ask an administrator. - Duplicate companies: standardize by domain and merge repeated records. - Contact without a company: confirm it was linked to the correct organization. See also - Contacts and CRM overview - Contacts: create, import (CSV) and segments - Contact and conversation custom attributes - CRM: pipelines, kanban and deals - Organizations & Relationships: companies, roles and hierarchy

Organizations & Relationships: companies, roles and hierarchy

Overview The Organizations & Relationships module makes companies first-class entities in the platform. Each organization carries fiscal identity (CPF/CNPJ, EIN, VAT), multiple domains, address, owner and lifecycle stage — and connects everything happening around it: contacts with roles (Financial guardian, Student, Broker…), conversations, CRM deals and a 360 view with aggregated indicators. The Overview counts only records directly linked to the organization: contacts, conversations, deals, tasks, contracts, orders, charges, subscriptions, meetings and follow-ups. This prevents unrelated data from being mixed in. Parents and branches remain navigable in the Hierarchy tab, each with its own totals. It is designed for any niche: schools (guardian ⟷ student), accounting firms (accountant ⟷ client), real-estate agencies (guarantor ⟷ tenant), clinics (guardian ⟷ patient), agencies and B2B operations with a parent/branch structure. Prerequisites - The module is optional and ships disabled; an administrator must enable it for the account. - Administration permission to configure relationship types and the module options. - Contacts already registered so you can link them to organizations (contact import helps here). Step by step 1. With the module enabled, open Organizations in the sidebar. 2. Click New organization and enter at least the name. Pick the kind (individual or business), the country and the fiscal document — CPF and CNPJ are validated with check digits, and the value stays visible to your team (masked only if an access role says so). 3. Fill in the fiscal registrations (state and municipal) when the company issues invoices — the fields sit right below the document. 4. Add the organization's domains (the first one is primary). With auto-association on, new contacts with a corporate email on that domain are linked automatically. 5. Pick the owner (the agent who owns the account), the size and the timezone — all three are closed lists, so filters and segments match exactly the value you picked here. 6. Fill in the full address: type the postal code and the rest autofills; adjust number and complement. The whole address (street, number, complement, neighborhood, city, state and postal code) shows on the Overview and is the same one company invoices use. 7. In the organization's Contacts tab, link people with a role and title; mark one organization as each contact's primary. 8. In the Relationships tab, connect contacts and organizations using types that carry a label and its inverse (e.g. "Guardian" ⟷ "Dependent"). Apply a niche preset in Settings to start with the right vocabulary. 9. For corporate groups, set the parent on the branch's hierarchy field — the tree shows up in the Hierarchy tab. 10. Use Load demo in Settings to create 10 varied, connected organizations, 20 contacts and native examples of deals, tasks, orders, payments, contracts, meetings, conversations and follow-ups. Removing the demo deletes only those marked records. Settings & options - Relationship types: an account-owned catalog with label, inverse and category; idempotent presets for school, accounting, real estate, clinic, agency and B2B. - Auto-association by domain: toggles linking contacts by corporate email (free domains like gmail.com are ignored; manual links are never overwritten). - Custom attributes: create organization-specific fields in Settings → Custom Attributes, under the Organizations tab. They appear and are editable in the Custom attributes card on the organization Overview. - Lifecycle stages: use the stage field (lead, customer…) to filter the list and build segments. - Import and export: the export writes the address as separate columns (address_zip_code, address_street_name, …), plus registrations and domains — the exact format the import reads. An exported file re-imports without losing fields. The one deliberate exception is the fiscal document: it always leaves masked and the import refuses masked values, so a CPF/CNPJ never travels in the clear inside a spreadsheet. - Relationships: Add relationship accepts either another organization or a contact; each row opens the corresponding record for further analysis. - 360 overview: cards summarize every module and preserve navigation to the source record without duplicating information. Use cases - School: the organization is the school; parents join as the students' "Financial guardian" and the front desk sees the whole family before replying. - Accounting firm: every business client is an organization with a validated CNPJ; the accountant follows conversations and charges per company. - Corporate group: parent and branches in a hierarchy, with the 360 view consolidating each unit's conversations and deals. Tips, limits & best practices - The fiscal document stays prefilled in the form after saving, ready to correct. It only shows masked if the access role's tax_id field rule says so. - The hierarchy rejects cycles (a branch cannot be the parent of its own parent). - Each contact has one primary organization; the other memberships still count for search and relationships. - Automations, macros and flows work with organizations: besides Set the contact's organization and Set organization lifecycle stage, there are Set organization field (document, address, email, phone, timezone, registrations…) and Set organization custom attribute. So a flow that collected the tax id or the postal code writes it straight onto the record. - Conditions and segments now reach email, phone, website, timezone, document scheme and the address components (city, state, neighborhood, street, postal code) — you can finally ask "which companies in SP have no email". - In messages, campaigns, follow-ups and flows, use the organization variables: {{organization.address}} (full address), {{organization.address_city}}, {{organization.state_registration}} and the rest. Contracts do not have these variables yet: a contract template resolves contact.*, crm_item.*, conversation.*, account.* and company.* (your own issuing company) — use a manual variable for counterparty company data. Troubleshooting - I don't see the Organizations menu: the module is disabled for the account — ask an administrator. - Document rejected: the value failed validation (CPF/CNPJ check digits or EIN/VAT format). Check the number and the selected country. - Contact was not auto-associated: confirm auto-association is on, the email domain is corporate and the contact didn't already have a manual link. - Cannot delete a relationship type: it is in use by existing relationships; remove those first. - Postal code, street, number or state looked empty when editing: this was a bug, now fixed — the form did not read those four keys and, on save, wrote the blanks over what was stored. The form now loads the whole address, and a partial write never clears a field that was not sent. If an address was lost before the fix, just fill it in again. - I see Tax ID, Postal code, Street, City… among the contact attributes: those are the seven legacy payment fields, now superseded by the contact's native fiscal and address fields. An administrator can retire them with rake "organizations:cleanup_legacy_payment_attributes[<account_id>,apply]" — the task migrates the values to the native fields and removes only the definitions; no data is deleted. See also - Contacts: import and segments - Custom attributes - CRM: pipelines and deals

CRM: pipelines, kanban and deals

Overview The Conversa Labs CRM organizes your sales opportunities into pipelines (funnels). Each pipeline has stages (for example, Lead, Qualified, Proposal, Negotiation, Won, Lost), and each opportunity is a deal that moves across stages on a kanban board. A deal brings together everything that matters about the opportunity: title, value, current stage, priority, owner, related contact and company, expected close date and the movement history. When a deal is won or lost, you record the date and, optionally, the reason. Prerequisites - The CRM (pipelines) module must be enabled for the account — it is usually on by default. - The CRM management permission to create and move deals. Without it, you can only view. - Contacts created so you can associate them with deals. Step by step Create a pipeline 1. Open the CRM from the sidebar. 2. Create a new pipeline. You can start from a ready-made template (by niche) or build from scratch. 3. Adjust the stages: name, order and close probability for each. Create and move deals 1. Inside the pipeline, create a deal with a title and, optionally, value and contact. 2. Set priority, owner and expected close date. 3. On the kanban board, drag the deal card across stages as it progresses. 4. When done, mark the deal as Won or Lost, providing the date and the reason. 5. Need to correct the opening date (for example, a deal registered late)? On the deal page, click the opening-date badge next to the title — or edit the Opening date field in the form. The sales cycle and reports then use the corrected date. Settings & options - Stages: each stage has a name, color and probability (the "Won" stage is 100% and "Lost" is 0%). - Pipeline templates: a catalog of ready funnels by niche (B2B sales, real estate, e-commerce, post-sales, onboarding and more) to start quickly. - Deal fields: title, value, currency, priority, owner, contact, company, team, opening date and expected close date. - Deal health: the platform can compute a health indicator to flag stalled or at-risk deals. - Filters and saved views: save combinations of pipeline, period and filters to reuse. Use cases - Track a visual sales funnel, with each deal in its stage. - Prioritize the portfolio by expected close date and deal health. - Connect the customer's conversation directly to the corresponding deal. - Measure conversion rates by stage and by pipeline in reports. Tips, limits & best practices - Start with a simple pipeline; too many stages make the funnel hard to read. - Keep stage probability realistic — it feeds revenue forecasts. - Use the expected close date to prioritize and avoid forgotten deals. - Always record the loss reason to learn from opportunities that did not close. Troubleshooting - I cannot move a deal: confirm you have the CRM management permission. - I do not see the CRM: the module may be disabled for the account — ask an administrator. - The forecast value is off: review the stage probabilities and each deal's value. See also - Contacts and CRM overview - Deals: notes, attachments, checklists, line items and automatic value - Companies and contact linking - Orders Registry in the CRM

Move one stage at a time (sequential pipeline stages)

Overview A funnel only tells the truth when every deal walks the stages in order. When a deal jumps from Contact straight to Closed, your conversion report stops making sense: it looks like the opportunity closed with no qualification, no proposal and no negotiation. That jump happened often when the Bot moved deals. It only saw the number of the destination stage — no name, no type — so it picked by the name of the outcome ("Closed", "Won") and skipped the middle of the funnel. Two things were fixed: 1. The Bot now sees the funnel in order. When it looks up a pipeline's stages, it receives the real sequence, with each stage's name and type (open, won or lost). That alone cuts most of the skipping, because the Bot starts treating it as a funnel instead of a menu of options. 2. There is a per-pipeline option that REFUSES a move that skips a stage. That is the hard guarantee: with it on, the server returns an error and the deal does not move. The first fix is guidance. The second is a rule. If your operation needs a guarantee, turn the option on. Prerequisites - The CRM module enabled on the account. - At least one pipeline with stages already created and in the right order (the stage order on the settings screen is the order the rule uses). - An Administrator profile to turn the option on or off. Agents can see the setting but cannot change it. Step by step 1. Open CRM from the sidebar. 2. Click the CRM Settings (gear) and pick the pipeline you want to protect. 3. Scroll to the Closing deals section — the same one that holds Require a reason when marking won or lost. 4. Turn on the Move one stage at a time switch. 5. That is it. From then on, any attempt to move a deal past a stage is refused — whether it comes from the kanban board, the list view, an automation, the FlowBuilder or the Bot. To turn it off, flip the same switch back. The setting is per pipeline: you can enforce the sequence on your sales funnel and leave the support funnel free. Settings & options | Option | Where it lives | Default | What it does | |---|---|---|---| | Move one stage at a time | Pipeline settings → Closing deals | Off | Refuses a move that skips stages | | Require a reason when marking won or lost | Same section | Off | Asks for a written reason on close | The two options are independent and can be used together. What is ALWAYS allowed, even with the option on: - Moving back. Falling back is not skipping. A deal can return from "Proposal" to "Qualification" as many times as needed. - Marking as lost. A lost stage is always reachable, from anywhere in the funnel. A deal can die at any point — the rule never traps a live deal inside a funnel it has already left. - Advancing to the next stage. The rule blocks the jump, not the normal step forward. What gets blocked is the forward leap: leaving stage 1 and landing on stage 4. That includes jumping straight into a won stage — winning without walking the funnel distorts the report just as much. What the refusal looks like: the platform returns a message that names the missing stage, for example: "This pipeline advances one stage at a time. Move this deal to 'Proposal' first." That wording is deliberate — the Bot reads it and corrects itself, moving to the right stage instead of retrying the same jump. Use cases - A sales funnel with a trustworthy report. If the team is measured by stage-to-stage conversion, a skip breaks the metric. Turn the option on for that pipeline. - A Bot moving deals on its own. When the Bot is allowed to move CRM deals, this option is the safety net against an accidental "everything closed". - A team still learning the process. People also mis-drag cards on the kanban. The rule teaches the process in practice, with a message that says exactly where to move next. - An operational board with no strict order (support, triage, production): leave it off. Not every board is a sequential funnel. Tips, limits & best practices - The rule applies to people too, not only to the Bot. It is enforced on the server, at the moment the move is saved. The Bot acts with the same credentials as the team, so there is no way to apply the rule only to it — and that is a good thing: the same discipline applies to everyone. - Stage order is the order shown in the pipeline settings. If you reorder the stages, the rule immediately follows the new order. Review the order before turning the option on. - HONEST LIMIT — the rule fails open. If the platform cannot determine the position of one of the stages involved (for example, the deal is sitting on a stage that was archived afterwards), the move is allowed, not blocked. That was a deliberate choice: better to let a rare case through than to trap a deal with no way out. The option prevents the common skip; it does not replace human review of the funnel. - Off by default. No existing pipeline changes behavior until someone flips the switch. - Reordering a card inside the same stage is not a stage move — it is never blocked. - If you also enabled Require a reason when marking won or lost, the reason stays mandatory on close, including when the close happens by dragging the card. Troubleshooting "I can't drag the card to the stage I want." Read the message: it names the stage the deal has to go through first. Move there and continue. If your real process genuinely skips that stage every day, either the stage should not exist, or the option should not be on for that pipeline. "The Bot keeps skipping stages." Confirm the switch is on for that deal's pipeline (the setting is per pipeline, not per account). With it on, the skip is refused on the server — the Bot has no way around it. "We turned it on and a deal got stuck." Marking as lost and moving back are always allowed, so a deal never runs out of exits. If something still looks stuck, check whether the deal's current stage still exists and is active in the pipeline settings. "The switch is disabled for me." Only Administrators can change pipeline settings. Ask an administrator. "A skip went through even with the option on." That is the fail-open behavior described above: when a stage's position cannot be determined, the move goes through. Check whether a stage along the path was archived and tidy up the funnel. See also - CRM: pipelines, kanban and deals - CRM reports and analytics (funnel, SLA and forecast) - Maestro tools per module and how to enable them - Bot autonomy modes and human approval (HITL)

Deals: notes, attachments, checklists, line items and automatic value

Overview A deal in the Conversa Labs CRM is much more than a title and a stage. Each deal brings together the elements that tell the full story of the opportunity: - Notes — internal team records about progress. - Attachments — related files (proposals, contracts, receipts). - Checklists — tasks to complete, with a done/total counter. - Line items — catalog products and quantities, with the price captured when the line is added. - Value — the deal amount, which can be automatic (summed from line items) or manual (typed by you). When you add line items, the platform calculates the deal value automatically by summing each line total. This turns the deal into a small, consistent quote. Prerequisites - The CRM (pipelines) module enabled and a deal already created. - Permission to edit CRM records to change notes, attachments, checklists, items and value. - To pull items from the catalog, the Catalog module with products in place. Step by step Add notes and attachments 1. Open the deal in the CRM. 2. In the workspace, select Add note. The composer stays available in both History and Saved notes, without creating a second draft. 3. Write the context of the conversation or decision and select Save. With focus in the editor, you can also use ⌘/Ctrl + Enter. 4. Use History to follow deal changes and filter by stage, agents, links, notes or edits. Use Saved notes to review, edit, delete or load older notes. 5. Before deleting a note, confirm carefully: deletion is permanent and cannot be undone. 6. Attach relevant files to the deal to keep everything in one place. The active tab and filter are kept in the page address. Reloading or sharing the link opens the workspace in the same context. Create a checklist 1. In the deal, open the checklist section. 2. Add the items that must be completed (e.g., send proposal, schedule meeting). 3. Check each item as you go; the platform shows the completed total. Build the quote with line items 1. In the line items section, select an available catalog product. 2. Set the quantity and add the line. The unit price is captured from the catalog. 3. The platform computes the total of each line and adds it all into the deal value. 4. To return to a manual value, remove the line items. Settings & options - Automatic vs manual value: if any line item exists, the value becomes automatic (sum of the lines). With no line items, you set the value manually. - Editing the quote: on this screen, the product and price come from the catalog; to correct a line, remove it and add it again with the desired product and quantity. - Single currency per deal: all lines use the deal's currency; the first line sets the currency. - Catalog snapshot: when you add a catalog item, the name and price are frozen at that moment — editing the product in the catalog later does not change a quote you already built. - Counters: the deal shows counts of notes, attachments and checklist items (done/total). - Per-deal draft: switching between History and Saved notes preserves the text; navigating to another deal uses a separate draft so content cannot be recorded in the wrong place. - History in the account timezone: history dates and day groups follow the timezone configured for the account. Use cases - Build a proposal inside the deal itself, with catalog products and quantities. - Track a qualification checklist before advancing the stage. - Keep the PDF proposal and receipts as attachments on the deal. - Keep the pipeline value consistent with the customer's real quote. Tips, limits & best practices - Prefer line items for quotes: the value stays correct and auditable. - Since the catalog item is a snapshot, update prices in the catalog before building new quotes. - Use notes for internal history and attachments for documents — don't mix the two. - Keep the checklist lean and actionable; it guides progress through the stages. Troubleshooting - The value doesn't sum the items: check that line items exist; with none, the value is manual. - I can't change the currency: the currency is single per deal and set by the first line — remove the lines to reset it. - The price differs from the catalog: the item keeps the price from the moment it was added (snapshot). - I don't see line items: confirm the Catalog module is enabled and has products. - I can't find an older note: open Saved notes and use Load more notes until you reach the record you need. - History is empty after applying a filter: select Clear filter; the loaded pages may not contain matching events. - A note was not saved: keep the editor open and try again. The draft remains with the deal while the page is open. See also - CRM: pipelines, kanban and deals - Companies and linking to contacts - Contacts and CRM overview - Orders Registry in the CRM

Contact type: Visitor, Lead and Customer

Overview Every contact has a type that represents their stage in the relationship: - Visitor — not yet identified (no email, phone or social profile). - Lead — already has some way to reach them (email, phone or an external channel like WhatsApp). - Customer — promoted manually (or by automation) after buying/closing. The type appears as a colored badge in the Contacts list and in the contact panel inside a conversation, where you can change it in one click. Prerequisites - None. The contact type is native and always available. Step by step See the type 1. Open Contacts. Each contact shows its type badge next to the name. 2. Inside a conversation, open the contact panel on the right — the badge appears next to the name. Change the type (in a conversation) 1. In the contact panel, click the type badge. 2. Pick Visitor, Lead or Customer. The change is saved immediately. Filter / segment by type 1. In Contacts, open Filter. 2. Choose the Contact type attribute and a value (Visitor / Lead / Customer). 3. Save it as a segment to reuse. Settings & options - Automatic promotion: a Visitor contact automatically becomes a Lead as soon as it gets an email, phone or a social identifier (for example, when it arrives via WhatsApp). The Customer type is never set automatically — only manually or by automation. - Change via automation, macro or FlowBuilder: use the Change contact type action (change_contact_type) — available in automation rules, macros and the FlowBuilder Contact action node — to set Visitor / Lead / Customer automatically (e.g. become a Customer when a payment is confirmed). Use cases - Qualification: a flow marks the contact as Customer when a sale closes. - Segmentation: build a Customers segment for a post-sale campaign. - Hygiene: filter old unidentified Visitors for cleanup. Tips, limits & best practices - The type is never downgraded automatically — a Customer won't revert to Lead on its own. - The three types (Visitor, Lead, Customer) are fixed; custom types aren't part of this release. Troubleshooting - The contact reverted to Lead after I saved it as Visitor? If it has an email/phone, automatic promotion sets it to Lead on save. To keep it at another stage, use Customer. See also - Contact import and segments - Custom attributes

Orders Registry in the CRM

Overview The Orders Registry is a contact-centric purchase history. For each contact (and, optionally, for each deal) you record orders with a title, value, currency, status and date, building a clear view of everything that person has bought. It's important to understand what it is and what it is not: the orders registry is a log, not a payment gateway. It does not charge, refund or reconcile money — billing is handled by the Payments module. Marking an order as "refunded" or "canceled" here is just a history note, not a financial operation. Orders can arrive from several origins: entered manually, received via webhook, created through the API, originated from the Payments module, or from commerce integrations. Prerequisites - The Orders Registry is optional and off by default. Ask an administrator to enable it for the account. - CRM management permission to create and edit orders. - Contacts in place — every order belongs to a contact. Step by step 1. Confirm with an administrator that the Orders Registry is enabled. 2. In the sidebar, open Orders. The page brings together the orders you are allowed to consult, including those linked to existing contacts and deals. 3. Use search, date range, source, gateway, status and sorting to find the required slice. Those filters stay in the page address, so they can be reloaded or shared. 4. Create a manual order with an existing contact, title, value, currency and status. 5. When products are involved, inspect their name, quantity, unit price and discount; they preserve the financial snapshot of the sale. 6. Optionally, set the order date and paid date, and link the order to a deal. 7. Export the same slice as CSV or select manual orders for the available bulk action. Their checkbox is disabled and Select every manual order in these filters also reaches manual orders only. Integration orders are protected from editing and deletion in the screen. 8. If an integration order has the wrong customer or links, use Fix the sale customer and links. Choose the contact, review the related charge and recovery event, and apply the preview. This does not edit the order's financial snapshot and remains available when the integration record is immutable. Settings & options - Order status: pending, paid, partially paid, overdue, refunded, canceled and failed. - Source: manual, webhook, API, Payments or commerce — identifies where the record came from. - Links: every order belongs to a contact and can be linked to a CRM deal. - Currency and value: each order has its own value and currency (default BRL). - External identifier: orders from integrations carry an external ID that prevents duplicates. - Order items: each item's name and amounts are a sale snapshot. Later Catalog changes do not rewrite what was sold; when available, the item also retains its link to the same account's product or variant. - Owner-based wallet: when owner-based privacy is active, each rep sees only the orders of the contacts/deals they can access. - Global list and CSV: the Orders page is server-paginated; export honors the current filters and selection without including data outside your scope. - Edit vs fix links: only manual orders have normal edit and delete. The separate contact, organization, deal, and conversation correction preserves amount, status, items, dates, and external identity. Use cases - Keep each customer's purchase history right on the contact profile. - Track, on the deal, the orders already placed for that opportunity. - Consolidate orders from multiple origins (manual, Payments, commerce) into a single log. - Feed automation and reports based on what each contact has bought. - Compare a deal's quoted budget with the catalog items that were actually settled in the Catalog report. Tips, limits & best practices - Use the orders registry for history; to actually charge, use the Payments module. - Standardize titles and statuses to make reading and filtering easier. - When integrating via webhook/API, send a stable external ID so orders aren't duplicated. - Send a stable item identifier for every integrated item too; a redelivery of the same order then does not duplicate its lines. - Link the order to the matching deal when it makes sense, to connect sale and opportunity. - Edit or delete manual records only. On an imported order, use Fix customer and links only for associations; correct amount, status, items, dates, or external ID at the source and synchronize again. Troubleshooting - I don't see the Orders section: the module may be disabled for the account — talk to an administrator. - Duplicate order: check that the integration is sending the same external ID instead of creating a new one. - The order didn't charge the customer: that's expected — the registry is a log; charging is done in Payments. - The Catalog name or price changed: the recorded item keeps the original sale snapshot; this is intentional to preserve financial history. - I can't create an order: check your CRM management permission and that the contact exists. - I can't edit an imported order: this is intentional. Records received from Payments, commerce, API or a webhook protect financial facts from redelivery. If only the customer or another association is wrong, use Fix the sale customer and links on the order row. See also - CRM: pipelines, kanban and deals - Deals: notes, attachments, checklists, line items and automatic value - Contacts and CRM overview Remove test or orphaned orders In Orders, administrators can remove records created by charges or integrations. Select a correction type and enter a reason. The order immediately leaves the Operational view, while its source, actor, reason, and any compensations remain in the audit history. A never-paid manual order without a linked charge can be deleted permanently. Paid or integration-backed orders are voided, not erased: open commissions, stock, and engagement score are compensated atomically. A closed commission blocks the operation to prevent financial divergence. Use Record state → Voided to review removed records. Restore is available only when the void created no accounting, stock, or engagement compensation and the external identity is still available. To purge the charge itself, archive it first. Only a non-settled charge can be deleted permanently; deletion requires a reason and voids/unlinks the related order before removing the local charge. These actions never cancel or refund money at the gateway.

CRM reports and analytics (funnel, SLA and forecast)

Overview CRM Reports is the analytics dashboard for your sales operation in Conversa Labs. On a single screen you track conversion, open and won value, weighted forecast, the per-stage funnel, SLA compliance, deal health and priority, and a top-owners ranking — all filterable by pipeline and period. It is an administrative surface: access is restricted to users with the administrator role. You open it from the sidebar at CRM > Reports (route crm_reports_index). Prerequisites - The administrator role on the account. Agents cannot access this screen. - The CRM (pipelines) module enabled for the account. - At least one pipeline with deals so the panels have data to display. Step by step 1. Open the CRM from the sidebar and select Reports. 2. In the pipeline filter, pick All pipelines (account-wide report) or a specific pipeline. 3. In the period filter, pick a preset window (7, 30 or 90 days), All time, or Custom to enter a start and end date. 4. Read each panel top to bottom: the summary KPIs, the distributions (SLA, health, priority), the per-stage funnel (when a pipeline is selected), and the top owners. 5. To reuse a pipeline + period combination, save a view (see "Settings & options"). Settings & options Panels and metrics - Summary (KPIs) — the big picture of your book of business: - Open deals, plus the won / lost counts. - Conversion rate = won ÷ (won + lost). - Win rate = won ÷ total deals in the period. - Average cycle time — the average time between the opening date and the close for closed deals (the opening date is editable on the deal; it defaults to the creation date). - Open value, won value and weighted forecast, always grouped by currency. - Per-stage funnel — per pipeline stage: deal count, open value and forecast by currency, and the stage SLA. Requires a specific pipeline to be selected. - SLA of open deals — buckets open deals into on track, due soon (near the limit), breached (over the SLA) and no SLA (stage without an SLA defined). - Health distribution — healthy, at risk and critical. - Priority distribution — low, medium, high and urgent. - Top owners — a ranking of deal owners by number of open deals and by open value per currency. Weighted forecast The forecast sums, for each open deal, its value multiplied by the probability of the stage it sits in. More advanced stages weigh more in the forecast — so keeping stage probabilities realistic makes the forecast more reliable. Filters and saved views - Pipeline: All pipelines or a specific pipeline. - Period: 7 / 30 / 90 day windows, All time, or Custom (start/end date). - Saved views: save the current pipeline + period combination as a named preset and apply it later with one click. Views use the saved-filter mechanism (a report filter type). Multi-currency Values are grouped by currency, with no automatic conversion. If your book has deals in different currencies (for example BRL and USD), each currency shows its own total, side by side. Use cases - Track conversion by stage and spot where deals stall in the funnel. - Prioritize the team's effort by the weighted forecast and the open value. - Monitor SLA and health so you can act before deals breach their deadline or turn into risk. - Compare owners by open-deal volume and by open value. Tips, limits & best practices - The funnel only appears with a specific pipeline selected. With All pipelines, the account-wide report omits the funnel (stages belong to each pipeline, so a consolidated funnel would not make sense). - The period filters by the deal's opening date (by default the creation date — correctable on the deal itself), not by the close date. Adjust the window to match what you want to measure. - Keep stage probabilities realistic — they feed the weighted forecast directly. - The owners ranking shows the top owners by open deals; owners with no open deals in the period do not appear. Troubleshooting - The funnel is empty: select a specific pipeline in the filter — the account-wide report shows no funnel. - Access denied / I can't see Reports: the screen is administrator-only. Ask an account administrator for access. - Values show in different currencies: this is expected — there is no automatic conversion; each currency has its own total. - The numbers look low: check the period (it filters by opening date) and the selected pipeline before comparing. See also - CRM: pipelines, kanban and deals - Orders Registry in the CRM - Contacts and CRM overview