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

  • For Resia staff only. Omit it: your key acts on your own organization.

Body·

required
application/json
  • Properties: 1
  • Properties: 1
  • The instructions the agent follows for each chat. Use $name or ${name} to insert a top-level input property. Declare every placeholder in input_schema.properties. Supply every referenced value in the chat's inputs, even if the schema does not require it. Use $$ for a literal dollar sign. Nested property paths are not supported.

  • HTTPS 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.

  • HTTPS 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.

  • 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.

    Properties: 2
  • 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.

    Properties: 1
  • 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
Request Example for post/v1/chat-agents
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"
}