Get message status

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.

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

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.

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

string

required

Your workspace subdomain.

string

required

The WhatsApp wamid.* returned from any send endpoint.

Example request

curl "https://dash.xobito.com/api/v1/acme/messages/wamid.HBgM.../status" \
  -H "Authorization: Bearer <your_token>" \
  -H "Accept: application/json"

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();

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
$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);

Example response

200 OK

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

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

Introduction

API Reference

Webhooks

Data Types

Get message status

Endpoint

Headers

Path parameters

Example request

Example response

Response fields

Error responses

​Endpoint

​Headers

​Path parameters

​Example request

​Example response

​Response fields

​Error responses

Endpoint

Headers

Path parameters

Example request

Example response

Response fields

Error responses