Five flow recipes

Five working flow definitions you can paste into the Flows API today: a welcome series, an appointment reminder, support triage, survey collection, and order updates. Each recipe covers the trigger to pick, the full definition JSON, and what a run does. The Flows overview covers trigger types, node semantics, and edge handles; this page assumes those concepts and goes straight to definitions. Build your first automation flow walks one flow design end to end — this page gives you the other five.

1. Choose the trigger

Every flow starts from exactly one trigger, declared top-level as trigger_type.

Trigger	Use it for	API shape
Business Event (`event`)	React to a platform event — a new contact, an inbound message, a completed call	`"trigger_type": "event"` with `definition.trigger.event` naming the event (`contact.created`, an inbound-message event, `call.completed`, …)
Schedule (`schedule`)	Batch work on a cadence — reminders, digests, re-checks	`"trigger_type": "schedule"` plus top-level `cron_expr` (5-field cron) and optional `cron_tz` (IANA timezone, defaults to UTC). A missing or unparseable `cron_expr` is rejected with a 422.
Webhook (`webhook`)	An external system (your storefront, booking app, helpdesk) starts the flow	`"trigger_type": "webhook"`; the caller POSTs free-form JSON to the flow’s webhook URL and every posted key lands in the run context as a flat variable
Manual (`manual`)	Start runs from your own backend via the Start Flow / Execute call, or the dashboard Run action	`"trigger_type": "manual"`; call `POST /flows/:id/start` with `contact_id` and a `context` object

Two golden rules before the recipes:

Gate business-event triggers. contact.created fires on API imports and CSV uploads too, not just your signup form. Put a Condition first, or a 50,000-row import tags along behind your welcome SMS.
Variables are flat. Write {{first_name}}, never {{contact.first_name}}. A placeholder for a missing key renders as an empty string — so a webhook flow referencing a key the caller didn’t post sends an empty body. Validate with Test mode before publishing.

2. Recipe 1 — welcome series

Shape: contact created → gate → welcome SMS → wait 24h → follow-up email. New contacts get an SMS immediately and an email the next day. The condition gate keeps imports and API batches from entering the series.

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "trigger_type": "event",
    "definition": {
      "trigger": { "type": "event", "event": "contact.created" },
      "nodes": [
        {
          "id": "gate_source",
          "type": "condition",
          "data": { "field": "source", "operator": "equals", "value": "signup_form" }
        },
        {
          "id": "welcome_sms",
          "type": "sendSms",
          "data": {
            "to": "{{phone}}",
            "body": "Welcome to Acme, {{first_name}}! Reply HELP for help, STOP to opt out."
          }
        },
        { "id": "wait_24h", "type": "delay", "data": { "amount": 24, "unit": "hours" } },
        {
          "id": "followup_email",
          "type": "sendEmail",
          "data": {
            "to": "{{email}}",
            "subject": "Getting started with Acme",
            "body": "Hi {{first_name}}, here are three things worth doing first."
          }
        }
      ],
      "edges": [
        { "source": "gate_source", "sourceHandle": "yes", "target": "welcome_sms" },
        { "source": "welcome_sms", "target": "wait_24h" },
        { "source": "wait_24h", "target": "followup_email" }
      ]
    }
  }'

Expected behavior. Each contact.created event starts one run. Runs where source is not signup_form exit at the gate (no has no target, so the run ends cleanly). The 24-hour delay parks the run in waiting status and resumes automatically — long waits never send early. The same series is available in the dashboard’s New Flow template list under Welcome SMS; the API route below adds the import gate and the email step.

3. Recipe 2 — appointment reminder

Shape: booking webhook → confirm-or-reschedule at T-24h → final ping at T-1h. Your booking system POSTs when an appointment is scheduled; the flow fires the webhook into wait_24h (a T-24 reminder, booked appointments get a confirmation request) and then the T-1 ping. Booking-time context carries appointment_at — the delay offsets are scheduled against it. The two wait nodes are date-relative, so a booking made Monday for Wednesday lands the confirmation message Tuesday, not two days after booking.

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminder",
    "trigger_type": "webhook",
    "definition": {
      "trigger": { "type": "webhook", "event": "appointment.booked" },
      "nodes": [
        {
          "id": "check_optin",
          "type": "condition",
          "data": { "field": "sms_opt_in", "operator": "equals", "value": "true" }
        },
        {
          "id": "wait_t24",
          "type": "delay",
          "data": { "amount": -24, "unit": "hours", "relativeTo": "appointment_at" }
        },
        {
          "id": "reminder_t24",
          "type": "sendSms",
          "data": {
            "to": "{{phone}}",
            "body": "Hi {{first_name}} — your appointment is tomorrow at {{appointment_time}}. Reply C to confirm, or {{reschedule_link}} to change."
          }
        },
        {
          "id": "wait_t1",
          "type": "delay",
          "data": { "amount": -1, "unit": "hours", "relativeTo": "appointment_at" }
        },
        {
          "id": "reminder_t1",
          "type": "sendSms",
          "data": {
            "to": "{{phone}}",
            "body": "See you in an hour at {{location}}. Running late? Call {{office_phone}}."
          }
        }
      ],
      "edges": [
        { "source": "check_optin", "sourceHandle": "yes", "target": "wait_t24" },
        { "source": "wait_t24", "target": "reminder_t24" },
        { "source": "reminder_t24", "target": "wait_t1" },
        { "source": "wait_t1", "target": "reminder_t1" }
      ]
    }
  }'

Expected behavior. Your booking system POSTs

{ "appointment_at", "appointment_time", "first_name", "phone", "location", "reschedule_link", "sms_opt_in": "true", ... }

to the flow’s webhook URL. Contacts without opt-in exit at the gate. The T-24 message carries the confirm/reschedule call-to-action; the T-1 message is a bare logistics ping on the channel the tenant’s inbox monitors. The dashboard template Appointment Reminder (24h + 1h) is the same skeleton — clone it from New Flow if you’d rather click than curl.

4. Recipe 3 — support triage

Shape: inbound message → classify intent → AI agent answers → complaints escalate to a human. Inbound SMS (or WhatsApp) hits an inbound-routing rule that starts the flow. An AI Classify node routes by intent; the agent handles routine questions; complaints fan out to your team’s escalation webhook; anything unrecognized ends for manual pickup.

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support triage",
    "trigger_type": "event",
    "definition": {
      "trigger": { "type": "event", "event": "message.inbound" },
      "nodes": [
        {
          "id": "classify",
          "type": "aiClassify",
          "data": { "intents": "question,billing,complaint,other" }
        },
        {
          "id": "support_agent",
          "type": "aiAgent",
          "data": { "agent_id": "agent_support_01" }
        },
        {
          "id": "billing_agent",
          "type": "aiAgent",
          "data": { "agent_id": "agent_billing_01" }
        },
        {
          "id": "escalate",
          "type": "webhook",
          "data": {
            "url": "https://your-app.example.com/hooks/support-escalation",
            "method": "POST"
          }
        }
      ],
      "edges": [
        { "source": "classify", "sourceHandle": "question", "target": "support_agent" },
        { "source": "classify", "sourceHandle": "billing", "target": "billing_agent" },
        { "source": "classify", "sourceHandle": "complaint", "target": "escalate" }
      ]
    }
  }'

Expected behavior. The classifier routes on the matching intent edge; yes/no handles exist as fallbacks — other and unrecognized classifications end the run when no edge carries them. The webhook node’s body carries execution_id and the sanitized run context, so your helpdesk gets the message text and intent. Webhook URLs must be public; private or internal addresses are rejected. Provision the two agents first — agent_id pointing at a non-existent agent fails the run at that node (with an entry in the step trace), not a graceful fallback. Routing start: wire the inbound-routing rule to this flow (see Where Flows Fire).

5. Recipe 4 — survey collection

Shape: post-call event → wait → send the survey → responses arrive at your webhook. After a call completes, wait a day, then send the NPS or CSAT survey over SMS. Recipients answer on the hosted page via the single-use token link in the message; each response fires a webhook event you capture at your endpoint.

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Post-call NPS survey",
    "trigger_type": "event",
    "definition": {
      "trigger": { "type": "event", "event": "call.completed" },
      "nodes": [
        {
          "id": "check_consent",
          "type": "condition",
          "data": { "field": "survey_opt_out", "operator": "not_equals", "value": "true" }
        },
        { "id": "wait_24h", "type": "delay", "data": { "amount": 24, "unit": "hours" } },
        {
          "id": "send_nps",
          "type": "sendSurvey",
          "data": {
            "survey_id": "survey_nps_quarterly",
            "channel": "sms",
            "contact_id": "{{contact_id}}"
          }
        }
      ],
      "edges": [
        { "source": "check_consent", "sourceHandle": "yes", "target": "wait_24h" },
        { "source": "wait_24h", "target": "send_nps" }
      ]
    }
  }'

Expected behavior. survey_id references a survey you created in the Surveys API; channel accepts sms, whatsapp, email, viber, rcs, or push. A missing or unsupported value skips the node with a skipped output in the step trace — check it in Test mode, because a typo’d channel does not fail the run. Recipients receive the single-use survey link; responses land as survey.nps.response_recorded and survey.csat.response_recorded webhook events, and a low score additionally fires survey.response.detractor. Subscribe to those events (see Webhook Events) to close the loop — page a CSM on a detractor, for example.

6. Recipe 5 — order updates

Shape: commerce webhook → SMS + email fan-out. Your commerce layer (Shopify, a custom storefront, an OMS) POSTs order events — confirmation, shipped, delivered, exception. The flow fans out on both channels. Draw a branch per event stage by chaining a condition on the event key, or run one flow per stage with its own trigger filter.

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order delivered notification",
    "trigger_type": "webhook",
    "definition": {
      "trigger": { "type": "webhook", "event": "order.delivered" },
      "nodes": [
        {
          "id": "delivered_sms",
          "type": "sendSms",
          "data": {
            "to": "{{phone}}",
            "body": "Order {{order_id}} was delivered. Questions? Just reply to this text."
          }
        },
        {
          "id": "has_email",
          "type": "condition",
          "data": { "field": "email", "operator": "not_equals", "value": "" }
        },
        {
          "id": "delivered_email",
          "type": "sendEmail",
          "data": {
            "to": "{{email}}",
            "subject": "Delivered: order {{order_id}}",
            "body": "Hi {{first_name}}, order {{order_id}} shows as delivered. Rate your delivery experience: {{review_link}}"
          }
        }
      ],
      "edges": [
        { "source": "delivered_sms", "target": "has_email" },
        { "source": "has_email", "sourceHandle": "yes", "target": "delivered_email" }
      ]
    }
  }'

Expected behavior. The storefront POSTs the order event with flat keys (order_id, first_name, phone, email, tracking_url, review_link); both messages render those values inline. Every contact gets the SMS; the has_email gate skips the email step for phone-only contacts (an empty email resolves to an empty string, so the test is email != ""). When one flow covers several stages, chain conditions on the event key the storefront posts — order.confirmed, order.shipped, order.delivered.

7. Validate before launch

Three tools, in the order to use them: 1. Structural validation. Check the definition parses and has no obvious wiring mistakes before you test behavior:

curl https://api.orbit.devotel.io/api/v1/flows/flow_abc123/validate \
  -H "X-API-Key: dv_live_sk_..."

2. Test mode and the simulator. Click Test in the builder toolbar to walk the flow with sample data and watch the exact branch each node takes. Then, before any schedule or event trigger touches real traffic, dry-run the flow against your real audience size — no contact is enrolled, nothing is sent:

curl -X POST https://api.orbit.devotel.io/api/v1/flows/flow_abc123/simulate \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"audience_size": 10000, "default_country": "US"}'

The response projects the per-step funnel, the channel mix, the projected send cost at your live rates, and a predicted conversion. If the first step drops 90% of the audience, the gate is eating the traffic — fix the trigger filter before publishing. 3. Analytics after launch. Once runs accumulate, read the actual funnel:

curl "https://api.orbit.devotel.io/api/v1/flows/flow_abc123/analytics" \
  -H "X-API-Key: dv_live_sk_..."

GET /flows/:id/analytics returns entered / completed / converted counts and the per-node drop-off funnel; GET /flows/:id/ab-results rolls up any abTest node variants with the leading variant. The simulator’s assumed drop-off converges on this history as runs accumulate, so forecasts get sharper over time. Where to wire webhooks first. A list of every webhook event the platform emits lives at Webhook Events; subscribe at the endpoint in Webhooks and verify the HMAC signature in Webhook Security. For the surveys recipe, the survey-response events are the wire that closes the loop; for failures, flow.execution.failed pages you instead of a silent drop-off.

Next steps

Flows overview — trigger catalog, node taxonomy, edge semantics
Build your first automation flow — the design walkthrough for recipe-style flows
Flow Builder — canvas reference and the template library (New Flow dialog)
Flow Executions — the step-trace reference for debugging runs
Webhook Events — every event you can subscribe to

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Five flow recipes: welcome series, reminders, support triage, surveys, order updates

Five flow recipes

1. Choose the trigger

2. Recipe 1 — welcome series

3. Recipe 2 — appointment reminder

4. Recipe 3 — support triage

5. Recipe 4 — survey collection

6. Recipe 5 — order updates

7. Validate before launch

Next steps

​Five flow recipes

​1. Choose the trigger

​2. Recipe 1 — welcome series

​3. Recipe 2 — appointment reminder

​4. Recipe 3 — support triage

​5. Recipe 4 — survey collection

​6. Recipe 5 — order updates

​7. Validate before launch

​Next steps

Five flow recipes

1. Choose the trigger

2. Recipe 1 — welcome series

3. Recipe 2 — appointment reminder

4. Recipe 3 — support triage

5. Recipe 4 — survey collection

6. Recipe 5 — order updates

7. Validate before launch

Next steps