Create a Chat Agent
Saves the instructions and settings a text conversation should follow. A new Chat Agent may need review before it can run production chats; the response review_status reports whether it is approved or pending review.
Headers
- Type: stringnullableX
- Resia - Organization - Id For Resia staff only. Omit it: your key acts on your own organization.
Body·
- Type: stringanalysis
_prompt required - Properties: 1Type:analysis
_schema required - Properties: 1Type:input
_schema required - Type: stringinstructionsrequired
The instructions the agent follows for each chat. Use
$nameor${name}to insert a top-level input property. Declare every placeholder ininput_schema.properties. Supply every referenced value in the chat'sinputs, even if the schema does not require it. Use$$for a literal dollar sign. Nested property paths are not supported. - Type: stringnamemin length:1required
- Type: stringchat
_ended _webhook _url min length:1Format: urinullableHTTPS URL Resia POSTs a chat.ended event to each time a chat this Chat Agent runs reaches a terminal status. The body is a JSON WebhookEvent: {"type": "chat.ended", "chat": ...}, where chat is the same ChatDetail that GET /v1/chats/{chat_id} returns. Resia makes one immediate attempt when the chat ends and retries a failed delivery on a fixed schedule; any 2xx response is success. The chat's id repeats unchanged across retries, so treat a repeated chat.id as a duplicate. Treat the complete URL as a credential: delivery authenticity is HTTPS plus URL secrecy. Null clears the webhook and stops pending deliveries.
- Type: stringdescriptionmin length:1max length:280nullable
- Type: stringinbound
_input _webhook _url min length:1Format: urinullableHTTPS URL Resia calls to fetch the inputs for a new inbound conversation this agent answers. For a Call Agent, Resia POSTs a call.incoming event — {"type": "call.incoming", "call": {"from_phone_number": , "to_phone_number": }} — when an inbound call arrives. For a Chat Agent, Resia POSTs a chat.incoming event — {"type": "chat.incoming", "chat": {"channel": "sms", "participant_handle": , "agent_handle": }} — when a text starts a new chat; later texts in that chat do not call it. Neither event carries message content. Resia waits up to 30 seconds for a single attempt — no retry. The 200 response body must be the InboundCallInputWebhookResponse envelope, {"inputs": {...}}, at most 1 MiB (1048576 bytes); a bare inputs object is an invalid response. inputs must satisfy this agent's input_schema; it is stored as the call's or chat's inputs and rendered into the agent's instructions. On a timeout, a non-200 status, an unreadable body, or inputs the input schema rejects: a Call Agent whose input schema accepts an empty object answers unpersonalized with empty inputs, and any other Call Agent lets the call ring out; a Chat Agent starts no chat and sends no reply, so a Chat Agent's webhook works as an allow list — answer with inputs for a person you accept (an empty object when the agent needs none) and 404 for anyone else. An agent whose instructions need inputs must have this URL before PATCH /v1/phone-numbers/{phone_number} can assign it to a number. The webhook may be delivered more than once for the same call or person, so the endpoint must be read-only and tolerate duplicates. The URL is not a credential inside Resia: Resia stores it, returns it on reads, and logs it in the clear. Delivery authenticity to your endpoint is HTTPS; embed your own token in the URL if you want to authenticate Resia's requests. Inbound-only: outbound calls and chats always supply inputs in their start request and never consult this URL. Null clears the webhook.
- Type: array of AgentMilestone 1…32nullablemilestonesProperties: 2
The stages a chat with this Chat Agent may report, each a name and a description. During a chat the agent records the stage it has reached, using a name from this list; GET the chat to read the current stage. Names must be unique. Null (the default) means the agent reports no milestone.
- Type: TagsnullableProperties: 1
Open key/value labels on this record. Set any keys and any values. Filter a list by one key and value pair. Resia never interprets a tag. Do not put names, phone numbers, or any personal, health, credential, or secret information in a tag: a tag travels in URLs when used as a filter, and URLs appear in ordinary infrastructure request logs.
- Type: array of string …64nullabletools
The names of your organization's tools that chats of this version may call. Null or an empty list names none.
Responses
- application/json
- application/json
curl https://api.resia.ai/v1/chat-agents \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"name": "",
"description": "",
"chat_ended_webhook_url": "https://example.com",
"inbound_input_webhook_url": "https://example.com",
"tags": {
"additionalProperty": ""
},
"instructions": "",
"input_schema": {
"additionalProperty": null
},
"analysis_prompt": "",
"analysis_schema": {
"additionalProperty": null
},
"tools": [
""
],
"milestones": [
{
"name": "",
"description": ""
}
]
}'
{
"name": "string",
"description": "string",
"chat_ended_webhook_url": "https://example.com",
"inbound_input_webhook_url": "https://example.com",
"tags": {
"additionalProperty": "string"
},
"instructions": "string",
"input_schema": {
"additionalProperty": null
},
"analysis_prompt": "string",
"analysis_schema": {
"additionalProperty": null
},
"tools": [
"string"
],
"milestones": [
{
"name": "string",
"description": "string"
}
],
"id": "string",
"review_status": "pending_review",
"is_active": true,
"created_at": "2026-11-20T21:45:14.986Z",
"submitted_at": "2026-11-20T21:45:14.986Z",
"active_updated_at": "2026-11-20T21:45:14.986Z",
"archived_at": "2026-11-20T21:45:14.986Z"
}
