> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blujay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chats

> Create, list and read chats, the conversations between your phone numbers and the people you text.

A chat is one conversation between one of your Blujay phone numbers and one or more people. A chat with one person is `direct`; a chat with two or more is a `group`.

## Create a chat

You create a chat by sending its first message with `POST /v1/chats`. See [Sending Messages](https://docs.blujay.io/messaging/send-messages.md#send-the-first-message).

## List chats

```bash curl theme={null}
curl "https://api.blujay.io/v1/chats?limit=25" \
  -H "Authorization: Bearer blu_your_api_key"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.blujay.io/v1/chats?limit=25", {
  headers: { Authorization: `Bearer ${process.env.BLUJAY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.data.map((chat) => chat.chat_id), data.has_more);
```

```python Python theme={null}
import os
import requests

response = requests.get(
    "https://api.blujay.io/v1/chats",
    headers={"Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}"},
    params={"limit": 25},
    timeout=60,
)
data = response.json()["data"]
print([chat["chat_id"] for chat in data["data"]], data["has_more"])
```

Chats come back most recently active first. Pass `next_cursor` as `cursor` for the next page. See [Pagination](https://docs.blujay.io/making-requests.md#pagination).

### Find a person's chats

Add `to` to list only the chats a person is in, direct and group, by their phone number or email address. Add `from` to keep only the chats on one of your numbers. Together they find the direct chat between your number and that person:

```bash curl theme={null}
curl -G https://api.blujay.io/v1/chats \
  --data-urlencode "to=+15555550123" \
  --data-urlencode "from=+15555550100" \
  -H "Authorization: Bearer blu_your_api_key"
```

```javascript Node.js theme={null}
const params = new URLSearchParams({ to: "+15555550123", from: "+15555550100" });
const response = await fetch(`https://api.blujay.io/v1/chats?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BLUJAY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.data.find((chat) => chat.type === "direct")?.chat_id);
```

```python Python theme={null}
import os
import requests

response = requests.get(
    "https://api.blujay.io/v1/chats",
    headers={"Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}"},
    params={"to": "+15555550123", "from": "+15555550100"},
    timeout=60,
)
chats = response.json()["data"]["data"]
print(next((chat["chat_id"] for chat in chats if chat["type"] == "direct"), None))
```

* `to` takes a US phone number, in E.164 or US format, or an email address. Groups the person has left aren't included.
* Passing one of your own numbers in `to` returns `400` [`VALIDATION_ERROR`](https://docs.blujay.io/errors/validation-error); use `from` for that.
* A `from` number that isn't in your workspace returns an empty list.

## Retrieve a chat

```bash curl theme={null}
curl https://api.blujay.io/v1/chats/chat_abc123 \
  -H "Authorization: Bearer blu_your_api_key"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.blujay.io/v1/chats/chat_abc123", {
  headers: { Authorization: `Bearer ${process.env.BLUJAY_API_KEY}` },
});
const { data } = await response.json();
console.log(data.type, data.service, data.participants);
```

```python Python theme={null}
import os
import requests

response = requests.get(
    "https://api.blujay.io/v1/chats/chat_abc123",
    headers={"Authorization": f"Bearer {os.environ['BLUJAY_API_KEY']}"},
    timeout=60,
)
data = response.json()["data"]
print(data["type"], data["service"], data["participants"])
```

| Field | What it tells you |
| - | - |
| `type` | `direct` or `group` |
| `participants` | The people in the chat, with their `contact_id` |
| `phone_number_id` | Which of your numbers the chat uses |
| `service` | `iMessage`, `RCS` or `SMS`, once Blujay has confirmed it |

## Read a chat's messages

`GET /v1/chats/{chat_id}/messages` returns the messages in one chat. See [Sending Messages](https://docs.blujay.io/messaging/send-messages.md#read-chats-and-messages).

## Mark a chat as read

`POST /v1/chats/{chat_id}/read` marks the chat read and, in direct iMessage and RCS chats, sends a read receipt. See [Typing and Read Receipts](https://docs.blujay.io/messaging/typing-and-read-receipts.md#mark-a-chat-as-read).

## Related

> [card] [Group Chats](https://docs.blujay.io/messaging/group-chats.md)
>
> Start a group, change its name and photo, and manage who's in it.

> [card] [Number Lookup](https://docs.blujay.io/messaging/choosing-a-service.md)
>
> Check whether a number uses iMessage before you text it.

> [card] [Typing and Read Receipts](https://docs.blujay.io/messaging/typing-and-read-receipts.md)
>
> Show typing and mark chats as read.

> [card] [Name and Photo Sharing](https://docs.blujay.io/messaging/name-and-photo.md)
>
> Share your number's name and photo with the people you text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.