Automation & Flows

Automation & Flows overview

Overview The Automation & Flows area brings together the tools that make ConversaLabs 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 ConversaLabs 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 how the rule runs. The When should this rule run? selector appears when delayed execution is enabled on the account: - Run instantly — "Runs the moment an event happens, as long as the conditions match." This is the classic behavior, with the trigger selector and the condition list right below it. - Run after a wait — "Waits for a set time and runs only if things are still the same. If they change, the rule is skipped." In this mode the trigger and conditions give way to the Wait condition block, detailed under Settings & options. 4. 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, partial refund adjusted, order refunded, payment reversed and deal orders fully paid (with the Payments/Commerce modules active); - Payments: charge created, confirmed, paid, partially refunded, overdue, refunded, failed or canceled. Confirmed means the customer completed the payment although the gateway may make the balance available to the merchant later; paid/received records that later provider stage. Do not create duplicate rules with the same actions for both events; - 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. 5. 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. 6. Define one or more actions (see the list below). 7. 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. Subscriptions: what fires and what does not A subscription created in the gateway dashboard is adopted here and does fire the rule: as far as the platform is concerned it is happening now, already filtered by the connection's cutoff date. A subscription brought in by a history import never fires — it is the past, and replaying it would open deals and send notifications about old sales. An adopted subscription can arrive with no linked customer. Actions that need a person (opening a deal, messaging, scoring) have nobody to address, and a deal with no contact, company or conversation is refused rather than becoming a useless card in the funnel. To act only when there is somebody on the other side, add the Subscription linked contact condition with "is present". - 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. Variables in actions ({ } Insert) Every text field the platform resolves at run time shows the { } Insert button and opens the variable list when you type {{. The chosen variable goes where the cursor is and the rule window stays open. The same fields accept variables in Automations, Macros and the Flow Builder — in a flow, those fields also resolve {{ vars.* }} and {{ steps.* }}. | Action | Fields that accept variables | | --- | --- | | Send message, Add private note | Message | | Send an email to the team | Message | | Send transcript by email | Emails | | Create contact | Name, email, phone, identifier, tax ID, tax country and custom attribute values | | Create conversation | First message | | Add note to contact | Note | | Set contact / company attribute or field | Value (text) | | Set contact affiliate | Referral code | | Create CRM deal | Title, description, contact email and phone, value, dates and custom attribute values | | Deal attribute, status and messages | Attribute value, close reason, note, checklist item, message | | Create task, Comment on task | Title, description, due date, custom attribute values, comment | | Create, cancel and invite on an appointment | Title, description, location, start, end, custom attributes, reason, invitee email | | Create charge, Create subscription | Description | | Register order | Title, amount, external ID | | Sales | Points metric, transfer and reward reason | | WhatsApp (groups and contacts) | Phone, contact name, community announcement | | Send WhatsApp template or Flow | Template variables, header and content; Flow button, body, header and footer | | Ask Maestro | Question | | Adjust ad budget | Daily budget | Fields that deliberately do not accept variables: - Pickers (agent, team, label, pipeline, stage, inbox, connection): the value comes from the list. - Webhook URL: the destination is fixed for security; the conversation or contact data already travels in the webhook body. - Amount of charges and subscriptions: it is money sent to the gateway and never comes from text. - Order gateway, template language and namespace: they are identifiers. - Additional attributes and the number and date fields of the rule editor (for example, the deal value in "Set value"): in the Flow Builder form the deal value accepts a variable. Which variables the list offers depends on the trigger: - Conversation and message: contact, conversation, inbox, agent, team, SLA, account and the modules (CRM, company, payment, order, calendar, task, contract and others). - Contact and company: there is no conversation — the list hides conversation, inbox, agent, team and SLA. - Payments: {{ payment.* }} describes the charge that fired the rule. CRM: {{ crm.* }} describes the deal that fired the rule. - The other contact-linked modules (order, calendar, task, contract) use the contact's most recent record. - Rules and macros never offer the Flow Builder-only variables (vars, steps, trigger) nor those of other screens (product, campaign, group, article). When a variable has no value, that part of the text is left blank — the customer never receives {{ ... }}. In fields that are data (phone, invitee email, IDs, amounts and dates), the action is skipped and logged instead of saving a wrong value. The phone is normalized to the international format after the variable is resolved, so 55 11 98888-7777 becomes +5511988887777. A variable's value is always treated as text: if a contact name, an attribute or a customer reply contains {{ }} or {% %}, it shows up exactly as it is — it is never executed — and in the team email it never becomes HTML either. A template that produces too much text or loops without end is stopped and left blank. The rule form The rule opens as a modal window over the list, anchored to the top of the screen and scrolling on its own: the whole form fits in there, from the name down to the actions. Condition and action menus open inside that window — a deliberate choice on this platform, so that no dropdown ends up hidden behind the modal. The field order is always the same: name, description, the When should this rule run? selector (when delayed execution is enabled) and, below it, the trigger and the conditions — or the Wait condition block, if you pick the wait. Actions come last, followed by the cancel and save buttons. A few details that prevent surprises: - Switching between "run instantly" and "run after a wait" does not lose the duration you typed. The value is held by the form, so you can move back and forth between the two cards without typing "4 hours" again. - When you reopen a rule with a wait, the time is shown in the largest whole unit: 240 minutes reads as "4 hours"; 2,880 minutes, as "2 days". - When you turn an instant rule into a rule with a wait, the instant editor's conditions are replaced by the conditions of the wait trigger you chose. That is deliberate: a filter left over from the previous editor would arm the clock on the wrong event. - In the wait block the status comes pre-filled with Pending; the options are Open, Resolved, Pending and Snoozed — "All" is not offered here, because a wait needs one concrete status to count against. - On a new rule, changing the event warns in plain text: "Changing event type will reset the conditions and events you have added below". - Triggers whose subject has no filterable field at all (WhatsApp group, catalog and others) simply don't show the conditions section — instead of rendering an empty condition row. Rules with a wait: run after some time has passed Delayed execution is controlled by the Delayed Automations feature (delayed_automations), which ships turned off and is enabled per account. With it on, the rule form gains the When should this rule run? selector, with two card options: Run instantly and Run after a wait. When you pick the wait, the trigger and the condition list give way to the Wait condition block, with four fields: | Field | What you fill in | | --- | --- | | When | The situation that starts the clock: Conversation stays in a status, Customer hasn't replied or No teammate has replied. | | Status is | Only shown for the first option: the status the conversation has to stay in. | | For | The duration, in minutes, hours or days. | | Inbox | Restricts the rule to specific inboxes. With none selected, it applies to all of them. | Next to the fields there is a side panel with an information icon. It explains in plain sentences what the chosen combination means, using the same unit you typed ("4 hours", "2 days"): - Conversation stays in a status — "The clock starts when a conversation moves into this status. If it is still there {duration} later, the actions below run. If the status changes before then, nothing happens." - Customer hasn't replied — "The clock starts when a teammate replies. If the customer hasn't written back {duration} later, the actions below run. If they do reply, nothing happens, and the next teammate reply starts the clock again." - No teammate has replied — "The clock starts when a customer sends a message. If no teammate has replied {duration} later, the actions below run. If someone replies before then, nothing happens." The same panel carries the footnote: "Only new activity starts a clock. Conversations already sitting in this state are picked up the next time something happens on them." Two precisions the panel has no room to explain, and that change the outcome: - On Customer hasn't replied, every new teammate reply pushes the due time forward: the clock now counts from the most recent reply. A burst of team messages moves the deadline along; it does not stack up several deadlines. - On No teammate has replied, the clock is the one of the customer's first unanswered message. If they send three more messages in a row, the deadline keeps counting from the first one — it does not restart with each message. Wait limits - Minimum of 10 minutes and maximum of 30 days (43,200 minutes). The field clamps a value outside that range to the nearest bound — when you leave the field, press Enter or change the unit. Typing 5 minutes leaves 10. The error "The wait must be between 10 minutes and 30 days" appears when you try to save with the duration field empty. - The duration suggested on a new rule is 4 hours. - When you switch units, the minimum follows: in days, the smallest possible value is 1 day. - A private note is an outgoing message. That is why the Customer hasn't replied option adds a filter of its own that ignores internal notes — a team note doesn't restart the clock. What a wait does not accept - Conditions using the attribute changed operator (attribute_changed): the re-check done at run time cannot reconstruct what changed, so the rule is refused on save. - On conversation triggers, only status and inbox can be used as conditions. The other fields change during the wait and would blend distinct stretches into a single clock. Editing a rule with a wait clears the clocks in flight Changing the trigger, conditions, actions or duration — or simply turning the rule off and on — discards the waits already armed. They arm again on the next matching event. This is deliberate: a rule switched off and back on before its due time must not run exactly the actions you switched it off to prevent. One exception: a wait that has already started running the actions is not interrupted — what is in flight cannot be called back. Everything that was still only waiting is discarded. How the list separates instant rules from rules with a wait When the account can create rules with a wait (or still has one), the list gains two tabs with counters: Runs instantly and Runs after a wait. Creating a rule from the second tab opens the form with the wait already selected. - Each rule with a wait shows the badge Runs after {time} next to its name, written in the largest whole unit: 30m, 4h, 2d. - The wait tab with no rules shows "No rules run after a wait yet". - Every row carries three action icons, each with a hover tooltip: Edit, Clone and Delete. In the form, every rule action has its own icon too (an envelope for the email transcript, a tag for labeling, a crossed-out bell for muting, a clock for snoozing, and so on) — the same icons appear in Macros. The full set of action icons: a person (assign agent), rounded people (assign team), a person with an X (remove agent), people (remove team), a tag (labeling), a tag with a minus (remove label), an envelope (email transcript), a paper plane (email to team), a speech bubble (send message), a sticky note (private note), a paperclip (attachment), a webhook, a crossed-out bell (mute), a clock (snooze), a circle with a dot (reopen), a dashed circle (mark as pending), a circle with a check (resolve), signal bars (priority) and a gauge (SLA). Any action without its own icon uses the lightning bolt. The header also carries the search box ("Search automation rules..."), which filters by name and description at once and applies to both tabs — the counters follow the filter. With no match, the table shows "No automation rules found matching your search". Next to the tabs sits the count of the rules visible in the current tab. The table has four columns: Name, Active, Created on and Actions. The date column shows the day; the full time appears on hover. The Active switch asks for confirmation before turning a rule on or off, and the question names the rule ("This action will deactivate the automation rule '...'"). When the wait is turned off If the feature is disabled and the account still has rules with a wait, a highlighted banner appears above the list: "Delayed execution is turned off for this account, so the rules below that run after a wait are paused until it is turned back on." In that state: - The waits already armed are not deleted — they sit still. When the feature is turned back on, the ones that went past the 3-day limit during the pause get a fresh due time of now, instead of being dropped as expired; the rest simply come up in the next sweep. All of them go through the normal re-check before running. - No new wait is armed, and the rule does not start running instantly: silently becoming instant would be worse than not running. - Cloning a rule with a wait is refused, instead of creating a copy that would fire immediately. The screen shows the generic notice "Could not clone automation rule, Please try again later"; the specific reason comes back in the API response ("Delayed automations are not enabled for this account."). How a wait runs behind the scenes Knowing this helps you read what you see on screen: 1. When the event happens and the conditions pass, the platform schedules the execution instead of running the actions. The clock starts at the moment of the event — not at the moment processing happened — so a backlogged queue still fires on schedule. 2. Every 5 minutes a sweep collects the executions that came due and hands them to the workers. 3. Before running, the platform re-checks everything: is the rule still active? Does the conversation still exist? Is it still the same stretch (the status didn't change, nobody replied)? Are the conditions still true? Any "no" records the reason and drops the execution without running the actions. 4. An execution more than 3 days past due never runs — that keeps a long outage from dumping old messages all at once. Finished records are purged after 30 days. 5. Actions are never repeated: if something fails after they started, the platform does not re-run them. Re-sending a message, email or webhook is worse than not sending it. Two safeguards complete the picture: - Each sweep hands over at most 1,000 executions. The overflow waits for the next sweep, 5 minutes later, and whoever runs the installation can change that ceiling. Accounts with delayed execution turned off do not consume that budget — one paused account's backlog never delays the others. - A worker that dies before acting has its execution reclaimed after 15 minutes and handed back to the queue. A worker that dies in the middle of the actions is not repeated, for the same reason as item 5. Every discarded execution keeps the reason, which makes diagnosis direct: expired (more than 3 days past due), rule_inactive (the rule was turned off), conversation_gone (the conversation no longer exists), episode_moved (the stretch ended — someone replied or the status changed) and conditions_changed (a condition stopped being true). One detail that explains the panel's footnote: a wait on status only arms when the conversation has a record of when it entered its current status. Conversations that predate the feature have no such record — they start counting on their next status change, instead of all coming due at once on the first sweep. Sending the transcript to the contact's email The Send transcript by email action accepts a comma-separated list of addresses, and each address goes through variables before sending. To send the history to the customer themselves, write: {{contact.email}} You can combine a variable and a fixed address: {{contact.email}}, supervisor@yourcompany.com. Other contact variables work in this field too (for example {{contact.custom_attribute.billing_email}} for a custom attribute). Only use the variable on rules whose conditions guarantee a contact with an email on file — with no email there is nothing to resolve. Sending only happens when email transcripts are enabled for the account, and it respects the account's email limit. Two details about the field: all whitespace is stripped before the list is split on the commas — {{contact.email}} , supervisor@yourcompany.com behaves exactly like the version without spaces. And the field resolves the same variable set as the reply composer (contact, conversation, inbox, account and the active modules), not only the contact ones. If the account hits its email limit mid-list, the remaining addresses of that send are left out. 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. - Customer went quiet (with a wait): if the customer hasn't replied 4 hours after the team's last reply, label it "no reply" and create a follow-up task. - First response running late (with a wait): if no teammate replies within 30 minutes, notify the team by email and raise the priority. - Stalled queue (with a wait): a conversation sitting in "Pending" for 2 days, resolve it and send the transcript to the contact's email. 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. - Start with generous waits (hours, not minutes) and shorten them once you've seen the result: a wait that is too short fires on conversations that were still being handled. - The wait is a continuous clock, not a business-hours one: 12 hours starting at 8pm come due at 8am the next day. - When you enable delayed execution, conversations already sitting in that state don't start counting on their own — the clock starts on their next activity. - Restrict the rule by inbox when the acceptable response time differs per channel. 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. - An action shows a locked value, just a number: the action points to a record of a module that is off for the account or that your role cannot open (for example a follow-up sequence or an SLA policy). A locked value can also mean the list has not loaded, its request failed, or your access role's list does not include the record (it may be outside your reach or removed). The hint explains the cause. The saved reference is kept unchanged when you save unrelated changes. Reload the page to retry a failed list; for restricted access, ask someone with access or turn the module back on. - An action shows a number instead of a name: the record may be outside the loaded page of a long list or may have been removed. A prepared batch can also appear only by its identifier. When a lookup confirms removal, the field identifies it as removed. The value stays selected and is saved unchanged; choose another item only if you want to change it. - The webhook didn't arrive: check the endpoint URL and that it responds successfully. - The rule with a wait never ran: the most common reason is that the stretch ended before the due time — someone replied, the status changed, or a condition stopped being true. Also check that the rule is still active and the conversation still exists. - Every rule with a wait stopped at once: look for the banner above the list. It means delayed execution was disabled for the account; turning it back on reschedules the waits that came due. - I want to know why a wait was discarded: the reason is recorded on the execution itself — expired, rule_inactive, conversation_gone, episode_moved or conditions_changed. Ask whoever runs the installation to look it up when the behavior isn't clear. - Waits are coming due late: each sweep hands over up to 1,000 executions and runs every 5 minutes. A backlog larger than that is drained across the following sweeps. - I can't save the wait: remove conditions that use the attribute-changed operator and, on conversation triggers, keep only status and inbox. - I can't clone a rule with a wait: the generic clone-failure notice appears because the feature is disabled on the account. Enable it again before cloning, so you don't end up with a copy that lost its wait. - The wait block doesn't appear in the form: the Delayed Automations feature is not enabled for the account. CRM stage changes Use CRM deal stage changed and choose the stage in the conditions. Only an actual move triggers the rule; reordering a card inside its current column does not start another execution. Attachments (including PDF) and Meta conversions use the deal’s linked conversation. If the link is missing, that action is recorded as skipped; the webhook can run independently. Check the inbox conversion settings and attach files to the rule itself. Queuing a conversion does not prove Meta accepted it: inspect the conversion delivery record as well. For delayed execution, the clock starts at the stage change. At execution time the system checks the stage, conditions and active rule again. Pausing the feature preserves pending actions. Reactivation resumes eligible actions; work overdue by more than three days is marked expired. Editing or disabling the rule cancels pending work from its previous definition. Each action keeps its own outcome. Replaying an event or restarting a worker does not repeat completed actions. If an external integration may have acted before a failure, its outcome remains uncertain and needs reconciliation before another send. Do not replay historical stage moves in bulk to recover a rule: that can trigger valid commercial effects again. 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. - An action shows a locked value, just a number: the action points to a record of a module that is off for the account or that your role cannot open (for example a follow-up sequence or an SLA policy). A locked value can also mean the list has not loaded, its request failed, or your access role's list does not include the record (it may be outside your reach or removed). The hint explains the cause. The saved reference is kept unchanged when you save unrelated changes. Reload the page to retry a failed list; for restricted access, ask someone with access or turn the module back on. - An action shows a number instead of a name: the record may be outside the loaded page of a long list or may have been removed. A prepared batch can also appear only by its identifier. When a lookup confirms removal, the field identifies it as removed. The value stays selected and is saved unchanged; choose another item only if you want to change it. - The warning "We could not check which modules are on for this account" appears: the platform could not load the account settings. Click Try again on the warning itself. Meanwhile, the actions that depend on a module stay locked with their saved values, and saving other changes does not alter them. - I cannot find a flow, follow-up or contract action when creating a macro: these actions only appear when the matching module (Flow Builder, Follow-up or Contracts) is on for the account. A macro that already uses the action keeps showing it, locked and with its saved value. 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 ConversaLabs 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. Buttons and lists on WhatsApp The Send buttons and Send list nodes arrive as a native interactive message on WhatsApp Cloud, Coexistence, WhatsApp Web and the unified hybrid inbox. Besides the message and the items, you can set: | Field | Node | What shows on WhatsApp | | --- | --- | --- | | Header | Buttons and list | Bold title above the message, up to 60 characters. | | List button text | List | Text of the button that opens the list, up to 20 characters. | | Description | List items | Smaller text below each item, up to 72 characters. | | Section title | List (Advanced) | Heading above the items when the list is open, up to 24 characters. | | Footer | Buttons and list (Advanced) | Small gray text below the message, up to 60 characters. | Every field is optional and accepts variables. Leave the header empty for the list to arrive with no title. When the list button text is empty, "Choose an item" is used in the account language. On WhatsApp Web, buttons always show a title: with no header, "Options" is used in the account language. The value of each item identifies the chosen option: it is what the flow compares in an option wait. In any other wait, the flow receives the item title. Reply waits and human handling In Wait for reply and Wait for follow-up reply, set the input type and valid options. While attempts remain, an invalid reply sends the Invalid-reply message; if it is empty, the Re-prompt message is used. Fill in at least one to guide the contact, for example: "I did not understand. Reply 1 to confirm or 2 to cancel". Processing the same contact message again does not consume another attempt or send the notice twice. Under Human handling, the default is End wait and session: when an agent sends a public reply in the conversation, that reply wait and its session are canceled. Private notes, bot messages, campaigns and messages identified as automation do not count as human handling. Cancellation sends no message, does not reopen the conversation and does not change its assignment. A later contact reply does not resume the canceled session or execute its next steps. In the session history, the node output records the reason human_takeover and the trigger agent_message. Sessions of the same flow already queued for this conversation are also canceled, with the same reason in their history. They do not start later and reply over the agent. A macro sent manually by an agent and a follow-up draft approved by that agent count as human replies. A scheduled-message delivery does not count, even if its sender is an agent or the delivery is brought forward with send now. An immediate copy outside that scheduled delivery counts when it uses the agent's user. A meeting link sent automatically by Calendar does not count. This default also applies to published flows that do not have the setting. To keep waiting after an agent replies, choose Keep waiting in the node and publish a new version. The choice is recorded when the wait begins; editing the node does not change waits that already started. This rule does not change Wait until or event waits. Resolving the conversation without replying does not end the wait: the flow may still consume the contact's next message. Send a public reply before resolving or cancel the session from the sessions screen. Automatic resolution does not cancel this wait either. An integration or MCP tool that sends a public reply using an agent's user counts as human handling and ends the wait. To keep the previous behavior in that case, select Keep waiting in the node. Handling from a phone or an external message echo without an identified agent user does not end the wait under this rule; the echo may also confirm a message that the platform itself sent. 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. - The list arrived with a title or button in another language: set the Header and the List button text in the node. Empty fields use the default texts in the language configured for the account. - The button or header text arrived cut off: WhatsApp limits these fields and emojis take more space. Shorten the text or the variable you used. 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 ConversaLabs 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. | | ConversaLabs 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. - An action shows a locked value, just a number: the node points to a record of a module that is off for the account or that your role cannot open (for example a distribution or a contract template). It can also mean the list has not loaded, its request failed, or your access role's list does not include the record (it may be outside your reach or removed). The hint explains the cause. The reference is kept unchanged whenever the flow can be saved; for a loading failure, reload the page to try again. For restricted access, ask someone with access or turn the module back on. - The whole action is locked, with a notice that it is not available on this node: the action's module is off for the account, or the action does not belong to this kind of node. The node stays exactly as saved (opening the panel does not replace the action) until you choose another action in the selector. An unavailable action prevents testing and publishing the flow. If the node itself belongs to a module that is off, saving the draft is refused too; keeping its stored values does not override that rule. - A field shows a number instead of a name: the saved record is not in the part of the list the screen loaded (long lists arrive in pages), or the record may have been removed. When a lookup confirms removal, the field identifies it as removed. The saved value is kept; choose another item only if you want to change it. Saving unrelated changes does not silently replace that reference. 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, currency, description (with variables), 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. 4.97 means R$ 4,97. The deal and order value also accept a token like {{ crm.value }}, rendered when the flow runs; the charge and subscription amount is always typed, because it goes straight to the gateway. - 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 ConversaLabs 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. - Receive messages during human handling: for an external webhook bot, enable Keep receiving messages when an assignee is present only when the integration needs to preserve context. The option is off by default, applies to every linked inbox, and does not authorize the bot to reply over the agent. Maestro always receives events and uses its own pause policy. - Inbox automatic responder: when you link a support bot or Captain assistant, that choice becomes the only responder allowed to send automated replies for the inbox. In a hybrid inbox, the choice covers the Cloud + Web pair. Existing links remain for configuration and auditing, but the responder that was not selected stays silent. 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. - The length of a Captain reply follows the limit of the conversation's transport: up to 65,536 characters on WhatsApp Web without a hybrid pairing; up to 4,096 on WhatsApp Cloud, in a hybrid inbox and in a WhatsApp channel conversation. A longer reply is rewritten to fit; if it still does not fit, the conversation is handed over to a human. Troubleshooting - The AI didn't reply: confirm the assistant/bot is active and connected to the right inbox. - Bot and Captain are linked, but only one replies: this is intentional. Link the responder that should take over again to update the inbox's explicit choice; the other remains silent to prevent duplicate replies. - 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. - The external bot stops receiving after assignment: edit the bot and enable assigned-conversation delivery. First ensure the integration checks the assignee and stays silent while the human handles it. - 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 ConversaLabs 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. Plain-text secret warning. When you click Test, the editor shows an amber warning on the node if it finds a secret typed directly into the request: a header, URL parameter or body field with a secret-like name (token, API key, password, Authorization) and a literal value, or a platform API access token in any field. The warning says where the secret is and never shows its value. To fix it: 1. Ask an administrator to create an HTTP credential with that header. 2. Select the credential in the node and delete the typed header. 3. If the secret was a platform access token, also ask the administrator to generate a new token. Moving the token into a credential does not undo the exposure. A secret in a URL parameter or in the body has to be adjusted by hand, because moving it changes what the destination server receives. 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. Beyond new conversations, the engine runs a periodic sweep over the inboxes with a bound policy: conversations that are already open and unassigned — including the ones that were already sitting that way before you turned routing on — are distributed automatically, oldest first. You don't have to reassign them by hand or build a flow for it. 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, and the periodic sweep takes care of the backlog that was already unassigned. 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. Sweeping unassigned conversations Routing doesn't act only at the moment a conversation is born. Periodically, the platform walks the inboxes with an enabled and bound policy and distributes the conversations that are open and unassigned — using the same strategy, the same priority and the same capacity and fair- distribution limits as the automatic path. - It reaches the existing backlog: old unassigned conversations enter the sweep queue. - It honours the order set in Conversation priority. - It distributes in batches per round, so the team isn't flooded at once — a large backlog is drained over a few rounds. - It only acts on inboxes bound to an enabled policy. Disabling or unbinding the policy stops the sweep. 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. - Clear the backlog: when you turn routing on in an operation that already has conversations sitting unassigned, the sweep distributes that backlog on its own, with no manual step. 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. - Old conversations are still unassigned: the sweep only reaches inboxes bound to an enabled policy and needs available agents. If the backlog is large, wait a few rounds — it drains in batches. - 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