Chats and text messages
Resia runs text conversations in two ways:
- A chat is a two-way conversation between a Chat Agent and one person, over text messages or in your own web page.
- A text message is a one-way message, such as a reminder. Send many at once with a text message batch.
Chat Agents
A Chat Agent is the text version of a Call Agent. It has the same required fields (name, instructions, input_schema, analysis_prompt, analysis_schema), the same $name variables, and the same review process.
Optional fields:
| Field | What it does |
|---|---|
description |
One line that says what the agent is for. |
inbound_input_webhook_url |
Supplies inputs when a person texts your number, and decides who may chat. See Give an inbound agent details about the caller. |
chat_ended_webhook_url |
Receives a chat.ended event when each chat ends. |
milestones |
Named stages that the chat can report. |
tools |
The names of your organization's custom tools that chats of this agent may use, at most 64. See Give your agents a custom tool. |
Do not add STOP, HELP, or other opt-out wording to the instructions. In a text-message chat, Resia adds the required notice itself. A web chat does not need it.
Channels
| Channel | How it starts | Needs a phone number? |
|---|---|---|
sms, outbound |
You call POST /v1/chats with the person's phone number as participant_handle. |
Yes, on an active 10DLC campaign. |
sms, inbound |
A person texts a number that has an inbound_chat_agent_id. |
Yes, on an active 10DLC campaign. |
web |
You call POST /v1/chats with your own ID for the person. Your server relays messages. |
No |
Text size in a text-message chat
Each text of an SMS chat has the text size limits of any text: at most 10 SMS parts. That is up to 1,530 characters when the text has only GSM-7 characters, and up to 670 characters when it has any other character, such as á, í, ó, ú, or an emoji. The opt-out notice that Resia adds to an opener uses the same space.
The agent writes its own texts, so Resia does not check their size before it sends them. The carrier refuses a text above the limit:
- A refused opener ends the chat as
failed. Itsfailureexplains the size limit. - A refused reply does not reach the person, and the chat stays open. The agent is not told.
Ask the agent in its instructions to keep each text short. For a chat in Spanish, ask it to stay well under 670 characters.
Chat status
| Status | Meaning |
|---|---|
pending |
Resia accepted the chat. The agent is writing its first message. |
active |
The conversation is open. |
post_processing |
The conversation ended. Resia is writing the chat's analysis, usually for a few seconds. |
completed |
The agent finished its task and ended the chat. analysis holds the result. |
cancelled |
You cancelled it with POST /v1/chats/{chat_id}/cancel. A chat that started keeps the analysis written after the cancel. |
failed |
The chat never started. When its first text could not be delivered, failure gives the reason, such as sender_not_registered. |
A chat that started always passes through post_processing before it ends as completed or cancelled. A chat that you cancel before it starts becomes cancelled at once.
Read a chat and its transcript with GET /v1/chats/{chat_id}. Add include_tool_activity=true to also see each tool request and result. List chats with GET /v1/chats, newest first. Filter by chat_agent_id, orchestration_run_id, status, the creation time with created_after and created_before, agent_handle, participant_handle, one analysis pair with analysis_key and analysis_value, or one tag pair. All filters combine. Each item has the chat's analysis, or null before the analysis is written.
To give one chat reference data, add database_id to POST /v1/chats. See Let an agent answer from your data.
Text messages
Use a text message batch to send the same text to up to 1,000 recipients from one of your numbers. Each recipient gets its own text_message_id. See Send text messages in bulk.
Text message status: accepted, queued, sent, delivered, delivery_unconfirmed, failed, or canceled.
Resia sends text messages to numbers in the United States only. Use POST /v1/text-messages for one recipient. Use a batch for multiple recipients.
For human replies, connect a human-text receiver to your number. Your tool receives the messages; your staff replies through the single-send API. No AI executes.
A number uses either a human-text receiver or AI SMS chats. A conflicting assignment returns 409. Pending or active SMS chats prevent receiver registration. Voice calls are independent.
In the portal
To create a Chat Agent, open Agents, select New agent, and choose Chat Agent. Describe the agent and select Create with Butler, or select Create manually instead.
An agent's Visual Builder tab shows one chat as a canvas: how a chat starts, the inputs, the agent, the milestones, the outputs, and the chat-ended webhook. Add milestones on the canvas or on the Behavior tab.
Select Test chat in the page header to start a real web chat with the saved, active version. The chat runs in the Test chat panel on the right of the page, and no text message goes to a phone. The canvas follows the same chat and marks the milestone it reached. Save or revert your changes before you start a test chat. The Chats tab lists the agent's chats. A chat's details show each tool request and result in the conversation, in order.
Guides
- Answer texts to your number
- Run a web chat
- Send an event to a running agent
- Send text messages in bulk
- Register for 10DLC texting

