Call a list of numbers

This guide queues many outbound calls with one request. A call batch holds up to 1,000 calls that use the same Call Agent. Resia dials them from a queue at the pace your rate limits allow.

Before you start

• Complete Get access, and keep the terminal open.
• Have an approved, active Call Agent. The Quickstart creates one.
• Every call in a batch incurs normal call charges.

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.

read -r -p 'Call Agent id: ' CALL_AGENT_ID
BATCH_REQUEST_KEY=$(uuidgen)

jq -n --arg agent "$CALL_AGENT_ID" '{
  call_agent_id: $agent,
  calls: [
    {to_phone_number: "+12125550142", inputs: {}, client_reference: "patient-1001"},
    {to_phone_number: "+13125550187", inputs: {}, 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.

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

Rejected entries

Resia checks each entry on its own. A bad entry does not stop the rest of the batch. 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.

Resia refuses the whole request only when the Call Agent is unknown, you do not own the from_phone_number, or the batch is larger than your queued-call limit (429).

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.

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.

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: Call Batches