# Trigger Outbound Voice AI Calls via API or Workflow

Start outbound calls from a voice agent with the call trigger API or from a workflow, pass customer details, set call windows and retries, and handle errors.

> Source: https://www.robylon.ai/docs/voice/triggering-calls
> Section: Voice

A voice agent places outbound calls when something asks it to. You can trigger calls from your own systems with the call trigger API, or from a Robylon workflow.

The endpoint and a sample payload for each agent are in the voice agent builder under **Set Call Triggers via API**.

## How do I trigger a call with the API?

Send a `POST` request with the agent's ID, the phone number and the customer's details, authenticated with your API key.

```bash
curl -X POST https://api.robylon.ai/voice/agent/test-call/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "phone_number": "+15551234567",
    "variables_info": {
      "customer_name": "Alex",
      "order_id": "10234"
    }
  }'
```

- **Endpoint:** `POST https://api.robylon.ai/voice/agent/test-call/`. Despite the name, this endpoint places real calls. It is shown under **API Endpoint** in the agent. `https://api.robylon.ai/voice/agent/trigger-call/` works the same way.
- **Authentication:** your workspace API key, in an `X-API-Key` header or as `Authorization: Bearer YOUR_API_KEY`. Create keys in **Settings → Data & Developer → API Keys**, see [API keys](https://www.robylon.ai/docs/developers/api-keys).
- **Agent ID:** shown under **Agent ID** in **Set Call Triggers via API**. Use **Copy sample payload** to start from a payload that already lists your agent's variables.

## What can I send in the request?

| Field | Required | What it does |
| --- | --- | --- |
| `agent_id` | Yes | The voice agent to call with. |
| `phone_number` | Yes | The number to call, with country code, for example `+15551234567`. |
| `variables_info` | Yes (can be `{}`) | The customer's details, as variable name and value pairs. These fill the `{variables}` in the prompt and first message. The sample payload lists the variables your agent uses. |
| `call_timing` | No | The window in which retries may be placed: `start` and `end` (each with `hour` and `minute`) and a `timezone` such as `Asia/Kolkata` or `America/New_York`. Add `"queue_requests": true` to turn on retries (see below). If you leave `call_timing` out, the window is 04:00 to 13:30 `Asia/Calcutta`. The first dial is not held to this window. |
| `voice_retry_config` | No | Retries for unanswered calls: `should_retry` (true or false), `max_retries` and `retry_in_minutes`. If you leave it out, your workspace's default retry settings are used. |
| `key_terms` | No | A list of extra words to recognise on this call, such as an unusual product name. |
| `include_variable_key_terms` | No | `true` adds the words in `variables_info` (such as the customer's name) as recognition keywords. Default `false`. |
| `is_test_call` | No | `true` calls with the agent's unpublished draft, `false` with the published version. Default `false`. |
| `user_id` | No | The ID of an existing Robylon contact to attach the call to. If it is missing or invalid, Robylon matches the contact by phone number. |

A full example:

```json
{
  "agent_id": "YOUR_AGENT_ID",
  "phone_number": "+15551234567",
  "variables_info": {
    "customer_name": "Alex",
    "order_id": "10234"
  },
  "call_timing": {
    "start": { "hour": 9, "minute": 0 },
    "end": { "hour": 18, "minute": 0 },
    "timezone": "America/New_York",
    "queue_requests": true
  },
  "voice_retry_config": {
    "should_retry": true,
    "max_retries": 3,
    "retry_in_minutes": 60
  },
  "key_terms": ["Acme"],
  "include_variable_key_terms": false,
  "is_test_call": false
}
```

## How do retries work?

Robylon calls again after a call **fails**, is **not answered** or is **busy**, when both of these are set in the request:

- `voice_retry_config.should_retry` is `true`, and
- `call_timing.queue_requests` is `true`.

Without `queue_requests`, the call is dialled once and not retried. Robylon waits `retry_in_minutes` between attempts.

- `max_retries` is the total number of dials **including the first one**. With `max_retries: 3`, the customer is called at most three times.
- A single request is never dialled more than 15 times, whatever you set.
- A retry that would fall outside the `call_timing` window is moved to the start of the next window.
- A request still waiting for a retry 48 hours after it was created is cancelled.
- Inbound calls are never retried.

## What does the API return?

A successful request returns `200` with:

```json
{ "result": true }
```

This means the call was queued, not that it was answered. The call's outcome appears in Robylon once it ends. Errors return `400` or `401` with an `error` message:

| Status | Error | Cause |
| --- | --- | --- |
| 401 | `API key is required` / `Invalid API key` | The API key is missing or wrong. |
| 400 | `Invalid Agent Id...` | The `agent_id` does not match a voice agent in your workspace. |
| 400 | `Duplicate call received for agent=... number=... within ...s` | The same agent was asked to call the same number again while the first request is still in progress, within 100 seconds. |
| 400 | `Not enough voice seconds to create voice request, upgrade your plan.` | Your workspace has run out of voice minutes. See [Usage](https://www.robylon.ai/docs/account/usage). |
| 400 | Missing field | A required field such as `phone_number` or `variables_info` is missing. |

The API does not return a call ID. To act on the outcome, use [post-call analysis](https://www.robylon.ai/docs/voice/post-call-analysis): extracted values are saved on the call's ticket, and a post-call workflow receives the call's status, transcript, summary and recording. A webhook that posts each call's result to your own URL is available on request, email support@robylon.ai.

## Can I trigger calls in bulk?

There is no bulk endpoint. To call many people:

- Send one API request per person, or
- Use a workflow (below), which runs the voice agent each time its trigger fires.

## How do I trigger calls from a workflow?

Add an AI agent step to a workflow, set **Select Channel** to **Voice**, and choose the agent under **Select Voice AI Agent**. The workflow's trigger decides when calls are made.

In the step:

- Under **Configure the variables used in the voice AI agent**, map each of the agent's variables to data from the trigger or earlier steps.
- Under **Set Retry logic**, switch on **Do you want to retry the calls** and set **No. of times to retry**, **Interval between retries** and **Max time uptill retries**.

Calls started from a workflow follow the agent's **Calling Hour Config**, and retries only happen while **Queue call requests outside calling hours** is on. See [Call settings](https://www.robylon.ai/docs/voice/call-settings#how-do-calling-hours-work).

After each try, the step fills variables such as `{voice_call_status}`, `{voice_call_transcript}`, `{voice_call_duration}`, `{voice_call_summary}`, `{voice_call_count}` and `{voice_call_number}` for later steps.

See [Workflows](https://www.robylon.ai/docs/product/product) and [Triggers](https://www.robylon.ai/docs/product/triggers).