Quickstart: your first call

This guide creates a simple Call Agent and uses it to call your own phone. It takes about five minutes.

This places a real phone call, and normal call charges apply. You need a phone in the United States or Canada. Resia does not call premium-rate numbers.

Before you start: complete Get access, and keep the terminal open with RESIA_API_BASE and RESIA_API_KEY set.

Create a Call Agent

A Call Agent stores the instructions for a phone conversation. The two schemas describe the inputs the agent accepts and the result you get back after the call. This agent needs no inputs.

cat > first-agent.json <<'JSON'
{
  "name": "My first Resia call",
  "instructions": "You are a friendly test assistant. Say hello and explain that this is a Resia test call. Ask whether the person can hear you clearly. Thank them and end the call.",
  "input_schema": {"type": "object", "properties": {}, "additionalProperties": false},
  "analysis_prompt": "Summarize the conversation in one sentence.",
  "analysis_schema": {
    "type": "object",
    "properties": {"summary": {"type": "string"}},
    "required": ["summary"],
    "additionalProperties": false
  },
  "agent_speaks_first": true,
  "should_leave_voicemail": false
}
JSON

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-agents" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @first-agent.json \
  --output agent-response.json

jq '{id, review_status, is_active}' agent-response.json

Expected result: HTTP 201 with an id. Continue when review_status is approved and is_active is true.

If the agent is pending_review, contact Resia. Do not create the same agent again. If the name is already in use, pick another name or use the existing agent's id.

Call your phone

Enter your number in E.164 format: a +, the country code, and the number, such as +12125550142.

CALL_AGENT_ID=$(jq -er '.id' agent-response.json)
read -r -p 'Your phone number, including + and country code: ' TO_PHONE_NUMBER
CALL_REQUEST_KEY=$(uuidgen)

jq -n --arg agent "$CALL_AGENT_ID" --arg phone "$TO_PHONE_NUMBER" \
  '{call_agent_id: $agent, to_phone_number: $phone, inputs: {}}' > first-call.json

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

jq '{id, status}' call-response.json

Expected result: HTTP 202 with a call id. Resia accepted the request. The phone has not rung yet. Answer it when it rings.

The Idempotency-Key makes a retry safe. If you are not sure whether a request arrived, send it again with the same key and body, and Resia returns the original call instead of dialing twice. Use a new key for each new call.

This example uses Resia's default caller number. To call from a number your organization owns, add from_phone_number to the body.

Read the result

CALL_ID=$(jq -er '.id' call-response.json)

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/calls/$CALL_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --output call-result.json

jq '{id, status, transcript, analysis, failure}' call-result.json

Read the call again after you hang up. The final status is completed, error, or canceled. The analysis object follows the analysis_schema you defined, so here it contains a one-sentence summary.

Place the call from code

The same request in other languages:

import os
import uuid

import requests

response = requests.post(
    "https://api.resia.ai/v1/calls",
    headers={
        "Authorization": f"Bearer {os.environ['RESIA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "call_agent_id": "YOUR_CALL_AGENT_ID",
        "to_phone_number": "+12125550142",
        "inputs": {},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["id"])

import { randomUUID } from "node:crypto";

const response = await fetch("https://api.resia.ai/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RESIA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    call_agent_id: "YOUR_CALL_AGENT_ID",
    to_phone_number: "+12125550142",
    inputs: {},
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).id);

If something goes wrong

Response	Meaning	What to do
`401`	Resia did not accept your key.	Check the key. See Get access.
`402`	Your prepaid balance is $0.00 or less.	Add funds. See Billing.
`422`	The inputs or the agent are not valid. The `message` names the problem.	Fix the request. Do not retry it unchanged.
`429`	A call rate limit blocked the request.	Wait for the number of seconds in `Retry-After`. See Rate limits.

If Resia accepted the call but it failed, read its failure field.

completed means that the call ended normally. It does not prove that a person answered or that the task succeeded. Check the transcript and the analysis.

Next steps

Get results after a call

Receive a webhook when every call ends.

Pass inputs to an agent

Personalize each call with variables.

Answer inbound calls

Put the agent on your own number.

Call a list

Queue up to 1,000 calls in one request.

Get access

How Resia fits together