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 in the X-API-Key header. The agent calls from its own number.

Request

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": "[phone]",
    "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

{ "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.

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

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.