Skip to main content

Get a WhatsApp message

GET/messaging/v1/whatsapp/{id}

Returns a WhatsApp message by its id, with its current status, cost, and the reason if it wasn't delivered.

Path parameters​

  • #iduuidRequired
    The message's id, from the response when you sent it, or from a webhook.
    Example: 8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d

To follow a message as it changes, use a webhook. Don't poll this endpoint.

Example request​

curl "https://sandbox-api.ponitor.com/messaging/v1/whatsapp/8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d" \
-H "apiKey: $PONITOR_API_KEY"

Responses​

OK. The message, with its current status. If you sent an smsFallback, its messageId is the SMS's ID once it's sent. Read the SMS with Get an SMS.

{
"message": {
"id": "8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d",
"channel": "WHATSAPP",
"direction": "OUTBOUND",
"sender": "+231770000000",
"recipient": "+231770123456",
"messageType": "TEMPLATE",
"inServiceWindow": null,
"template": {
"id": "6f1c2a3e-8b4d-4e5f-9a1b-2c3d4e5f6a7b",
"name": "repayment_reminder",
"language": "en"
},
"text": "Hi Blama, your repayment of LRD 4,500 is due 18 June.",
"status": "DELIVERED",
"cost": 0.03,
"failureReason": null,
"failureCode": null,
"externalId": "remind-0412",
"conversationId": null,
"createdAt": "2026-10-05T09:30:00.112Z",
"updatedAt": "2026-10-05T09:30:06.402Z"
}
}

The message object​

FieldTypeMeaning
iduuidPonitor's ID for the message.
channelstringAlways WHATSAPP.
directionstringOUTBOUND for messages you send, INBOUND for messages a customer sends you.
senderstringYour WhatsApp number, or the customer's for a message they sent.
recipientstringThe customer's number, in international format, or yours for a message they sent.
messageTypestring or nullTEMPLATE or FREE_FORM for a message you sent. null for one a customer sent.
inServiceWindowboolean or nullFor a message you sent, whether it went out inside the 24-hour window. null for one a customer sent.
text, image, video, audio, document, sticker, location, contacts, order, templateThe message, in the field named after its type, as you send it. order is a customer's order from your WhatsApp catalog: its catalogId and items (productId, quantity, price, currency). A file has its url (for a received file, a link that works for an hour), and its caption, mimeType, filename and size when known. A template has its id, name and language, and text holds what the customer read.
buttons, list, linkSent with text, as you sent them.
replyobjectSet when the customer tapped a button or quick reply, or picked a list row. Has the id you sent, the title they saw, and a row's description.
referralobjectSet when the customer wrote from your click-to-WhatsApp ad. Has the ad's headline, body, sourceUrl, sourceType, sourceId and clickId.
forwardedstringSet on a forwarded message. FORWARDED, or FREQUENTLY_FORWARDED if it has been forwarded many times.
statusstringQUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN or FAILED. A message a customer sent is DELIVERED. See Delivery statuses.
costnumberWhat the message cost, in US dollars. Refunded if it ends as FAILED.
failureReasonstring or nullWhy the message wasn't delivered, in plain words. Set for EXPIRED, UNDELIVERED and FAILED.
failureCodestring or nullThe same reason as a code that never changes, such as E11001. Branch on it. See Why a message wasn't delivered.
externalIdstring or nullYour reference. null for a message a customer sent.
conversationIduuid or nullGroups the messages with one customer.
smsFallbackobjectOnly if you sent one. Has sender, text and messageId. messageId is the SMS's ID once it's sent, and null until then. See If they're not on WhatsApp.
createdAtdate-timeWhen Ponitor accepted it.
updatedAtdate-timeWhen it last changed, usually its latest status.

Fields from before /whatsapp aren't here: the message is in text or the field named after its type, never content, and the reason is failureReason, not failedReason. /messages and the webhooks still have both.