Preserve context between calls

An orchestration run can tell Resia to expect a call from a person, and give that call the run's context. When the person calls your number, the agent that answers already knows who they are and why they call. When the call ends, the run gets its outcome and continues. In this guide, you will set up the agent that answers expected calls, write an Orchestration Agent that registers the person, start a run, and test the call with your own phone. Read Preserve context between calls for the concepts.

Some examples:

Business The run The later call
School Leaves a message for a parent about a pickup change. The parent calls back, and the agent knows which child and which change.
Restaurant Asks a guest to confirm a large reservation. The guest calls to confirm, and the agent has the date, the time, and the party size.
Clinic Calls about an appointment, and nobody answers. The person returns the call, and the agent knows the appointment.
Repair shop Texts a repair quote. The customer calls to approve it, and the agent has the quote.

The run does not have to call first. It can expect a call after a text, an email, or anything else your systems do.

Register the person before the run places its call or sends its text. A person can call back within seconds, for example right after a voicemail. If the run registers only after its own call ends, that early call takes the normal path and does not get the run's context.

Before you start

  • Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
  • A Resia number that gets the expected calls. See Buy a phone number.
  • The test call is a real inbound call. Normal call charges apply.
  • Write every phone number in E.164 form, such as +12125550142. See Number format.

Create the agent that answers expected calls

The number's inbound Call Agent answers every call to the number. Give it inputs for the context that a run supplies, such as caller_name and reason. Make each input optional: leave it out of required. A caller that no run registered then reaches the same agent, and each variable without a value is empty in the instructions. Write the instructions so that they also work with empty values. The agent needs no inbound_input_webhook_url. To look up an unregistered caller, you can add one; see Give an inbound agent details about the caller.

jq -n '{
  name: "Expected call",
  instructions: "You answer the phone for our business. Caller name, if known: $caller_name. Why we expect the call, if known: $reason. If you know the name, greet them by name. If you know why they call, say so and help them with it. Otherwise ask how you can help. Thank them and end the call.",
  input_schema: {
    type: "object",
    properties: {
      caller_name: {type: "string"},
      reason: {type: "string", description: "Why we expect the call, in one sentence."}
    },
    additionalProperties: false
  },
  analysis_prompt: "Record whether the caller got what they called about, and what they decided.",
  analysis_schema: {
    type: "object",
    properties: {
      resolved: {type: "boolean"},
      decision: {type: ["string", "null"]}
    },
    required: ["resolved", "decision"],
    additionalProperties: false
  },
  agent_speaks_first: true
}' > expected-call-agent.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 @expected-call-agent.json \
  --output expected-call-agent-response.json

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

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

API reference: Create a Call Agent.

Assign the agent to your number

read -r -p 'Your Resia number (E.164): ' RESIA_NUMBER
EXPECTED_CALL_AGENT_ID=$(jq -er '.id' expected-call-agent-response.json)

curl --fail-with-body --silent --show-error \
  --request PATCH "$RESIA_API_BASE/v1/phone-numbers/$RESIA_NUMBER" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "$(jq -n --arg agent "$EXPECTED_CALL_AGENT_ID" '{inbound_call_agent_id: $agent}')"

Expected result: HTTP 200 with your agent in inbound_call_agent_id.

In the portal: open Numbers, select Manage next to the number, choose the Call Agent, and select Save.

API reference: Update a phone number.

Write the Orchestration Agent

Tell the run when to register the caller and what context to give. This example only waits for the call. If your run also calls or texts the person, put that step after the registration, as in the second example. Copy this instruction text, and change the details:

Register the caller $phone_number on the number $resia_number with the call inputs {"inputs": {"caller_name": "$caller_name", "reason": "$reason"}}. Then wait up to one day.
When a finished call with direction inbound arrives, read its analysis and finish the run with it.
If the wait ends with no call, release the registration and finish the run with resolved false.

A run that calls first registers before the call:

Register the caller $phone_number on the number $resia_number with the call inputs {"inputs": {"caller_name": "$caller_name", "reason": "$reason"}}.
Then call $phone_number from $resia_number with the outreach Call Agent.
If the person answers, finish the run with that call's outcome.
If nobody answers, wait up to one day. When a finished call with direction inbound arrives, finish the run with its outcome.

Create the agent as in Create the Orchestration Agent, with this instruction text. Its input_schema declares the strings caller_name, reason, phone_number, and resia_number. It needs no Call Agent in triggerable_call_agent_ids, because the run places no call.

The run registers the caller with the register_inbound_call tool and releases the registration with release_inbound_call. Every run has both tools. Your instructions only say when to use them.

Start a run

Start a run as in Start a run, with these inputs:

{
  "caller_name": "Sam Rivera",
  "reason": "We sent a quote for a brake repair, and Sam can approve it by phone.",
  "phone_number": "+12125550142",
  "resia_number": "+12125550199"
}

Keep the run ID: ORCHESTRATION_RUN_ID=$(jq -er '.orchestration_run_id' orchestration-run-response.json).

Expected result: HTTP 201. Within a minute or two, the run status becomes waiting, and waiting_for says why.

Test the call

To test with your own phone, start a run with your phone number in phone_number. When the run is waiting, call your Resia number from that phone.

Expected result: the agent greets you by the name in the run's inputs and says why it expects your call. About a minute after you hang up, the run wakes and finishes:

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

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/calls?orchestration_run_id=$ORCHESTRATION_RUN_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  | jq '.items[] | {id, direction, from_phone_number, status}'

The run ends with the outcome of your call. The call list has your call with direction inbound.

API reference: List calls.

Limits

  • A registration matches one caller on one number, exactly as written in E.164.
  • One run at a time holds a caller on a number. A second run that registers the same pair is refused, and the first run keeps it.
  • A registration ends when the run releases it or when the run ends. After that, a call from that person takes the normal path: the agent answers with empty values, or with the inputs from its inbound_input_webhook_url when it has one.
  • The run's inputs must fit the agent's current version when the call arrives. If they do not, the agent answers with empty inputs when it accepts them. Otherwise the call rings out, and the run does not wake. Neither case calls an inbound_input_webhook_url.
  • The call costs the same as any inbound call. It does not count against the run's max_calls or max_spend_in_cents.

If something fails

  • 422 when you assign the agent: an input is in required, and the agent has no inbound_input_webhook_url. Make every input optional.
  • The agent answers without the run's context, or the call reaches a different agent: the run did not register that caller on that number, or it ended. Read the run with include_tool_activity=true and look for register_inbound_call.
  • The call rings out: the number has no inbound Call Agent, or the run's inputs do not fit the agent. Compare the inputs with the agent's input_schema.
  • The run stays waiting after the call: read the run again after a minute. A run wakes when the call ends, not when it starts.

Next steps