Automation & Flows

Automation & Flows overview

Overview The Automation & Flows area brings together the tools that make Conversa Labs work for you: assigning conversations, replying at the right moment, moving deals in the CRM, firing webhooks, and running entire dialogues with no manual effort. Instead of repeating tasks, you describe what should happen and the platform does it. There are five complementary capabilities, from the simplest to the most advanced: - Automation rules — "when X happens, do Y" (trigger → conditions → actions). - Macros — reusable sequences of actions an agent runs with one click on a conversation. - Flow Builder — a visual builder for conversational flows (menus, questions, integrations). - Smart Routing — distributes conversations to agents based on a policy. - Bots and Captain — AI-powered replies and support bots. Prerequisites - An active Conversa Labs account and a user with admin permission to configure automations. - At least one connected inbox, so there are conversations to automate. - Some capabilities are optional (enabled by plan or feature flag): Flow Builder, Smart Routing, and Captain may need to be enabled for your account. If they aren't in the menu, talk to an administrator. Step by step 1. Start with the basics: create an automation rule for your team's most frequent repetitive task (for example, assigning new conversations to a team). 2. Standardize day-to-day replies and procedures with macros. 3. When you need a multi-step dialogue (menu, data capture, integration), use the Flow Builder. 4. Decide how conversations reach agents with Smart Routing. 5. Add bots and Captain to answer common questions and qualify contacts automatically. Settings & options - Automation rules: live under Settings, in Automation. Each rule has a trigger, conditions, and one or more actions. - Macros: also under Settings; they become available inside the conversation for the agent to run. - Flow Builder: its own module, with a visual node builder (messages, options, conditions, HTTP requests, and more). - Smart Routing: routing policies and capacity policies, bound to inboxes. - Captain: AI assistants, a document and response knowledge base, and the agent copilot. Use cases - Automatically assign new conversations to the right team and add labels by keyword. - Send an after-hours greeting and resolve a conversation after inactivity. - Run a menu-based self-service experience on WhatsApp with the Flow Builder. - Balance load across agents with a balanced routing policy. - Let Captain answer frequently asked questions and only escalate to a human when needed. Tips, limits & best practices - Start with a few rules and watch the result before creating dozens of automations. - Give rules and macros clear names — it keeps maintenance manageable as the operation grows. - Watch out for overlapping rules (two rules acting on the same conversation). Test in a sandbox inbox before applying to production. - Respect channel limits (for example, WhatsApp anti-ban best practices when sending automatic messages). Troubleshooting - My rule didn't fire: check the trigger and conditions — all conditions must be true. Also confirm the rule is active. - I don't see Flow Builder / Smart Routing / Captain: the capability may not be enabled for your account or your access role. Talk to an administrator. - The action didn't happen: confirm the agent/team/label referenced in the action still exists. See also - Automation rules: triggers, conditions, and actions - Macros: reusable actions - Flow Builder: visual conversational flows - Smart Routing - Bots and Captain (support AI)

Automation rules: triggers, conditions, and actions

Overview An automation rule runs actions automatically when an event happens and the conditions you set are met. It's the most direct way to remove repetitive work: assigning conversations, adding labels, sending messages, resolving conversations, moving CRM deals, or notifying external systems via webhook. Every rule follows the structure trigger → conditions → actions: - Trigger: the event that starts the evaluation (for example, "conversation created"). - Conditions: filters that must be true for the rule to act. - Actions: what the platform does when the trigger fires and the conditions pass. Prerequisites - Admin permission to access the Automation area under Settings. - At least one inbox with conversations, so triggers have something to evaluate. - For actions that depend on other modules (CRM, Catalog, Tasks, Follow-ups), the matching module must be enabled on the account. Step by step If there are no rules yet, the page's empty state summarizes what automation does and lets you create the first rule without hunting for another action on the screen. 1. Under Settings, open the Automation area and create a new rule. 2. Give the rule a clear name and description. 3. Choose the trigger (event). The main ones are: - Conversation created, Conversation updated, Conversation resolved, Conversation opened; - Message created (incoming or outgoing); - Contact created, Contact updated, Contact merged, Contact deleted — rules that act directly on the contact record, with no conversation required; - Orders: order registered, order status changed, order paid, order refunded and deal orders fully paid (with the Payments/Commerce modules active); - Contracts: contract viewed, signer signed and contract expired (with the Contracts module active); - Calendar — two levels, and the difference matters: - Booking created / rescheduled / cancelled: the customer booked, rescheduled or cancelled through the public booking page (that is, there is a booking behind it); - Calendar event created / rescheduled / cancelled: the appointment itself changed — including when an agent edits, drags or cancels it from the panel, or from the Schedule tab inside a conversation. An appointment that has a booking fires both levels when you change it from the panel; an appointment created straight on the calendar, with no booking, fires only the event level. - CRM, Catalog, and Task events when those modules are active. 4. Add conditions. Combine fields (status, priority, inbox, labels, browser language, contact/conversation attributes, CRM fields) with operators such as equal to, not equal to, contains, or does not contain. Contact and order triggers expose dedicated conditions: city, contact type (visitor, lead or customer), blocked, order status, order gateway and order amount — plus the contact's custom attributes. 5. Define one or more actions (see the list below). 6. Save and activate the rule. Test with a real conversation to confirm the behavior. Settings & options Available actions (they vary by trigger and active modules): | Action | What it does | | --- | --- | | Assign agent | Routes the conversation to a specific agent. | | Assign team | Routes the conversation to a team. | | Add label | Tags the conversation with one or more labels. | | Send message | Sends a message to the contact. | | Send email to team | Notifies the team by email. | | Send transcript by email | Emails the conversation history. | | Mute conversation | Mutes the conversation. | | Resolve conversation | Closes the conversation automatically. | | Send attachment | Attaches a file to the conversation. | | Fire webhook | Sends the event to an external endpoint. | | Add contact label | Tags the contact (not the conversation) with labels. | | Remove contact label | Removes labels from the contact record. | | Add contact note | Logs an internal note on the contact record. | | Set contact attribute | Writes a value into a contact custom attribute. | | Launch mass run | Starts a mass run of a published Flow Builder flow. | When the modules are active, module-specific actions appear: move a deal between stages, assign and set value/priority in the CRM, add a product to a deal in the Catalog, create tasks, and enroll the contact in a Follow-ups sequence. On the contact triggers (created/updated/merged) the rule runs against the contact — and now offers the whole contact-anchored catalog: beyond the contact actions (labels, note, attribute), you can create a CRM deal already linked to the contact, move a stage, create a task or appointment tied to the contact, send charges and subscriptions, enroll in follow-ups and contracts, run engagement and WhatsApp group actions (the default participant is the contact itself), fire a webhook, and launch a mass flow run. Actions that operate on a conversation (assign agent/team, resolve, send message/note/attachment, SLA, AI/Maestro, WhatsApp template) remain unavailable on these triggers because there is no conversation — use Create conversation to chain into a conversation trigger. - "AND" conditions: every condition must be true for the rule to act. - Order: actions run in the order they appear in the rule. - Enable/disable: you can pause a rule without deleting it. Actions by trigger The action list is scoped by the trigger's subject: each trigger offers every action its subject can actually run — so you build the complete rule without combinations that would never fire. - Conversation and message triggers (conversation created, updated, opened, resolved and message created) offer the full catalog of actions. - Contact triggers (created/updated/merged) offer the whole contact-anchored catalog: CRM (create a deal already linked to the contact, move a stage), tasks and appointments tied to the contact, charges and subscriptions, follow-ups, contracts, engagement, WhatsApp group actions (default participant = the contact), webhook and mass flow run. Actions that operate on a conversation are left out (there is no conversation) — chain with Create conversation. - Contact deleted trigger: because the record no longer exists, it offers only webhook and fully parameter-driven actions. - Order triggers anchor on the order's contact — every contact-anchored action is available. - Task, calendar, WhatsApp group, subscription, commerce, contract, engagement, CRM and ads triggers gained the full catalog their subject supports — including conversation actions when the subject has a linked conversation (for example, a task with a linked conversation or a group with the group's conversation). When you create a new rule (or switch the trigger), the selector already comes with the first valid action for that trigger pre-selected — you never again open a new rule and find "Assign to Agent · Not available for this trigger". If you edit an older rule that holds an action no longer belonging to the current trigger, that action stays visible with a "Not available for this trigger" tag. It is not removed: the rule is still saveable and you can swap it for a compatible action whenever you want. Actions with no parameters Some actions ask for no extra field because they resolve the context on their own from the trigger. They save without requiring parameters, in both Automations and Macros: - Cancel, pause, resume and skip step for follow-ups; - Send charge and cancel subscription; - Send product card; - Pause ad campaign, send conversion and tag as ad lead. When an action doesn't apply If an action depends on something that doesn't exist in that context — for example, a conversation action on a trigger that has no linked conversation — it is skipped and logged, without breaking the rule: the remaining actions still run normally. Use cases - Channel routing: conversations created on the sales WhatsApp go to the Sales team. - Keyword triage: if the message contains "invoice", add the "billing" label. - After hours: when a conversation is created outside business hours, send an automatic message. - Queue hygiene: resolve conversations with no reply for a long time and notify the team. - CRM: when a lead's conversation is created, create a deal and assign it to the right rep. Tips, limits & best practices - Use descriptive names and keep each rule focused on a single goal. - Avoid conflicting rules that try to do opposite things on the same conversation. - For actions that send automatic messages, respect channel limits (WhatsApp anti-ban best practices). - Test in a sandbox inbox before applying the rule to production. - Document for the team what each rule does — it makes future maintenance easier. Troubleshooting - The rule didn't fire: confirm the trigger and that all conditions are true; check the rule is active. - The action didn't run: verify the referenced agent, team, or label still exists; and that the action's module (CRM, Catalog, etc.) is enabled. - The rule acted on the wrong conversation: the conditions are too broad. Refine the filters. - An action was skipped: some actions only run when there is a conversation in the trigger's context; otherwise they are logged and skipped without interrupting the rule. Prefer an action that is compatible with the chosen trigger. - The webhook didn't arrive: check the endpoint URL and that it responds successfully. See also - Automation & Flows overview - Automation triggers about the AI (Maestro) - Macros: reusable actions - Flow Builder: visual conversational flows - Smart Routing

Contact automations: triggers and actions on the record

Overview Contact automations let you react to changes on the contact record, not just on conversations. With them, the platform can tag a contact, log a note, write a custom attribute, create a new contact, or even open a new conversation — automatically, the moment the data changes. Two groups of capabilities work together: - Contact triggers: contact created, contact updated, contact merged, and contact deleted. They evaluate the rule against the contact itself, with no open conversation required. - Contact and create actions: add/remove label, add note, set custom attribute, create contact, create conversation, and add private note — available in Automation rules, in Macros, and in the Flow Builder. In Automation rules, the contact triggers created, updated, and merged are no longer limited to these actions: they now offer the whole catalog of contact-anchored actions — CRM, tasks, calendar, charges, subscriptions, follow-ups, contracts, engagement, and WhatsApp group actions — described in the "The full catalog on the contact" section below. Prerequisites - Admin permission to create rules, macros, and flows with contact actions. - At least one contact on the record, so contact triggers have something to evaluate. - For the create conversation action, you must pick a destination inbox. - For conditions on a contact custom attribute, the attributes must be defined on the account (they appear automatically in the pickers). Step by step Example: when a contact is updated AND the custom attribute plan equals premium, add the premium-customer label. 1. Under Settings, open the Automation area and create a new rule. 2. For the trigger, choose Contact updated. 3. Add the condition: select the custom attribute plan, the operator equal to, and the value premium. The possible values are loaded automatically in the picker — you don't type free text. 4. For actions, choose Add contact label and select premium-customer. 5. Save and activate the rule. Update a test contact to confirm the behavior. To use the same actions elsewhere: in a Macro, add the contact action to the sequence the agent runs with one click; in the Flow Builder, use the Contact action node (or the matching action inside the action node) — see the Flow Builder native-actions article. Settings & options Actions available in all three places (Automations, Macros, and the Flow Builder): | Action | Key | What it does | | --- | --- | --- | | Add contact label | add_contact_label | Tags the contact with one or more labels. | | Remove contact label | remove_contact_label | Removes labels from the contact record. | | Add contact note | add_contact_note | Logs an internal note on the contact. | | Set contact attribute | set_contact_custom_attribute | Writes a value into a custom attribute. | | Create contact | create_contact | Creates a contact with name, email, and phone (inbox optional). | | Create conversation | create_conversation | Opens a conversation in an inbox, with optional status and first message. | | Add private note | add_private_note | Writes a private note on the conversation. | - Create contact: provide name, email, and phone, and optionally the inbox. Creation goes through the native contact builder, which deduplicates by identifier, email, or phone — if the contact already exists, it is reused instead of duplicated. - Create conversation: pick the inbox (required) and, if you want, the initial status (open, pending, or snoozed) and a first message. The conversation is created for the resolved contact. - Condition auto-load: in the condition pickers, the contact's custom attributes and their values are loaded automatically — no free-text boxes to guess. - Account webhooks: besides contact created and updated, you can subscribe to the contact.merged and contact.deleted events to notify external systems. The full catalog on the contact In Automation rules, beyond the actions in the table above, the contact triggers created, updated, and merged now offer every action that has the contact as its anchor: - CRM: create a deal already linked to the contact, move a stage, set value/priority, and assign an owner. - Tasks and calendar: create a task or an appointment tied to the contact. - Payments: send charges and subscriptions to the contact. - Follow-ups, contracts, and engagement: enroll the contact in sequences, send contracts, and run engagement actions. - WhatsApp groups: group actions where the default participant is the contact itself. - Webhook and mass flow run: notify external systems and launch published flows. Conversation actions do not apply on these triggers — assign agent/team, resolve, send message/note/attachment, SLA, AI/Maestro, and WhatsApp template all need a conversation, which does not exist in this context. To chain them: use Create conversation in the contact rule itself and build the second step on a conversation trigger (the "Create conversation to chain" pattern). Contact deleted is the exception: because the record no longer exists, that trigger offers only webhook and fully parameter-driven actions. Use cases - Automatic segmentation: when a contact is updated and the plan attribute becomes premium, add the premium-customer label. - Record hygiene: when contacts are merged, log a note with the merge origin. - Onboarding: when a contact is created from a form, open a welcome conversation in a specific inbox. - Context for the team: write an attribute (for example, source = campaign-x) to guide routing and reports. Tips, limits & best practices - Loop safety: contact actions honor loop protections — avoid rules that fire in a chain (an update that triggers another update). Keep each rule focused. - Create contact deduplicates: don't worry about duplicates — the same person (same email, phone, or identifier) is reused. - Create conversation needs an inbox: with no inbox selected, the action won't run. - Admins only: these actions require admin permission to be configured. - Variables in action fields: when an action field shows the { } button, it can receive a variable ({{ contact.name }}, {{ contact.custom_attribute.quote_value }}…) in flows, automations, and macros. The hint under the field tells you when the option is available. - Amounts, dates and links never guess: when a variable does not exist — or the text is not a valid amount, date, or link — a compatible action does not write an invented value such as 0 or an empty date. A deal silently worth 0 is worse than an action that did not run. - Document for the team what each contact automation does — it makes maintenance easier. Troubleshooting - The contact rule didn't fire: confirm the trigger (created/updated/merged/deleted) and that all conditions are true; check the rule is active. - Create conversation didn't work: confirm an inbox was selected on the action. - Did I create a duplicate contact?: the action deduplicates by email/phone/identifier; if it still looks duplicated, check that the key data matches exactly. - The condition value doesn't appear: custom attributes and their values are loaded from account data — confirm the attribute exists and has recorded values. - The action did not store the amount/date I expected: confirm the variable exists for that contact (a custom attribute that was never filled resolves to empty). In a flow, the reason appears in the step output. In an automation or macro, the conversation activity records the number of declined actions, and the audit identifies the action and field to review. - The merged/deleted webhook didn't arrive: check the endpoint subscribes to contact.merged / contact.deleted and responds successfully. See also - Automation rules: triggers, conditions, and actions - Macros: reusable actions in one click - Flow Builder: native actions and the Contact action node

Automation triggers about the AI (Maestro)

Overview Platform automation has always had more than a hundred triggers — conversation created, label changed, order paid, contract signed — and none about the Bot. You could automate on almost anything except the event that matters most to anyone running AI-assisted support: the Bot claiming an action it never executed. There are now five triggers about the health of an AI turn. They appear in the same Automation screen you already use, with the same catalog of actions (assign, label, private note, priority, status, webhook…). | Trigger (as it appears in the list) | Fires when | |---|---| | Maestro — Reply claimed an action that never ran | The reply asserted a result the turn did not execute — or executed and it failed. This is the unsupported-claim trigger. | | Maestro — Reply altered by verification | Verification changed the reply before delivery (deleted a sentence, removed a fabricated link/price, softened a passage). | | Maestro — Tool call failed | A module action the Bot invoked (calendar, billing, task, catalog, records…) failed during the turn. | | Maestro — Turn failed without replying | The turn died mid-way and nothing was delivered to the contact. Nobody answered, and the contact is still waiting. | | Maestro — Handoff to a human requested | The Bot asked for a person (contact frustration, out of scope, repeated failure). | All five are reaction, not prevention: they alert and organize work after the fact. To stop a doubtful reply from reaching the contact, the mechanism is a different one — holding the reply, in the turn-verification article (under "See also"). Prerequisites - Maestro enabled on the account and a Bot configured on the inbox handling the conversation. - Administrator permission to create and edit automation rules. - The per-module tools the Bot uses must be enabled — their execution is what produces the "failed" and "claimed without executing" signals. - An owner (agent or team) to receive whatever the rule dispatches. A trigger with no recipient is just noise. - Nothing else to provision: the events come from the Maestro service itself. On an account without Maestro the rule simply never fires — it stays inert rather than erroring. Step by step 1. In Settings → Automation, create a new rule. 2. Give it a clear name — names like "AI claimed a booking" save minutes of investigation later. 3. For the trigger, pick one of the five "Maestro —" events in the list. 4. There will be no filters to choose. That is expected and explained in the settings section below. The rule applies to every occurrence of that event on the account. 5. Pick the actions. For these triggers the most useful ones are usually: - Add label (e.g. review-ai) — cheap, silent, and lets you measure volume before turning on notifications; - Add private note mentioning the supervisor — the mention fires the native notification; - Assign to a team and change priority; - Change status (for example, un-resolve when the turn failed); - Webhook, if you track this on an external dashboard. 6. Save and leave the rule active. 7. After a day of operation, filter the conversation list by the label the rule applies. That is your volume thermometer before escalating to notifications. Settings & options Filters (conditions): not available yet for these five triggers When you pick one of these triggers, the conditions area stays empty. That is a deliberate decision, not a missing field: the turn-specific information (verdict, which tool failed, severity) travels in the event, but there is still no server-side matcher that can compare it. Offering a filter field that would in practice match everything is worse than offering none — it would look like it works and it would not. Practical consequence: the rule fires on every occurrence. Size the action accordingly. Start with a label, measure, and only then add notifications or assignment. Available actions The full conversation action catalog works, because the event resolves to the conversation where the turn happened. Be careful with "send a message" on these triggers. These are events about an internal failure. Sending the contact an automated message when the Bot stumbled usually makes things worse. Prefer private note, assignment, label and priority. What the event does not carry For privacy, the event carries only identifiers and the kind of occurrence. Reply text, tool arguments and the prompt never travel. You cannot (and will not be able to, from here) print the reply content in an automated note — to read what was said, open the conversation. One name, two meanings There is a notification called "Maestro Approval" (approval of a Brain department run) that internally uses wording similar to the Handoff to a human requested trigger. They are different things in different places: one is a Brain notification, the other is an automation rule trigger. If you look for one on the other's screen, you will not find it. Use cases - Supervisor alerted when the Bot claims a booking that never happened — trigger Reply claimed an action that never ran → private note mentioning the supervisor + assign to the scheduling team - high priority + label review-ai. This is the classic case: the contact leaves believing they have an appointment, and somebody needs to call before they show up at the door. - Contact left hanging — trigger Turn failed without replying → assign to a human immediately and set the status to open. The urgency here is higher than in the other four: nobody answered at all. - Handoff queue — trigger Handoff to a human requested → assign to the right team and set priority, so the Bot's request does not die in an unowned conversation. - Broken integration surfacing early — trigger Tool call failed → label tool-failed. Three days later the label shows which module is failing most often (expired credential, missing required data, module rule blocking the operation). - Weekly quality review — trigger Reply altered by verification → label only. Expect this to be the noisiest of the five: every cosmetic correction counts. Use it as a Friday reading sample, not as an alert. Tips, limits & best practices - These triggers prevent nothing. They react afterwards. When you need the reply not to go out, the path is holding for verification or human approval — not an automation rule. - Start with a single rule. Five rules with notifications, all switched on the same day, produce five times more noise than the team can read — and the natural reaction is to turn everything off. - Label first, notify later. It is the cheap way to learn your operation's real volume before committing someone's attention. - No filters means no exceptions: you cannot restrict the rule to one inbox, one time window or one kind of verdict. If you need a slice, it has to happen when reading (via the label), not in the rule. - Nothing is written to a table of its own by these events: they route the signal into automation. The durable turn record lives in Maestro. In other words: if you create no rule, the event passes and leaves no trace in the automation area. - Failures are isolated per rule: if one rule's action breaks, the other rules on the same event keep running. - Combine with human approval on sensitive actions (money, cancellation, records). The rule is the safety net below; approval prevents the fall. Troubleshooting - "I created the rule and it never fires": check, in this order — the rule is active; the inbox has a Bot answering; Maestro is enabled; and the event actually happened. A turn that goes well produces none of the five — silence can be good news. - "It fires too much": expected behavior while there are no filters, especially on Reply altered by verification. Switch to a cheap action (label), or turn that specific trigger off and keep the other four. - "I cannot find the filters/conditions": they do not exist yet for these five triggers. It is documented above — it is not a problem with your account. - "The contact received a strange message": one of these rules has a send message action. Replace it with a private note. - "The private note showed up for the customer": private notes are not delivered on any channel. If the text reached the contact, it went out as a normal message — review the rule's action. - "I want to know exactly what the AI said": the event does not carry the text. Open the conversation and read the delivered message and the private notes. See also - Automation rules: triggers, conditions and actions - Turn verification and holding the reply - Checking what the Bot claims before it is sent - Bot autonomy modes and human approval (HITL) - Maestro tools by module

Macros: reusable actions in one click

Overview A macro is a sequence of predefined actions an agent triggers manually inside a conversation. While an automation rule acts on its own when an event happens, a macro is triggered by a person, at the right moment, with a single click. Macros are ideal for standardized procedures: closing a conversation with a goodbye message, escalating to another team, applying labels, and replying with a standard text — all at once, with no mistakes and no repetition. Prerequisites - Admin permission to create and edit macros under Settings. - At least one conversation where the agent will run the macro. - For actions that involve other modules (CRM, Tasks, Catalog), the matching module must be active. Step by step If the account has no macros yet, the empty state explains the next step and provides the create button directly in the card. 1. Under Settings, open the Macros area and create a new macro. 2. Give it a clear name (it's what the agent will see on the conversation). 3. Add the actions in the order they should run — for example: 1. Assign to a team; 2. Add a label; 3. Send a message to the contact; 4. Resolve the conversation. 4. Save the macro. 5. To run it: open a conversation, find the macros area, and click the macro you want. The actions are applied in the defined sequence. Settings & options - Visibility: decide whether the macro is available to the whole account or only to its creator, per the form options. - Action order: actions run top to bottom — reorder them to match the procedure. - Action types: assign agent/team, add/remove label, send message, add a private note, reopen conversation, mark as pending, resolve conversation, send attachment, send an email to the team, add SLA (requires the SLA module), and actions from active modules (CRM, Tasks, Catalog). - Contact actions: add contact label (add_contact_label), remove contact label (remove_contact_label), add contact note (add_contact_note), set contact attribute (set_contact_custom_attribute), create contact (create_contact), and create conversation (create_conversation) — the same actions available in Automations and the Flow Builder. - Actions with no parameters: actions such as cancel, pause, resume and skip step for follow-ups, send charge, cancel subscription and send product card save without requiring parameters — they resolve the context from the conversation the macro runs on. - Editing: you can edit the sequence at any time; the change applies to future runs. Use cases - Standard close: send the goodbye message, label as "resolved", and resolve. - Escalation: assign to the advanced support team and add an internal note with context. - Qualification: label as "hot lead" and create/update the deal in the CRM. - First response: send the welcome message and assign to the channel owner. Tips, limits & best practices - Build macros for your team's 5–10 most common procedures — that's where they save the most time. - Use names that describe the outcome ("Close conversation", "Escalate to L2"), not the steps. - Review macros periodically: labels and teams change, and orphaned actions can fail. - Macro vs. rule: if the action should happen on its own when an event occurs, use an automation rule; if it should be decided by the agent, use a macro. Troubleshooting - I don't see the macro on the conversation: confirm it's saved and visible to your user. - A macro action didn't run: verify the referenced agent, team, or label still exists and that the action's module is active. - The order came out wrong: reopen the macro and reorder the actions; they run top to bottom. See also - Automation rules: triggers, conditions, and actions - Contact automations: triggers and actions on the record - Automation & Flows overview - Flow Builder: visual conversational flows

Flow Builder: build conversational flows visually

Overview The Flow Builder is the Conversa Labs visual builder for conversational flows. Instead of writing code, you assemble the dialogue by connecting nodes on a canvas: a message leads to an option menu, which leads to a condition, which can call an API and take different paths based on the contact's reply. It's the right tool when automation needs multiple steps and interaction — menu self-service, lead qualification, scheduling, data capture, and integrations — beyond what a simple rule can do. Prerequisites - The Flow Builder module enabled for your account (an optional capability, enabled by plan/flag). If it isn't in the menu, talk to an administrator. - Admin permission to create and publish flows. - An inbox (for example, WhatsApp) where the flow will be triggered. - For nodes that depend on other modules (Payments, Follow-ups, CRM, Contracts), the matching module must be active. Step by step 1. Open the Flow Builder and create a new flow (you can start from a gallery template). 2. Configure the flow trigger (the event that starts it) in the start node. 3. Drag nodes from the palette onto the canvas and connect them to draw the conversation path. 4. Configure each node in the side panel (message text, menu options, condition rule, request URL, etc.). 5. Use variables to store and reuse the contact's replies and integration data. 6. Test the flow (there are request-testing and session-trace tools) and publish it. Settings & options Most-used node types: | Node | What it's for | | --- | --- | | Text message | Sends text to the contact. | | Option menu | Presents buttons or a list for the contact to choose from. | | Media | Sends an image, video, audio, or document. | | Condition | Takes different paths based on a rule/variable. | | HTTP request | Calls an external API and uses the response in the flow. | | A/B variation | Splits traffic across paths to test messages. | | Payment | Creates/sends a charge and waits for payment (Payments module). | | Follow-up | Enrolls or cancels the contact in a sequence (Follow-ups module). | | Contract | Sends a contract for signature (Contracts module). | | Contact action | Runs actions on the contact: label, note, and custom attribute (Contacts category). | | Create contact | Creates a contact (name, email, phone), with native deduplication. | | Create conversation | Opens a conversation in an inbox, with optional status and first message. | | Private note | Leaves a private note on the conversation (available in flows too). | - Variables: capture replies and API data and reuse them in messages and conditions. - Calendar booking trigger: starts the flow when a booking is created or changes state in the Calendar module; its linked contact and conversation are available when present. - Calendar appointment trigger: starts the flow when an appointment is created, rescheduled or cancelled — including ones made from the dashboard, from Maestro, from an automation, or changed directly in Google Calendar. Use this one when the appointment does not come from the public booking page (which is the trigger above). The status reaches the flow, so a Condition can tell created, rescheduled and cancelled apart. - Template gallery: start from a ready-made flow and adapt it. - Testing and session trace: validate behavior before publishing. Use cases - Menu self-service: the contact picks a topic and is routed to the right team. - Lead qualification: a sequence of questions that store answers in variables and the CRM. - Scheduling and billing: collect data, create a charge, and confirm after payment. - Integration: look up an order via an HTTP request and reply with the status to the customer. Tips, limits & best practices - Sketch the flow on paper before building — map the paths and exit points. - Always offer a path to talk to a human; not everything should stay automated. - Test every path, including unexpected replies from the contact. - Watch out for loops and excessive messages (WhatsApp anti-ban best practices). - Keep flows short and focused — split very large flows into reusable parts. Troubleshooting - I don't see the Flow Builder: the module may not be enabled for the account or your role. - The flow doesn't start: check the trigger and that the flow is published and bound to the right inbox. - The flow stops midway: a node likely has no exit path for the reply received — cover every option and add a default path. - The HTTP request failed: use the request tester to check the URL, headers, and response. See also - Automation & Flows overview - Automation rules: triggers, conditions, and actions - Flow Builder: native actions and the Contact action node - Bots and Captain (support AI) - Smart Routing - Mass Run in the Flow Builder

Flow Builder: native actions and the Contact action node

Overview Beyond talking to the contact, a Flow Builder flow can run platform actions along the way: tag the contact, log a note, write an attribute, create a contact, open a new conversation, or leave a private note. This is done with action nodes. The highlight is the Contact action node (Contacts category): a dedicated node that exposes exactly the actions that operate on the contact record, with the right fields ready to go. For the other platform actions, the generic Conversa Labs action node (system action) can run them too. Prerequisites - The Flow Builder module enabled for the account (an optional capability by plan/flag). - Admin permission to create and publish flows. - For the create conversation action, a destination inbox. - For conditions/values on a contact custom attribute, the attributes defined on the account (they load automatically in the node pickers). Step by step How to add a Contact action node to a flow: 1. Open the flow in the Flow Builder. 2. In the node palette, find the Contacts category and drag the Contact action node onto the canvas. 3. Connect it to the point in the flow where the action should happen. 4. In the side panel, choose the action (for example, Add contact label) and fill in the fields. In the attribute and value fields, the options are loaded automatically — no free text. 5. For create conversation, select the inbox and, if you want, the initial status and first message. 6. Test the flow and publish it. Settings & options Native nodes/actions available in flows: | Node / action | What it does | | --- | --- | | Contact action node | Runs contact actions: add/remove label, add note, and set custom attribute. | | Create contact action | Creates a contact (name, email, phone; inbox optional), with native deduplication. | | Create conversation action | Opens a conversation in an inbox, with optional status and first message. | | Add private note action | Leaves a private note on the conversation (now available in flows too). | | Send/create contract action | Sends or creates a contract from a template (requires the Contracts module). | | Send an email to the team action | Notifies the team by email during the flow. | | Conversa Labs action node | Generic system-action node; can run the same contact/create actions. | - Auto-loading picker: when you configure the action, the contact's custom attributes and their values appear automatically — you select, you don't type. - Private note in flows: adding a private note, previously available only in Automations and Macros, now also runs inside a flow. - Contract and email-to-team actions: sending or creating a contract from a template (requires the Contracts module) and sending an email to the team now publish and run correctly inside the action node. The Add SLA action is not available in flows — use it in Automations or Macros. Use cases - Tag mid-flow: when the contact picks a menu option, add the matching label to the contact. - Escalate to another inbox: create a new conversation in an advanced-support inbox when the flow detects a complex case. - Record context: write a custom attribute (for example, interest = annual-plan) during qualification. - Alert the team: leave a private note with the summary gathered in the flow, without sending anything to the contact. Tips, limits & best practices - Loop safety: contact actions honor loop protections — design the flow so it doesn't trigger chained updates. - Create contact deduplicates: the same person (email/phone/identifier) is reused, with no duplicates. - Create conversation needs an inbox: with no inbox selected, the action won't run. - Admins only: native actions require admin permission to be assembled in the flow. - Prefer the Contact action node when you only need to touch the record — it brings the right fields ready. Troubleshooting - I can't find the Contact action node: confirm the Flow Builder is enabled and that you have an admin role. - The action didn't run in the flow: check the node is connected to the right path and that the required fields are filled in. - Create conversation failed: confirm an inbox was selected on the node. - The condition/attribute value doesn't appear: values are loaded from account data — confirm the attribute exists and has recorded values. See also - Flow Builder: visual conversational flows - Contact automations: triggers and actions on the record - Macros: reusable actions in one click

Flow Builder: action forms and categorized event & action lists

Overview Some native actions do a lot more than set a single value — creating a CRM deal, a charge, a task, a contact or a conversation takes several fields. Those actions now expose a real form in the Flow Builder action node, instead of a single-value picker. You fill each field with the same typed inputs used everywhere else in the builder, including the {{ variable }} picker. At the same time, the long event and action lists are now grouped by module and searchable, so you can find crm_item_won or "Create deal" without scrolling through everything. Prerequisites - Admin permission to edit automations, macros, flows and webhooks. - The relevant module enabled (CRM, Payments, Tasks, Follow-ups, …) so its pickers can load. Step by step 1. Open a flow, add a General actions node and choose the action. 2. Fill dependency fields first, such as pipeline → stage. 3. Use { } for variables and Advanced for targets, links and attributes. 4. Run Run test with the right context and inspect outputs, skips and effects before publishing. Settings & options Action forms (param-driven) When you pick one of these actions on a General actions node, a form appears with exactly the fields the action accepts: - Create CRM deal — title, description, pipeline → stage (the stage list follows the pipeline you choose), value (with variables), currency, priority, assignee, team, expected close date, opening date, contact (by id, email or phone), organization, participants (deal collaborators), and the custom and additional attributes. - Create charge — billing type, amount (with variables), currency, description, due date, installments (for credit card), and, under Advanced, the payment connection, deal link, catalog products and source. - Create task — title, description, assignee, priority, status, due date or "due in N days", task list, and, under Advanced, the team, the parent task, the start date, the labels and the custom and additional attributes. - Create an appointment — calendar, title, description, location, timezone, start and end, all-day, conferencing, invitees, recurrence, and, under Advanced, the explicit contact, the link to a deal and to a task, plus the custom and additional attributes. - Create contact / Create conversation — the identity fields (name, email, phone, identifier), inbox, custom attributes; and for conversations, the initial status, assignee, team and message. - Enroll in follow-up — the sequence, plus optional deal/charge links under Advanced. - Create subscription — billing type, amount, currency, cycle (weekly to yearly), description, first due date and, under Advanced, the payment connection and plan. - Send WhatsApp template — the Meta-approved template's name, language and variables, with the namespace and fallback text under Advanced. - Chaining verbs — add note/checklist/participant, assign a deal or task, comment/label/link a task, send/cancel a charge or subscription, take over a conversation, and adjust an ad budget now have forms with an explicit target field under Advanced (see "Chaining steps" below). Two details worth knowing: - Money is written in major units and accepts variables. 4.97 means R$ 4,97; you can also type a token like {{ crm.value }} and it is rendered when the flow runs. - The pipeline → stage picker is dependent: choosing a different pipeline clears the stage so you never keep a stage that belongs to another pipeline. The same forms in Automations and Macros These forms are no longer exclusive to the Flow Builder. Create a CRM deal, Create a task, Create an appointment, Create a contact, Link a task to a record, Set the task team and Register an order now show the full form in the Automations and Macros editors too — before this, "Create a deal in the CRM" offered only a title and a description there, with no pipeline, stage, value or owner. Every other action is unchanged: the ones that already have a dedicated editor (deal value, custom attribute, catalog, payments, commerce, WhatsApp…) keep their rich widget. A few fields appear in the Flow Builder only: the ones that exist for step chaining (the contact and company on "Create a deal", the parent task on "Create a task"). In a rule that fires per conversation, a fixed value there would pin every run to the same record — leaving them blank makes the action use the triggering conversation's contact, which is the correct behavior. No more typing ids: searchable pickers and a real date field Every field that used to ask for a raw id is now a searchable picker over real records — deal, task, contact, company, task list, calendar, charge, subscription, plan, affiliate and ad campaign. Each field has a toggle between: - Choose — search by name (or title) across the account's records; - Variable — the text field with the {{ }} picker, for chaining {{ steps.create_deal.id }}. The mode follows the value itself: a value containing {{ opens in variable mode. Switching modes does not erase what you had configured, and a saved id whose record is not in the first page still reads as #123 instead of looking empty. The list is only fetched when you open the picker. Business timestamps (an appointment's start and end, a deal's opened at) now use the date and time picker in the account timezone — the same component as the rest of the product — with the variable mode beside it. Pure day fields (due date, expected close date) stay plain dates. "Link a task to a record" is complete now: besides the type (Conversation, Contact, Deal) it has the target record picker, which follows the chosen type. Without that target, the action did nothing. Two actions that gained a screen - Set the task team — pick the task's team; leave it empty to remove the current one. - Register an order — registers an order for the conversation's contact: title, amount, currency, status, source/gateway, external id and, under Advanced, the deal link and the affiliate. It only appears on accounts with the Orders Registry module. Orders are de-duplicated by external id. Links: who owns the record you just created When the flow runs inside a conversation, the new deal automatically inherits that conversation and its contact — the classic "conversation resolved → create deal" behaviour, and it still applies whenever you leave those fields empty. What you fill in beats that inheritance. If the form names a contact, that is the contact on the deal, even when the conversation points at somebody else. Inheritance becomes just a default for when the flow never said who the record belongs to. In a flow without a conversation (webhook trigger, API, schedule) there is nobody to inherit from. For those runs the form accepts three routes, in this order: 1. Contact — the id of an existing contact, usually coming from an earlier step. 2. Contact email — looks the address up and, when nobody matches, creates the person. 3. Contact phone — same rule, with the number normalized to the international format (you can send 21971532700; it becomes +5521971532700). If the person can be neither found nor created (an invalid email, say), the deal is still created — only without the link — and the reason shows up as a "skipped" badge in the data panel. Losing the link is bad; losing the deal would be worse. Custom attributes follow the pipeline's fields Watch out for this rule, it catches people out: when the target pipeline has custom fields configured, the deal keeps only the attributes on that list. Any key you send that is not configured as a field of that pipeline is dropped silently — no error, no warning, no failed node. - Before mapping an attribute in the form, check under CRM → Settings that it exists as a field of the pipeline the action will use. - When the pipeline configures no custom fields at all, everything you send is stored. - The pipeline's required fields stay required: sending one of them blank makes the creation fail (and the node records the error) instead of writing a half-filled record. Categorized, searchable lists - Webhook events (Settings → Integrations → Webhooks): events are grouped by module (Conversations & Contacts, CRM — Deals, Tasks, Payments, WhatsApp, …). Each group has a search box, a select-all checkbox with a count badge, and a partial (indeterminate) state when only some events of the group are selected. - Automation triggers: the event dropdown is grouped into module sections. - Actions (Automations, Macros and the Flow Builder): the action picker shows a module header above each set of actions. None of this changes the stored data — event keys, action names and the webhook payload are exactly the same as before. Only the way they are presented changed. Run a test straight from the editor The Run test button executes the flow's current draft once, without publishing. After the run, every node on the canvas shows a result badge (✓ completed with its duration, ✗ failed with the error, ◇ skipped) and the data panel starts showing the real values each step produced. - Heads-up: the test runs actions for real — it creates records, fires charges and webhooks. An explicit confirmation appears before running. - Without a test conversation, message nodes are skipped (the rest of the flow still runs). You can provide a conversation or contact to exercise the full path. - Available to administrators. Webhook trigger: flexible authentication and pre-publish testing - The webhook URL and token exist from the draft — the panel's curl example is real from the first save. - An authenticated delivery to an unpublished flow is accepted as a test sample (the panel captures the body for mapping) without starting a session. Publish when you are ready. - Three authentication modes: Signed (HMAC over the body — the default and safest), Bearer (the Authorization header) and URL secret (?token=…) — the last two for tools that cannot sign the body (form builders, ERPs, no-code tools). - The panel shows the last delivery received (accepted, sample captured, replayed or rejected by authentication) with its time — no more guessing whether the POST arrived. Chaining steps (ids of created records) Every action that creates a record now exposes its id (and main fields) in the step output. In the variable picker, look for the node's name — a "Create deal" step, for example, offers its id for later steps to use as a target: 1. Receive lead (webhook trigger) → 2. Create contact → 3. Create CRM deal → 2. Create charge → 5. Enroll in follow-up → 6. Create task. The step key is the node's name in lower case, with _ replacing anything that is not an unaccented letter, a digit or _. A node called "Find contact" becomes find_contact, and its output reads like this: - {{ steps.find_contact.contact_id }} — the contact that was found, ready to drop into the Contact field of a "Create CRM deal" right after it. - {{ steps.create_deal.id }} — the deal you just created, to attach a charge, an appointment or a task to it. - {{ steps.create_task.id }} — the new task, handy as the parent task of subtasks or as an appointment's link. Careful with accents and punctuation: they do not fold into the plain letter, they become _. A node called "Create quote (São Paulo)" answers to create_quote_s_o_paulo. Name the nodes you intend to chain with plain letters and digits — or simply pick the token from the variable picker. Renamed the node? The key follows the new name — revisit the tokens that pointed at it. If two nodes share the exact same name, the first one keeps the key and the other answers by its node id (the variable picker always shows the correct token, so prefer picking from it over typing from memory). - In a flow without a conversation (webhook/API), the contact created in step 2 automatically becomes the target of the following steps. - The note, checklist, participant, assign, comment, label and link forms carry a target field under Advanced that accepts the id of an earlier step; when empty, the flow's own records are targeted. When an action does nothing: the reason in the panel, and strict mode Some actions simply have nothing to do — there was no deal to assign, the contact could not be resolved, the module was not configured. That used to go unnoticed: the flow moved on, the step came back empty and nothing explained why. Now an action that decides not to act records the reason alongside the step. To read it: 1. Open the Available data panel and go to the Steps tab. 2. The step shows the "Action skipped" warning followed by the reason, in the same alert block as the truncation warnings. 3. With the step collapsed, the warning icon in its header already carries the reason in its tooltip — you do not need to expand it to understand what happened. This applies to both Run test and the execution history. By default a skipped action does not stop the flow: it is recorded and execution continues. Use the warning to find out why a later step did not find the record it expected. Strict mode: stop instead of carrying on with a half-built record When moving on is worse than stopping, open Advanced on the action node and turn on the "Fail the node when the action does nothing" switch: - Off (default) — today's behaviour, with no change to any existing flow: when the action declines to act, the flow moves on and the reason appears on the step output. - On — an action that declines to act and produces nothing makes the node fail instead of advancing. Use it on critical steps, such as the charge that must exist before you send the payment link. Mind the carve-out, it is subtle: a partial success still moves on even with the switch on — for example, the contact was created but could not be linked to the inbox (the chosen inbox's channel could not derive a source_id). The contact exists and the next steps already have a real record to use, so stopping there would be wrong. The switch only halts the case where the action produced nothing at all. The option appears under Advanced on the generic General actions node and on every per-module action node: CRM, Tasks, Contacts, WhatsApp, Calendar, Payments, Catalog, Commerce and Ads. The Account Brain node runs on its own engine, so it does not carry the switch. Send WhatsApp template and send WhatsApp flow Both WhatsApp messaging actions existed in the engine but appeared in no picker — you could not build a rule or macro with them. They are now in the Automations, Macros and Flow Builder catalogs (in the generic action node and in the WhatsApp node), with a full form: - Send template — the template is a list of the account's approved templates (no typing the name). Leave the language empty and the send adopts the picked template's own language. The variables fill the {{1}}, {{2}} placeholders in the body. - Under Advanced, two new fields cover the templates a flat map could never reach: header variables (including media_url + media_type for a media header) and button variables (a JSON array, one object per dynamic button). Without them a template with a media header or a dynamic button was rejected by Meta. - Send flow — pick the published flow from a list; the flow token is minted on every send. You can set the button text, message, header, footer, mode (published/draft), initial screen and initial data. List and size conditions In a Flow Builder condition, the Value field now follows the operator, not only the field: - in list / not in list — pick several values at once; they are stored comma-separated, exactly what the engine reads. Before you could only pick one, which made the operator a slower "equals". - length greater/less than, date within N days, date before/after — go back to free text, because the compared value is a size, a number of days or a date, not a value of the field. - array contains keeps a single pick: it compares one member of the array. An invalid delay is now blocked at publish time A delay node with every unit at zero silently waited 1 second, and a mistyped unit failed the node only at run time. Both now show up as an error when publishing the flow. A unit holding a variable ({{ }}) is still resolved at run time. WhatsApp option lists A list with more than 10 rows, a title over 24 characters or a description over 72 was refused by WhatsApp and the message was lost. It is now trimmed to the limit before sending (extra rows are dropped, long text is cut) and the message goes through. Use cases - Create a contact, chain its id into a deal, then use the deal id in a charge or task. - Update CRM and tasks from webhook/API data without pinning IDs from another run. - Stop a critical path when an action produces no effect by enabling strict mode. Tips, limits & best practices - Leaving an optional field empty simply omits it — the action uses its default. - Prefer variables over hard-coded values in titles, descriptions and amounts so the same flow adapts to each contact or deal. - Only fill Contact when you really mean to override: inside a conversation-driven flow, leaving it empty keeps the conversation's own contact, which is usually the right answer. - Before mapping custom attributes, confirm they are configured as fields of the target pipeline — otherwise they are dropped without warning. - When a later step cannot find the record it expected, look for the previous step's "Action skipped" warning in the Steps tab — the reason is usually right there. - Turn strict mode on only for the nodes where "did nothing" is a real problem, and handle the error output with a notification or an alternative path. - Use the group search to jump straight to an event by its label or its technical key. Troubleshooting - If a picker is empty, confirm the module, permission and any dependency selected first. - If an action is skipped, read its trace reason before changing downstream steps. - If publish rejects the node, fix the schema field reported by validation; v2 does not accept undeclared fields. See also - Flow Builder: trigger data, mapping and transformation - Flow Builder: native actions - Flow Builder in practice

Flow Builder: trigger data, mapping, and transformation

Overview A flow gets far more powerful when it can read the data that started it and reuse the output of every step. The Flow Builder now ships a set of data and mapping features: the webhook/API body becomes a variable, the response of any earlier node is available to the next ones, the outbound webhook can store its response, and two new nodes — Loop items and Transform data — let you walk through lists and manipulate data without leaving the canvas. Everything is optional and backward compatible: existing flows keep working exactly as before. Prerequisites - The Flow Builder module enabled for your account. - Administrator to edit and publish the flow. Agents can follow the runs. - For the trigger-data features: a Webhook or API trigger in the flow. - Basic grasp of variables: in the editor, the variables button ({ }) and typing {{ open the list of available tokens. Insert a token by writing it in double braces, e.g. {{ trigger.body.email }}. Step by step Example: an order arrives via webhook and you want to use the order number in a message. 1. On the trigger node (Webhook or API), open the Sample payload section. 2. Click Fetch last event (or Paste JSON) to bring in a real example of the body. 3. In the tree that appears, click the value you want (e.g. order.id). That creates a variable ← path mapping (e.g. id ← body.order.id). 4. Optional: Pin the sample to keep it on the flow and feed the editor's variable list. 5. In any later node, use the mapped variable ({{ vars.id }}) — or go straight to the body with {{ trigger.body.order.id }}. 6. Publish the flow. Settings & options Trigger data - Webhook/API body as a variable: the body that started the flow is available in {{ trigger.body.field }} — for example {{ trigger.body.order.id }} or {{ trigger.body.items[0].sku }}. It works for JSON and for form posts; unstructured content arrives in {{ trigger.body.raw }}. - Size limit: the body is stored up to 64 KB. Larger payloads are truncated (top-level fields are kept and a warning is flagged). - Direct mapping on the trigger: besides reading the body, you can map paths into named variables right on the trigger (variable ← path). This mapping works for all trigger families, not just webhooks — paths are relative to the data that started the flow. Sample payload in the editor Available on the Webhook and API triggers: | Action | What it does | | --- | --- | | Fetch last event | Brings in the last real call received by that trigger. | | Listening | If there's no event yet, the editor keeps listening and checks every few seconds (up to 60s). Send a test call to capture it. | | Paste JSON | Paste an example manually when there's no real traffic yet. | | Clickable tree | Renders the sample; clicking a value creates a variable ← path mapping. | | Pin | Keeps the sample on the flow. The pinned sample feeds the editor's variable list and travels with the export (you can unpin anytime). | The "Available data" panel in the inspector When you select any node, the inspector shows the Available data panel — a catalog of everything you can insert, organized into four tabs: - Trigger — the trigger payload tree (pinned sample or the real last run). Click a value to insert {{ trigger.… }}. No sample yet? Use Fetch last event. - Steps — the output of each earlier node, with the real values from the last run. Steps with no output yet show "no output yet"; renamed or removed steps are greyed out. - Variables — the variables the flow produces (vars.*), with the last-run value when there is one. - Standard — the standard contact, conversation, agent, inbox, account, CRM, flow, and Account Brain fields. Each field shows an example value (from the last run) next to the token when available — the same chip appears in the variables button ({ }) list. Click a field and it is inserted where the cursor is. The values reflect the last run and may be outdated; use Refresh to fetch the latest. Auto-map fields On the mapping surfaces (the HTTP request test, the trigger sample, and the Outbound webhook), when a response sample is present the Auto-map fields button creates one row per top-level field: the variable name is normalized (lowercase with _) and the path points at the field. Repeated names get a suffix (_2, _3), already-mapped fields are skipped, and the cap is 20 per click. The path field also suggests paths from the sample as you type. Insert variables in actions The action nodes (create contact, CRM actions, tasks, WhatsApp, etc.) now offer the variables button too. Typing {{ in a text field opens the list, and the header carries Insert variable for actions made only of selectors. The variable lands in the focused field, exactly like in messages. Step outputs - The response of any earlier node is available to the next ones in {{ steps.step_name.field }}. - The step name is the node label in lowercase with _ replacing spaces/symbols (or the node id when the label is empty). Rename the node to get a predictable name. - Common fields: status on any node; the HTTP request node also exposes body and handle (e.g. {{ steps.lookup.body.total }}, {{ steps.lookup.status }}). Outbound webhook: capture the response - The Outbound webhook node can optionally store the response in a variable and map fields from it into named variables (dot paths, e.g. data.id). - It is off by default: with no variable and no mappings, the behavior is identical to before. New nodes: Loop items and Transform data Loop items — walks a list one item at a time: - Point at the list (e.g. {{ vars.orders }}, {{ steps.lookup.body }}, or a dotted path). - Each pass exposes the current item and the index in variables (e.g. {{ vars.item }}, {{ vars.loop_index }}). - Wire the item output back into the node to loop; the done output fires when finished. - Limits: up to 100 items per loop; each pass spends the body's steps within the session step budget (so very large loops can exhaust it — the editor warns). Transform data — manipulates data into a variable, with success / error outputs: - Template: renders text from a template. - JSON: produces structured data (the text must be valid JSON). - Array operation: applies one operation over a list — pick, filter, first, last, count, sum, unique, sort, join. - String: splits text into a list or extracts values with a regular expression. Use cases - Turn an order received by webhook into a chained contact, deal, charge and task. - Iterate over HTTP response items and run one controlled action for each item. - Map provider IDs and statuses into waits, conditions and later messages. Mapping at scale (large, nested payloads) Mapping was hardened for real-world payloads — large, deep and full of nested objects: - Auto-map fields now descends 6 levels and maps every leaf (nested objects like utm{} and contact{} included), deriving names from the last segment (utm.utm_source → utm_source) and disambiguating collisions automatically (contact.id and order.id → id and order_id). When there are more fields than the 100-per-click cap, the toast says exactly "Mapped X of Y". - Search everywhere: the variable picker and the data panel gained search — including fields beyond the display cap (the footer tells you how many stayed hidden). - Huge trees under control: each branch renders 50 items at a time ("Show more"), with a size badge (~N KB), hover copy-path/copy-value, and navigation over EVERY array index (you can map items.3.sku, not just the first element). - Nothing disappears silently: when the server must prune an oversized response, the dropped branches show up in an amber banner (with the exact paths); a mapped path that doesn't exist in the payload becomes a "path not found" chip in the trace — the variable stays empty, but you know. - Negative index: items.-1.sku grabs the last element. Bracket form (items[0].sku) is accepted as you type and converted automatically. - Richer conditions: 14 new operators (ends with, is in list, is empty, is a number, is true/false, date before/after/within N days, length greater/less, list contains) plus condition groups with ALL/ANY between groups. - Transform data gained new operations (min, max, average, slice, reverse, flatten, compact, to JSON) and a string mode (split into list and extract with regex). Tips, limits & best practices - No parallel branches: a flow moves one step at a time — there's no simultaneous execution of two paths and no join nodes. Loop items processes the list in sequence (which also lets waits inside the loop work naturally). - Large payloads are truncated: the trigger body (64 KB) and step outputs have limits; when they're exceeded, the data is truncated and a warning is flagged so you notice. Troubleshooting - Path not found: refresh the sample and verify the complete path, including array indexes. - Missing output: confirm the step ran and check the trace for truncation or eviction markers. - Publish refused: fix the variable, handle or out-of-schema field identified by validation. - Unsupported transform mode: choose Template, JSON, Array, or String. The run error shows the received value and the valid identifiers: template, json, array, string. See also - Flow Builder: build conversational flows visually - Flow Builder: native actions and the Contact action node - Flow Builder in practice: sessions, versions, reports, and database connections - Automation rules: triggers, conditions, and actions

Flow Builder: a complete chatbot ready for every channel

Overview The Complete chatbot: menu, Q&A, CRM deal & tasks template ships an end-to-end, production-ready automated assistant that adapts itself to the channel the conversation runs on: - On channels with interactive messages (WhatsApp, web chat, Telegram, Messenger, Instagram and API), the menu renders as buttons. - On text-only channels (email, SMS), the same menu automatically becomes a numbered list — and the contact can reply with the number ("2"), the option text or by tapping the button: every form works. All the content (messages, buttons and even the understanding keywords) is created in your account's language — English, Portuguese or Spanish. Prerequisites - Flow Builder enabled and Admin permission to edit and publish. - CRM and Tasks enabled to run every path in the template. - A configured inbox and a team with an eligible agent for human handoff. Step by step 1. Open Flows → Templates and choose Complete chatbot. 2. Apply it and review the messages, keywords and default CRM pipeline. 3. Check lead_name, lead_email, lead_need, lead_valor and duvida in the data panel. 4. Use Run test with a test conversation and exercise sales, support and handoff. 5. Publish and attach the flow to inboxes only after every output has been validated. Settings & options 1. Initial menu with three paths: Quotes and sales · Support and questions · Talk to an agent. 2. Sales trail — asks for the name, the email (validated), the need and the budget in mind (numbers only). With the answers it: - creates a CRM deal (default pipeline) titled "Opportunity — {name}", with the quoted value and high priority; - logs a note on the deal with every mapped answer; - opens a task "Send the quote to {name}" due in 1 day; - confirms to the contact and hands off to a human. 3. Support trail — asks the question and auto-answers pricing and opening-hours FAQs; anything else becomes a task and goes to an agent. 4. Human agent — option 3 transfers straight away, any time. 5. No valid reply — after 2 guided retries the contact is routed to a human (never stuck). Use cases - Lead qualification with a deal, note and follow-up task. - Support triage with quick answers and escalation for unmatched questions. - One omnichannel menu for WhatsApp, web chat, email and SMS. Tips, limits & best practices - Buttons and numbered lists share the same items: editing the menu once updates the behavior on every channel. - FAQ answers match keywords in the account language (e.g. "pricing", "cost") — add your own on the condition nodes. - The quoted value lands on the deal in major units (4900 = $4,900.00). - Interactive controls depend on the channel's proven capability; always configure the text fallback. Troubleshooting - If an action is skipped, inspect the trace and confirm CRM/Tasks are enabled and the target exists. - If handoff fails, confirm the team belongs to the account and has an eligible inbox member. - If a reply does not match, review the wait node's input type, options and retry limit. See also - Flow Builder: build conversational flows visually - Flow Builder: trigger data, mapping and transformation - Flow Builder: action forms

Mass Run in the Flow Builder

Overview Mass Run (the Mass Run tab of the Flow Builder) executes a published flow against an entire audience, one subject at a time, respecting WhatsApp's 24h/HSM window and a cadence control that keeps the number from being banned. Where a manual run fires the flow for one conversation, a mass run: - resolves who receives it (5 audience families); - automatically resolves each contact's conversation (reuses the existing one or creates a new one) so every node works — messages and actions; - drips the sends with an anti-ban throttle, quiet hours and business days; - shows a funnel by status (started / pending / skipped / failed) and lets you pause, resume, cancel and retry failures. Prerequisites - The Flow Builder module enabled on the account. - A published flow (drafts can't be dispatched). - A sending inbox (usually WhatsApp). - Administrator role to create and launch mass runs (agents can view and follow along). Step by step 1. Publish the flow you want to run. 2. Open the flow in the list and click Run in bulk (paper-plane icon) — or go to the Mass Run tab, click New mass run and pick the published flow. 3. Step 1 — Audience: choose the sending inbox and the audience family: - Contacts: all, by label (applied to the contact), or by saved segment. - Conversations: all, by saved filter (a Folder), or by conversation label — both the all and the by label modes still let you pick a status (all, open, pending, snoozed, resolved). It is also the only family that accepts one target per conversation (see below). - CRM deals: a pipeline and, optionally, a stage. - Companies: a company saved segment or specific companies. - Imported list: paste numbers (one per line or comma/CSV) and click Import numbers. 4. Step 2 — Conversation: choose how the conversation is resolved (see Settings & options). 5. Step 3 — Cadence: set the anti-ban limit, drip, quiet hours, business days and, if you want, schedule the start. 6. Step 4 — Review: check the estimated count and confirm. The run starts dripping and you follow the funnel on the Mass Run tab; click a run to inspect the targets one by one. Settings & options Audience (step 1): - Contact label vs conversation label: two different places. A label applied to a conversation does not land on the contact — that is why the Conversations family has a by label mode. If the audience came back zero using a label under Contacts, this is almost always why. - Conversation status: applies to both the all and the by label modes of the Conversations family — either one can be narrowed by status without creating a saved filter first. All is the default. - CRM — open deals only: won, lost and archived deals never enter the audience. - Companies — everyone, not just the primary: includes the primary contact and everyone else linked through a company membership. - Where each saved list is created: contact segments under Contacts → Filter → Save segment; conversation Folders under Conversations → Filter → save; company segments under Companies → filter → save. - Union: different entries add up, and a contact reached by more than one criterion is targeted once. Conversation policy (step 2): - Automatic: reuses the contact's latest conversation on the chosen inbox, or creates a new one. Message and action nodes both run. Recommended for most cases. - Reuse only: dispatches only to contacts that already have an open conversation; the rest are skipped (they show as skipped in the funnel). - Actions only: no conversation is created. Message nodes are skipped and only action nodes run (e.g. add contact, apply a label, call an API). Cadence (step 3): - Anti-ban limit: a ceiling of sends per second and per hour per inbox. Leave blank for the safe provider defaults (WhatsApp Cloud/Web). When the limit is reached, the run defers and retries — it never drops a target. - Drip: N targets per interval (in seconds), to pace even slower than the anti-ban limit. - Quiet hours and business days: outside the allowed window nothing is dispatched; the next tick resumes when the window reopens. - Schedule start: begin the run at a future date/time — it stays scheduled and the platform materializes it and starts dripping on its own at the set time. Bulk actions on the list (Mass Run tab): select several runs at once and pause, resume, cancel, retry failures or delete them in one go — to operate many runs without opening them one by one. Target mode and conversation reuse Two wizard choices decide what the flow runs on. They are independent of the step-2 conversation policy: the policy decides whether a conversation is reused or created; these two decide which. Target mode (step 1, right under the audience): - One target per contact (default): each person gets the flow once, on whichever conversation the mass run resolves for them. This is the long-standing behavior. - One target per conversation: the flow runs on every conversation that matched the filter. Someone with three matching conversations is handled in all three, and each run acts on the conversation that matched — not on "that person's most recent conversation". This is what you want when the subject lives in the conversation (a support label, a folder of pending threads) rather than in the person. One target per conversation is only available when the whole audience comes from the Conversations family. Contacts, CRM deals, companies and imported lists carry no matched conversation to run on — there the option is shown disabled, with the reason next to it. Conversation reuse (step 2, under the policy): - Prefer an open conversation (default): reuses the contact's most recent open or snoozed conversation on that inbox. With none, it falls back to the most recent of any status. This avoids reopening an already resolved subject and burying the run at the end of an old history. - Always the most recent: reuses the contact's latest conversation on that inbox, even when it is already resolved. This is the previous behavior, kept for anyone who relies on it. Reuse only decides which existing conversation is reused. When the run uses one target per conversation, each target already carries the conversation that matched, so the preference does not apply to it. All conversations with a status: the Conversations → All audience can now be narrowed by status (all, open, pending, snoozed, resolved) without creating a saved filter first. Both choices appear on the review step before you confirm, and stay visible after launch: open the run on the Mass Run tab and they sit at the top, next to the funnel. Launch from an automation rule (run_flow_batch) Besides launching manually, you can fire a prepared draft mass run from an automation rule — the bulk analog of the "Start flow" action. All the heavy config (flow, inbox, audience, cadence) lives on the draft; the action just triggers the launch. How to use it: 1. Build the mass run as usual (published flow, audience, cadence) but leave it as a draft — don't launch. 2. In Automation, create a rule and add the Launch mass run action, choosing the draft. 3. When the rule's trigger fires, the draft is launched and starts dripping like any other run. Anti-loop guard: only a draft run is launched, and launching is one-way (draft → scheduled). So even if the rule fires the action many times (e.g. one trigger per conversation), the run is launched exactly once — later calls find an already-launched run and are safely ignored. Use cases - Fix/update contacts in bulk with an action flow (e.g. add a contact on WhatsApp). - Re-engage a saved segment or a label with a win-back message. - Warm up a CRM pipeline: run a flow for every open deal in a stage. - Campaign from a pasted list (spreadsheet/CSV) without registering each contact first. - Follow up on whoever was labeled during support: target the label applied to the conversations, optionally only the resolved ones. - Talk to a group of companies: reach everyone linked to the chosen accounts. Tips, limits & best practices - Keep the anti-ban limit on — WhatsApp bans numbers that send too fast. - Start with a small run on a test inbox before running against your whole base. - A contact without a phone (on a WhatsApp inbox) is skipped, it doesn't fail the batch. - The run is resumable and idempotent: pause/resume never duplicates; the same contact appears once per run. - The audience has a safety cap; very large audiences are truncated (recorded on the run). Troubleshooting - "Flow not published": publish the flow before running. - Many "skipped": check the conversation policy (reuse only skips contacts with no conversation) and whether the contacts have a phone. - Estimated count is 0 with a label: you probably chose Contacts → by label for a label that lives on the conversations. Switch to Conversations → by label. - Segment missing: each family reads its own saved list — conversation Folders never appear among contact segments, and vice versa. - Many "failed": open the run, read the per-target reason and use Retry failures after fixing. - Run stalled: check whether it's in quiet hours or outside business days — it resumes on its own at the next window. See also - Flow Builder: build conversational flows visually - Flow Builder in practice: sessions, versions, reports and database connections - Follow-ups (re-engagement cadences) - Defining the campaign audience

Flow Builder: lookup nodes and Wait until

Overview Besides acting (sending messages, creating deals, opening tasks), a flow can now read what already exists in the platform and decide from it. There are seven lookup nodes: | Node | What it reads | Outputs | |---|---|---| | Find contact | A contact by email, phone, identifier or custom attribute | Found · Not found · Error | | Find conversations | The contact's conversations (status/inbox filters) | Found · Empty · Error | | CRM lookup | The contact's deals (pipeline, stage and status filters) | Found · Empty · Error | | Task lookup | Tasks linked to the contact or the conversation | Found · Empty · Error | | Commerce lookup | The contact's latest purchase/payment event and history | Found · Empty · Error | | Charge lookup | The contact's charges by status (Payments module) | Found · Empty · Error | | Booking lookup | The contact's next or last appointment (Calendar module) | Found · Empty · Error | Plus a smart wait: - Wait until: pauses the flow until a condition (the same editor as the Condition node, groups included) becomes true — re-checking at regular intervals — or until the timeout elapses. A lookup never crashes the flow: any failure exits through the Error port, which you can wire to a fallback path. Prerequisites - The Flow Builder module enabled; Administrator to edit and publish. - Charge lookup requires the Payments module; Booking lookup requires the Calendar module. The others work on any account (CRM/Tasks/Commerce degrade to the Empty output when the module is unavailable). Step by step Example: dedupe leads arriving via webhook. 1. On the Webhook trigger, map the payload's email into the lead_email variable (use the Auto-map fields button). 2. Add Find contact with Look up by = Email and Value = {{ vars.lead_email }}. Wire Not found to the path that creates the contact/deal. 3. Wire Found into a CRM lookup with Deal status = Open. 4. On the CRM node's Found output, end the flow (the lead already has an open deal); on Empty, create the deal. Tip: the gallery ships the "Webhook lead intake (dedupe + CRM)" template with this flow ready. Settings & options - Result variable: each lookup writes what it found into a variable (e.g. found_contact, found_deal). List lookups add _count and _list companions — use {{ vars.found_deal.title }}, {{ vars.found_deal_count }} and so on. - Subject contact: defaults to the conversation/session contact; pick From a variable to point at another one (an id or the result of a previous Find contact). - Use the found contact in this flow (Find contact): downstream nodes — including {{ contact.* }} — read the found contact. When the conversation already pins a different contact, the switch is safely ignored (the variable stays available). - Wait until: define the conditions (flat list or ALL/ANY groups), the check interval (minimum 60 s) and the timeout (required, up to 30 days). The Condition met output fires as soon as the condition passes — including immediately when the contact replies; Timeout fires when the deadline elapses. Checks are bounded (at most 500 per wait) and never consume the flow's step budget. Use cases - Dedupe before create: Find contact + CRM lookup before opening a deal (ready-made template). - VIP routing: Find conversations and compare {{ vars.found_conversations.count }} to recognize recurring customers ("VIP routing" template). - Payment rescue: Commerce lookup + Wait until {{ commerce.stage }} = payment_confirmed ("Pending payment rescue" template). - Overdue charge: Charge lookup with status Overdue and resend the link ("Overdue charge notice" template). Tips, limits & best practices - Lookups return at most 10 items (newest first). - Stored data are safe summaries (essential fields only — never a full record dump). - Wait until re-evaluates LIVE data when the condition uses context tokens (e.g. {{ commerce.stage }}); variables written by earlier lookups are snapshots of the moment they ran. - Always wire the Error output to a fallback path on critical flows. Troubleshooting - Always lands on Empty: check the subject contact (does the session have one?) and the filters (status/pipeline). The session trace shows count and the reason (no_contact) per step. - Charge/booking lookup lands on Empty as "unavailable": the corresponding module is disabled for the account. - Wait until never fires: check the interval/timeout and whether the condition uses a token that actually changes (a static variable will never change on its own). See also - Flow Builder: trigger data, mapping and transformation - Flow Builder: build conversational flows visually - Flow Builder: native actions and the contact action node

Bots and Captain (support AI)

Overview Conversa Labs offers two ways to automate replies intelligently: - Support bots: bots connected to an inbox that handle the conversation first, answer structured questions, and hand off to a human when needed. - Captain: the platform's AI layer. Captain assistants answer based on your knowledge (documents and responses), and the copilot helps agents draft replies and resolve faster. Together, they reduce the volume reaching agents and improve the consistency and speed of support. Prerequisites - The Captain and/or bots capability enabled for your account (optional, enabled by plan/flag). If it isn't in the menu, talk to an administrator. - Admin permission to configure assistants, the knowledge base, and bots. - A connected inbox where the AI will operate. - Content to feed the knowledge: documents, help pages, or question/answer pairs. Step by step On the Bots page, start from a Maestro model or use Add Bot in the empty state to configure a webhook integration. 1. Open the Captain area and create an assistant. 2. Feed the assistant's knowledge: - add documents (or sync pages) for the AI to consult; - register responses (question-and-answer pairs) for frequent questions. 3. Define the assistant's behavior (tone, scope, and when to hand off to a human). 4. Connect the assistant/bot to the desired inbox. 5. Enable the copilot so agents get suggestions inside the conversation. 6. Test with real questions and tune the knowledge based on the answers. Settings & options - Assistants: the AI's "personality" and scope; each assistant can serve specific inboxes. - Documents: the knowledge base the AI uses to answer; these can be synced from pages. - Responses: question/answer pairs that reinforce frequent questions and standardize messages. - Copilot: an assistant for the agent — it suggests replies and summarizes the conversation inside the workspace. - Handoff to a human: define when the AI should transfer the conversation to an agent. Use cases - First-line support: the assistant answers common questions 24/7 and only escalates what's needed. - Qualification: the bot collects initial information before passing the contact to a rep. - Agent support: the copilot suggests the reply from your knowledge, speeding up handling. - Consistency: standardized responses prevent inconsistencies between agents. Tips, limits & best practices - AI quality depends on the knowledge: keep documents and responses up to date. - Always offer a clear path to talk to a human. - Start with a narrow scope (a few topics) and expand as you gain confidence in the answers. - Periodically review conversations where the AI acted to spot knowledge gaps. - Bot vs. Flow Builder: use bot/Captain for knowledge-based replies (natural language); use the Flow Builder for structured dialogues with steps and integrations. Troubleshooting - The AI didn't reply: confirm the assistant/bot is active and connected to the right inbox. - Inaccurate answers: the knowledge may be incomplete or outdated — add documents and responses and refine the scope. - The conversation wasn't handed off: review the handoff-to-human rule. - I don't see Captain: the capability may not be enabled for the account or your access role. See also - Automation & Flows overview - Flow Builder: visual conversational flows - Automation rules: triggers, conditions, and actions - Smart Routing

Advanced Captain: scenarios and custom tools

Overview The Captain does not have to be limited to answering questions from the knowledge base. Two advanced features turn the assistant into an agent: - Scenarios: guided playbooks, attached to an assistant, that describe a script (instructions/steps) to follow in specific situations — for example, qualifying a lead or running a collection flow. - Custom tools: HTTP calls the assistant can invoke during a conversation to read or write data in your systems (look up an order, validate a document, open a ticket). Together they turn static answers into service that follows processes and fetches information in real time, while always keeping the option to hand off to a human. Prerequisites - The Captain feature enabled on the account and at least one assistant already created (scenarios and tools attach to it). - Administrator permission to create, edit and delete scenarios and tools. - Custom tools may require an extra flag (custom_tools or the Captain v2 integration). If the tools menu does not appear, ask an administrator to enable it. - For tools that call your systems: the endpoint URL, the HTTP method and, when applicable, the authentication credentials. Step by step 1. Open the Captain area and select (or create) the assistant that will receive the advanced features. 2. Create a scenario: provide a title, a description and the instruction (the script/steps the assistant should follow). Optionally restrict which tools the scenario may use and leave it enabled. 3. Create a custom tool: define title, description, endpoint URL, HTTP method, the parameters the AI must fill in, and the authentication type. 4. Test the tool with the test button — the platform performs a real request and shows the status and a snippet of the response, so you can validate before enabling it. 5. Enable the tool and, if you wish, associate it with a specific scenario. 6. Perform bulk knowledge maintenance (approve responses, sync/delete documents) and review the agents' copilot history. 7. Test with real questions in the assistant playground and tune instructions, parameters and scope. Settings & options Scenarios Each scenario belongs to an assistant and has: - Title and description: identify the scenario and when it applies. - Instruction: the script in natural language — the steps the assistant should follow in that context. - Tools: the list of tools the scenario is allowed to use. - Enabled: turns the scenario on/off; only enabled scenarios are available to the assistant. Scenarios can be created, edited and deleted at any time without affecting the rest of the knowledge. Custom tools A tool describes an HTTP call the assistant can trigger: | Field | Purpose | |---|---| | Title / Description | Name and explanation; the description helps the AI decide when to use the tool. | | Endpoint URL | The address that will be called. | | HTTP method | GET, POST, etc. | | Parameters | Each parameter has name, type, description and whether it is required — this is what the AI fills in. | | Request / response template | How to build the body sent and how to interpret the return. | | Authentication type and config | For example, a token/key; credentials are kept protected. | | Enabled | Activates or deactivates the tool for the assistant. | The platform may cap the number of tools per account; once the limit is reached, creation is blocked with a clear message. Bulk knowledge - Responses (assistant responses): bulk actions to approve pending responses or delete several at once, speeding up knowledge curation. - Documents (assistant documents): bulk actions to delete or re-sync documents (only documents that can be synced are reprocessed). - Copilot threads: the copilot history is per user and tied to an assistant. Each query consumes the account's Captain response quota; when it runs out, the copilot notifies instead of answering. Use cases - Order lookup via tool: the customer asks "where is my order?"; the assistant calls a custom tool that queries your system and replies with the real status. - Guided collection via scenario: a scenario describes the collection script (greeting, data confirmation, sending the payment link) and the assistant follows it step by step. - Guided scheduling: a scenario that drives the booking and uses a tool to check available times. - Fast curation: the team uses bulk actions to approve dozens of responses and re-sync documents after a content update. Tips, limits & best practices - Start with a narrow scope: a few scenarios and one or two tools; expand as you gain confidence in the results. - Clear descriptions on tools and parameters help the AI choose and fill them in correctly. - Always test the tool before enabling, and review real executions periodically. - Keep the handoff: always offer a clear path to talk to a human when the AI cannot resolve. - Scenario vs. tool: the scenario defines what to do (the script); the tool defines how to fetch or record data (the HTTP call). Troubleshooting - The tool does not appear: the custom tools feature may not be enabled for the account (flag). Ask an administrator. - The scenario does not trigger: confirm it is enabled and attached to the correct assistant, and that the instruction clearly describes when to apply it. - The tool returned an error: use the test to see the status and response; review URL, method, parameters and authentication. Down endpoints or invalid credentials cause failures. - I cannot create more tools: you may have reached the account's tool limit. - The copilot stopped answering: the Captain response quota may have run out for the period. See also - Bots and Captain (service AI) - Flow Builder: visual conversational flows - Automation rules: triggers, conditions and actions

Flow Builder in production: sessions, versions, reports and database connections

Overview Building the flow on the canvas is only the start. Then comes operation: taking the flow live, keeping a version history so you can roll back safely, watching sessions (each run of the flow in a conversation), reading performance reports, organizing flows into folders, and connecting external data to the SQL node. The Mass runs tab completes the operation: run a published flow against an entire audience (mass run) with anti-ban pacing — see the dedicated article under See also. This article covers the lifecycle of a flow on Conversa Labs after it has been designed. To learn how to build the flow itself, see the Flow Builder article under See also. Prerequisites - The Flow Builder module enabled for your account. - Administrator to publish/unpublish, version, manage folders and manage database connections. Agents can list and monitor sessions, open reports and use connections that already exist. - For the SQL node (sql_query): an external database connection configured and tested. - For reports and monitoring to be meaningful: at least one published flow in use. Step by step 1. Publish the flow when it is ready. From then on its triggers can start it. 2. Monitor sessions in the run list: filter by flow, conversation or status. 3. Open the reports to see volume, completions and failures over a period. 4. When you need a change, edit the draft and publish again — the previous version stays in history so you can roll back if needed. 5. Organize flows into folders by team or purpose. 6. If a flow reads data, create and test the database connection before using the SQL node. Settings & options Publishing and versions - Publish / Unpublish: publishing makes the flow live for its triggers; unpublishing takes it offline without deleting it. - Draft: the editing copy. Saving the draft validates the definition and never touches the published version — you can edit freely without affecting flows already running. - Version history: each publication stores a version. You can open an old version to review what changed. - Restore (roll back): brings a previous version back as the current one. - Duplicate: creates a copy of the flow so you can experiment without risk to the original. - Purge (permanent delete): removes the flow permanently. This action cannot be undone. Session monitoring A session is one run of the flow inside a conversation. From the list you can: | Action | What it does | | --- | --- | | List / filter | View sessions by flow, conversation or status (running, waiting, completed, failed, canceled), paginated. | | Cancel | Stops an active session (running or waiting) and releases the conversation. | | Rerun | Runs the flow from the start as a fresh session (same flow, conversation, contact and variables). Ideal for a session that failed or was canceled. | | Resume | Forces a session stuck in "waiting" to continue from the current node, as if the wait had been satisfied. | | Delete | Removes the session and its step trace. If it was active, the conversation is released first. | | Bulk actions | Select several sessions and cancel (active ones only) or delete at once. | Runtime v2 metrics and alerts The protected /monitoring/metrics endpoint publishes global and per-tenant metrics for trigger, queue, resume, and due lag; step, effect, and provider latency; retries, deduplication, stale leases, unknown effects, DLQ, locks, pools, and batches. It only exists after the operator configures OPERATIONS_METRICS_TOKEN. Alerts are evaluated every minute and thresholds can be tuned with FLOW_BUILDER_ALERT_* variables; episodes live in one TTL-bound Redis hash. No payload, secret, contact, conversation, or personal data is published. Operators must apply the additive observability indexes before enabling this collection at scale. Reports Reports show the execution metrics of your flows — session volume, completions and failures. You can filter by flow and by period (start and end date) to compare performance over time. Organizing into folders Group flows into folders by team, channel or purpose. Deleting a folder does not delete the flows inside it — they simply go back to having no folder. Database connections (SQL node) The SQL node queries an external database using a connection you register once: - Create/edit a connection: provide the adapter (PostgreSQL, MySQL or SQL Server), host, port, database, username and password. The password is write-only — it is accepted when you save but never returned to the screen. When editing, leave the password blank to keep the current one. - Test connection: opens the pool and runs SELECT 1 to confirm the credentials work. - Test query: runs the node's query against a bounded sample and shows the rows plus the compiled SQL and parameters — you see exactly "what will run", with {{ variables }} resolved just like at runtime. - SQL template gallery: ready-made read-only snippets (search, listing, aggregation, and joins) in the dialect of the chosen adapter, to fill the query field without starting from scratch. The v2 runtime accepts one parameterized read statement per node. SQL writes are not shown in the gallery and cannot be published until an administrator-only, human-confirmed surface exists. Write-only credentials for HTTP and webhooks After an administrator provisions a vault credential, select it by name in the node. The flow definition stores only an opaque reference: - HTTP request supports bearer tokens, API keys, Basic Auth, and OAuth2. OAuth2 can use a static access token, client_credentials, or refresh_token; token exchange uses the same request limits and SSRF protection as the main request. - Outbound webhook uses a separate signing credential. - Secrets never enter the definition, export, history, or trace. Rotating a credential preserves the flow reference and invalidates the cached OAuth2 token. Import / export - Export: downloads a flow's definition to store it or move it to another account. - Import: creates a flow from an exported definition. - Test HTTP request: fires a single request in isolation (without running the whole flow) to check the URL, headers and response before using it in a node. Use cases - Change a live flow safely: edit the draft, publish, and if something goes wrong, restore the previous version in seconds. - Recover problem runs: find failed sessions with the status filter and rerun them in bulk. - Unblock a stalled chat: a "waiting" session that never received its reply can be resumed manually. - Look up orders inside the flow: configure a database connection, validate it with "Test query" and use the SQL node to answer the customer with real data. Tips, limits & best practices - Publish important changes during quieter hours and keep the history so you can roll back. - Rerun creates a fresh session; it can be blocked if the flow is no longer published or if another active session already exists for the same conversation and flow. - Bulk actions have a per-call item cap — for large volumes, repeat in batches. - Treat the database password as a secret: it is write-only and never shown back in the interface. - Always run Test connection and Test query before publishing a flow that uses the SQL node. Troubleshooting - Session stuck in "waiting": use Resume to force it to continue from the current node. This only works for sessions in that state. - Session failed or was canceled: use Rerun to run the flow from the start as a fresh session. If it is blocked, confirm the flow is still published and that no other active session exists for the same conversation. - The database connection failed the test: check adapter, host, port, database, username and password; verify the adapter is available on the server and that the network allows access. - Flow is published but never fires: check the trigger and whether the flow is linked to the right inbox; look for errors in recent sessions and confirm the published version is the one you expect. See also - Flow Builder: build conversational flows visually - Automation rules: triggers, conditions and actions - Automation and Flows overview - Mass runs in the Flow Builder

Smart Routing

Overview Smart Routing decides which agent each conversation goes to and how many conversations each agent receives — automatically. Instead of distributing manually, the platform applies policies to every new conversation, balancing the load and improving response time. Two policy types work together: - Routing policy: sets the distribution strategy and the priority order. - Capacity policy: sets the load limits per agent and per inbox. Management is done by the account administrator in Settings → Smart Routing, including a ready-made templates section to start with one click. Prerequisites - Administrator profile (or a custom role holding the routing-management permission). - The Smart Routing feature enabled on the account. If the item is missing from the Settings menu, talk to the account owner. - Inboxes and agents already configured — the policies bind to them. Step by step 1. Open Settings → Smart Routing. 2. To start fast, use the ready-made templates: apply a routing archetype (Round-robin, Load balanced, Skill-based, Fair distribution) or a capacity one (Default capacity, Ignore old conversations) — or load all defaults at once. 3. Or build from scratch: under Routing policy, pick the strategy, priority and options. 4. Under Capacity policy, set the per-inbox limits, exclusion rules and participating agents. 5. Bind the policy to an inbox — from then on every new conversation is auto-assigned. 6. Watch the distribution on real conversations and tune the policies as the operation evolves. Settings & options Routing strategies: | Strategy | How it distributes | | --- | --- | | Round-robin | Rotates conversations equally among agents. | | Balanced | Assigns to the agent with the fewest open conversations. | | Skill-based | Prefers agents on the conversation's team, then rotates. | Conversation priority: oldest first, or the ones waiting the longest for a reply. Additional routing-policy options: - Fair distribution: caps how many conversations an agent receives within a time window. - Reassign on unassign: automatically re-routes the conversation if the assigned agent is removed. - Enable/disable: pauses a policy without deleting it. Capacity policy: - conversation limit per inbox; - exclusion rules (for example, by conversation age); - agents bound to the policy. Ready-made templates: applying a template is idempotent — if you already edited a same-named policy, your edit is never overwritten. Linking to an inbox 1. Go to Settings → Inboxes → (your inbox) → Collaborators/Agents tab. 2. In the Smart routing panel, pick an active policy and click Link policy. 3. Once linked, the routing engine takes over assignment: the inbox's automatic assignment toggle is turned off automatically (and restored when you unlink). 4. Use Switch to replace the policy in charge or Unlink to return to the inbox's native behavior. If the account has no policies yet, the panel offers a shortcut to create one from the ready-made Smart Routing templates. Integrated operation The Smart Routing screen gathers, in a strip of shortcuts, the modules that operate alongside distribution — so routing, capacity, schedules, queues and permissions live in one place. The shortcuts appear according to the features enabled on the account: - Team Management — when the feature is on: Monitoring (real-time board), Schedules and Queues. This is where you control which agents/teams take part in service and how load is tracked. - Roles & Access — when granular permissions are on: manage the roles (e.g. Sales Rep and Sales Manager) that authorize each agent. - Agents — the account's agent list. The shortcuts only navigate to each module; nothing changes when you click. Use cases - Balance the team: the balanced strategy prevents one agent from piling up conversations. - Specialty service: skill-based routing sends to the right team first. - Overload protection: a capacity policy caps simultaneous conversations per agent. - SLA: prioritize the longest-waiting conversations to cut response time. Tips, limits & best practices - Combine routing + capacity: the strategy picks who, the capacity avoids overloading. - Make sure agents are available (online) — policies distribute to whoever can serve. - Review capacity limits as the team grows or during demand spikes. - Template applies are recorded in the audit trail (when enabled). Troubleshooting - The item is missing from Settings: the feature is not enabled on the account. - Conversations are not being assigned: confirm the policy is enabled and bound to the right inbox, and check that agents are available. - One agent receives too many conversations: review the strategy and add a capacity policy with limits. - Conflicts with automation rules: if a rule also assigns agents, align both so they don't overlap. See also - Automation & Flows overview - Automation rules: triggers, conditions and actions - Governance & LGPD