Calls and call batches
A call is one attempt to place or answer a phone call with a Call Agent. Each call has its own ID, status, transcript, recording, analysis, and charge.
Place a call
POST /v1/calls queues one outbound call and answers 202 Accepted at once. The phone has not rung yet when you get the response.
| Field | Required | What it does |
|---|---|---|
call_agent_id |
Yes | The Call Agent that handles the call. |
to_phone_number |
Yes | The destination, in E.164 format, such as +12125550142. |
inputs |
When the agent needs them | Values that match the agent's input_schema. |
from_phone_number |
No | A number your organization owns. If you leave it out, Resia uses its default caller number. People who call this number back reach its inbound agent. See Callbacks. |
database_id |
No | A ready database that the agent can search during this call. See Let an agent answer from your data. |
client_reference |
No | Your own label, such as an order ID. Resia stores it, returns it on every read, and lets you filter GET /v1/calls by it. |
call_ended_webhook_url |
No | Overrides the agent's result webhook for this call only. |
additional_participants |
No | Numbers for a multi-party call. See Bring another person onto a call. |
tags |
No | Your own key and value labels. Filter GET /v1/calls by one pair. See Tags. |
timezone |
No | An IANA time zone for this call, such as America/Los_Angeles. The agent knows today's date and the local time in that zone. If you leave it out, the agent's timezone applies. A name that is not an IANA zone gets 422. GET /v1/calls/{call_id} returns the value you sent, or null. |
Resia calls numbers in the United States and Canada only, and refuses premium-rate numbers.
Idempotency
Send an Idempotency-Key header with a new UUID for each call. If you repeat a request with the same key, Resia returns the call from the first request and does not dial again. The first request's inputs, webhook URL, and timezone stay on that call, even if a retry sends different values.
Call status
| Status | Meaning | Final? |
|---|---|---|
queued |
Resia accepted the call. It is waiting for its turn. | No |
initiated |
The call is being placed. | No |
in_progress |
The call is connected. | No |
post_processing |
The call ended. Resia is preparing the transcript and analysis. |
No |
completed |
The call ended normally, and the results are ready. | Yes |
error |
The call failed. Read failure for the reason. |
Yes |
canceled |
The call was stopped before it was dialed. | Yes |
unknown |
Resia could not read the live status at this moment. Read the call again. | No |
Failure codes
A call with the status error has a failure object. Branch on failure.code. failure.message gives the same reason for a person, and hangup_cause and sip_hangup_cause carry the carrier's own reason when it sent one.
failure.code |
Meaning |
|---|---|
no_answer |
Nobody answered the call. |
busy |
The destination was busy. |
call_rejected |
The destination rejected the call. |
executor_error |
The call ended without completing, for a reason not listed above. |
dispatch_outcome_unknown |
An earlier attempt to place this call never reported an outcome, so Resia does not send it again. To try again, send a new request with a new Idempotency-Key. |
completed does not prove that a person answered or that the task succeeded. Check the transcript and the analysis for the real outcome. A completed call can have a null analysis. See Call analysis.
Read calls
GET /v1/calls/{call_id}returns one call with its transcript,analysis, andfailure. Addinclude_tool_activity=trueto also see each background task and each tool request and result. See See each tool call of a call.GET /v1/callslists calls, newest first. Filter bycall_agent_id,orchestration_run_id,status,client_reference, the creation time, each phone number, one analysis pair withanalysis_keyandanalysis_value, or one tag pair withtag_keyandtag_value. Each item has the call'sanalysis. See Tags. Follownext_cursorfor the next page. See List and filter calls.GET /v1/calls/{call_id}/recordingdownloads the call recording. Checkrecording.availableon the call first. A call with no recording returns404. For a speech-to-speech call,recordingcan be null or sayavailable: falsewhile a file exists. Request the download to check. The format and start time of the downloaded file can differ from this metadata.GET /v1/call-chargeslists what each call cost.
A recording is an MP3 or a WAV file. Read recording.format on the call (mp3 or wav) to choose the file extension. The download has the matching Content-Type, audio/mpeg or audio/wav. In rare cases the carrier no longer holds its MP3 file, and the download is the WAV file while recording.format still says mp3. The Content-Type of the download always gives the actual format.
Call batches
A call batch queues up to 1,000 outbound calls that use the same Call Agent, in one request. Resia dials from a queue as your concurrent call limit allows, so a large list does not fail with a wall of 429 errors.
- The response lists one
call_idfor each accepted call, in the order you submitted them. Each call reads throughGET /v1/calls/{call_id}like any other call. - Resia checks each entry on its own. A bad entry goes to
rejected_callswith itsposition, number,client_reference, andreason. An invalidtimezonerejects the whole batch. - If a destination appears twice, Resia calls the first entry and rejects the later ones.
- Each entry can set its own
timezone, as on a single call. A name that is not an IANA zone refuses the whole batch with422. Idempotency-Keyis required.
Batch status is in_progress, completed, or canceled. Cancel a batch with POST /v1/call-batches/{batch_id}/cancel. This stops the calls that are still queued. Calls that already started run to their end.
See Call a list of numbers for a full example.
Calls in progress
Inbound and outbound calls share one limit for calls in progress in your organization. Read the limit and the current count with GET /v1/rate-limits. See Concurrent calls.
In the portal
Open History to see your organization's activity. The Runs, Calls, and Chats tabs list orchestration runs, calls, and chats, newest first. Times show in your browser's time zone. Each tab has an Analysis column with the first analysis fields of each record, and one filter row: Filter by tag, the agent, the status, the Created days, the phone numbers where a record has them, and Filter by Outcome (one analysis field with one value). See List and filter calls.
Select a call to open its details on the right: the status, the other person's number, the duration and cost, the analysis, a recording player, and the transcript. Select a turn in the transcript to play the recording from that point. A failed call shows its failure reason at the top. Select Give Feedback to write a draft request to Butler about the call.

