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.

You can also create and edit Call Agents in the portal under Agents → New agent.

The New Call Agent form in the portal, with name, description, instructions, and analysis fields

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. See Number format.

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.

To run a call on a speech-to-speech model, such as gpt-live-1, set model_architecture and speech_to_speech_model on the Call Agent. Such an agent has some limits. See Speech-to-speech models.

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

Every call also appears in the portal under History → Calls, with its status, From and To numbers, duration, and charge. See Calls in the portal.

The History page in the portal, listing calls with agent, status, From and To numbers, duration, charge, and start time

Read the call again after you hang up. The final status is completed, error, or canceled. An unknown status means that Resia cannot read the live status at that moment. It is not a final result, so read the call again. 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 fails

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 Your calls in progress reached your concurrent call limit. Try again after a call ends. See Concurrent calls.

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