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

# Status de entrega da mensagem

> Consulta o status de entrega de uma mensagem (pending/sent/delivered/read/played)

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** sim

## Descrição

Retorna o **status de entrega** de uma mensagem enviada, equivalente aos checks (cinza, duplo, azul) que aparecem no WhatsApp. O status é atualizado em tempo real conforme eventos do WhatsMeow informam que a mensagem foi recebida pelo servidor, entregue ao destinatário, lida ou reproduzida.

<Info>
  Para receber a evolução do status em tempo real, assine o webhook [`message.status`](/pt/api/events/catalog). Este endpoint é a leitura pontual do snapshot atual.
</Info>

### Mapa de `status`

| `status` (string) | `status_code` | Semântica                                                 |
| ----------------- | ------------- | --------------------------------------------------------- |
| `pending`         | 0             | Aguardando ACK do servidor.                               |
| `sent`            | 1             | ACK do servidor (check simples).                          |
| `delivered`       | 2             | Entregue ao celular do destinatário (check duplo).        |
| `received`        | 3             | Mensagem recebida (apenas para `direction = "received"`). |
| `read`            | 4             | Lida pelo destinatário (check azul).                      |
| `played`          | 5             | Áudio/vídeo reproduzido.                                  |
| `error`           | -1            | Falha permanente de envio.                                |

## Exemplo

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

## Resposta de sucesso

`status` é o estado textual (`sent`, `received`, `delivered`, `read`, `played`, `error`, `pending`) e `status_code` traz o código numérico equivalente do WhatsMeow (0–5). `direction` distingue mensagens enviadas pela instância (`"sent"`) das recebidas (`"received"`). `timestamp` é o instante em que a mensagem trafegou.

```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 rota

<ParamField path="instance" type="string" required>
  Nome da instância.
</ParamField>

## Query params

<ParamField query="messageId" type="string" required>
  ID da mensagem cujo status deseja consultar.
</ParamField>

## Headers

| Nome    | Obrigatório              | Exemplo        | Descrição                      |
| ------- | ------------------------ | -------------- | ------------------------------ |
| `token` | sim (ou `Authorization`) | `a1b2c3d4-...` | TokenAccount ou TokenInstance. |

## Respostas de erro

| HTTP | `error.message`                            | Quando ocorre                        |
| ---- | ------------------------------------------ | ------------------------------------ |
| 400  | `Instance name is required`                | ,                                    |
| 400  | `messageId query parameter is required`    | ,                                    |
| 401  | `Invalid token`                            | ,                                    |
| 404  | `Instance not found`                       | ,                                    |
| 404  | `Message not found`                        | `messageId` inexistente.             |
| 404  | `Message does not belong to this instance` | Mensagem pertence a outra instância. |

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

## Notas e gotchas

<Note>
  * `played` (5) só faz sentido para áudio e vídeo, mensagens de texto não chegam a esse estado.
  * Pode haver um delay de 1 a 3 segundos entre a ação no celular do destinatário e o status atualizado aqui.
  * Para acompanhar várias mensagens em tempo real, prefira o webhook [`message.status`](/pt/api/events/catalog) em vez de polling.
</Note>

## Relacionados

<CardGroup cols={2}>
  <Card title="Buscar mensagem" href="/pt/api/chat/find-message">
    Recuperar conteúdo e metadados.
  </Card>

  <Card title="Marcar como lida" href="/pt/api/chat/mark-read">
    Sinalizar que você já leu uma mensagem recebida.
  </Card>
</CardGroup>