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

# Call

# 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.

```http theme={null}
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. |

#### `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.

### Example Request

```json theme={null}
{
  "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

```json theme={null}
{
  "status": 200,
  "data": {
    "status": "Queued",
    "call_id": "call-123"
  }
}
```

## List Calls

Retrieve a list of calls with optional filtering and pagination.

```http theme={null}
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

```json theme={null}
{
  "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"
      },
      "recording_url": "https://storage.brilo.com/recordings/call-123.mp3",
      "workspace_id": "workspace-123"
    }
  ],
  "totalRecords": 100,
  "currentPage": 1
}
```

## Get Call

Retrieve details of a specific call.

```http theme={null}
GET /call/{id}
```

### Parameters

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

### Response

```json theme={null}
{
  "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"
  },
  "recording_url": "https://storage.brilo.com/recordings/call-123.mp3",
  "workspace_id": "workspace-123"
}
```

## Get Call Recording

Stream the audio recording of a call.

```http theme={null}
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.

```http theme={null}
DELETE /call/{id}
```

### Parameters

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

### Response

```json theme={null}
{
  "status": 200,
  "message": "Call deleted successfully"
}
```