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

# Message delivery status

> Queries the delivery status of a message (pending/sent/delivered/read/played)

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

<Info>
  To receive status evolution in real time, subscribe to the [`message.status`](/en/api/events/catalog) webhook. This endpoint is the point-in-time read of the current snapshot.
</Info>

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

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

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

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

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name.
</ParamField>

## Query params

<ParamField query="messageId" type="string" required>
  ID of the message whose status you want to query.
</ParamField>

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

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

## Notes and gotchas

<Note>
  * `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`](/en/api/events/catalog) webhook over polling.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Find message" href="/en/api/chat/find-message">
    Retrieve content and metadata.
  </Card>

  <Card title="Mark as read" href="/en/api/chat/mark-read">
    Signal that you have read a received message.
  </Card>
</CardGroup>