Personalize each call with inputs

A Call Agent can use details that differ from call to call, such as the person's name and an appointment time. You declare them once on the agent as inputs, and you pass the values with each call. In this guide, you will create a Call Agent with two inputs, place a call with values for them, and check the values on the call.

Before you start

Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
A phone in the United States or Canada to receive the test call.
A test call is a real call. Normal call charges apply.

Create an agent with inputs

Write each input as a variable in the instructions: $patient_name or ${patient_name}. Declare every variable in input_schema.properties. Use $$ for a literal dollar sign. Do not use {{patient_name}} or a nested path such as $person.name.

cat > reminder-agent.json <<'JSON'
{
  "name": "Appointment reminder",
  "instructions": "You are calling $patient_name from Midtown Eye Care to remind them of an appointment on $appointment_time. Ask whether they can still attend. If they cannot, ask which day suits them better. Thank them and end the call.",
  "input_schema": {
    "type": "object",
    "properties": {
      "patient_name": {"type": "string"},
      "appointment_time": {"type": "string", "description": "The day and time in words, for example Thursday at 3:30 PM."}
    },
    "required": ["patient_name", "appointment_time"],
    "additionalProperties": false
  },
  "analysis_prompt": "Record whether the patient confirmed the appointment. If they cannot attend, record the day they asked for.",
  "analysis_schema": {
    "type": "object",
    "properties": {
      "confirmed": {"type": "boolean"},
      "requested_day": {"type": ["string", "null"]}
    },
    "required": ["confirmed", "requested_day"],
    "additionalProperties": false
  },
  "agent_speaks_first": true
}
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 @reminder-agent.json \
  --output reminder-agent-response.json

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

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

In the portal: open Agents and select New agent. In Instructions, type @ to insert a variable from the input schema, or select + Add new variable to declare a new one.

API reference: Create a Call Agent.

Place a call with values

Send one value for each variable in inputs. The names must match the schema.

CALL_AGENT_ID=$(jq -er '.id' reminder-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: {patient_name: "Ada", appointment_time: "Thursday at 3:30 PM"}
}' > reminder-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 @reminder-call.json \
  --output reminder-call-response.json

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

Expected result: HTTP 202 with a call id. Answer the phone. The agent greets you by name and names the appointment time.

Resia puts the values into the instructions before the call starts. A request with values that do not match the schema is refused with 422 and creates no call. A retry with the same Idempotency-Key and corrected values places the call.

In the portal: open the agent and select Test call. The dialog asks for the destination and shows one field for each input.

API reference: Place a call.

Check the values on the call

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

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/calls/$CALL_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '{status, inputs, analysis}'

Expected result: inputs holds the values you sent. After the call ends, analysis holds confirmed and requested_day.

In the portal: open History → Calls and select the call to read its transcript and analysis.

API reference: Read a call.

Where else inputs come from

A call batch takes inputs on each entry. See Call a list of numbers.
An inbound call has no request. Your own endpoint supplies the inputs. See Give an inbound agent details about the caller.
An orchestration run passes values from its own inputs to the Call Agents it dials. See Run an Orchestration Agent.

If something fails

422 when you create the agent: the instructions use a variable that input_schema.properties does not declare, or the schema is not valid.
422 when you place the call: inputs does not match the schema, such as a missing required value or an extra key. No call is created.
The agent says a value in an odd way: write the value as it should be spoken, such as "Thursday at 3:30 PM", not a timestamp.

Next steps

Change what an agent says: edit the instructions of an existing agent.
Call a list of numbers: different values for each person in one request.
Call Agents: every field of an agent.

Change what an agent says

Get results after a call