Status de entrega da mensagem

GET

api

chat

status

:instance

Status de entrega da mensagem

curl --request GET \
  --url https://api.example.com/api/chat/status/:instance

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.

Para receber a evolução do status em tempo real, assine o webhook message.status. Este endpoint é a leitura pontual do snapshot atual.

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

curl -X GET "https://ryzeapi.cloud/api/chat/status/$Instance_Name?messageId=3EB08FCF27E532F1B0F5" \
  -H "token: $Token_Instance"

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

import os, requests

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

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

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.

200 OK

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

string

obrigatório

Nome da instância.

Query params

string

obrigatório

ID da mensagem cujo status deseja consultar.

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.

Erro 404

{
  "success": false,
  "error": { "message": "Message not found" }
}

Notas e gotchas

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 em vez de polling.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Status de entrega da mensagem

Descrição

Mapa de `status`

Exemplo

Resposta de sucesso

Parâmetros de rota

Query params

Headers

Respostas de erro

Notas e gotchas

Relacionados

Buscar mensagem

Marcar como lida

​Descrição

​Mapa de status

​Exemplo

​Resposta de sucesso

​Parâmetros de rota

​Query params

​Headers

​Respostas de erro

​Notas e gotchas

​Relacionados

Buscar mensagem

Marcar como lida

Descrição

Mapa de `status`

Exemplo

Resposta de sucesso

Parâmetros de rota

Query params

Headers

Respostas de erro

Notas e gotchas

Relacionados