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_BASE and RESIA_API_KEY set.
  • 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.

A phone number's page in the portal, with the Call Agent that answers inbound calls

API reference: Assign an inbound Call Agent.

Test an inbound call

  1. Call the Resia number directly from another phone.
  2. Confirm that the expected agent answers.
  3. 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.

  1. 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."
  2. Place a call with that agent to your Resia number, as in the Quickstart. Set to_phone_number to your Resia number.
  3. Wait until the call ends.
  4. 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_active value, and the required inputs.
  • The phone does not answer and inbound_input_webhook_url is 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.incoming webhook. GET /v1/rate-limits shows the limit as call.concurrent and the count as call.in_progress. See Concurrent calls.
  • 422 when you assign the agent: the agent has a required input and no inbound_input_webhook_url. Add the webhook, or make every input optional.

Next steps