Endpoint
GET https://app.octopods.io/api/v1/whatsapp/messages
Returns messages in reverse chronological order (most recent first).
Authentication
Include your WhatsApp Business API Key in the request header:
X-Octopods-Auth: YOUR_WHATSAPP_BUSINESS_API_KEY
Only messages sent through the API with this same key are returned. Messages sent from the Intercom or HubSpot inbox, or through Broadcasts or Proactive Messaging in the UI, are not included.
Query parameters
limit— the maximum number of messages to return. Defaults to100, which is also the maximum. Requests with a larger value are capped at100.
Example request
GET https://app.octopods.io/api/v1/whatsapp/messages?limit=25 X-Octopods-Auth: YOUR_WHATSAPP_BUSINESS_API_KEY
Success response
On success the API returns HTTP 200 OK with a JSON body:
{
"request_id": "5f0b9c8a-2d1e-4e9a-9c4b-3a2d1e4e9a9c",
"messages": [
{
"message_id": 3851828,
"status": "delivered",
"phone_number": "+15551234567",
"sent_at": "2026-04-24T10:23:45Z"
},
{
"message_id": 3851827,
"status": "failed",
"phone_number": "+15557654321",
"sent_at": "2026-04-24T10:19:02Z",
"failure_reason": "Recipient is not a WhatsApp user."
}
]
}
Each item summarises one sent message. For the full status timeline of a single message, call the status endpoint with its message_id.
Error response
On failure the API returns HTTP 400 Bad Request:
{
"request_id": "5f0b9c8a-2d1e-4e9a-9c4b-3a2d1e4e9a9c",
"error_code": 6,
"error": "Deprecated API Key. Please go to your Octopods App, and get your new API Key"
}
Error codes
Code | Name | When it happens |
6 |
| The API key has been rotated or revoked. Fetch the current key from Octopods. |
Use cases
Nightly reconciliation. Pull yesterday’s sends and cross-check against your own records.
Dashboards. Surface send volume and failure rate inside your own admin tools.
Retry failed sends. Iterate through the list, look for
status: "failed", and decide whether to retry.
Rate limits
Listing calls share the same per-API-key rate limit as WhatsApp template sends. On a breach, the response is HTTP 429 with a retry timestamp; pause until the timestamp passes before retrying. If you need to page through many messages, space your requests accordingly.
What’s next