Get a WhatsApp message
/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
- 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
- Node.js
- Python
- PHP
curl "https://sandbox-api.ponitor.com/messaging/v1/whatsapp/8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d" \
-H "apiKey: $PONITOR_API_KEY"
const response = await fetch('https://sandbox-api.ponitor.com/messaging/v1/whatsapp/8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d', {
headers: { apiKey: process.env.PONITOR_API_KEY },
});
console.log(response.status, await response.json());
import os
import requests
response = requests.get(
"https://sandbox-api.ponitor.com/messaging/v1/whatsapp/8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d",
headers={"apiKey": os.environ["PONITOR_API_KEY"]},
timeout=30,
)
print(response.status_code, response.json())
<?php
$ch = curl_init('https://sandbox-api.ponitor.com/messaging/v1/whatsapp/8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['apiKey: ' . getenv('PONITOR_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status, ' ', $body, PHP_EOL;
Responses
- 200
- 401
- 404
- 429
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"
}
}
Unauthorized. The API key is missing (E02001), wrong or revoked (E02002), or sent to the other base URL (E02003). See API keys and base URLs.
Not Found. Your team has no WhatsApp message with this id (E01005). An SMS's id answers the same: read it with Get an SMS.
{
"error": {
"type": "not_found_error",
"code": "E01005",
"name": "NotFound",
"message": "message with id (8d0f3c2a-5b7e-4a91-b6c4-1e2f3a4b5c6d) not found",
"doc_url": "https://docs.ponitor.com/api/errors#E01005",
"request_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a"
}
}
Every error has this error object. The body also still carries fields from before codes, which are deprecated. See The error body.
Too Many Requests. Your team went over its rate limit (E01011). Wait, then try again.
The message object
| Field | Type | Meaning |
|---|---|---|
id | uuid | Ponitor's ID for the message. |
channel | string | Always WHATSAPP. |
direction | string | OUTBOUND for messages you send, INBOUND for messages a customer sends you. |
sender | string | Your WhatsApp number, or the customer's for a message they sent. |
recipient | string | The customer's number, in international format, or yours for a message they sent. |
messageType | string or null | TEMPLATE or FREE_FORM for a message you sent. null for one a customer sent. |
inServiceWindow | boolean or null | For 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, template | The 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, link | Sent with text, as you sent them. | |
reply | object | Set 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. |
referral | object | Set when the customer wrote from your click-to-WhatsApp ad. Has the ad's headline, body, sourceUrl, sourceType, sourceId and clickId. |
forwarded | string | Set on a forwarded message. FORWARDED, or FREQUENTLY_FORWARDED if it has been forwarded many times. |
status | string | QUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN or FAILED. A message a customer sent is DELIVERED. See Delivery statuses. |
cost | number | What the message cost, in US dollars. Refunded if it ends as FAILED. |
failureReason | string or null | Why the message wasn't delivered, in plain words. Set for EXPIRED, UNDELIVERED and FAILED. |
failureCode | string or null | The same reason as a code that never changes, such as E11001. Branch on it. See Why a message wasn't delivered. |
externalId | string or null | Your reference. null for a message a customer sent. |
conversationId | uuid or null | Groups the messages with one customer. |
smsFallback | object | Only 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. |
createdAt | date-time | When Ponitor accepted it. |
updatedAt | date-time | When 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.