> ## 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.

# Visão Geral

> Gerencie contatos, etiquetas, estado dos chats e atue sobre mensagens já enviadas ou recebidas

O módulo **Chat** agrupa tudo o que acontece **depois** que uma mensagem entra ou sai, gestão de contatos, organização com etiquetas, controle do estado dos chats (arquivar, fixar, silenciar, bloquear) e ações sobre mensagens individuais (editar, apagar, encaminhar, favoritar).

É o módulo mais amplo da API: vai de uma chamada simples como "listar contatos" até fluxos completos como "criar uma etiqueta, atribuir a vários chats e depois listar tudo que tem essa etiqueta".

<Info>
  Todas as rotas aceitam **TokenAccount** ou **TokenInstance** e validam ownership da instância antes de operar.
</Info>

## Endpoints

| Método | Path                                  | Função                             |
| ------ | ------------------------------------- | ---------------------------------- |
| GET    | `/api/chat/contacts/:instance`        | Listar/buscar contatos             |
| GET    | `/api/chat/contactsByLabel/:instance` | Chats filtrados por etiqueta       |
| GET    | `/api/chat/getMessage/:instance`      | Buscar mensagem por ID             |
| GET    | `/api/chat/tag/:instance`             | Listar etiquetas                   |
| POST   | `/api/chat/tag/:instance`             | Criar etiqueta                     |
| DELETE | `/api/chat/tag/:instance`             | Deletar etiqueta                   |
| POST   | `/api/chat/assignTag/:instance`       | Aplicar etiqueta a chat            |
| DELETE | `/api/chat/assignTag/:instance`       | Remover etiqueta de chat           |
| POST   | `/api/chat/archive/:instance`         | Arquivar/desarquivar               |
| POST   | `/api/chat/markRead/:instance`        | Marcar mensagem como lida          |
| POST   | `/api/chat/markChatRead/:instance`    | Marcar chat inteiro como lido      |
| POST   | `/api/chat/pinChat/:instance`         | Fixar/desafixar chat               |
| POST   | `/api/chat/pinMessage/:instance`      | Fixar/desafixar mensagem           |
| POST   | `/api/chat/favorite/:instance`        | Favoritar chat ou mensagem         |
| POST   | `/api/chat/mute/:instance`            | Silenciar                          |
| POST   | `/api/chat/block/:instance`           | Bloquear/desbloquear contato       |
| POST   | `/api/chat/presence/:instance`        | Enviar presença (typing/recording) |
| POST   | `/api/chat/history/:instance`         | Histórico do chat                  |
| GET    | `/api/chat/base64/:instance`          | Mídia em base64                    |
| GET    | `/api/chat/status/:instance`          | Status de entrega de mensagem      |
| GET    | `/api/chat/poll/:instance`            | Votos de uma enquete               |
| POST   | `/api/chat/forward/:instance`         | Encaminhar mensagem                |
| POST   | `/api/chat/edit/:instance`            | Editar mensagem                    |
| DELETE | `/api/chat/delete/:instance`          | Apagar mensagem                    |
| DELETE | `/api/chat/deleteChat/:instance`      | Apagar chat inteiro                |

## Contatos

Consulta de contatos sincronizados e filtragem por etiquetas.

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

  <Card title="Contatos por etiqueta" href="/pt/api/chat/contacts-by-label">
    `GET /api/chat/contactsByLabel/:instance`
  </Card>
</CardGroup>

## Etiquetas (tags / labels)

Crie etiquetas, aplique aos chats e use-as como filtro, exatamente como o WhatsApp Business permite, mas via API.

<CardGroup cols={2}>
  <Card title="Listar etiquetas" href="/pt/api/chat/tags-list">
    `GET /api/chat/tag/:instance`
  </Card>

  <Card title="Criar etiqueta" href="/pt/api/chat/tags-create">
    `POST /api/chat/tag/:instance`
  </Card>

  <Card title="Deletar etiqueta" href="/pt/api/chat/tags-delete">
    `DELETE /api/chat/tag/:instance`
  </Card>

  <Card title="Atribuir etiqueta" href="/pt/api/chat/tags-assign">
    `POST /api/chat/assignTag/:instance`
  </Card>

  <Card title="Desatribuir etiqueta" href="/pt/api/chat/tags-unassign">
    `DELETE /api/chat/assignTag/:instance`
  </Card>
</CardGroup>

## Estado do chat

Controle como cada conversa aparece para o usuário do WhatsApp, arquivar, fixar, silenciar, favoritar, bloquear.

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

  <Card title="Fixar chat" href="/pt/api/chat/pinChat">
    `POST /api/chat/pinChat/:instance`
  </Card>

  <Card title="Fixar mensagem" href="/pt/api/chat/pinMessage">
    `POST /api/chat/pinMessage/:instance`
  </Card>

  <Card title="Silenciar chat" href="/pt/api/chat/mute">
    `POST /api/chat/mute/:instance`
  </Card>

  <Card title="Favoritar chat ou mensagem" href="/pt/api/chat/favorite">
    `POST /api/chat/favorite/:instance`
  </Card>

  <Card title="Bloquear / desbloquear" href="/pt/api/chat/block">
    `POST /api/chat/block/:instance`
  </Card>
</CardGroup>

## Leitura

<CardGroup cols={2}>
  <Card title="Marcar mensagem como lida" href="/pt/api/chat/mark-read">
    `POST /api/chat/markRead/:instance`
  </Card>

  <Card title="Marcar chat como lido" href="/pt/api/chat/mark-chat-read">
    `POST /api/chat/markChatRead/:instance`
  </Card>
</CardGroup>

## Presença

<CardGroup cols={1}>
  <Card title="Enviar presença (digitando/gravando)" href="/pt/api/chat/presence">
    `POST /api/chat/presence/:instance`, mostra `typing` ou `recording` para o contato.
  </Card>
</CardGroup>

## Histórico

<CardGroup cols={1}>
  <Card title="Solicitar histórico" href="/pt/api/chat/history">
    `POST /api/chat/history/:instance`, mensagens armazenadas com filtros opcionais por data.
  </Card>
</CardGroup>

## Mensagens

Ações sobre mensagens específicas, além de utilitários para baixar mídia, ler enquetes e checar status de entrega.

<CardGroup cols={2}>
  <Card title="Buscar mensagem por ID" href="/pt/api/chat/find-message">
    `GET /api/chat/getMessage/:instance`
  </Card>

  <Card title="Encaminhar mensagem" href="/pt/api/chat/forward">
    `POST /api/chat/forward/:instance`
  </Card>

  <Card title="Editar mensagem" href="/pt/api/chat/edit">
    `POST /api/chat/edit/:instance`
  </Card>

  <Card title="Apagar mensagem" href="/pt/api/chat/delete-message">
    `DELETE /api/chat/delete/:instance`
  </Card>

  <Card title="Apagar chat inteiro" href="/pt/api/chat/delete-chat">
    `DELETE /api/chat/deleteChat/:instance`
  </Card>

  <Card title="Mídia em base64" href="/pt/api/chat/media-base64">
    `GET /api/chat/base64/:instance`
  </Card>

  <Card title="Status de entrega" href="/pt/api/chat/contact-status">
    `GET /api/chat/status/:instance`
  </Card>

  <Card title="Votos de enquete" href="/pt/api/chat/poll-read">
    `GET /api/chat/poll/:instance`
  </Card>
</CardGroup>

## Identificadores aceitos

A maioria dos endpoints aceita os mesmos formatos para identificar chat ou destino. A tabela abaixo resume:

| Endpoint            | Aceita                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| Maioria (`number`)  | Número (`5511...`), JID privado (`...@s.whatsapp.net` ou `...@lid`), JID grupo (`...@g.us`), JID newsletter |
| `markRead` em grupo | Exige `sender` (JID do autor da mensagem, `...@s.whatsapp.net` ou `...@lid`)                                |
| `forward` (`to`)    | Mesmo conjunto que `number`                                                                                 |

<Note>
  **Sobre `@lid` (LinkedID):** identificador alternativo que o WhatsApp usa para usuários individuais quando o número de telefone não está exposto (privacidade em comunidades, grupos grandes, etc.). É equivalente ao `...@s.whatsapp.net` para fins de roteamento, qualquer endpoint que aceite JID privado também aceita `@lid`. Use o JID exato vindo de webhook ou de respostas anteriores da API; não tente converter `@lid` em número.
</Note>

## Janelas do WhatsApp

| Ação                                          | Limite                                  |
| --------------------------------------------- | --------------------------------------- |
| Editar mensagem                               | \~15 minutos após envio                 |
| Apagar para todos (`deleteForEveryone: true`) | \~2 dias e 12 h após envio              |
| Após a janela                                 | Apenas exclusão local (`delete_for_me`) |

## Padrões de uso

### Workflow de etiquetas

```bash theme={null}
# 1. Criar etiqueta
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. Aplicar a um 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. Listar chats com a etiqueta
curl "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelIds=1" \
  -H "token: $Token_Instance"

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

### Workflow de moderação

```bash theme={null}
# 1. Marcar como lido
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. Silenciar 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. Arquivar
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. Bloquear (último recurso)
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}'
```

## Relacionados

<CardGroup cols={2}>
  <Card title="Enviar mensagens" icon="paper-plane" href="/pt/api/messages/overview">
    Enviar conteúdo antes de gerenciar.
  </Card>

  <Card title="Eventos em tempo real" icon="webhook" href="/pt/api/events/overview">
    Webhooks `message.exchange`, `message.status` e `label.update`.
  </Card>
</CardGroup>