When to use the API

The API is the right choice when you need to send programmatically or at volume, for example:

Triggering a message from a custom backend (an order confirmation system, a billing app, an appointment scheduler).
Integrating Octopods with a CRM or automation tool that is not HubSpot or Intercom.
Sending large batches of templated messages from a script or scheduled job.
Wiring proactive messaging into a product flow you already own.

For one-off sends, use the Intercom Inbox App, the HubSpot card, or the Reach browser extension instead — no code required.

The endpoints

All endpoints live under https://app.octopods.io/api/v1/ and respond with JSON. The public proactive messaging surface is:

Endpoint	Method	Purpose
`/api/v1/whatsapp/templates/{template_id}/messages`	POST	Send a WhatsApp template message.
`/api/v1/whatsapp/messages/{message_id}`	GET	Get delivery status of a WhatsApp message.
`/api/v1/whatsapp/messages`	GET	List recent WhatsApp messages.
`/api/v1/sms/messages`	POST	Send a free-text SMS message.
`/api/v1/sms/messages/{message_id}`	GET	Get delivery status of an SMS message.
`/api/v1/vbm/templates/{template_id}/messages`	POST	Send a VBM template message.

The deep reference for each endpoint lives in the following articles.

Authenticating requests

Every request must include an API key in the X-Octopods-Auth header:

X-Octopods-Auth: YOUR_API_KEY_HERE

Two kinds of key exist. The right one depends on the endpoint:

Endpoint family	Key type	Where to find it
`/api/v1/whatsapp/*`	WhatsApp API key	WhatsApp channel settings for the channel you want to send from.
`/api/v1/sms/*`	Channel API key	SMS channel settings for the channel you want to send from.
`/api/v1/vbm/*`	Channel API key	VBM channel settings for the channel you want to send from.

Note: Each key is scoped to a single channel. If you send from multiple channels, you will manage one key per channel.

Finding your API key.

In Octopods, open Settings → Channels.
Open the channel you want to send from.
Copy the API key from the channel’s settings screen.

Treat the key like a password. Rotate it from the same screen if it leaks, and store it in a secrets manager — never in source control.

Tip: If you see an error with code 6 and the message “Deprecated API Key. Please go to your Octopods App, and get your new API Key,” the key is from an older format. Re-copy it from the current channel settings screen.

Response format

Successful creates return HTTP 201 Created with a JSON body that always includes a request_id you can quote when contacting support:

{
  "request_id": "abc123…",
  "message_id": 98765,
  "channel_message_id": "provider-id-here"
}

Errors return HTTP 400 Bad Request (or 429 when rate-limited) with a JSON body of the form:

{
  "request_id": "abc123…",
  "error_code": 3,
  "error": "Message Template does not exist."
}

The per-endpoint articles list every error_code value for that endpoint.

Rate limits

WhatsApp endpoints are rate-limited per channel. If you exceed the ceiling, Octopods returns HTTP 429 with a retry timestamp telling you when the block lifts:

{
  "message": "You have fired too many requests. Please try after 2026-04-24 12:34:56 UTC."
}

Recommended client behavior:

On a 429, pause sends until the timestamp returned before retrying.
If you hit the ceiling repeatedly, batch sends across time rather than bursting.

Tip: If you have sustained high-volume needs that outgrow the default limit, contact Octopods support to discuss a higher ceiling for your account.

TLS and transport

All requests must use HTTPS. Requests to http:// are rejected.
Use Content-Type: application/json for POST bodies.
Octopods does not require IP allowlisting — any host can call the API with a valid key.

API Overview and Authentication