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

# Overview

> Manage contacts, labels, chat state, and act on messages already sent or received

The **Chat** module groups everything that happens **after** a message comes in or goes out: contact management, organization with labels, chat state control (archive, pin, mute, block), and actions on individual messages (edit, delete, forward, favorite).

It is the broadest module in the API: from a simple call like "list contacts" to complete flows like "create a label, assign it to several chats, then list everything that has that label".

<Info>
  Every route accepts **TokenAccount** or **TokenInstance** and validates instance ownership before operating.
</Info>

## Endpoints

| Method | Path                                  | Function                         |
| ------ | ------------------------------------- | -------------------------------- |
| GET    | `/api/chat/contacts/:instance`        | List/search contacts             |
| GET    | `/api/chat/contactsByLabel/:instance` | Chats filtered by label          |
| GET    | `/api/chat/getMessage/:instance`      | Find message by ID               |
| GET    | `/api/chat/tag/:instance`             | List labels                      |
| POST   | `/api/chat/tag/:instance`             | Create label                     |
| DELETE | `/api/chat/tag/:instance`             | Delete label                     |
| POST   | `/api/chat/assignTag/:instance`       | Apply label to chat              |
| DELETE | `/api/chat/assignTag/:instance`       | Remove label from chat           |
| POST   | `/api/chat/archive/:instance`         | Archive/unarchive                |
| POST   | `/api/chat/markRead/:instance`        | Mark message as read             |
| POST   | `/api/chat/markChatRead/:instance`    | Mark entire chat as read         |
| POST   | `/api/chat/pinChat/:instance`         | Pin/unpin chat                   |
| POST   | `/api/chat/pinMessage/:instance`      | Pin/unpin message                |
| POST   | `/api/chat/favorite/:instance`        | Favorite chat or message         |
| POST   | `/api/chat/mute/:instance`            | Mute                             |
| POST   | `/api/chat/block/:instance`           | Block/unblock contact            |
| POST   | `/api/chat/presence/:instance`        | Send presence (typing/recording) |
| POST   | `/api/chat/history/:instance`         | Chat history                     |
| GET    | `/api/chat/base64/:instance`          | Media as base64                  |
| GET    | `/api/chat/status/:instance`          | Message delivery status          |
| GET    | `/api/chat/poll/:instance`            | Poll votes                       |
| POST   | `/api/chat/forward/:instance`         | Forward message                  |
| POST   | `/api/chat/edit/:instance`            | Edit message                     |
| DELETE | `/api/chat/delete/:instance`          | Delete message                   |
| DELETE | `/api/chat/deleteChat/:instance`      | Delete entire chat               |

## Contacts

Query synced contacts and filter by labels.

<CardGroup cols={2}>
  <Card title="List contacts" href="/en/api/chat/contacts-list">
    `GET /api/chat/contacts/:instance`
  </Card>

  <Card title="Contacts by label" href="/en/api/chat/contacts-by-label">
    `GET /api/chat/contactsByLabel/:instance`
  </Card>
</CardGroup>

## Labels (tags / labels)

Create labels, apply them to chats, and use them as filters, exactly what WhatsApp Business allows, but via API.

<CardGroup cols={2}>
  <Card title="List labels" href="/en/api/chat/tags-list">
    `GET /api/chat/tag/:instance`
  </Card>

  <Card title="Create label" href="/en/api/chat/tags-create">
    `POST /api/chat/tag/:instance`
  </Card>

  <Card title="Delete label" href="/en/api/chat/tags-delete">
    `DELETE /api/chat/tag/:instance`
  </Card>

  <Card title="Assign label" href="/en/api/chat/tags-assign">
    `POST /api/chat/assignTag/:instance`
  </Card>

  <Card title="Unassign label" href="/en/api/chat/tags-unassign">
    `DELETE /api/chat/assignTag/:instance`
  </Card>
</CardGroup>

## Chat state

Control how each conversation appears to the WhatsApp user, archive, pin, mute, favorite, block.

<CardGroup cols={2}>
  <Card title="Archive chat" href="/en/api/chat/archive">
    `POST /api/chat/archive/:instance`
  </Card>

  <Card title="Pin chat" href="/en/api/chat/pinChat">
    `POST /api/chat/pinChat/:instance`
  </Card>

  <Card title="Pin message" href="/en/api/chat/pinMessage">
    `POST /api/chat/pinMessage/:instance`
  </Card>

  <Card title="Mute chat" href="/en/api/chat/mute">
    `POST /api/chat/mute/:instance`
  </Card>

  <Card title="Favorite chat or message" href="/en/api/chat/favorite">
    `POST /api/chat/favorite/:instance`
  </Card>

  <Card title="Block / unblock" href="/en/api/chat/block">
    `POST /api/chat/block/:instance`
  </Card>
</CardGroup>

## Read

<CardGroup cols={2}>
  <Card title="Mark message as read" href="/en/api/chat/mark-read">
    `POST /api/chat/markRead/:instance`
  </Card>

  <Card title="Mark chat as read" href="/en/api/chat/mark-chat-read">
    `POST /api/chat/markChatRead/:instance`
  </Card>
</CardGroup>

## Presence

<CardGroup cols={1}>
  <Card title="Send presence (typing/recording)" href="/en/api/chat/presence">
    `POST /api/chat/presence/:instance`, shows `typing` or `recording` to the contact.
  </Card>
</CardGroup>

## History

<CardGroup cols={1}>
  <Card title="Request history" href="/en/api/chat/history">
    `POST /api/chat/history/:instance`, stored messages with optional date filters.
  </Card>
</CardGroup>

## Messages

Actions on specific messages, plus utilities to download media, read polls, and check delivery status.

<CardGroup cols={2}>
  <Card title="Find message by ID" href="/en/api/chat/find-message">
    `GET /api/chat/getMessage/:instance`
  </Card>

  <Card title="Forward message" href="/en/api/chat/forward">
    `POST /api/chat/forward/:instance`
  </Card>

  <Card title="Edit message" href="/en/api/chat/edit">
    `POST /api/chat/edit/:instance`
  </Card>

  <Card title="Delete message" href="/en/api/chat/delete-message">
    `DELETE /api/chat/delete/:instance`
  </Card>

  <Card title="Delete entire chat" href="/en/api/chat/delete-chat">
    `DELETE /api/chat/deleteChat/:instance`
  </Card>

  <Card title="Media as base64" href="/en/api/chat/media-base64">
    `GET /api/chat/base64/:instance`
  </Card>

  <Card title="Delivery status" href="/en/api/chat/contact-status">
    `GET /api/chat/status/:instance`
  </Card>

  <Card title="Poll votes" href="/en/api/chat/poll-read">
    `GET /api/chat/poll/:instance`
  </Card>
</CardGroup>

## Accepted identifiers

Most endpoints accept the same formats to identify a chat or destination. The table below summarizes them:

| Endpoint             | Accepts                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| Most (`number`)      | Number (`5511...`), private JID (`...@s.whatsapp.net` or `...@lid`), group JID (`...@g.us`), newsletter JID |
| `markRead` in groups | Requires `sender` (JID of the message author, `...@s.whatsapp.net` or `...@lid`)                            |
| `forward` (`to`)     | Same set as `number`                                                                                        |

<Note>
  **About `@lid` (LinkedID):** an alternative identifier WhatsApp uses for individual users when the phone number is not exposed (privacy in communities, large groups, etc.). It is equivalent to `...@s.whatsapp.net` for routing purposes, any endpoint that accepts a private JID also accepts `@lid`. Use the exact JID coming from a webhook or previous API responses; do not try to convert `@lid` into a number.
</Note>

## WhatsApp windows

| Action                                          | Limit                                 |
| ----------------------------------------------- | ------------------------------------- |
| Edit message                                    | \~15 minutes after sending            |
| Delete for everyone (`deleteForEveryone: true`) | \~2 days and 12 h after sending       |
| After the window                                | Local deletion only (`delete_for_me`) |

## Usage patterns

### Label workflow

```bash theme={null}
# 1. Create label
curl -X POST "https://ryzeapi.cloud/api/chat/tag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP","color":3}'

# 2. Apply to a chat
curl -X POST "https://ryzeapi.cloud/api/chat/assignTag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","tagId":"1"}'

# 3. List chats with the label
curl "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelIds=1" \
  -H "token: $Token_Instance"

# 4. Remove the label from the chat
curl -X DELETE "https://ryzeapi.cloud/api/chat/assignTag/$Instance_Name?number=5511999999999&tagId=1" \
  -H "token: $Token_Instance"
```

### Moderation workflow

```bash theme={null}
# 1. Mark as read
curl -X POST "https://ryzeapi.cloud/api/chat/markChatRead/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","read":true}'

# 2. Mute for 8h
curl -X POST "https://ryzeapi.cloud/api/chat/mute/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","mute":true,"duration":"8h"}'

# 3. Archive
curl -X POST "https://ryzeapi.cloud/api/chat/archive/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","archive":true}'

# 4. Block (last resort)
curl -X POST "https://ryzeapi.cloud/api/chat/block/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","block":true}'
```

## Related

<CardGroup cols={2}>
  <Card title="Send messages" icon="paper-plane" href="/en/api/messages/overview">
    Send content before managing it.
  </Card>

  <Card title="Real-time events" icon="webhook" href="/en/api/events/overview">
    Webhooks `message.exchange`, `message.status`, and `label.update`.
  </Card>
</CardGroup>