Answer texts to your number
When a person texts your Resia number, a Chat Agent can answer.
Resia starts a new chat when a person's first text arrives, so you do not send POST /v1/chats for it. Later texts from the same person go to that chat until it ends.
In this guide, you will create a Chat Agent, assign it to your number, and test it with a text.
A number with a human text receiver refuses Chat Agent assignment and new AI SMS chats with 409. Voice calls remain independent.
Before you start
- Complete Get access. Keep that terminal open, with
RESIA_API_BASEandRESIA_API_KEYset. - Use a Resia number that your organization owns. The agent's replies need that number on an active 10DLC campaign; see Register for 10DLC texting. The assignment below is refused until the number shows as
ASSIGNEDon that campaign; see See which numbers are on a campaign.
Create a Chat Agent for texts to your number
The person's text opens the chat, so the agent answers it. For a first test, use an agent that needs no inputs.
Do not add STOP, HELP, or other opt-out text.
Ask the agent to keep its replies short.
The text size limits also apply to SMS replies: up to 1,530 characters with GSM-7 characters only, and up to 670 with any other character, such as á or an emoji.
Resia does not check a reply's size before the send. If the carrier refuses a reply for its size, the person gets no text, and the agent is not told. See Text size in a text-message chat.
Resia adds no opt-out notice to these replies.
A refused reply does not set the chat's failure field or end the chat.
cat > inbound-chat-agent.json <<'JSON'
{
"name": "My first inbound text agent",
"instructions": "You answer questions from patients who text the clinic. Answer in short, plain sentences. End the chat when the patient has no more questions.",
"input_schema": {"type": "object", "properties": {}, "additionalProperties": false},
"analysis_prompt": "Record the patient's main question.",
"analysis_schema": {
"type": "object",
"properties": {"question": {"type": "string"}},
"required": ["question"],
"additionalProperties": false
}
}
JSON
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/chat-agents" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @inbound-chat-agent.json \
--output inbound-chat-agent-response.json
jq '{id, review_status, is_active}' inbound-chat-agent-response.json
Expected result: HTTP 201, an id, and the agent's review state.
Continue only when review_status is approved and is_active is true.
In the portal: open Agents, select New agent, and choose Chat Agent.
API reference: Create a Chat Agent.
Assign the agent to your number
This action changes which Chat Agent answers new texts to the selected number. A number can have an inbound Call Agent and an inbound Chat Agent at the same time. This request changes only the Chat Agent.
read -r -p 'Your Resia number, including + and country code: ' RESIA_PHONE_NUMBER
CHAT_AGENT_ID=$(jq -er '.id' inbound-chat-agent-response.json)
jq -n --arg agent "$CHAT_AGENT_ID" \
'{inbound_chat_agent_id: $agent}' > inbound-chat-assignment.json
curl --fail-with-body --silent --show-error \
--request PATCH "$RESIA_API_BASE/v1/phone-numbers/$RESIA_PHONE_NUMBER" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @inbound-chat-assignment.json
Expected result: HTTP 200 with the selected inbound_chat_agent_id.
If the number is not ASSIGNED on an active 10DLC campaign, the response is 422, because the agent's replies would fail at the carrier. Attach the number with Put a number on a campaign, wait until it shows as ASSIGNED, and retry.
If the agent has a required input and no inbound_input_webhook_url, the response is 422, because a text that starts a chat has no inputs of its own.
Add the webhook below, or make every input optional.
In the portal: select Manage next to the number and choose the Chat Agent. The choice is locked until the number is on an active 10DLC campaign.
API reference: Assign an inbound agent.
Test it
- Text the Resia number from another phone.
- List the agent's chats and find the new one.
- Read that chat to see the transcript.
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/chats?chat_agent_id=$CHAT_AGENT_ID&limit=5" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--output inbound-chats.json
jq '.items[] | {id, status, participant_handle}' inbound-chats.json
Expected result: A new chat with status active and your phone number as participant_handle.
Later texts from the same person go to the same chat until it ends.
To stop answering texts on the number, send {"inbound_chat_agent_id": null} through the same PATCH operation.
In the portal: open History → Chats to see the new chat and its transcript.
To list only the chats that one orchestration run started, send orchestration_run_id instead of chat_agent_id.
To also see each tool request and result of a chat, read it with include_tool_activity=true. Give an agent a custom tool lists the fields.
API reference: List chats and Read one chat.
Choose who can text
Without an inbound endpoint, anyone who texts the number starts a chat.
To give the agent details about the person, or to answer only people you know, set inbound_input_webhook_url on the Chat Agent. The endpoint works as an allow list.
See Give an inbound agent details about the caller.
If something fails
422when you assign the agent and the message names 10DLC: the number is notASSIGNEDon an active campaign yet. See which numbers are on a campaign.422when you assign the agent: the agent has a required input and noinbound_input_webhook_url.- No chat after a text: check the number assignment and that the agent is active. If
inbound_input_webhook_urlis set, inspect request logs for its response or timeout. - A chat, but no reply reaches the phone: check that the number is on an active 10DLC campaign.
- No reply and no new chat while
paid_actions_allowedis false inGET /v1/billing(your balance is $0.00 or less): Resia does not answer the text and does not call your inbound webhook. Add funds; the next text gets a reply. 402when you start a chat:paid_actions_allowedis false. Add funds, then retry.
Next steps
- Send text messages in bulk: one-way texts to many people.
- Run a web chat: the same Chat Agent inside your own web page.
- Chats and text messages: every field and status.

