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

# Phone calls

> Place outbound calls with an agent, personalize each call, and call a list of numbers in a batch.

An agent can place outbound phone calls. You start a call with one REST request. The call itself runs in the background, and you read the result when it ends.

## Before you start

* An [API key](/authentication).
* An agent with a phone number set up through Twilio or Telnyx.
* The agent's `agent_id`.

## Place a call

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://app.eclatira.com/api/v1/calls \
    -H "Authorization: Bearer $ECLATIRA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "your-agent-id",
      "to_number": "+15551234567"
    }'
  ```

  ```python Python theme={"system"}
  import os

  import httpx

  response = httpx.post(
      "https://app.eclatira.com/api/v1/calls",
      headers={"Authorization": f"Bearer {os.environ['ECLATIRA_API_KEY']}"},
      json={"agent_id": "your-agent-id", "to_number": "+15551234567"},
  )
  response.raise_for_status()
  print(response.json()["call_id"])
  ```

  ```js Node.js theme={"system"}
  const response = await fetch("https://app.eclatira.com/api/v1/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ECLATIRA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "your-agent-id", to_number: "+15551234567" }),
  });
  const call = await response.json();
  console.log(call.call_id);
  ```
</CodeGroup>

The response comes back right away with status `initiated`:

```json theme={"system"}
{
  "call_id": "CAc29a9cb3a1dc3e077f4a9a25f5161e4d",
  "call_sid": "CAc29a9cb3a1dc3e077f4a9a25f5161e4d",
  "agent_id": "your-agent-id",
  "to_number": "+15551234567",
  "status": "initiated",
  "provider": "twilio",
  "warnings": []
}
```

### Request fields

<ParamField body="agent_id" type="string" required>
  The agent that makes the call.
</ParamField>

<ParamField body="to_number" type="string" required>
  The number to call, in E.164 format. For example, `+15551234567`.
</ParamField>

<ParamField body="variables" type="object">
  Values for the `{{placeholders}}` in the agent's instructions and first message. Keys and values are strings.
</ParamField>

<ParamField body="first_message" type="string">
  Replaces the agent's first message for this call only.
</ParamField>

<ParamField body="provider" type="string">
  `twilio` or `telnyx`. Use this when the agent has both. If you leave it out, Eclatira uses Twilio when it is set up, and Telnyx otherwise.
</ParamField>

<ParamField body="webhook_url" type="string">
  A URL that receives a `POST` when this call ends. See [Webhooks](/webhooks).
</ParamField>

## Personalize each call

Put placeholders in the agent's instructions or first message with double braces:

```text theme={"system"}
Hi {{first_name}}, this is Sam from Acme. I'm calling about your appointment on {{date}}.
```

Then fill them in when you place the call:

```json theme={"system"}
{
  "agent_id": "your-agent-id",
  "to_number": "+15551234567",
  "variables": {
    "first_name": "Maria",
    "date": "Friday"
  }
}
```

## Retry safely

Network errors happen. To retry a request without placing a second call, send an `Idempotency-Key` header:

```bash theme={"system"}
-H "Idempotency-Key: order-4821-reminder"
```

* If you repeat a request with the same key and the same body, you get the first response back. No new call is placed.
* If you reuse a key with a different body, the request is rejected.

This works for both `POST /api/v1/calls` and `POST /api/v1/batches`.

## Get the result

When the call ends, read it with `GET /api/v1/calls/{call_id}`:

```bash theme={"system"}
curl https://app.eclatira.com/api/v1/calls/CAc29a9cb3a1dc3e077f4a9a25f5161e4d \
  -H "Authorization: Bearer $ECLATIRA_API_KEY"
```

The response includes:

| Field | What it holds |
| - | - |
| `status` | Where the call is now |
| `duration` | Length of the call |
| `transcript` | Every turn of the conversation |
| `summary` | A short summary of the call |
| `sentiment` | The caller's overall sentiment |
| `goal_met` | Whether the agent reached its goal |
| `answered_by` | Who or what answered the call |
| `unanswered_questions` | Questions the agent could not answer |
| `call_cost` | What the call cost |
| `recording_available` | Whether a recording exists |

<Tip>
  Polling works, but a [webhook](/webhooks) is simpler. Eclatira sends you the full result when the call ends.
</Tip>

To list all calls, use `GET /api/v1/calls` with `limit` and `offset`.

### Flag a call for review

You can mark a finished call for human review. This is the same as the review toggle in the dashboard:

```bash theme={"system"}
curl -X PATCH https://app.eclatira.com/api/v1/calls/CAc29a9cb3a1dc3e077f4a9a25f5161e4d \
  -H "Authorization: Bearer $ECLATIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"needs_review": true}'
```

This only works after the call has ended.

## Call a list of numbers

A batch calls many people with the same agent. It uses the same engine as the CSV upload in the dashboard, with the same scheduling, retries and concurrency.

```bash theme={"system"}
curl -X POST https://app.eclatira.com/api/v1/batches \
  -H "Authorization: Bearer $ECLATIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "name": "Appointment reminders",
    "recipients": [
      { "to_number": "+15551234567", "variables": { "first_name": "Maria" } },
      { "to_number": "+15557654321", "variables": { "first_name": "James" } }
    ]
  }'
```

Each recipient needs a `to_number`. It can also have its own `variables` and `first_message`.

A batch starts right away. To run it later, add `scheduled_at` with an ISO 8601 time. To get one notification when the whole batch is done, add `webhook_url`.

### Manage a batch

| Action | Endpoint | What happens |
| - | - | - |
| Check progress | `GET /api/v1/batches/{batch_id}` | Returns counts (completed, failed, voicemail, in progress) and a page of recipients. |
| Cancel | `POST /api/v1/batches/{batch_id}/cancel` | No new calls start. Calls already in progress finish normally. |
| Retry | `POST /api/v1/batches/{batch_id}/retry` | Queues again anyone who did not answer, was busy, reached voicemail, or had a technical failure. |

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Get call results pushed to your server.
  </Card>

  <Card title="Calls API" icon="code" href="/api-reference/calls/create-a-call">
    The full request and response schema.
  </Card>
</CardGroup>


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