Receive an inbound call
Resia lets your Call Agent answer inbound calls to a Resia phone number. In this guide, you will assign an agent to a Resia number and make a test call.
Before you start
- Complete Get access. Keep that terminal open, with
RESIA_API_BASEandRESIA_API_KEYset. - An approved, active Call Agent. The Quickstart creates one.
- A Resia number that your organization owns and can use for this test.
- Write every phone number in E.164 form, such as
+12125550142. See Number format.
For your first inbound test, use an agent that needs no inputs.
Set agent_speaks_first to true if the agent should greet the caller immediately.
Find your Resia number
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/phone-numbers" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--output phone-numbers.json
jq '.items[] | {phone_number, inbound_call_agent_id}' phone-numbers.json
Expected result: Each item shows a number and the agent that currently answers it, or null if none does.
If next_cursor is not null, another page exists.
If you have no number, buy one. See Buy a phone number. To answer a number that stays on your own carrier or phone system, see Connect your own number.
A number costs one month when its order completes, then one month on the same day of each later month until you release it.
In the portal: open Numbers. The Inbound calls column shows the agent that answers each number.
API reference: List your phone numbers.
Assign the agent
This action changes which agent answers new calls to the selected number. Record the current assignment before you replace it.
read -r -p 'Your Resia number, including + and country code: ' RESIA_PHONE_NUMBER
read -r -p 'The active Call Agent id: ' CALL_AGENT_ID
jq -n --arg agent "$CALL_AGENT_ID" \
'{inbound_call_agent_id: $agent}' > inbound-assignment.json
curl --fail-with-body --silent --show-error \
--request PATCH "$RESIA_API_BASE/v1/phone-numbers/$RESIA_PHONE_NUMBER" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @inbound-assignment.json
Expected result: HTTP 200 with the selected inbound_call_agent_id.
The path contains the full phone number, not a phone number record ID.
If the agent has a required input and no inbound_input_webhook_url, the response is 422, because every call to the number would ring out. An optional input needs no webhook: without a value, its variable is empty.
A speech-to-speech agent supports inbound assignment on a number bought from Resia and on your own number.
In the portal: open Numbers, select Manage next to the number, choose the Call Agent, and select Save.

API reference: Assign an inbound Call Agent.
Test an inbound call
- Call the Resia number directly from another phone.
- Confirm that the expected agent answers.
- Inspect the result with Get results after a call.
Restore or remove the assignment
To restore the previous agent, repeat the assignment with its ID.
To stop Resia from answering on the number, send {"inbound_call_agent_id": null} through the same PATCH operation.
In the portal: select Manage next to the number, choose the previous agent or No agent, and save.
Test your inbound agent with the API
You can also test without a second phone. Place a call to your Resia number with a different Call Agent that plays the caller.
- Create a second Call Agent whose instructions describe the caller, for example: "You are a patient who calls the clinic to ask about office hours. Ask one question, listen to the answer, and end the call."
- Place a call with that agent to your Resia number, as in the Quickstart. Set
to_phone_numberto your Resia number. - Wait until the call ends.
- List the calls of the answering agent and find the inbound record:
read -r -p 'The answering Call Agent id: ' CALL_AGENT_ID
curl --fail-with-body --silent --show-error --get \
"$RESIA_API_BASE/v1/calls" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--data-urlencode "call_agent_id=$CALL_AGENT_ID" \
--data-urlencode 'limit=5' \
--output inbound-calls.json
jq '.items[] | {id, direction, status, from_phone_number, to_phone_number}' inbound-calls.json
Expected result: A call with direction inbound and your Resia number as to_phone_number. Read it with GET /v1/calls/{call_id} to see the transcript.
A call to your own Resia number creates two call records: one outbound record for the calling agent and one inbound record for the answering agent. Normal call charges apply to both calls.
API reference: List calls.
Add caller-specific information later
The agent answers with no details about the caller. To greet a known person by name, your server can supply the inputs before the call answers.
Set inbound_input_webhook_url on the Call Agent. See Give an inbound agent details about the caller.
If something fails
- The phone does not answer: check the number assignment, the agent's
is_activevalue, and the required inputs. - The phone does not answer and
inbound_input_webhook_urlis set: inspect request logs for its response or timeout. See Give an inbound agent details about the caller. - The phone still does not answer: your organization can be at its limit for calls in progress. Inbound and outbound calls share that limit. At the limit, a new inbound call rings out before Resia sends the
call.incomingwebhook.GET /v1/rate-limitsshows the limit ascall.concurrentand the count ascall.in_progress. See Concurrent calls. 422when you assign the agent: the agent has a required input and noinbound_input_webhook_url. Add the webhook, or make every input optional.
Next steps
- Get results after a call: read the transcript and analysis of the test call.
- Answer texts to your number: answer texts to the same number.
- Connect your own number: answer and place calls on a number on your own carrier.
- Callbacks: what a person reaches when they call a number that called them.
- Preserve context between calls: an orchestration run gives this agent the context of a call that it expects.

