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, and failure. Add include_tool_activity=true to also see each background task and each tool request and result. See See each tool call of a call.
  • GET /v1/calls lists calls, newest first. Filter by call_agent_id, orchestration_run_id, status, client_reference, the creation time, each phone number, one analysis pair with analysis_key and analysis_value, or one tag pair with tag_key and tag_value. Each item has the call's analysis. See Tags. Follow next_cursor for the next page. See List and filter calls.
  • GET /v1/calls/{call_id}/recording downloads the call recording. Check recording.available on the call first. A call with no recording returns 404. For a speech-to-speech call, recording can be null or say available: false while 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-charges lists 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_id for each accepted call, in the order you submitted them. Each call reads through GET /v1/calls/{call_id} like any other call.
  • Resia checks each entry on its own. A bad entry goes to rejected_calls with its position, number, client_reference, and reason. An invalid timezone rejects 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 with 422.
  • Idempotency-Key is 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.

Guides

API reference

Calls · Call Batches