Endpoint

GET https://app.octopods.io/api/v1/whatsapp/templates

Returns every template registered against the WABA the API key belongs to, without pagination. A single template detail endpoint is also available:

GET https://app.octopods.io/api/v1/whatsapp/templates/:template_id

Authentication

Include your WhatsApp Business API Key in the request header:

X-Octopods-Auth: YOUR_WHATSAPP_BUSINESS_API_KEY

Query parameters

All filters are optional. If multiple are supplied, they’re combined with AND.

status — filter by template state. One of pending, under_review, needs_modification, rejected, accepted, deleted. Any other value returns error code 10 (INVALID_STATUS).
active — true or false. Filters to templates that are currently active or inactive inside Octopods.
lang — filter by language code. Accepts either a broad code (en, zh, pt, es) or a specific regional code (en_US, en_GB, zh_CN, pt_BR, and so on). Broad codes expand to match every regional variant: en matches en, en_GB, and en_US; zh matches zh_CN, zh_HK, and zh_TW; pt matches pt_BR and pt_PT; es matches es, es_AR, es_ES, and es_MX.

Only accepted templates are eligible to be used by the send endpoint, regardless of what the list endpoint returns.

Example request

GET https://app.octopods.io/api/v1/whatsapp/templates?status=accepted&lang=en
X-Octopods-Auth: YOUR_WHATSAPP_BUSINESS_API_KEY

Success response (list)

On success the API returns HTTP 200 OK with a JSON array:

[
  {
    "created_at": "2026-02-10T15:42:00Z",
    "template_id": 84579,
    "template_name": "order_shipped_v1",
    "template_body": "Hi {{1}}, your order {{2}} has shipped and should arrive by {{3}}.",
    "template_components": [
      { "type": "HEADER", "format": "TEXT", "text": "Shipping update" },
      { "type": "BODY",   "text": "Hi {{1}}, your order {{2}} has shipped and should arrive by {{3}}." },
      { "type": "FOOTER", "text": "Reply STOP to unsubscribe." }
    ],
    "account_phone_number": "+15551234567",
    "template_status": "Accepted"
  },
  {
    "created_at": "2026-01-05T09:12:00Z",
    "template_id": 73112,
    "template_name": "appointment_reminder",
    "template_body": "Hi {{1}}, reminder: your appointment is on {{2}} at {{3}}.",
    "template_components": [
      { "type": "BODY", "text": "Hi {{1}}, reminder: your appointment is on {{2}} at {{3}}." }
    ],
    "account_phone_number": "+15551234567",
    "template_status": "Accepted"
  }
]

Response fields

template_id — the value to use as :template_id when sending.
template_name — human-readable identifier for the template.
template_body — the body text with {{N}} placeholders.
template_components — the template’s full component list as returned by WhatsApp, covering header, body, footer, and buttons. Use this to determine how many placeholders each section needs and whether the header is text or media.
account_phone_number — the WhatsApp sender number associated with this template.
template_status — the template’s current review state.

Success response (single template)

The detail endpoint returns a single object with the same fields:

GET https://app.octopods.io/api/v1/whatsapp/templates/84579

{
  "created_at": "2026-02-10T15:42:00Z",
  "template_id": 84579,
  "template_name": "order_shipped_v1",
  "template_body": "Hi {{1}}, your order {{2}} has shipped and should arrive by {{3}}.",
  "template_components": [...],
  "account_phone_number": "+15551234567",
  "template_status": "Accepted"
}

Requesting a template that does not exist for this WABA returns error code 3 (TEMPLATE_NOT_EXIST).

Error codes

Code	Name	When it happens
1	`ARGUMENT_MISSING`	`:template_id` was omitted from the detail endpoint URL.
3	`TEMPLATE_NOT_EXIST`	No template matches `:template_id` on the detail endpoint.
6	`DEPRECATED_API_KEY`	The API key has been rotated or revoked.
10	`INVALID_STATUS`	`status` query parameter was not one of the accepted values.

When to call the list endpoint

At startup. Cache the list of accepted templates and their component shapes so your integration knows which IDs are safe to send.
After template changes. Re-fetch whenever you register, edit, or delete a template so your cache reflects the latest state.
For reporting. Combine the list with the sent messages endpoint to produce per-template volume reports.

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.

List WhatsApp Templates