Endpoint
GET https://app.octopods.io/api/v1/whatsapp/messages
Authentication:
X-Octopods-Auth: YOUR_WHATSAPP_API_KEYfor the WhatsApp channel whose history you want to read.Content type: none — this is a GET request.
Query parameters
Parameter | Type | Required | Description |
| integer | No | Maximum number of messages to return. Defaults to 100 and is capped at 100 per call. |
The endpoint returns the most recent messages first.
Request
curl "https://app.octopods.io/api/v1/whatsapp/messages?limit=25" \ -H "X-Octopods-Auth: YOUR_WHATSAPP_API_KEY"
Response
HTTP 200 OK with an array of messages:
[
{
"user_phone_number": "+14155552671",
"created_at": "2026-04-24T12:34:56Z",
"message_content": "Hi Alex — your order is on the way!",
"message_status": {
"channel_message_id": 98765,
"message_status": "DELIVERED",
"failure_reason": ""
}
},
{
"user_phone_number": "+14155551234",
"created_at": "2026-04-24T12:30:10Z",
"message_content": "Your verification code is 482910.",
"message_status": {
"channel_message_id": 98764,
"message_status": "FAILED",
"failure_reason": { "code": 470, "title": "Re-engagement window expired" }
}
}
]
Field | Description |
| Recipient phone, in E.164 format. |
| When Octopods received the send request. |
| The rendered message body (sanitized of any HTML). |
| The Octopods message ID — the same value returned as |
| One of |
| For |
Pagination
The endpoint returns one page of up to 100 messages. If you need older history, request pages of 100 and store the oldest created_at you have seen; keep records externally if you need longer-term audit.
Error responses
HTTP status | When | How to handle |
400 | Missing or deprecated API key. | Copy the current key from the WhatsApp channel settings screen. |
400 (as | No messages have been sent on this channel yet. | Send at least one message before listing. |
Note: Listing is only available for WhatsApp channels. For SMS and Viber Business Messages (VBM), retrieve per-message status with Checking Message Delivery Status.
What’s next