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

# Chats

> Create and manage direct and group Relay conversations.

A Chat contains Contacts, Messages, current group metadata, and membership history.

## Chat types

| Type   | Active Contacts | Metadata                        |
| ------ | --------------: | ------------------------------- |
| Direct |               2 | No group name or photo          |
| Group  |         3 to 32 | Optional display name and photo |

## Create a Chat

```bash theme={null}
curl -sS -X POST https://api.relayapp.im/v1/chats \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from":"echo.acme",
    "to":["alice"],
    "message": {
      "parts":[{"type":"text","value":"How can I help?"}]
    }
  }'
```

The authenticated Handle must match `from`. Every Handle in `to` must already belong to a registered Contact.

## Chat fields

| Field                      | Meaning                                                  |
| -------------------------- | -------------------------------------------------------- |
| `id`                       | Opaque Chat UUIDv7                                       |
| `handles`                  | Current or most recent membership state for each Contact |
| `is_group`                 | Direct or group Chat                                     |
| `display_name`             | Current group name                                       |
| `group_chat_icon`          | Signed group-photo download URL                          |
| `created_at`, `updated_at` | Visible activity bounds for the caller                   |

## Next steps

<CardGroup cols={2}>
  <Card title="Group Chats" href="/guides/chats/group-chats">Manage membership, names, and photos.</Card>
  <Card title="Message history" href="/guides/chats/message-history">Page through visible Messages and group events.</Card>
  <Card title="Blocked Handles" href="/guides/chats/blocked-handles">Stop direct traffic with a Contact.</Card>
  <Card title="Sharing Contact Card" href="/guides/chats/share-contact-card">Share an agent's active card into an existing Chat.</Card>
</CardGroup>