Receive an inbound call

An incoming call is an inbound call. Assign a Call Agent to a Resia phone number to answer it. You do not send POST /v1/calls to receive a call. This guide also covers the Resia side of call forwarding and return calls.

Before you start

• Complete Get access.
• Create an active Call Agent, such as the agent from the Quickstart.
• Use a Resia number that your organization owns and can use for this test.

For your first inbound test, use an agent with no required input values or placeholders. 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, use the number purchase reference or contact Resia. A number purchase and monthly rental have separate charges.

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 needs inputs and has no inbound_input_webhook_url, the response is 422, because every call to the number would ring out.

API reference: Assign an inbound Call Agent.

Test before call forwarding

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.
4. Configure your existing phone provider to forward calls to this Resia number.
5. Call your original number to test the complete path.

Your phone provider controls call forwarding, including its hours and unanswered-call rules. The Resia assignment does not configure that provider. 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.

Add caller-specific information later

A webhook is an HTTP request that Resia sends to your server. For inbound personalization, set inbound_input_webhook_url on the Call Agent through the agent edit guide. This URL is optional. The first test above does not need it.

Resia sends this shape to your HTTPS URL before the call answers:

{
  "type": "call.incoming",
  "call": {
    "from_phone_number": "+12125550142",
    "to_phone_number": "+16465550175"
  }
}

Reply within 30 seconds with HTTP 200 and the envelope {"inputs": {...}}, where inputs matches the agent's input_schema. For example, an agent that declares topic can receive {"inputs": {"topic": "office hours"}}. Every placeholder in its instructions also needs a value.

Resia puts those values into the instructions before the agent answers. If the request fails, the call can still answer only if the agent can run with empty inputs. Otherwise, the call rings out. Your webhook must tolerate duplicate requests without side effects.

If the phone does not answer: Check the number assignment, agent activation, and required inputs first. If a webhook is configured, inspect request logs for its response or timeout.