> ## Documentation Index
> Fetch the complete documentation index at: https://brosbots.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API trigger

> Start a voice agent's outbound call from an external system, e.g. n8n, Zapier or your own code.

You place an outbound call with a single POST request carrying your
[API key](../configurations/api-keys) in the `X-API-Key` header. The agent
calls from its own number.

## Request

```bash theme={null}
curl -X POST "https://app.brosbots.com/api/v1/agents/{agent_id}/calls" \
  -H "X-API-Key: bb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+48123456789",
    "initial_context": {
      "user": { "name": "Jan" }
    }
  }'
```

`{agent_id}` is the agent's ID, e.g. `agent_7fK2mQ9xLp3RtV8wYb1N` (in the
agent editor, next to its name), or its number.

| Field | Required | Description |
| - | - | - |
| `phone_number` | yes | The number the agent calls, in E.164 format (`+48...`) |
| `initial_context` | no | A JSON object with data for the agent |

`phone_number` and `initial_context` are **sibling** fields at the top level
of the body. Don't put the number inside `initial_context` - the agent sees
it as `{{initial_context.phone_number}}` anyway.

## Initial Context

`initial_context` is a JSON object with any contextual data the agent
should have access to. You reference it in prompts via **Handle Bars**,
i.e. values wrapped in `{{` and `}}`. For the request above, the caller's
name in prompts is `{{initial_context.user.name}}`.

## Response

```json theme={null}
{ "status": "initiated", "workflow_run_id": 580, "workflow_run_name": "WR-API-4821" }
```

`workflow_run_id` is the call's ID. Once the call ends, read it with
`GET /agents/{agent_id}/conversations/{workflow_run_id}` - see
[API introduction](/en/api-reference/introduction#reading-a-call).

## Errors

| Status | When |
| - | - |
| `400` | The organization's telephony isn't configured |
| `402` | Not enough credit for calls |
| `403` | Outbound calling is blocked for the organization (plan, verification), or the number is on its Do not call list (`detail` starts with `do_not_call`) |
| `404` | The agent doesn't exist or belongs to another organization |
| `409` | Outside 08:00-21:00 the recipient's local time. The `Retry-After` header and the `detail.retry_at` field say when you may call |
| `429` | Every outbound channel is busy. Retry after as many seconds as `Retry-After` says |

<Note>
  Agents with a trigger node in their flow also have the older
  `POST /api/v1/triggers/{trigger_id}/calls` address, with the same body and errors.
  It keeps working for existing integrations. Build new ones on
  `/agents/{agent_id}/calls` - it needs no trigger node.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.