Get message status

Save the messageId returned by a send endpoint, then request its latest status with the same customer app token.

Endpoint

Field	Value
Method	`GET`
Path	`/api/messages/{messageId}/status`
Required header	`X-API-KEY: your-app-token`

curl "https://modawer.com/api/messages/01a172ee-9200-7000-8000-000000000001/status" \
  -H "X-API-KEY: your-app-token"

Response

{
  "messageId": "01a172ee-9200-7000-8000-000000000001",
  "status": "Delivered",
  "deliveryChannel": "WhatsApp",
  "createdAt": "2026-10-25T12:00:00Z",
  "sentAt": "2026-10-25T12:00:01Z",
  "deliveredAt": "2026-10-25T12:00:02Z",
  "readAt": null,
  "failedAt": null,
  "failureCode": null,
  "failureReason": null
}

Status	Meaning
`Pending`	Accepted for processing, or waiting for the next delivery channel.
`Sent`	The provider accepted the message. Delivery is not yet confirmed.
`Delivered`	The provider confirmed delivery.
`Read`	The provider confirmed the recipient read the message.
`Warning`	A provider warning or an uncertain outcome requiring reconciliation.
`Failed`	The active attempt failed and no fallback is pending. Check `failureCode` and `failureReason` when available.

deliveryChannel identifies the active delivery attempt. During fallback it changes to the next channel, and the status remains Pending until that attempt progresses. Receipt timestamps describe that active attempt. All timestamps use ISO 8601. Receipt timestamps are nullable. Provider timestamps take precedence when available; otherwise the API records when the status was reported or provider acceptance was observed. A read receipt without a delivery timestamp does not create a delivery timestamp. Historical messages can have a known status with null receipt timestamps and a null delivery channel. Delivery and read receipts depend on provider reporting. A missing receipt does not establish that the message failed. The endpoint excludes message content, OTP values, recipient details, and provider identifiers.

Authentication and errors

Use the customer app token that submitted the message. For OTPs sent through Modawer’s shared sender, use your own app token. Dashboard sessions and dev tokens do not authorize this endpoint.

HTTP status	Meaning
`400`	The message ID is not a valid UUID.
`401`	The app token is missing or invalid.
`404`	The message does not exist or belongs to another app.

For polling, start with a two-second interval and back off for messages that remain pending. Continue after Sent or Delivered if you need later receipts. In development and OTP log-only mode, sends receive a durable ID but remain Pending with null receipt timestamps because no provider receives the message.

Overview

Setup

Endpoints

API reference

Get message status

Endpoint

Response

Authentication and errors

​Endpoint

​Response

​Authentication and errors

Endpoint

Response

Authentication and errors