Start an Automation from a voice sequence

Warning: Voice sequences are in preview. Steps, entry data, and the sequence definition format can change in ways that break existing sequences and API requests.

Use Send Automation Event to start an Automation while the call continues. For example, when a caller presses 1 to request a callback, send their number to an Automation that schedules the call back. The call does not wait for the Automation's run.

The step is in preview. Automations is in early access, and your workspace permissions determine what you can configure.

Prepare the automation

1. Create an automation with Event from your application as its trigger.
2. Set Event name, for example callback_requested.
3. Define Event fields for the values the call will send, such as string fields named caller and digits.
4. Publish the automation.

In the automation, trigger.data is the event envelope, and trigger.data.data is the data you mapped, so the caller's number is at trigger.data.data.caller. Connect your application to an automation explains the envelope, event names, event fields, and runs.

Add the step

1. Add Send Automation Event on the path that should start the automation, such as the keypad choice for a callback.
2. Under Automation event, choose the automation, then choose its event. The list shows the events that the automation's published version can start.
3. Under Data, fill in the event's fields. Each field can be a fixed value, a value from earlier call data, or, for text fields, text that mixes both. If the event has no event fields, add your own names and values.
4. Connect the Success and Failure outcomes.

The data you map is the event's entire data. Bird adds no fields, so map every value the automation reads. The caller's number is at execution.call.orig.address and can be absent, so guard it. The call ID is at execution.call.id, and keypad digits are at steps.<gather step>.output.digits. The sequence ID is not available as call data; enter it as a fixed value when the automation needs it.

Choosing an automation requires permission to read Automations. Without it, enter the automation ID, event name, and data yourself.

Handle the outcomes

An unconnected failure ends the run as failed. Connect it, even to the same step as success, when the call should continue regardless.

Neither outcome reports what the automation did. A paused, unpublished, or deleted automation, an event name it does not use, or data that does not match its event fields still takes success. Check the automation's Runs tab to see whether a run started.

Check before publishing

Publishing the sequence warns, without blocking, when the chosen automation is missing, paused, or not published, or when its published version cannot start a run from the chosen event. A paused automation or an event used only by a wait or cancellation rule still gets the warning, even though the event can continue or cancel existing runs. If you cannot read Automations, the warning says the step was not checked.

Delivery

• The step runs only after the call is answered. An unanswered or abandoned call sends nothing.
• The event usually reaches the automation within about a second of the step.
• Each visit to the step sends one event, and repeated deliveries of it are discarded. Duplicate protection is bounded, so design the automation to tolerate a rare repeat.
• A Transfer that returns to the step sends a new event.
• Every event goes to the automation's published version, including from test calls. A test call is a real call, and the automation can perform real actions.
• Preview sends no event. Choose a success or failure sample for the step.

Use the definition

In a sequence definition, the step is an automation.send_event node:

{
  "id": "notify",
  "type": "automation.send_event",
  "type_version": 1,
  "config": {},
  "input": {
    "automation_id": "atm_01jz8x3v4w5y6z7a8b9c0d1e2f",
    "event": "callback_requested",
    "data": {
      "caller": {
        "$expr": "execution.call.orig != null && has(execution.call.orig.address) ? execution.call.orig.address : ''"
      },
      "digits": { "$expr": "steps.menu.output.digits" }
    }
  },
  "connections": {
    "success": { "node_id": "confirm", "port": "input" },
    "failure": { "node_id": "confirm", "port": "input" }
  }
}

Next steps

• Use call data in the mapping.
• Configure keypad menus for keypad choices.
• Connect your application to an automation.