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_BASEandRESIA_API_KEYset. - 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_urlwhen 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_callsormax_spend_in_cents.
If something fails
422when you assign the agent: an input is inrequired, and the agent has noinbound_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=trueand look forregister_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
waitingafter the call: read the run again after a minute. A run wakes when the call ends, not when it starts.

