Let an agent answer from your data

An agent can look up your own data during a call or a chat, such as your services, locations, and prices. You publish the data as a JSON export at an HTTPS URL. Resia imports it into a database and reads the export again before each conversation that uses it. In this guide, you will publish an export, create a database, and use it on a call and in a chat.

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 place to publish a JSON file at a public HTTPS URL.
A test call is a real call. Normal call charges apply.

Publish the export

The export is one JSON object. Every top-level value is an array of row objects:

{
  "services": [
    {"name": "Eye exam", "duration_minutes": 30, "price_usd": 120},
    {"name": "Contact lens fitting", "duration_minutes": 45, "price_usd": 90}
  ],
  "locations": [
    {"name": "Midtown", "address": "100 W 40th St, New York, NY", "phone": "+12125550100"}
  ]
}

Resia does not support other values beside the arrays. Change the file whenever your data changes. Resia reads it again before each call or chat that uses the database.

If your server sends an ETag or a Last-Modified header, change it when the export changes. Resia then sends a conditional request, and your server can answer 304 Not Modified to skip the download. Without a header, Resia downloads the full export each time. See Databases for the refresh rules.

Create the database

read -r -p 'HTTPS URL of your export: ' EXPORT_URL

jq -n --arg url "$EXPORT_URL" '{refresh_url: $url}' > database.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/databases" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @database.json \
  --output database-response.json

jq '{id, ready, last_source_version}' database-response.json

Expected result: HTTP 201. Resia imports the export at once. ready is true when the first import worked. A database that is not ready answers no calls until a later refresh succeeds.

In the portal: open Databases, select Add database, and enter the URL. The page shows the status and the imported version. Select Check again to read them again.

The Databases page in the portal, with one database and its import status

API reference: Create a database and Read one database.

Use it on a call

Pass the ID as database_id when you place the call. The agent can then look answers up in your data during the conversation.

DATABASE_ID=$(jq -er '.id' database-response.json)
read -r -p 'Call Agent id: ' CALL_AGENT_ID
read -r -p 'Your phone number, including + and country code: ' TO_PHONE_NUMBER
CALL_REQUEST_KEY=$(uuidgen)

jq -n --arg agent "$CALL_AGENT_ID" --arg phone "$TO_PHONE_NUMBER" --arg database "$DATABASE_ID" \
  '{call_agent_id: $agent, to_phone_number: $phone, inputs: {}, database_id: $database}' > database-call.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/calls" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CALL_REQUEST_KEY" \
  --data-binary @database-call.json \
  | jq '{id, status}'

Expected result: HTTP 202. Answer the phone and ask about something in your export, such as the price of a service.

A database that is not ready, or not in your organization, counts as none: the call answers without it. A Call Agent whose model_architecture is speech_to_speech cannot use a database. A call batch cannot name a database. Place those calls with POST /v1/calls.

API reference: Place a call.

Use it in a chat

Add database_id to POST /v1/chats in the same way. See Run a web chat for the chat request.

Resia prepares the database before it creates the chat. The chat keeps that database until it ends. A refresh failure keeps the last usable copy.
A database that is not ready, or not in your organization, becomes null, and the chat starts without data. Read database_id on the chat to see what it uses.
A retry of the chat request that resolves to a different database is refused with 409.

API reference: Start a chat.

If something fails

ready is false: Resia could not import the export. Check that the URL is public HTTPS and that the body is a JSON object whose values are arrays of objects. Fix the export. Resia reads it again before the next call or chat that names the database.
The agent does not use the data on a call: read the database. It must be ready before the call starts.
last_source_version does not change after you updated the export: your server returned the same ETag or Last-Modified value. Change the header when the data changes.

Next steps

Give your agents a custom tool: let the agent act in your system, not only read from it.
Databases: the export format and the refresh rules.
Run a web chat: a chat that can use the same data.

Run a web chat

Give your agents a custom tool