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

# Resumen

> Administra contactos, etiquetas, estado del chat y actúa sobre mensajes ya enviados o recibidos

El módulo **Chat** agrupa todo lo que ocurre **después** de que un mensaje entra o sale: gestión de contactos, organización con etiquetas, control del estado del chat (archivar, fijar, silenciar, bloquear) y acciones sobre mensajes individuales (editar, eliminar, reenviar, favorito).

Es el módulo más amplio de la API: desde una llamada simple como "listar contactos" hasta flujos completos como "crear una etiqueta, asignarla a varios chats, luego listar todo lo que tiene esa etiqueta".

<Info>
  Cada ruta acepta **TokenAccount** o **TokenInstance** y valida la propiedad de la instancia antes de operar.
</Info>

## Endpoints

| Method | Path                                  | Función                                 |
| ------ | ------------------------------------- | --------------------------------------- |
| GET    | `/api/chat/contacts/:instance`        | Listar/buscar contactos                 |
| GET    | `/api/chat/contactsByLabel/:instance` | Chats filtrados por etiqueta            |
| GET    | `/api/chat/getMessage/:instance`      | Buscar mensaje por ID                   |
| GET    | `/api/chat/tag/:instance`             | Listar etiquetas                        |
| POST   | `/api/chat/tag/:instance`             | Crear etiqueta                          |
| DELETE | `/api/chat/tag/:instance`             | Eliminar etiqueta                       |
| POST   | `/api/chat/assignTag/:instance`       | Aplicar etiqueta al chat                |
| DELETE | `/api/chat/assignTag/:instance`       | Quitar etiqueta del chat                |
| POST   | `/api/chat/archive/:instance`         | Archivar/desarchivar                    |
| POST   | `/api/chat/markRead/:instance`        | Marcar mensaje como leído               |
| POST   | `/api/chat/markChatRead/:instance`    | Marcar todo el chat como leído          |
| POST   | `/api/chat/pinChat/:instance`         | Fijar/desfijar chat                     |
| POST   | `/api/chat/pinMessage/:instance`      | Fijar/desfijar mensaje                  |
| POST   | `/api/chat/favorite/:instance`        | Marcar chat o mensaje como favorito     |
| POST   | `/api/chat/mute/:instance`            | Silenciar                               |
| POST   | `/api/chat/block/:instance`           | Bloquear/desbloquear contacto           |
| POST   | `/api/chat/presence/:instance`        | Enviar presencia (escribiendo/grabando) |
| POST   | `/api/chat/history/:instance`         | Historial del chat                      |
| GET    | `/api/chat/base64/:instance`          | Media en base64                         |
| GET    | `/api/chat/status/:instance`          | Estado de entrega del mensaje           |
| GET    | `/api/chat/poll/:instance`            | Votos de la encuesta                    |
| POST   | `/api/chat/forward/:instance`         | Reenviar mensaje                        |
| POST   | `/api/chat/edit/:instance`            | Editar mensaje                          |
| DELETE | `/api/chat/delete/:instance`          | Eliminar mensaje                        |
| DELETE | `/api/chat/deleteChat/:instance`      | Eliminar el chat completo               |

## Contactos

Consulta los contactos sincronizados y filtra por etiquetas.

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

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

## Etiquetas (tags / labels)

Crea etiquetas, aplícalas a chats y úsalas como filtros, exactamente lo que WhatsApp Business permite, pero vía API.

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

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

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

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

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

## Estado del chat

Controla cómo se muestra cada conversación al usuario de WhatsApp, archivar, fijar, silenciar, favorito, bloquear.

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

  <Card title="Fijar chat" href="/es/api/chat/pinChat">
    `POST /api/chat/pinChat/:instance`
  </Card>

  <Card title="Fijar mensaje" href="/es/api/chat/pinMessage">
    `POST /api/chat/pinMessage/:instance`
  </Card>

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

  <Card title="Marcar chat o mensaje como favorito" href="/es/api/chat/favorite">
    `POST /api/chat/favorite/:instance`
  </Card>

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

## Lectura

<CardGroup cols={2}>
  <Card title="Marcar mensaje como leído" href="/es/api/chat/mark-read">
    `POST /api/chat/markRead/:instance`
  </Card>

  <Card title="Marcar chat como leído" href="/es/api/chat/mark-chat-read">
    `POST /api/chat/markChatRead/:instance`
  </Card>
</CardGroup>

## Presencia

<CardGroup cols={1}>
  <Card title="Enviar presencia (escribiendo/grabando)" href="/es/api/chat/presence">
    `POST /api/chat/presence/:instance`, muestra `typing` o `recording` al contacto.
  </Card>
</CardGroup>

## Historial

<CardGroup cols={1}>
  <Card title="Solicitar historial" href="/es/api/chat/history">
    `POST /api/chat/history/:instance`, mensajes almacenados con filtros opcionales por fecha.
  </Card>
</CardGroup>

## Mensajes

Acciones sobre mensajes específicos, además de utilidades para descargar media, leer encuestas y consultar el estado de entrega.

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

  <Card title="Reenviar mensaje" href="/es/api/chat/forward">
    `POST /api/chat/forward/:instance`
  </Card>

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

  <Card title="Eliminar mensaje" href="/es/api/chat/delete-message">
    `DELETE /api/chat/delete/:instance`
  </Card>

  <Card title="Eliminar el chat completo" href="/es/api/chat/delete-chat">
    `DELETE /api/chat/deleteChat/:instance`
  </Card>

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

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

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

## Identificadores aceptados

La mayoría de los endpoints aceptan los mismos formatos para identificar un chat o destino. La tabla de abajo los resume:

| Endpoint             | Acepta                                                                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Mayoría (`number`)   | Número (`5511...`), JID privado (`...@s.whatsapp.net` o `...@lid`), JID de grupo (`...@g.us`), JID de newsletter |
| `markRead` en grupos | Requiere `sender` (JID del autor del mensaje, `...@s.whatsapp.net` o `...@lid`)                                  |
| `forward` (`to`)     | Mismo conjunto que `number`                                                                                      |

<Note>
  **Sobre `@lid` (LinkedID):** un identificador alternativo que WhatsApp utiliza para usuarios individuales cuando el número telefónico no está expuesto (privacidad en comunidades, grupos grandes, etc.). Es equivalente a `...@s.whatsapp.net` para fines de enrutamiento, cualquier endpoint que acepte un JID privado también acepta `@lid`. Usa el JID exacto que viene de un webhook o de respuestas previas de la API; no intentes convertir `@lid` en un número.
</Note>

## Ventanas de WhatsApp

| Acción                                          | Límite                                   |
| ----------------------------------------------- | ---------------------------------------- |
| Editar mensaje                                  | \~15 minutos después del envío           |
| Eliminar para todos (`deleteForEveryone: true`) | \~2 días y 12 h después del envío        |
| Después de la ventana                           | Solo eliminación local (`delete_for_me`) |

## Patrones de uso

### Flujo de etiquetas

```bash theme={null}
# 1. Crear 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 un 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 con la etiqueta
curl "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelIds=1" \
  -H "token: $Token_Instance"

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

### Flujo de moderación

```bash theme={null}
# 1. Marcar como leído
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 por 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. Archivar
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 mensajes" icon="paper-plane" href="/es/api/messages/overview">
    Envía contenido antes de gestionarlo.
  </Card>

  <Card title="Eventos en tiempo real" icon="webhook" href="/es/api/events/overview">
    Webhooks `message.exchange`, `message.status` y `label.update`.
  </Card>
</CardGroup>