Phone calls

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.
An agent with a phone number set up through Twilio or Telnyx.
The agent’s agent_id.

Place a call

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"
  }'

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"])

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);

The response comes back right away with status initiated:

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

Request fields

string

required

The agent that makes the call.

string

required

The number to call, in E.164 format. For example, +15551234567.

object

Values for the {{placeholders}} in the agent’s instructions and first message. Keys and values are strings.

string

Replaces the agent’s first message for this call only.

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.

string

A URL that receives a POST when this call ends. See Webhooks.

Personalize each call

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

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:

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

-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}:

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

Polling works, but a webhook is simpler. Eclatira sends you the full result when the call ends.

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:

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.

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.

Get started

Web sessions

Help

Phone calls

Before you start

Place a call

Request fields

Personalize each call

Retry safely

Get the result

Flag a call for review

Call a list of numbers

Manage a batch

Next steps

Webhooks

Calls API

​Before you start

​Place a call

​Request fields

​Personalize each call

​Retry safely

​Get the result

​Flag a call for review

​Call a list of numbers

​Manage a batch

​Next steps

Webhooks

Calls API

Before you start

Place a call

Request fields

Personalize each call

Retry safely

Get the result

Flag a call for review

Call a list of numbers

Manage a batch

Next steps