# Automations

Automations turns business events into phone calls and customer responses. When something happens
in your system, such as a delivery being scheduled or an appointment coming up, you send Signals one
request and Signals runs the call: it dials from a number you own, plays your message in the voice
you chose, asks a keypad question and returns the customer's answer to your software as an outcome
you defined. You configure the workflow once in the console instead of building call flows from
telephony primitives.

Teams use Automations to schedule and confirm deliveries, remind patients of appointments and
confirm attendance, follow up on customer onboarding and status changes, and deliver operational
notifications by phone. It runs on the same infrastructure as
[Programmable Voice](/programmable-voice/overview), so when you need full control over each call you
can move to the Calls API and [OneML](/programmable-voice/oneml/overview) without changing numbers
or accounts.

## The pieces

| Piece | What it is |
| --- | --- |
| Automation | The workflow you build in the console. Its id starts with `sig_`. It holds the originating number, the message and its voice, one keypad question with up to four options, the retry rule and the rules for when not to call. |
| Run | One customer to call, including any retries the automation allows. Every run has a status, and once it finishes, an outcome. |
| Trigger | The authenticated `POST` request your system sends to start a run for one customer. An `event_id` on the trigger makes retries safe. A spreadsheet upload in the console starts runs in bulk. |
| Outcome value | The short word, such as `confirmed`, that you attach to each keypad option. It is what your system receives when the customer presses that key. |
| Webhook events | The `automation.call.*` events Signals sends to your [webhook endpoint](/api/signals/webhooks) as a run moves from dialling to completion. |

## How a run works

1. Your system sends a trigger for one customer, or you upload a spreadsheet of up to 5,000
   customers in the console.
2. Before answering, Signals checks the automation's suppression rules: the automation is on, the
   number is not on the do-not-call list, it has not been called today, and it is inside calling
   hours. A run stopped by a rule finishes as `suppressed`; a run that arrives outside calling hours
   may wait for them. The response already shows that result.
3. Signals places the call from the originating number, reads the message with your variables
   filled in and asks the keypad question. If nobody answers, the retry rule decides when to try
   again.
4. When the customer presses a key, Signals maps it to its outcome value and sends
   `automation.call.completed` to your webhook. The run also appears on the automation's **Runs**
   tab with its status, outcome and the key pressed, linked to its call in call history.

For example, a clinic's automation calls from `+2342013300117` with the message "Hello `{{name}}`,
your appointment is confirmed for Friday at `{{time}}`." and asks the patient to press 1 to keep the
appointment or 2 to speak to the front desk. The clinic's system triggers one run per booking with
`event_id` set to the booking reference, and when the patient presses 1 the webhook receives
`automation.call.completed` with `pressed.outcome_value` set to `confirmed`.

## Next steps

| Page | Description |
| --- | --- |
| [Building an automation](/automations/building-an-automation) | The six builder steps, message variables, keypad options, voices and limits. |
| [Triggering calls](/automations/triggering-calls) | The trigger request, idempotency with `event_id`, responses and errors, suppression, run status and cancelling a run. |
| [Webhook events](/automations/webhook-events) | The four `automation.call.*` events and the fields they carry. |
| [Authentication](/getting-started/authentication) | Create the organization API key that triggers need. |
| [Programmable Voice overview](/programmable-voice/overview) | Control each call yourself when you outgrow Automations. |
