> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get message status

> Poll the delivery status of a sent WhatsApp message.

<Info>
  **Live as of 2026-05-28.** Both polling (this endpoint) and push (outbound webhooks) are supported. For real-time updates we recommend the push pattern — see [Webhook Events → Message Delivery Status](/developers/webhook-events#message-delivery-status-events).
</Info>

Return the latest delivery state for a message Xobito has sent.

<Tip>
  Most integrations should use **outbound webhooks** (push) instead of polling — Xobito will POST to your URL automatically as `sent → delivered → read` (or `failed`). Use this poll endpoint for one-off lookups or when push isn't an option. See [Webhook Events](/developers/webhook-events#message-delivery-status-events).
</Tip>

## Endpoint

```
GET /api/v1/{subdomain}/messages/{messageId}/status
```

Required ability: `messages.send`.

## Headers

| Header          | Value                        |
| --------------- | ---------------------------- |
| `Authorization` | `Bearer <your-64-hex-token>` |
| `Accept`        | `application/json`           |

## Path parameters

<ParamField path="subdomain" type="string" required={true}>
  Your workspace subdomain.
</ParamField>

<ParamField path="messageId" type="string" required={true}>
  The WhatsApp `wamid.*` returned from any send endpoint.
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://dash.xobito.com/api/v1/acme/messages/wamid.HBgM.../status" \
    -H "Authorization: Bearer <your_token>" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const messageId = "wamid.HBgM...";
  const res = await fetch(
    `https://dash.xobito.com/api/v1/acme/messages/${encodeURIComponent(messageId)}/status`,
    {
      headers: {
        Authorization: "Bearer <your_token>",
        Accept: "application/json",
      },
    }
  );
  const body = await res.json();
  ```

  ```python Python theme={null}
  import requests, urllib.parse

  mid = urllib.parse.quote("wamid.HBgM...", safe="")
  r = requests.get(
      f"https://dash.xobito.com/api/v1/acme/messages/{mid}/status",
      headers={
          "Authorization": "Bearer <your_token>",
          "Accept": "application/json",
      },
  )
  body = r.json()
  ```

  ```php PHP theme={null}
  <?php
  $mid = rawurlencode('wamid.HBgM...');
  $ch = curl_init("https://dash.xobito.com/api/v1/acme/messages/{$mid}/status");
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer <your_token>',
          'Accept: application/json',
      ],
  ]);
  $body = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```
</CodeGroup>

## Example response

```json 200 OK theme={null}
{
  "status": "success",
  "data": {
    "message_id": "wamid.HBgM...",
    "delivery_status": "delivered",
    "error_message": null,
    "source": "chat",
    "last_updated": "2026-04-08T14:35:10.000000Z",
    "statuses": {
      "sent": "Message accepted by WhatsApp",
      "delivered": "Message delivered to recipient phone",
      "read": "Recipient opened/read the message",
      "failed": "Message delivery failed",
      "pending": "Message queued, not yet sent"
    }
  }
}
```

### Response fields

| Field             | Type            | Notes                                                               |
| ----------------- | --------------- | ------------------------------------------------------------------- |
| `message_id`      | string          | The WhatsApp `wamid.*` you queried.                                 |
| `delivery_status` | string          | Current state: `pending`, `sent`, `delivered`, `read`, or `failed`. |
| `error_message`   | nullable string | Populated when `delivery_status: "failed"`.                         |
| `source`          | string          | Internal record type (e.g. `chat`).                                 |
| `last_updated`    | datetime        | Last time WhatsApp updated this status.                             |
| `statuses`        | object          | Human descriptions for every possible status.                       |

## Error responses

| Status | When                    | Example body                                                                             |
| ------ | ----------------------- | ---------------------------------------------------------------------------------------- |
| `401`  | Missing / invalid token | `{"status":"error","message":"Invalid API token"}`                                       |
| `403`  | Missing ability         | `{"status":"error","message":"Token does not have the required ability: messages.send"}` |
| `404`  | Unknown `messageId`     | `{"status":"error","message":"Message not found"}`                                       |
| `429`  | Rate limit              | `{"message":"Too many requests","retry_after":45}`                                       |
| `500`  | Server error            | `{"status":"error","message":"Failed to get message status"}`                            |

<Tip>Poll on a reasonable cadence — every few seconds while actively expecting a delivery update, longer intervals when idle. Respect rate limits.</Tip>