Guides

Give an inbound agent details about the caller

An inbound call or text arrives with nothing but the phone numbers. To let the agent greet a known person by name, or to answer only people you know, Resia asks your server for the inputs before the agent answers. In this guide, you will build that endpoint, set it on a Call Agent or a Chat Agent, and test it with a call or a text.

Before you start

Build the endpoint

Resia sends one POST for each new inbound call or chat. For a call, the body is:

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

For a text that starts a new chat, the body is:

{
  "type": "chat.incoming",
  "chat": {
    "channel": "sms",
    "participant_handle": "+12125550142",
    "agent_handle": "+16465550175"
  }
}

Neither body contains what the person says or writes. Later texts in the same chat send no event.

Look the person up by from_phone_number or participant_handle. Answer within 30 seconds with HTTP 200 and the inputs envelope. The values must match the agent's input_schema. For the reminder agent from Personalize each call with inputs, that is both of its inputs: 

{"inputs": {"patient_name": "Ada", "appointment_time": "Thursday at 3:30 PM"}}

Rules for the endpoint:

  • Resia makes one attempt and does not retry. The same event can arrive more than once, so the endpoint must only read data.
  • Return the envelope, not a bare inputs object. The body can be at most 1 MiB.
  • Put your own token in the URL, such as https://example.com/resia/inbound?token=..., and check it on every request. Resia stores the URL in the clear, so limit who can read the agent.

Set the endpoint on the agent

Set inbound_input_webhook_url on the agent that answers the number. The setting takes effect at once, without review.

In the portal: open the agent and its Settings tab, and fill in Inbound input webhook URL.

With the API, send a complete update, as in Change what an agent says, with the field added:

read -r -p 'Call Agent id: ' CALL_AGENT_ID
read -r -p 'Your HTTPS endpoint: ' WEBHOOK_URL

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --output agent-current.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/openapi.json" --output resia-openapi.json

jq --slurpfile api resia-openapi.json --arg url "$WEBHOOK_URL" \
  'with_entries(select(.key as $key | $api[0].components.schemas.CallAgentWrite.properties | has($key))) | .inbound_input_webhook_url = $url' \
  agent-current.json > agent-update.json

curl --fail-with-body --silent --show-error \
  --request PUT "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @agent-update.json \
  | jq '{id, inbound_input_webhook_url}'

Expected result: HTTP 200 with your URL in inbound_input_webhook_url.

For a Chat Agent, use /v1/chat-agents/{chat_agent_id} and the ChatAgentWrite schema in the same way.

API reference: Replace a Call Agent and Replace a Chat Agent.

Test it

  1. Call or text your Resia number from a phone number that your endpoint knows.
  2. Confirm that the agent uses the details, for example that it greets you by name.
  3. Read the record. A call holds the values in inputs:
read -r -p '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=1' \
  | jq '.items[0] | {id, direction, inputs}'

Expected result: direction is inbound and inputs holds what your endpoint returned. For a chat, read its transcript with GET /v1/chats/{chat_id}.

In the portal: open History → Calls or History → Chats and select the record to read its transcript.

API reference: List calls and Read one chat.

When the endpoint fails

A timeout, a status other than 200, an unreadable body, or values that the schema rejects count as a failure. The two agent types then differ:

  • Call Agent: an agent that accepts an empty object answers without personalization. Any other Call Agent lets the call ring out.
  • Chat Agent: no chat starts, and Resia sends no reply. So the endpoint works as an allow list: answer 200 with inputs for a person you accept, and 404 for anyone else.

Resia refuses to assign an agent that needs inputs to a number until the agent has this URL, with 422, because an inbound call or text supplies no inputs of its own. Outbound calls and chats never use this URL. They carry their inputs in the start request.

If something fails

  • The call rings out, or the text gets no reply: read the attempt in request logs with kind=webhook. Check the status your endpoint returned and whether it answered within 30 seconds.
  • The agent answers a call without the details: your endpoint failed, and the agent accepts empty inputs. Read the request log.
  • 422 when you assign the agent to a number: the agent needs inputs and has no inbound_input_webhook_url.
  • The call rings out before any request reaches your endpoint: your organization is at its limit for calls in progress. See Concurrent calls.

Next steps

Previous
Receive an inbound call
Next
Call a list of numbers