Automations

How the business builds a workflow on your events, and what it can do.

An automation is a workflow the business builds in the dashboard - Automation → New workflow - with one trigger, optional conditions, and a chain of actions. Your integration reaches it through the External API event trigger and POST /events (Business events). This page is for the person building the workflow and the developer sending the events, so the two agree on names and fields.

The shape of a workflow

trigger  →  condition?  →  action  →  action  →  wait?  →  action  →  end

Every workflow has exactly one trigger. Conditions filter which runs continue; a branch can send different contacts down different paths; a wait parks the run for minutes, hours or days; actions do the work. A workflow runs only once it is published - a draft never fires.

Triggers

For the External API event trigger the only setting is Event name, matched exactly against what your system sends. Keep names lowercase with dots: order.paid, order.shipped, cart.abandoned, appointment.booked, invoice.overdue.

What the workflow can read

Inside the workflow every text field - a message body, a note, a task title, a webhook body - accepts placeholders in double braces. For an External API event these are available:

An unknown placeholder renders as an empty string - never as literal braces in a customer's message - so agree the data keys with the business before they build on them.

Conditions

A condition keeps the run going only when it holds; otherwise the run ends at that step, recorded as such.

Actions

A worked example

The store from Integrating your system sends order.shipped with data: { order_id, courier, tracking_url, eta }. The business builds:

1. Trigger - External API event, name order.shipped.
2. Condition - Contact can be messaged.
3. Send WhatsApp message - template order_shipped, variables {{contact.first_name}}, {{data.order_id}}, {{data.courier}}, {{data.eta}}.
4. Add tag - shipped.
5. Wait - 3 days.
6. Send WhatsApp message - template delivery_check, variable {{data.order_id}}.
7. Create task - "Check order {{data.order_id}} arrived", due in 1 day, for the support team.

Your store then only ever sends the event. The messages go out under the business's number, the message.* webhooks report each one back to you with the message's external_reference empty and its conversation_id set, and every run is visible step by step under Automation → Runs - the input, each action's outcome, any error - so "why did my customer get this?" is answered by reading, not guessing.

Running twice

The same event with the same dedupe_key (or the same Idempotency-Key) does not start a second run for the same contact. Sending order.shipped twice for order 10025 is safe. Two different events for the same order - order.paid then order.shipped - start two runs, as they should.

Chatbots

A workflow of kind Chatbot holds a conversation instead of reacting once. It starts from Message received or Conversation started and can pause until the customer answers:

{{reply}} is the latest answer and {{var.<name>}} any stored one, in every text field. The The reply condition branches on what the customer said (equals, contains, starts_with, regex, is_number, is_email, in_options).

One bot talks to a conversation at a time. An agent always wins: the moment a person replies in the inbox or assigns the conversation to someone, the bot stops and stays quiet on that thread for its pause window (24 hours unless the bot says otherwise). Every bot run is readable question by question under Automation → Runs, and your integration hears bot.started, bot.handoff (with the answers the bot collected) and bot.completed through Webhooks.

Auto-replies

Without building anything, each connected number, page or mailbox can send a welcome (a conversation's first message, or once a day), an away message (outside the business hours set under Settings → Business hours) and keyword answers; chat channels also a delay notice when nobody has answered within a few minutes. At most one auto-reply answers any customer message, none while a chatbot is talking, and no welcome or away once a person has replied. Each is an ordinary outbound message: it appears in the thread and in message.* webhooks like any other.

Where to look when nothing happens

• workflows_matched was 0 - no published workflow listens for that exact name. Check spelling and that the workflow is published, not a draft.
• The run ended at a condition - open it under Automation → Runs; the step says which condition failed and what it saw.
• A send failed - the run's step carries the provider's error (a template not approved, a customer outside the 24-hour window with a text action instead of a template), and message.failed reached your webhook.