Call a list of numbers

A call batch queues up to 1,000 outbound calls that use the same Call Agent, in one request. Resia dials them from a queue as your concurrent call limit allows. In this guide, you will submit a batch, follow its progress, and stop it.

Before you start

  • Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
  • An approved, active Call Agent. The Quickstart creates one.
  • Every call in a batch is a real call. Normal call charges apply.
  • Write every phone number in E.164 form, such as +12125550142. See Number format.

Check the agent's inputs

Read the agent first. Each entry's inputs must match its input_schema.

read -r -p 'Call Agent id: ' CALL_AGENT_ID

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '{input_schema, instructions}'

Expected result: The agent's input_schema and instructions. The example below uses an agent whose input_schema declares patient_name and appointment_date as strings. Change the inputs to match your agent. An agent with no properties takes inputs: {}.

Give each entry a value for every input in required. Resia checks each entry against the schema when you submit the batch. A variable for an optional input with no value is empty in the instructions.

Submit the batch

Each entry needs a to_phone_number. Add inputs when the agent needs them, and a client_reference to match results back to your own records. Add to_extension, such as ww204, when the number answers with a phone menu. Resia presses those keys after the line answers. Do not put a PIN or another secret in to_extension. Every call read shows it. An invalid to_extension also refuses the whole batch with 422.

BATCH_REQUEST_KEY=$(uuidgen)

jq -n --arg agent "$CALL_AGENT_ID" '{
  call_agent_id: $agent,
  calls: [
    {to_phone_number: "+12125550142", inputs: {patient_name: "Ada Lovelace", appointment_date: "2026-10-12"}, client_reference: "patient-1001"},
    {to_phone_number: "+13125550187", inputs: {patient_name: "Alan Turing", appointment_date: "2026-10-13"}, client_reference: "patient-1002"}
  ]
}' > batch.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-batches" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $BATCH_REQUEST_KEY" \
  --data-binary @batch.json \
  --output batch-response.json

jq '.' batch-response.json

Expected result: HTTP 202. Nothing is dialed yet. The response lists one call_id for each accepted call, in the order you sent them, and a rejected_calls list for any entries that Resia refused.

Check rejected_calls in every response:

jq '{total, rejected_calls}' batch-response.json

202 does not mean that Resia accepted every entry. Resia answers 202 even when it rejects every entry. Such a batch has total 0, places no calls, and completes at once.

Add from_phone_number to the body to call from a number your organization owns.

Add timezone to an entry, such as "timezone": "America/Los_Angeles", when that person is in a different time zone from the agent. The agent then knows the local time in that zone. Without it, the agent's timezone applies.

In the portal: no page submits a batch. To do it without code, ask Butler, for example "Call these numbers with the agent Front desk". Butler asks you to confirm before it places a call batch.

Idempotency-Key is required. If you are not sure whether a batch arrived, send it again with the same key and body. Resia returns the original batch and queues nothing more. If you change the body and reuse the key, Resia answers 409.

API reference: Submit a batch of calls.

Rejected entries

Resia checks each entry on its own. An invalid timezone refuses the whole batch with 422. Other bad entries do not stop the rest. Resia rejects an entry when:

  • Resia cannot call the destination, such as a number outside the United States and Canada.
  • The destination already appears earlier in the batch. Resia calls the first entry only.
  • The entry is a multi-party call. Place those with POST /v1/calls.
  • The inputs do not match the agent's input_schema.

Each rejected entry has its position (starting at 0), the number you sent, its client_reference, and a reason. Accepted and rejected entries together account for every entry you sent.

Follow progress

BATCH_ID=$(jq -er '.id' batch-response.json)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-batches/$BATCH_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY"

This returns the batch status (in_progress, completed, or canceled) and a count of calls in each state. The counts always add up to total.

In the portal: open History → Calls. Each call of the batch appears there with its status.

To see each call, list them in the order you submitted them:

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-batches/$BATCH_ID/calls" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '.items[] | {call_id, client_reference, status}'

Read one call with GET /v1/calls/{call_id} for its transcript and analysis. To get each result as it finishes, set a call_ended_webhook_url on the Call Agent. See Get results after a call.

API reference: Read one call batch and List the calls in a batch.

Stop a batch

curl --fail-with-body --silent --show-error \
  --request POST "$RESIA_API_BASE/v1/call-batches/$BATCH_ID/cancel" \
  --header "Authorization: Bearer $RESIA_API_KEY"

Cancel stops the calls that are still queued. Those calls become canceled. Calls that already started run to their end. Cancel is safe to repeat.

API reference: Cancel a call batch.

If something fails

  • 409: you reused an Idempotency-Key with a different body. Use a new key for a new batch.
  • The whole request is refused: the Call Agent is unknown, you do not own from_phone_number, or an entry's timezone is not an IANA zone (422, the message names the entry, such as calls[1].timezone). Read the error message.
  • An entry is in rejected_calls: read its reason, fix the entry, and send it in a new batch.

Next steps