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. Its failure explains 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

API reference

Chat Agents · Chats · Text Messages · Text Message Batches