Receive and reply to human texts
Use your own inbox to receive SMS and MMS. Reply from the same Resia number through the API. No AI executes. In this guide, you will connect a receiver, read inbound texts, send a reply, and disable the receiver.
Before you start
- Complete Get access. Keep that terminal open, with
RESIA_API_BASEandRESIA_API_KEYset. - Use a number your organization owns. Complete business texting registration for outbound messages.
- Prepare an HTTPS receiver. See Test webhooks through a public tunnel.
- These steps send real texts and use your prepaid balance. See Billing.
Connect your inbox
Set your owned number and receiver URL:
read -r -p 'Owned number: ' PHONE_NUMBER
read -r -p 'Receiver HTTPS URL: ' WEBHOOK_URL
curl --fail-with-body --silent --show-error --request PUT \
"$RESIA_API_BASE/v1/text-messages/receivers/$PHONE_NUMBER" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--data "$(jq -n --arg url "$WEBHOOK_URL" '{webhook_url:$url}')"
Expected result: 200 with the owned number ID and saved URL.
API reference: Set or clear a human text receiver.
The request body has this shape:
{"webhook_url": "https://inbox.example.com/hooks/secret-token"}
Treat the complete URL as a credential. Resia uses HTTPS and URL secrecy for delivery authenticity.
A number cannot have both a human receiver and an inbound Chat Agent. Pending or active SMS chats also prevent registration.
Conflicting assignments and new AI SMS chats return 409. Voice calls are independent.
Check the saved configuration with GET /v1/text-messages/receivers/{phone_number}.
Receive a message
Resia saves each inbound message before it acknowledges the carrier. Resia POSTs this event to your endpoint:
{
"type": "text_message.received",
"text_message": {
"text_message_id": "received-message-id",
"phone_number_id": "owned-number-id",
"from_phone_number": "+12125550142",
"to_phone_number": "+14155550100",
"text": "Please call tomorrow.",
"received_at": "2026-11-19T15:04:05Z",
"media_urls": []
}
}
Return any 2xx status to acknowledge the event. Use text_message_id to discard duplicate deliveries.
received_at records gateway receipt time. The sender can be a short code.
An MMS can contain an empty text and media URLs. Carrier URLs expire; copy needed media promptly into your own storage.
Resia omits invalid or non-HTTPS carrier media entries. It retains valid URLs in their original order and retains the text.
If every URL is invalid and the text is empty, Resia still saves the received record and sends its event with empty content.
Resia does not guarantee media URL lifetime. Protect received content and media URLs as sensitive data.
Read saved messages:
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/text-messages/received" \
--header "Authorization: Bearer $RESIA_API_KEY"
Expected result: 200 with items, newest first. Follow next_cursor for another page.
API reference: List received text messages.
Optional filters are phone_number_id and from_phone_number. The sent-message ID route does not read received messages.
Group conversations by your number and the sender number. A received message does not identify an outbound batch.
Send a reply
Use a recipient who consented:
read -r -p 'Consenting recipient: ' RECIPIENT
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/text-messages" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--data "$(jq -n --arg sender "$PHONE_NUMBER" --arg recipient "$RECIPIENT" '{from_phone_number:$sender,to_phone_number:$recipient,text:"We will call tomorrow."}')"
Expected result: 202 with one text_message outcome.
API reference: Send one text message.
An SMS request has this shape:
{
"from_phone_number": "+14155550100",
"to_phone_number": "+12125550142",
"text": "We will call tomorrow.",
"media_urls": []
}
The 202 response contains one text_message outcome. Read its ID through GET /v1/text-messages/{text_message_id}.
Keep your submitted text and media in your inbox; sent-message reads contain outcomes, not sent content.
An Idempotency-Key is optional. Reuse the same key and exact content for a safe retry. Changed content returns 409.
Without a key, a repeated request can send another message.
For MMS, supply ordered HTTPS media_urls. The carrier must be able to fetch each URL when the message leaves the queue.
text is required. Exactly "" is valid only with media. Nonempty text must not be blank and cannot exceed 1,600 characters.
The SMS part limit applies only without media. Carrier formats and size rules also apply.
Only send messages to people who consented. Existing STOP and START rules apply.
Disable the receiver
Clear the saved URL to stop new human text delivery:
curl --fail-with-body --silent --show-error --request PUT \
"$RESIA_API_BASE/v1/text-messages/receivers/$PHONE_NUMBER" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' --data '{"webhook_url":null}'
Expected result: 200 with webhook_url: null.
API reference: Set or clear a human text receiver. New texts are not saved as human texts while the receiver is cleared. Resia abandons pending deliveries. Saved received messages remain available through the recovery list.
If something fails
404: check that your organization owns the number.429: wait for the rate window to reset.409: clear the conflicting AI SMS route or wait for open SMS chats to end.422: check the required text, recipient, and HTTPS media URLs.402: fund the organization balance before a new send.- A failed receiver attempt appears in request logs. Resia makes up to six attempts.
Next steps
- Send text messages in bulk: send to multiple recipients.
- Webhooks: check acknowledgements and retries.

