Call Agents

A Call Agent contains the instructions and settings for a phone conversation. The same Call Agent can place outbound calls and answer inbound calls. Reuse one agent for many calls. Pass per-call details as inputs.

Required fields

Field What it does
name A name that is unique in your organization.
instructions What the agent says and does. Refer to inputs with $name or ${name}.
input_schema A JSON Schema (draft 2020-12) object for the inputs each call receives.
analysis_prompt How Resia should read the finished call. See Call analysis.
analysis_schema A JSON Schema object for the structured analysis result. See Call analysis.

Resia refuses a request that contains a field it does not define, with 422. The error message shows the undefined field name as *.

Resia checks each call's inputs against input_schema, but it does not check format keywords, such as "format": "date-time". A value in the wrong form is accepted. Send each value in the form that your instructions expect.

Optional settings

Field What it does
description One line that says what the agent is for.
agent_speaks_first true makes the agent speak as soon as the call connects. Use it for inbound greetings. By default, the agent waits for the other person.
should_leave_voicemail true leaves a message when an outbound call reaches voicemail. By default, the agent hangs up.
enable_background_noise false turns off the quiet office background sound under the agent's voice. true or null, the default, plays the sound.
disclaimer Text that each person on the call hears word for word when their line connects, before the agent speaks, such as This call may be recorded. The agent's voice speaks it, and it always plays to the end. At most 300 characters. Empty text saves as null. null, the default, plays nothing.
voices Up to 32 voices, each a tts_provider and voice_id from the catalog or a private ID that Resia supplied. See Voices. Each call picks one at random.
timezone An IANA time zone, such as America/Chicago. The agent knows today's date and the local time in that zone. Without it, the agent knows only the date in America/New_York. A call that sends its own timezone uses that zone instead. See Place a call.
in_call_llm The provider (anthropic or openai) and the exact model identifier that provider publishes, for the live conversation. Resia checks the choice when it saves the agent. GPT-Live models are refused with 422. To run calls on a speech-to-speech model, use model_architecture instead. If you leave it out, Resia uses its current default. GET /v1/call-agents/available-in-call-llms lists the models you can choose, cheapest first, with what each adds to the price of a call minute.
model_architecture How the agent produces its speech. stt_llm_tts, the default, transcribes the other person, writes each reply with a language model, and speaks it with a voice. speech_to_speech runs the whole conversation on one speech-to-speech model. See Speech-to-speech models.
speech_to_speech_model The speech-to-speech model, such as gpt-live-1. Required when model_architecture is speech_to_speech, and must be null otherwise. Resia checks the name when it saves the agent. A model that has no price is refused with 422, when Resia saves the agent and when a call starts.
tools The names of your organization's custom tools that calls of this agent may use, at most 64. See Give your agents a custom tool.
call_ended_webhook_url An HTTPS URL that receives a call.ended event when each call ends. See Webhooks.
inbound_input_webhook_url An HTTPS URL that supplies inputs before an inbound call answers. See Give an inbound agent details about the caller.
primary_participant, additional_participants Let the agent bring more people onto a call. See Multi-party calls.

Variables in instructions

Use $topic or ${topic} to insert the top-level input named topic. Use $$ for a literal dollar sign.

You are calling $patient_name to confirm an appointment on $appointment_date.
The copay is $$20.

Rules:

  • Declare every variable in input_schema.properties.
  • Supply a value for each input in required. A variable for an optional input with no value is empty in the instructions.
  • Do not use {{name}} or nested paths such as $person.name.

Voices

List the voices you can use:

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

The default provider is cartesia. Resia also supports fish; pass ?provider=fish to list those voices. A speech-to-speech agent uses the voices of its model: openai for gpt-live-1, gemini for Gemini Live, and cartesia or fish for resia-fullplex-1.

GET /v1/available-voices returns the same list. It is deprecated; use GET /v1/call-agents/available-voices.

Each listed voice has a provider, an id, a name, a gender, and a language. To use a voice, add it to the agent's voices list with the provider as tts_provider and the id as voice_id:

"voices": [{"tts_provider": "cartesia", "voice_id": "VOICE_ID_FROM_THE_LIST"}]

A Fullplex Call Agent uses the selected Cartesia or Fish voice for its call audio. For any Call Agent that uses Cartesia or Fish, you can supply a private voice ID that Resia provided for your use. Resia's account with that provider must be able to access it. Private Cartesia and Fish voices do not appear in the public catalog. The organization restrictions below still apply. The custom OpenAI voices described under speech-to-speech calls are a separate provider option.

To keep a persona consistent, give an agent one voice, or several voices of the same gender. If voices is empty or null, Resia uses its default voice.

Resia checks each voice with its provider when you create or replace the agent. A voice_id that the provider does not have is refused with 422 and the code invalid_request. The message names the voice. If the voice list cannot be read at that moment, Resia refuses the save rather than store a voice it could not confirm. Try again later.

Providers under a BAA or zero data retention

When your organization has a business associate agreement (BAA) or zero data retention (ZDR) with Resia, its calls use only providers that hold the same agreement:

  • With either agreement, fish voices are not available. GET /v1/call-agents/available-voices?provider=fish returns an empty voices list.
  • With zero data retention, OpenAI models are not available: in_call_llm with provider openai, and the speech-to-speech model gpt-live-1. GET /v1/call-agents/available-in-call-llms leaves out the OpenAI models.
  • With zero data retention, the phone carrier keeps no recording of your calls. The recording that Resia stores stays available, and GET /v1/calls/{call_id}/recording still downloads it.
  • One exception applies under zero data retention: the speech-to-speech model resia-fullplex-1 stays available, and when it hands a task to another model, that model can be an OpenAI model.

A create or replace that names a provider your organization cannot use is refused with 422 and the code invalid_request. The message names the field and the provider, for example voices: fish is not allowed for an organization with baa_applicable. Contact Resia support to set or change your agreement.

Call analysis

After each call, Resia reads the transcript and writes a structured analysis object on the call. Two fields on the agent control it:

  • analysis_prompt tells Resia what to look for, in plain language. For example: "Decide if the patient confirmed the appointment. If they asked to reschedule, record the new date they asked for."
  • analysis_schema is a JSON Schema (draft 2020-12) object. It sets the shape of analysis: the field names, their types, and the allowed values.
{
  "type": "object",
  "properties": {
    "confirmed": {"type": "boolean"},
    "requested_date": {"type": ["string", "null"], "description": "The new date the patient asked for, if any."}
  },
  "required": ["confirmed", "requested_date"]
}

Give each property a clear description, and use enum when only some values are allowed. Resia reads the schema when it writes the analysis, so clear descriptions give better results.

When Resia checks the fields

Resia checks both fields when you create or replace the agent, and refuses a bad value with 422. The error message names the problem.

  • analysis_schema must be a valid JSON Schema draft 2020-12 object, no larger than 256 KiB.
  • analysis_prompt must not be empty, and must be no larger than 1 MiB.

When the analysis is missing

The call has the status post_processing while Resia prepares the transcript and the analysis. When the call is completed, analysis holds the result.

analysis can be null on a completed call. This happens when Resia could not produce a result for that call. Resia does not retry the analysis, and the call is still charged. The call has no separate field that gives the reason.

Treat a null analysis as "needs review": read the transcript with GET /v1/calls/{call_id} and decide the outcome yourself.

Review and versions

Every create and every PUT saves a new version. You see the result on the agent:

Field Meaning
review_status approved, or pending_review while Resia reviews the latest edit.
is_active true when a version of the agent can take calls.
submitted_at When the latest version was saved.
active_updated_at When the running version last changed.

While a new version is pending review, calls keep using the previous approved version. Webhook URLs, voices, time zone, disclaimer, and model settings, including model_architecture and speech_to_speech_model, take effect immediately, without review.

GET /v1/call-agents/{call_agent_id} returns the latest edit. Add ?active=true to read the version that calls use now.

PUT /v1/call-agents/{call_agent_id} replaces the whole agent. It is not a partial update. An optional field that you leave out is cleared. See Change what an agent says.

Anthropic model choices

For the live conversation, you can select claude-haiku-5-5 or claude-sonnet-5-5 with provider anthropic. Haiku 5.5 adds zero cents per connected minute to the base call rate. Sonnet 5.5 adds three cents. An organization price can override these global rates. The model list gives your current rate. Existing agents keep their selected model. To use a new model, select it in the portal or set in_call_llm through the API.

Speech-to-speech calls

By default, Resia transcribes the other person, writes each reply with a language model, and speaks the reply with a voice. model_architecture is then stt_llm_tts or null.

To run the agent's calls on one speech-to-speech model, set these fields on the Call Agent:

  • model_architecture to speech_to_speech.
  • speech_to_speech_model to a supported model, such as gpt-live-1.
  • in_call_llm to null.

These settings take effect at once, without review. To return to the default, set model_architecture and speech_to_speech_model to null.

A speech-to-speech agent has these limits:

  • Inbound calls require an agent assignment on a number. A speech_to_speech Call Agent can also answer your own number on a SIP connection. Its participant legs then dial through that connection's outbound details.
  • An outbound call can come from your own number when its SIP connection has outbound details: the call then goes through your carrier.
  • Its calls can use a database and custom tools.
  • Its single, orchestration, and inbound calls can bring on additional participants for a warm transfer. Each participant needs dial: on_agent_request, and intro can be private_first or direct; another mode is refused with 422. A batch call dials as a plain call, without additional participants.
  • voices takes only voices of the model's provider: openai for gpt-live-1, gemini for Gemini Live, and cartesia or fish for resia-fullplex-1. List the voices with GET /v1/call-agents/available-voices?provider=openai, ?provider=gemini, ?provider=cartesia, or ?provider=fish. Resia Fullplex speaks English only, so choose an English voice for it. Each call speaks in one voice from voices. A gpt-live-1 agent also takes a custom voice that Resia made for your organization, as {"tts_provider": "openai", "voice_id": "voice_..."}. Without voices, the model uses its default voice.
  • should_leave_voicemail applies to outbound calls: with true, the agent waits for the mailbox beep, then leaves its message.
  • agent_speaks_first works: with true, the agent greets the other person as soon as the call connects.
  • disclaimer works: the call speaks it word for word when the call connects, before the agent speaks.

Resia refuses a call that breaks one of these rules with 422. Some result fields have different values for these calls. See Results of a speech-to-speech call.

Multi-party calls

An agent can bring more people onto a call, such as a pharmacist onto a call with a patient. See Bring another person onto a call for the steps. Declare the roster on the agent:

  • primary_participant: what the person at to_phone_number (or the inbound caller) is called, such as "patient". Required when additional_participants is set, and not allowed without it. The names agent, assistant, caller, system, and user are reserved in any letter case. Do not use them here or as an additional_participants key.
  • additional_participants: the other roles, keyed by name (up to 40 characters). Two names must differ by more than letter case, spacing, or character form: Pharmacy and pharmacy cannot both be names, and neither can patient as primary_participant and Patient as a key. Each role has these fields:
Field Required What it does
dial Yes When Resia dials this person. on_agent_request dials only when the agent asks for it during the call. at_start would dial during call setup, but it is not available yet: a save with at_start returns 422.
intro No How this person joins. private_first, the default, lets the agent talk with them privately while everyone else waits on hold, then merges them onto the call. direct connects them with the caller as soon as they answer, and the agent leaves the call.
phone_number No A fixed number in E.164 format, such as an escalation desk. If you leave it out, each call supplies the number.
extension No Keys that Resia presses after the line answers, such as ww204, to reach an extension behind a phone menu. Digits, *, #, w (0.5-second pause), and W (1-second pause), up to 64 characters. A call can replace it. Do not put a PIN or another secret in an extension. Every call read shows it. See Reach an extension.

Each phone number uses E.164 form. See Number format.

{
  "primary_participant": "patient",
  "additional_participants": {
    "pharmacy": {"dial": "on_agent_request", "intro": "private_first", "phone_number": null}
  }
}

Then pass numbers for those roles in each call's additional_participants, such as {"pharmacy": "+16175550188"}. A role with a fixed phone_number needs no entry. The agent decides during the call when to bring each person on. Multi-party calls go through POST /v1/calls. Call batches do not accept them.

An agent can name up to 20 additional participants, and it adds one of them at a time: the person the caller asks for. Today each one needs dial set to on_agent_request. intro can be private_first or direct. A save with dial set to at_start is refused with 422, and the error names the limit. An agent that Resia stored earlier with at_start stays unchanged, and a call to it is refused with the same 422.

An inbound call has no request that can supply a number, so every role on an inbound agent needs a fixed phone_number. If the roster cannot be served, for example because a role has no fixed number, Resia does not answer the inbound call, and it rings out.

Archive an agent

DELETE /v1/call-agents/{call_agent_id} archives the agent. Its call history stays. The name of an archived agent stays in use: a new agent with the same name gets 409. Resia refuses the archive with 409 while an active Orchestration Agent lists the agent.

In the portal

Open Agents to see every agent and its review state. Select an agent to see its inputs, instructions, outputs, and webhooks as a diagram, and to edit it.

In the Visual Builder, choose a call in Replay a call to see that call's inputs, outputs, status, and cost on the diagram. Turn on Show statistics and pick a Statistics period to see how the agent's calls went across a range of days. Select Test call in the page header to place one real call with the saved, active version. The diagram follows the live call, and normal call charges apply.

A Call Agent in the portal's Visual Builder, showing inputs, instructions, outputs, and the post-call webhook

Guides

API reference

Call Agents endpoints