---
title: Chats | API Docs
description: 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: `user@example.com`
- No spaces, dashes, or parentheses in phone numbers

## Create a chat

Chats are created by sending the first message. See [Starting a conversation](/guides/messaging/sending-messages#starting-a-conversation/index.md) in the Sending Messages guide for the full example, or the [Create Chat API reference](/api/resources/chats/methods/create/index.md).

## 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](/api/resources/chats/methods/list_chats/index.md).

## Retrieve a chat

Fetch a single chat by ID. The response includes participants, conversation protocol, [chat health](/guides/chats/chat-health/index.md), and more. See the [Retrieve Chat API reference](/api/resources/chats/methods/retrieve/index.md) for full details.

## 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](/api/resources/chats/methods/mark_as_read/index.md).

> **Note:** Calling mark-as-read on a [group chat](/guides/chats/group-chats/index.md) has no effect. Read receipts only exist in one-to-one iMessage and RCS conversations.

## Related

- [Group Chats](/guides/chats/group-chats/index.md) — creating chats, managing participants, group name / icon, leaving a group
- [Typing Indicators](/guides/chats/typing-indicators/index.md) — typing state inside a chat
- [Chat Health](/guides/chats/chat-health/index.md) — how we score chat health and what it means for your line
- [Sending Messages](/guides/messaging/sending-messages#message-parts/index.md) — posting messages to a chat
- [API Reference: Chats](/api/resources/chats/index.md)