Chats
Overview of chats — conversation threads with one or more participants.
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
[email protected] - No spaces, dashes, or parentheses in phone numbers
Create a chat
Section titled “Create a chat”Chats are created by sending the first message. See Starting a conversation in the Sending Messages guide for the full example, or the Create Chat API reference.
List chats
Section titled “List chats”List every chat the authenticated partner has access to, optionally filtered by sender number (from) or participant (to). Results are paginated — pass the previous response’s next_cursor back as cursor until it returns null. Default page size is 20, max is 100. See the List Chats API reference.
Retrieve a chat
Section titled “Retrieve a chat”Fetch a single chat by ID. The response includes participants, conversation protocol, chat health, and more. See the Retrieve Chat API reference for full details.
Mark a chat as read
Section titled “Mark a chat as read”Mark every message in a chat as read, which sends a read receipt on iMessage/RCS. See the Mark As Read API reference.
Note: Calling mark-as-read on a group chat has no effect. Read receipts only exist in one-to-one iMessage and RCS conversations.
Related
Section titled “Related”- Group Chats — creating chats, managing participants, group name / icon, leaving a group
- Typing Indicators — typing state inside a chat
- Chat Health — how we score chat health and what it means for your line
- Sending Messages — posting messages to a chat
- API Reference: Chats