Message delivery status

GET

api

chat

status

:instance

Message delivery status

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

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes

Description

Returns the delivery status of a sent message, equivalent to the checks (gray, double, blue) shown in WhatsApp. The status is updated in real time as WhatsMeow events report that the message was received by the server, delivered to the recipient, read, or played.

To receive status evolution in real time, subscribe to the message.status webhook. This endpoint is the point-in-time read of the current snapshot.

`status` map

`status` (string)	`status_code`	Semantics
`pending`	0	Awaiting server ACK.
`sent`	1	Server ACK (single check).
`delivered`	2	Delivered to the recipient’s phone (double check).
`received`	3	Message received (only for `direction = "received"`).
`read`	4	Read by the recipient (blue check).
`played`	5	Audio/video played.
`error`	-1	Permanent send failure.

Example

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

Success response

status is the textual state (sent, received, delivered, read, played, error, pending) and status_code carries the equivalent numeric code from WhatsMeow (0–5). direction distinguishes messages sent by the instance ("sent") from received ones ("received"). timestamp is the moment the message traveled.

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

Path parameters

string

required

Instance name.

Query params

string

required

ID of the message whose status you want to query.

Headers

Name	Required	Example	Description
`token`	yes (or `Authorization`)	`a1b2c3d4-...`	TokenAccount or TokenInstance.

Error responses

HTTP	`error.message`	When it happens
400	`Instance name is required`	,
400	`messageId query parameter is required`	,
401	`Invalid token`	,
404	`Instance not found`	,
404	`Message not found`	`messageId` does not exist.
404	`Message does not belong to this instance`	Message belongs to another instance.

Error 404

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

Notes and gotchas

played (5) only makes sense for audio and video, text messages never reach this state.
There can be a 1–3 second delay between the action on the recipient’s phone and the status updated here.
To track multiple messages in real time, prefer the message.status webhook over polling.

Find message

Retrieve content and metadata.

Mark as read

Signal that you have read a received message.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Message delivery status

Description

`status` map

Example

Success response

Path parameters

Query params

Headers

Error responses

Notes and gotchas

Find message

Mark as read

​Description

​status map

​Example

​Success response

​Path parameters

​Query params

​Headers

​Error responses

​Notes and gotchas

​Related

Find message

Mark as read

Description

`status` map

Example

Success response

Path parameters

Query params

Headers

Error responses

Notes and gotchas

Related