> ## Documentation Index > Fetch the complete documentation index at: https://docs.alcmeon.ai/llms.txt > Use this file to discover all available pages before exploring further. # Automations: event-triggered WhatsApp flows in Simio > Build event-triggered WhatsApp flows in Simio using the shared visual builder, opt-in and API triggers, trigger variables, test sends, and status states. An automation is a flow triggered automatically by an event (a contact opting in, or an external system calling Simio's API), rather than by a manual send. Automations use the exact same visual flow builder, canvas, step types, and edit panels as [campaigns](/simio/platform/campaigns) and [chatbots](/simio/platform/chatbots). This page covers the shared builder mechanics once, then everything specific to automations. ## The flow builder: shared canvas mechanics The editor is a canvas where steps appear as cards and are connected with arrows describing what happens next for a given contact. This is identical for chatbots, automations, and campaigns. ### Adding a step * **Toolbar buttons**: click a step type in the toolbar to drop it onto the canvas. * **Drag and drop**: drag a step type from the toolbar directly onto the canvas at the position you want. * **Insert into an existing connection**: every arrow between two steps has a small "+" button. Clicking it opens the same step picker and inserts the new step directly into that connection, splitting it in two, instead of appending the new step somewhere else and requiring you to rewire everything by hand. ### Connecting, editing, and deleting Every step has a connection point on its left (incoming) and, where relevant, one or more on its right (outgoing). Drag from an outgoing point to another step to connect them. Steps with multiple possible outcomes (buttons, list items, Condition, AI assistant) expose one outgoing connection point per outcome. Clicking a step opens a side panel with that step's configuration. The step card on the canvas itself is often display-only (for example, the Action step's canvas card just shows a one-line summary); the panel is where the actual configuration happens. Each arrow has a small "×" button to remove that specific connection. Steps themselves are deleted from within the side panel or via the step's own controls, depending on step type. ### Saving Changes are staged locally as you build; nothing is written to the server until you explicitly save. Newly added steps only get a permanent ID once the save succeeds. Leaving the editor with unsaved changes (via any navigation, not just the back button) shows a confirmation dialog warning that you have unsaved modifications, so you don't lose in-progress work by accident. This does not protect against closing the browser tab entirely. ### Canvas controls The canvas supports pan, zoom in/out, and fit-to-view, plus a minimap for orientation on larger flows. ## Editor tabs | Tab | Chatbots | Automations | | - | - | - | | Scenario | The canvas itself | The canvas itself | | Details | Name, channel, connected account, trigger settings | Name, channel, connected account, trigger settings, active/inactive toggle | | Results / Analytics | Present but always disabled today | Present, gated the same way as campaign analytics | ## Step types: full reference For the exact fields exposed inside each step's edit panel, see the shared [Scenario builder](/simio/platform/scenario-builder) reference. | Step | What it does | Notes | | - | - | - | | Template | Sends a pre-approved WhatsApp template message | Required as the entry content step for automations (and campaigns); not required for chatbots | | Message | Sends free-form content: plain text/media, or a selectable list ("survey") | Does not need to be pre-approved; only deliverable within an open 24-hour conversation window (see limits below) | | Note | A sticky-note style annotation on the canvas | Sends nothing, has no connections, purely for the flow author's own reference | | Action (Opt-in / Opt-out) | Marks the contact as opted in or opted out of marketing messages | Internally called "Consent" | | Action (Add tag) | Applies a tag to the contact | | | Action (API Call) | Calls an external URL you control, with a configurable method, headers, body, and query/path parameters | Can be tested live from the panel; the response can be mapped into a contact's custom field | | Wait | Pauses the flow for that contact until a condition is met, then continues | Three variants: Duration, Answer, Message read (see dedicated section below) | | Condition | Branches the flow into two paths ("Yes"/"No") based on a check on the contact | See dedicated section below | | AI assistant | Hands the conversation to Simio's connected AI assistant (GAIA) | See dedicated section below | | Request phone number | Asks a contact who only has a WhatsApp identity (no phone number) to share it | Not addable from the toolbar; only ever appears automatically (see dedicated section below) | ### The Action step's two independent pickers The Action step is added from a single toolbar button and defaults to an opt-in Consent step. Its panel offers configuration through **two separate pickers**, not one combined menu: * If the step is currently a Consent step, its panel shows a two-option picker: **Opt-in** / **Opt-out**. * If the step is currently a Tag or API Call step, its panel shows a different two-option picker: **Add tag** / **API Call**. Switching between the Consent pair and the Tag/API Call pair is not available from within the panel today; changing an existing step from, say, Opt-in to Add tag requires deleting it and adding a fresh Action step instead. ### Content type switch on a Message step A Message step can be switched between three content types directly from its panel: * **Text & Media**: free text with an optional image or video. * **List message**: a selectable list of options shown to the contact (a "survey", see the Buttons and branching section below). * **Template**: converts the step into a full WhatsApp template message, keeping its position and connections. ### Surveys / list messages A "survey" is simply a Message step displaying a selectable list instead of free text. There is no separate survey feature or route; it is a display mode of the Message step. Each list option can be individually connected to a different next step, letting the flow branch on which option the contact picked. ## Buttons and branching Message and Template steps can carry buttons. Four button types exist: | Button type | Behavior | | - | - | | Reply button | A quick-reply chip. Tapping it routes the contact down whichever path is connected to that specific button. | | URL button | Opens a link. Clicks are tracked for analytics; tapping it does not automatically advance the contact to a connected next step. | | Flow button | Launches an embedded WhatsApp Flow (a native in-chat form/experience). | | Phone button | Lets the contact call a phone number directly from the message. | Every individual button on a step gets its own outgoing connection point, so different buttons on the same message can lead to entirely different next steps. ## Carousel messages (multiple cards) A Template step's category can be a carousel, which presents the contact with several horizontally-swipeable cards in one message, instead of a single body. Each card has its own media, its own body text, and its own set of buttons. Every card's buttons behave exactly like a flat message's buttons for branching purposes: a Reply button on card 2 can lead to a different next step than a Reply button on card 1. A carousel card's URL button is read-only inside the normal editing panel; its destination is fixed to whatever was configured when the underlying template was created or approved. If that destination still contains an unresolved placeholder, sending a real message with it isn't possible until it's resolved; the only place to manually supply a concrete destination for testing purposes is the "Send a test" screen (see below), which requires a real value for every such button before it allows the test to be sent. ## The Wait step in detail A Wait step pauses the flow for an individual contact until a specific condition is met, then continues to whatever is connected next. Three variants: | Variant | Label shown | Behavior | | - | - | - | | Duration | "Wait for a set duration" | Pauses for a configured number of days, hours, and minutes, then resumes automatically. | | Answer | "Wait for a reply message" | Pauses until the contact sends any reply. Can optionally store the contact's raw reply text into a chosen contact field. | | Message read | "Wait until the message is read" | Pauses until the previous outbound message is confirmed read by the contact. Does not work if the contact has disabled read receipts on their side, since no read confirmation will ever arrive. | ## The Condition step in detail A Condition step evaluates one check on the contact and routes to one of two outgoing paths, labeled **Yes** and **No**. Supported checks: | Check | What it evaluates | | - | - | | Tags | Whether the contact currently has a specific tag | | Optin status | Whether the contact is currently opted in or opted out | | Contact was created | Whether the contact record was created within a given time window (days/hours/minutes ago) | | Random split | A random percentage chance, useful for A/B-style branching (for example, 30% Yes / 70% No) | Once traffic has flowed through a Condition step, its canvas card shows a live running count and percentage split of how many contacts took each branch. ## The AI assistant step (GAIA) GAIA is Simio's connected AI assistant capability. It is configured once per company (company context plus one or more data sources), from the company's AI connector settings, separate from any individual flow. ### What the step does When a contact's flow reaches an AI assistant step, Simio hands GAIA the contact's most recent inbound message along with: * **Assistant context**: instructions specific to this step, set in the step's panel. * **Answer style**: tone/style guidance for the reply, also set in the step's panel. GAIA drafts a reply using the company-wide context/data sources plus this step's own instructions, and the reply is sent to the contact automatically once ready. ### Two outcomes * **Answered**: GAIA successfully returned a reply in time; the reply was sent, and the flow continues down this path. * **Timeout**: GAIA did not respond in time (or the initial call to GAIA failed); the flow continues down this path instead, without a message having been sent for this step. ### Availability gate The AI assistant step cannot be added, and cannot be dragged onto the canvas, until the company's AI connector is fully configured (company context and at least one data source both set). Until then, the toolbar button and the step picker both show it as disabled, with a link to go configure it. ## The Request phone number step Some contacts message a business through WhatsApp using only a WhatsApp identity, without a phone number available in the message Simio receives (for example, when they message through a username rather than sharing their number). The Request phone number step asks such a contact, with a single tap, to share their phone number via WhatsApp's native "share contact info" prompt. Key facts: * **Not addable from the toolbar or step picker**, in any of the three surfaces. It only ever appears on the canvas automatically. * **Auto-created exactly once**, and only for chatbots created with the "No phone number" trigger type (see [Chatbots](/simio/platform/chatbots)): it is wired in immediately after the trigger the moment such a chatbot is created. * Once present, it remains fully editable like any other step. * If the contact already has a phone number on file, this step is skipped with no message sent. If the contact has neither a phone number nor a WhatsApp identifier to send to, nothing happens either. * The step is a dead end on the canvas: once the request message is sent, the flow does not continue to a connected next step through the normal path. If the contact goes on to share their number, the conversation simply continues normally from there; it does not automatically resume into a "next step" on this same flow, except in the one deferred-resume scenario described under "No phone number" chatbots. * The prompt button's label ("Share contact info" or similar) is controlled by WhatsApp itself and cannot be customized. **Known limitation**: the message body you type into this step's panel does not currently get saved. Whatever text is configured, the message that actually goes out always uses Simio's fixed default wording ("Please share your phone number so we can reach you."). ## The Automations list The **Automations** entry in the left sidebar opens a full-page list of every automation on the company, with a left-hand filter rail and a table on the right. ### Left filter rail Three status filters, each with a live count: * **All automations** (default) * **Drafts** * **Active** * **Turned off** The current filter is highlighted; clicking another switches the table immediately. ### Toolbar * **`N automations`** live count on the left, matching the current filter. * **Search by name...** free-text input to filter the visible rows by automation name. * **New automation** primary button on the right, opens the creation slide-over (see below). ### Table columns | Column | Content | | - | - | | Channel | WhatsApp icon plus the connected phone account (for example, `Alcmeon preprod 33759623720`); filterable via the funnel icon in the header. | | Name | Automation name; blank for automations that were never renamed. | | Trigger Type | `API` or `Optin confirmation`; filterable via the funnel icon in the header. | | Status | Colored pill: green `ACTIVE`, gray `DRAFT`, yellow `TURNED OFF`. | | Phone Prefix | Country restriction (for example, `All phone indicators` for no restriction); filterable via the funnel icon in the header. | | Updated | Date and time of the last save, in the account's locale (for example, `17 sept. 26 11:49:17`). | | Actions | Per-row icon buttons: open the **Scenario**, open the **Details** (gear), open the **Results** (line chart), and **Delete** (trash). | Pagination controls at the bottom show the current page and total (for example, `1 / 1`) with previous/next arrows. ## Creating a new automation Clicking **New automation** opens a right-side slide-over titled **New automation**, with two sections and a two-button footer. ### General * **Channel**: dropdown of connected WhatsApp phone accounts, defaulting to the first one (for example, `Alcmeon preprod (33759623…)`). Shown with the WhatsApp icon. * **Automation name**: required text field, used as the internal label in listings, analytics, and the header. ### Trigger for this automation Two selectable cards, exactly one is active at a time: * **Optin confirmation**: *"Flow starts when a customer has optin for the first time"*. * **API**: *"Flow starts when an API request is made"*. The selected card gets a blue outline. ### Country code prefix Dropdown defaulting to **Any country**. Opening it reveals a **Search country or code...** field and a scrollable list starting with **Any country** followed by countries with their flag, ISO code, and dial code (for example, `FR +33 France`, `DE +49 Germany`, `IT +39 Italy`, `ES +34 Spain`, `GB +44 United Kingdom`). Typing filters the list live. Only contacts whose phone number starts with the selected prefix will receive this automation. Contacts with a different prefix are routed to the automation matching their own country code, or to an automation with no prefix set (catch-all). Leave as **Any country** to catch all contacts not matched by a more specific automation. ### Footer * **Create automation**: primary button, disabled until Channel, Automation name, and Trigger are set. Creates the automation as a Draft and opens its editor on the Scenario tab. * **Cancel**: dismisses the slide-over without creating anything. A close (**×**) button at the top-right of the slide-over also cancels. ## Automation details ### What an automation is An automation is a flow triggered automatically by an event rather than by a manual send or an inbound chat message. It uses the exact same editor as campaigns, including the requirement that the flow starts from a real, approved Template step (the same "anchor" concept campaigns use); a non-editable Trigger card is shown alongside it on the canvas, summarizing what fires the flow. ### Trigger types | Trigger type | Fires when | | - | - | | Optin confirmation | A contact opts in to marketing messages for the first time (for example, via an Opt-in Action step anywhere, in any chatbot, automation, or campaign flow) | | API | An external system calls Simio's automation-sending API | ### Optin confirmation details An Optin confirmation automation fires the first time a contact opts in to marketing messages on this WhatsApp number, sending the WhatsApp template wired into its scenario as the welcome message. #### The scenario canvas The Scenario tab shows a non-editable **Optin confirmation** card ("Flow starts when a customer has optin for the first time") wired directly into an approved Template step. In a typical setup the template is a welcome message (for example, `Bienvenue`) carrying an approved URL button (for example, `Support`). From there the flow continues like any other scenario. #### The Details tab Set on the Details tab, under **General** and **Trigger for this automation**: * **Channel**: the connected WhatsApp phone number this automation runs on (for example, `Alcmeon preprod (33759623…)`). * **Automation name**: internal label shown in listings and analytics (required). * **Trigger for this automation**: two-card picker with **Optin confirmation** ("Flow starts when a customer has optin for the first time") and **API** ("Flow starts when an API request is made"). The currently selected card is highlighted. * **Country code prefix**: dropdown defaulting to **Any country**. Only contacts whose phone number starts with the selected country code will receive this automation. Contacts with a different prefix are routed to the automation matching their own country code, or to an automation with no prefix set (catch-all). Leave empty to catch all contacts not matched by a more specific automation. #### The Automation trigger panel Clicking the **Optin confirmation** card on the canvas opens a right-side **Automation trigger** panel: * Header text: *"The flow will start after a specific event. Once the event happens, the WhatsApp template next to it will be sent."* * **Trigger**: read-only, shows `Optin confirmation`. Below it: *"Change the trigger from this automation's Details tab. To run more than one trigger on this phone number at once, [create a new automation](#) instead."* * **Country code prefix**: read-only, mirrors the Details setting (for example, **All countries**). Helper text: *"Only contacts whose phone number starts with this prefix are accepted by this automation. When set to 'All countries', contacts from any country code are accepted."* A close (**×**) button in the top-right dismisses the panel. #### Uniqueness rules * Only one active, non-API automation may exist per connected phone account and per country-code restriction ("all countries" and "+33 only" are treated as separate slots, so both can be active at once, but two separate "all countries" automations on the same number cannot both be active). * Trying to activate a conflicting automation is blocked with an error rather than silently deactivating the other one (this differs from the chatbot conflict rule, which auto-deactivates). #### The top-right toolbar (active automation) While an Optin confirmation automation is **Active**, the top-right toolbar shows an `ACTIVE` pill, a **Send a test** button, a **Save** button, and a **⋯** menu with **Deactivate** and **Duplicate scenario** (same as API automations). ### API trigger details An automation using the API trigger only fires when an external system calls Simio's automation-sending endpoint directly, supplying the automation's ID and a list of contacts (by phone number). #### The scenario canvas The Scenario tab shows a non-editable **API** card labeled "Flow starts when an API request is made", wired into the first step of the flow (typically an approved Template). From there the flow continues like any other scenario (Template → Wait → Message, and so on). #### The Details tab Set on the Details tab: * **Channel**: the connected WhatsApp phone number this automation runs on. * **Automation name**: internal label shown in listings and analytics. * **Trigger for this automation**: a two-card picker, **Optin confirmation** or **API**. * **Country code prefix**: dropdown defaulting to **Any country**. Only contacts whose phone number starts with the selected prefix will receive this automation. Contacts with a different prefix are routed to the automation matching their own country code, or to an automation with no prefix set (catch-all). Leave empty to catch all contacts not matched by a more specific automation. #### The Automation trigger panel (API configuration) Clicking the API card on the canvas opens a right-side **Automation trigger** panel with everything an external system needs to call the automation: * **Trigger**: read-only, shows `API`. To change it, switch to the Details tab; to run more than one trigger on the same phone number at once, create a new automation. * **Country code prefix**: mirrors the Details setting (for example, **All countries**). * **Destination URL**: the exact URL to POST to (for example, `https://getsimio.app/api/automations/send`). * **Key**: the required HTTP header name (`SIMIO-API-KEY`). * **Value**: the automation's own secret key, sent as the header value. Shown masked with a show/hide eye toggle. * **Variables**: the list of declared trigger variables (see below), with an inline **Variable name (e.g. prenom)** input, an **Add variable** button, a per-variable rename (pencil) and delete (trash) control, and a `N/20 variables` counter. * **JSON body**: a live-updating example payload showing the exact shape the caller must send, including `automation_id`, and a `contacts` array where each contact has a `phone` and a `customProperties` object keyed by the variables you declared. The helper text below reads: *"If a call is received without one of these variables, Simio rejects it with a missing parameter error and does not send the message."* Example body for an automation with `automation_id: 341` and one declared variable named `test`: ```json JSON body theme={null} { "automation_id": 341, "contacts": [ { "phone": "33601020304", "customProperties": { "test": "value" } } ] } ``` #### Trigger variables An API-triggered automation can declare named trigger variables (for example, `prenom`, `order_number`, `test`). When the external caller fires the automation, it must supply a value for every declared variable, under `customProperties`, for each contact in the `contacts` array. If any required variable is missing, Simio rejects the call with a missing parameter error before anything is sent. Up to **20** trigger variables can be declared per automation. Once declared, a Message step's header (image or video only, not document), body, or list header can each be individually switched to pull from a trigger variable instead of static text. In the editor this shows as the variable's name as a placeholder (for example, `{{ test }}` on the canvas), since the real value is only known per contact at send time. If a contact is somehow sent through the flow without a value for a currently-required trigger variable (for example, they were triggered before that variable existed), that specific message is not sent; it is recorded as a failed message rather than being sent with blank content. #### The Results tab Once an API automation has run, its **Results** tab shows: * **Performance · Last 30 days**: eight metric cards, each with a value, a `-N% vs. prev. period` delta, and a small sparkline. The cards are **Messages sent**, **Delivered**, **Open rate** (with the underlying open count in parentheses), **Click rate**, **WhatsApp cost** (in the account currency, for example `€0.07`), **Failed rate**, **Total opt-ins**, and **Opt-out rate**. * **Funnel**: horizontal bars for **Sent**, **Delivered**, **Opened**, **Clicked**, and **Failed**, each with the absolute count and percentage of sent. * **Deliverability**: five ring gauges for **Sent**, **Delivered**, **Opened**, **Clicked**, and **Failed**, each showing the percentage and an `X / Y` ratio underneath. A refresh icon in the top-right recomputes the numbers on demand. #### The top-right toolbar (active automation) While an API automation is **Active**, the top-right toolbar shows an `ACTIVE` pill, a **Send a test** button, a **Save** button, and a **⋯** menu with: * **Deactivate**: turns the automation off (moves it to Turned off). * **Duplicate scenario**: clones the scenario into a new draft automation. ### Editing an automation after creation Trigger type, country-code restriction, channel, and connected account can all be changed later from the automation's Details tab, not just set once at creation. The conflict rule above is re-checked whenever any of these change. ### Status lifecycle | Status | Meaning | | - | - | | Draft | Turned off, and its message content is not fully configured yet | | Active | Turned on and will fire | | Turned off | Turned off, but its message content is fully configured | Automations are switched on and off with a single toggle, not a schedule/send flow. Turning one on is blocked with an explanation if its flow doesn't yet have a configured WhatsApp template message (the required anchor step). ## Testing before going live ### Send a test Before turning an automation on (or scheduling a campaign), the current flow can be sent as a live test to one or more real phone numbers, from the editor itself. This becomes available once a Template step is selected and there are no unsaved changes. * **Phone numbers**: typed directly, or picked from clickable chips built from your own past test numbers and from teammates' phone numbers on file. * **Automation-only extra fields**: optional overrides for image, video, and link-button destinations used just for this test, plus a free-form JSON area to supply custom values, useful for testing trigger variables without needing the external system that would normally supply them. * **Carousel destination URLs**: if the template being tested has any carousel link button whose destination still contains an unresolved placeholder, the test screen requires a real value for every one of those before it allows the test to be sent. While a test is running, the app shows live delivery-status updates (sent, delivered, read, failed) for a short window after sending, so you get immediate feedback on whether the test actually arrived; if nothing comes back within about 10 seconds, it's shown as timed out. Test sends never affect the automation's or campaign's real trigger, status, or counters. ### API Call (webhook) step testing An API Call step's panel includes its own live test tool: pick a phone number, send a real test call to the configured URL, and see the raw response status and body directly in the editor, without needing to leave the flow or wait for a real contact to reach that step. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.