Skip to main content
Return the latest delivery state for a message Xobito has sent.
Xobito does not emit outbound webhooks for message delivery events. Polling this endpoint is the supported way to track sent → delivered → read (or failed) transitions. See Webhooks Overview for the full list of what does and does not fire webhooks.

​
Endpoint

GET /api/v1/{subdomain}/messages/{messageId}/status
Required ability: messages.send.

​
Headers

HeaderValue
AuthorizationBearer apitk_...
Acceptapplication/json

​
Path parameters

​
subdomain
string
required
Your workspace subdomain.
​
messageId
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 apitk_your_token_here" \
  -H "Accept: application/json"

​
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

FieldTypeNotes
message_idstringThe WhatsApp wamid.* you queried.
delivery_statusstringCurrent state: pending, sent, delivered, read, or failed.
error_messagenullable stringPopulated when delivery_status: "failed".
sourcestringInternal record type (e.g. chat).
last_updateddatetimeLast time WhatsApp updated this status.
statusesobjectHuman descriptions for every possible status.

​
Error responses

StatusWhenExample body
401Missing / invalid token{"status":"error","message":"Invalid API token"}
403Missing ability{"status":"error","message":"Token does not have the required ability: messages.send"}
404Unknown messageId{"status":"error","message":"Message not found"}
429Rate limit{"message":"Too many requests","retry_after":45}
500Server 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.