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, and 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.
`analysis_schema`	A JSON Schema object for the structured `analysis` result.

Resia refuses a request that contains a field it does not define, with 422. The error message names the field.

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.
`voices`	Up to 32 voices, each a `tts_provider` and `voice_id` from `GET /v1/available-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`.
`in_call_llm`	The provider and model for the live conversation. If you leave it out, Resia uses its current default.
`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 Receive an inbound call.
`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 every variable in the call's inputs, even if the schema marks it optional.
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/available-voices" \
  --header "Authorization: Bearer $RESIA_API_KEY"

The default provider is cartesia. Resia also supports fish; pass ?provider=fish to list those 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"}]

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.

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, and model settings take effect immediately, without review.

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.

Multi-party calls

An agent can bring more people onto a call, such as a pharmacist onto a call with a patient. Declare the roles on the agent:

primary_participant: what the person at to_phone_number (or the inbound caller) is called, such as "patient".
additional_participants: the other roles, keyed by name.

Then pass numbers for those roles in each call's additional_participants, such as {"pharmacy": "+16175550188"}. 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.

Archive an agent

DELETE /v1/call-agents/{call_agent_id} archives the agent. Its call history stays. Resia refuses the archive with 409 while an active Workflow Agent lists the agent.

API reference

Call Agents endpoints

How Resia fits together

Calls and call batches