List, search, and manage inbound SMS and MMS text messages for your phone numbers. Outbound SMS sending is coming soon. MMS messages include media attachments returned as presigned S3 URLs.
All text endpoints are scoped to a phone number: /numbers/{phone_number_id}/texts/...
Path parameters
Parameter
Type
Description
phone_number_id
UUID
Unique identifier of the phone number
List texts GET
GET /numbers/{phone_number_id}/texts
List text messages for a phone number, newest first. Excludes deleted messages.
Query parameters
Parameter
Type
Default
Description
limit
integer
50
Number of results (1--200)
offset
integer
0
Pagination offset
is_read
boolean
—
Filter by read state. Omit for all messages
Response (200)
JSON
Error responses
Status
Description
403
Phone number belongs to a different organization
404
Phone number not found or released
Get text GET
GET /numbers/{phone_number_id}/texts/{text_id}
Get a single text message by ID.
Path parameters
Parameter
Type
Description
text_id
UUID
Unique identifier of the text message
Response (200)
JSON
MMS messages have type: "mms" and a media array. Each media item includes a content_type, size in bytes, and a presigned url that expires after 1 hour.
Error responses
Status
Description
404
Text not found, wrong phone number, or wrong organization
Update text PATCH
PATCH /numbers/{phone_number_id}/texts/{text_id}
Update a text message. Use this to mark messages as read or to delete them.
Path parameters
Parameter
Type
Description
text_id
UUID
Unique identifier of the text message
Request body
Field
Type
Required
Description
is_read
boolean
No
Mark as read (true) or unread (false)
status
string
No
Set to "deleted" to delete the message. No other status value is accepted
Request example
JSON
Response (200)
Returns the updated TextMessage object.
Error responses
Status
Description
404
Text not found, wrong phone number, or wrong organization
422
Invalid status value. Only "deleted" is accepted
Search texts GET
GET /numbers/{phone_number_id}/texts/search
Full-text search across text message bodies for a phone number. Results are ranked by relevance and exclude deleted messages.
Query parameters
Parameter
Type
Default
Description
q
string
—
Search query (required, 1--500 characters)
limit
integer
50
Number of results (1--200)
Response (200)
Returns a list[TextMessage] matching the query.
Error responses
Status
Description
403
Phone number belongs to a different organization
404
Phone number not found or released
422
Missing or invalid q parameter
List conversations GET
GET /numbers/{phone_number_id}/texts/conversations
List conversation summaries — one row per remote phone number, ordered by most recent message, with the latest message preview and unread count.
Query parameters
Parameter
Type
Default
Description
limit
integer
50
Number of results (1--200)
offset
integer
0
Pagination offset
Response (200)
JSON
Error responses
Status
Description
403
Phone number belongs to a different organization
404
Phone number not found or released
Get conversation GET
GET /numbers/{phone_number_id}/texts/conversations/{remote_number}
Get all messages exchanged with a specific remote number, newest first. The remote_number can be an E.164 phone number (for example +15167251294) or a short code (for example 76934).
JSON