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

# Estado de entrega del mensaje

> Consulta el estado de entrega de un mensaje (pending/sent/delivered/read/played)

**Auth:** `TokenAccount` o `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sí

## Descripción

Devuelve el **estado de entrega** de un mensaje enviado, equivalente a los checks (gris, doble, azul) que muestra WhatsApp. El estado se actualiza en tiempo real a medida que los eventos de WhatsMeow informan que el mensaje fue recibido por el servidor, entregado al destinatario, leído o reproducido.

<Info>
  Para recibir la evolución del estado en tiempo real, suscríbete al webhook [`message.status`](/es/api/events/catalog). Este endpoint es la lectura puntual del snapshot actual.
</Info>

### Mapa de `status`

| `status` (string) | `status_code` | Semántica                                              |
| ----------------- | ------------- | ------------------------------------------------------ |
| `pending`         | 0             | Esperando ACK del servidor.                            |
| `sent`            | 1             | ACK del servidor (check único).                        |
| `delivered`       | 2             | Entregado al teléfono del destinatario (doble check).  |
| `received`        | 3             | Mensaje recibido (solo para `direction = "received"`). |
| `read`            | 4             | Leído por el destinatario (check azul).                |
| `played`          | 5             | Audio/video reproducido.                               |
| `error`           | -1            | Falla permanente de envío.                             |

## Ejemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/chat/status/$Instance_Name?messageId=3EB08FCF27E532F1B0F5" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/chat/status/${process.env.Instance_Name}?messageId=3EB08FCF27E532F1B0F5`, {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

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

  requests.get(
      f"https://ryzeapi.cloud/api/chat/status/{os.environ['Instance_Name']}?messageId=3EB08FCF27E532F1B0F5",
      headers={"token": os.environ["Token_Instance"]}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/status/"+os.Getenv("Instance_Name")+"?messageId=3EB08FCF27E532F1B0F5", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Respuesta exitosa

`status` es el estado textual (`sent`, `received`, `delivered`, `read`, `played`, `error`, `pending`) y `status_code` lleva el código numérico equivalente de WhatsMeow (0–5). `direction` distingue mensajes enviados por la instancia (`"sent"`) de los recibidos (`"received"`). `timestamp` es el momento en que el mensaje viajó.

```json 200 OK theme={null}
{
  "success": true,
  "message": "Message status retrieved successfully",
  "message_id": "3EB08FCF27E532F1B0F5",
  "status": "read",
  "status_code": 4,
  "direction": "sent",
  "chat_jid": "5511999999999@s.whatsapp.net",
  "timestamp": "2026-04-28T14:30:00Z"
}
```

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Nombre de la instancia.
</ParamField>

## Parámetros de consulta

<ParamField query="messageId" type="string" required>
  ID del mensaje cuyo estado quieres consultar.
</ParamField>

## Cabeceras

| Nombre  | Requerido              | Ejemplo        | Descripción                   |
| ------- | ---------------------- | -------------- | ----------------------------- |
| `token` | sí (o `Authorization`) | `a1b2c3d4-...` | TokenAccount o TokenInstance. |

## Respuestas de error

| HTTP | `error.message`                            | Cuándo ocurre                          |
| ---- | ------------------------------------------ | -------------------------------------- |
| 400  | `Instance name is required`                | ,                                      |
| 400  | `messageId query parameter is required`    | ,                                      |
| 401  | `Invalid token`                            | ,                                      |
| 404  | `Instance not found`                       | ,                                      |
| 404  | `Message not found`                        | El `messageId` no existe.              |
| 404  | `Message does not belong to this instance` | El mensaje pertenece a otra instancia. |

```json Error 404 theme={null}
{
  "success": false,
  "error": { "message": "Message not found" }
}
```

## Notas y precauciones

<Note>
  * `played` (5) solo tiene sentido para audio y video, los mensajes de texto nunca alcanzan este estado.
  * Puede haber un retraso de 1–3 segundos entre la acción en el teléfono del destinatario y el estado actualizado aquí.
  * Para rastrear varios mensajes en tiempo real, prefiere el webhook [`message.status`](/es/api/events/catalog) en lugar de polling.
</Note>

## Relacionados

<CardGroup cols={2}>
  <Card title="Buscar mensaje" href="/es/api/chat/find-message">
    Recupera contenido y metadatos.
  </Card>

  <Card title="Marcar como leído" href="/es/api/chat/mark-read">
    Indica que has leído un mensaje recibido.
  </Card>
</CardGroup>