Call Service

The Call Service allows you to manage outbound calls and retrieve call information. You can initiate calls, get call details, and manage call recordings.

Send Call

Initiate an outbound call to a phone number.

POST /call

Request Body

Field	Type	Required	Description
to	string	Yes	The recipient’s phone number in E.164 format (e.g., +1234567890)
agent_id	string	Yes	ID of the agent making the call
variables	object	No	Per-call dynamic variables. Reference them in the agent prompt and greeting as `{{var.KEY}}`. Values are coerced to strings; an unreferenced or omitted variable renders as empty. See constraints below.
agent_overrides	object	No	Change what this one call does without changing the agent. See Per-call agent overrides.

`variables` constraints

Max 50 keys.
Keys must match ^[a-zA-Z][a-zA-Z0-9_]{0,62}$ (start with a letter, then letters/digits/underscores). Keys are case-insensitive, so Foo and foo collide and are rejected.
Values must be a string, number, or boolean — no nested objects or arrays. Each value is capped at 1000 characters.
The whole variables object must serialize to under 4KB.
Invalid payloads return 400 with a message describing the violation.

Per-call agent overrides

agent_overrides lets one call behave differently from the agent that places it. The call still runs as the agent you named in agent_id, using that agent’s phone number, voice, actions and knowledge. Only the fields you send are changed, only for this call, and nothing is written back to the agent. Anything you leave out keeps the agent’s own setting. That is what “default” means here: your agent, not a generic fallback.

Field	Type	Description
`instruction`	string	What the agent should do on this call. Replaces the agent’s prompt for this call.
`greeting`	string	The first line the agent speaks when the call connects.
`language`	string	Language tag for this call, e.g. `en`, `es`, `en-GB`.
`voicemail_behavior`	string	`LEAVE_MESSAGE` or `HANG_UP`. Defaults to `LEAVE_MESSAGE` when `agent_overrides` is present.
`voicemail_message`	string	What to say when voicemail picks up and `voicemail_behavior` is `LEAVE_MESSAGE`.
`max_duration_minutes`	number	Hang up after this many minutes. 1 to 60.
`summary_instruction`	string	What the summary of this call should focus on. Replaces your agent’s Personalized Call Summary for this call.
`ask_a_human`	object	Let the agent phone a person mid-call when it is asked for something it does not know, then carry on. See Ask a Human.

Any other field returns 400. That is deliberate: a few agent settings look like they would work here but never reach the call, and silently ignoring them would leave you with a call that ignored your instructions and an API response that said it worked. The error tells you which case you hit, so you know whether to change the field or change the agent:

Use a different field. prompt is not accepted, use instruction. welcome_msg is not accepted, use greeting. post_call_notes is not accepted, use summary_instruction.
Change it on the agent instead. Recording, consent, retention and contact-access settings can only be changed in the dashboard, because they are compliance settings for the whole workspace rather than choices about one call.
Not available yet. Voice, model, response length, tone and the call-timing settings are set on the agent for now.

Idempotency-Key is optional. If you send one and a request times out, retrying with the same key and the same body returns the original response instead of placing a second call. The replayed response carries "idempotent_replay": true so you can tell it from a fresh call. Reusing a key with a different body returns 422; retrying while the first request is still running returns 409.Use a new key for a genuinely new attempt. If someone did not answer and you want to ring them again, that is a new call and needs a new key. Sending the old key returns the first call’s response and dials nobody. Deriving the key from the request content (a hash of the number and prompt, say) looks tidy and quietly breaks every redial for 24 hours.

Example: one agent, two different calls

curl -X POST https://api.brilo.ai/call \
  -H "Authorization: Bearer $BRILO_API_KEY" \
  -H "Idempotency-Key: 9f1c2b7e-6a41-4c1e-9a55-0f2d3c4b5a6d" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550142",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_overrides": {
      "instruction": "Confirm Sarah is still coming to her 3pm roof inspection on Tuesday. If she cannot make it, offer Thursday morning.",
      "greeting": "Hi Sarah, this is Alex from Brilo Roofing.",
      "voicemail_message": "Hi Sarah, calling about Tuesday at 3pm. Give us a ring back on 555 0100.",
      "max_duration_minutes": 5,
      "summary_instruction": "State whether Sarah confirmed, and any access instructions she gave."
    }
  }'

The same agent, called again an hour later with a completely different job, needs no new agent and no dashboard change:

{
  "to": "+14155550188",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_overrides": {
    "instruction": "Tell Mr Patel his invoice is 14 days overdue and ask when he can pay.",
    "greeting": "Good morning, this is Alex calling from Brilo Roofing accounts."
  }
}

Example Request

{
  "to": "+1234567890",
  "agent_id": "agent-123",
  "variables": {
    "lead_name": "Sarah",
    "product": "Roof inspection",
    "appt_time": "Tuesday 3pm"
  }
}

With the variables above, an agent prompt or greeting containing Hi {{var.lead_name}}, calling about your {{var.product}} on {{var.appt_time}}. is rendered as Hi Sarah, calling about your Roof inspection on Tuesday 3pm. before the call connects.

Response

{
  "status": 200,
  "data": {
    "status": "Queued",
    "call_id": "call-123"
  }
}

List Calls

Retrieve a list of calls with optional filtering and pagination.

GET /call

Query Parameters

Parameter	Type	Required	Description
skip	number	No	Number of records to skip (default: 0)
take	number	No	Number of records to return (default: 10)
where	object	No	Filter conditions for the query
orderBy	object	No	Sorting criteria

Response

{
  "calls": [
    {
      "id": "call-123",
      "created_at": "2024-03-20T10:00:00Z",
      "to": "+1234567890",
      "from": "+1987654321",
      "status": "completed",
      "duration": 120,
      "direction": "outbound",
      "metadata": {
        "purpose": "sales",
        "priority": "high"
      },
      "workspace_id": "workspace-123"
    }
  ],
  "totalRecords": 100,
  "currentPage": 1
}

The list leaves out the recording and transcript to keep pages small. Get them from Get Call. A campaign call that has not been dialled yet has to and from set to null.

Get Call

Retrieve details of a specific call.

GET /call/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the call to retrieve

Response

{
  "id": "call-123",
  "created_at": "2024-03-20T10:00:00Z",
  "to": "+1234567890",
  "from": "+1987654321",
  "status": "completed",
  "duration": 120,
  "direction": "outbound",
  "recording_url": "https://storage.brilo.com/recordings/call-123.mp3",
  "workspace_id": "workspace-123",
  "summary": "Sarah confirmed Tuesday at 3pm and asked the team to use the side gate.",
  "transcript": "Agent: Hi Sarah, this is Alex from Brilo Roofing.\nCustomer: Oh hi...",
  "transcript_obj": [
    { "role": "agent", "content": "Hi Sarah, this is Alex from Brilo Roofing." },
    { "role": "customer", "content": "Oh hi, yes, Tuesday still works." }
  ],
  "agent_overrides": {
    "instruction": "Confirm Sarah is still coming to her 3pm roof inspection on Tuesday.",
    "greeting": "Hi Sarah, this is Alex from Brilo Roofing.",
    "voicemail_behavior": "LEAVE_MESSAGE"
  }
}

Response fields

Field	Type	Description
`summary`	string	What happened on the call, in a few sentences. Follows your agent’s Personalized Call Summary, or this call’s `summary_instruction` if you sent one.
`transcript`	string	The conversation as plain text, one speaker turn per line.
`transcript_obj`	array	The same conversation as structured turns, with roles and, where relevant, the tools the agent used. Use this when you want to process the call rather than read it.
`agent_overrides`	object \| null	The per-call overrides this call ran with, or `null` if it ran on the agent’s own settings.

Get Call Recording

Stream the audio recording of a call.

GET /call/{id}/recording

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the call to retrieve the recording for

Response

The response is an audio stream of the call recording.

Delete Call

Delete a call record.

DELETE /call/{id}

Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the call to delete

Response

{
  "status": 200,
  "message": "Call deleted successfully"
}

Endpoints

Agents

MCP server

Agent pairing

Webhooks

Call

Call Service

Send Call

Request Body

`variables` constraints

Per-call agent overrides

Example: one agent, two different calls

Example Request

Response

List Calls

Query Parameters

Response

Get Call

Parameters

Response

Response fields

Get Call Recording

Parameters

Response

Delete Call

Parameters

Response

​Call Service

​Send Call

​Request Body

​variables constraints

​Per-call agent overrides

​Example: one agent, two different calls

​Example Request

​Response

​List Calls

​Query Parameters

​Response

​Get Call

​Parameters

​Response

​Response fields

​Get Call Recording

​Parameters

​Response

​Delete Call

​Parameters

​Response

Call Service

Send Call

Request Body

`variables` constraints

Per-call agent overrides

Example: one agent, two different calls

Example Request

Response

List Calls

Query Parameters

Response

Get Call

Parameters

Response

Response fields

Get Call Recording

Parameters

Response

Delete Call

Parameters

Response