Skip to main content

Sending WhatsApp Messages via API

Send approved WhatsApp template messages programmatically through the Octopods API, with variable values mapped to placeholders.

Written by Tarek Khalil

What this API is for

The Octopods WhatsApp API lets you send approved template messages from your own backend or automation tools. Typical use cases:

  • Transactional notifications from your own system (order shipped, appointment reminder).

  • Scheduled outreach triggered from a CRM or ticketing tool.

  • Programmatic first-touch messages for customers who haven’t messaged you yet.

Freeform (non-template) WhatsApp messages to customers inside the 24-hour messaging window are best sent from the Intercom or HubSpot inbox where your teammates are already working. Template sends are what this API is designed for.

This endpoint works for both Intercom and HubSpot workspaces.

Before you start

You need:

Endpoint

The template ID goes in the URL path. Send a POST to:

POST https://api.octopods.io/api/v1/whatsapp/templates/{template_id}/messages

Replace {template_id} with the ID of the approved template (visible on the template detail page).

Authenticate with your WhatsApp Business API key in the X-Octopods-Auth header:

X-Octopods-Auth: <your-whatsapp-api-key>

Required parameters

Send the payload as JSON:

  • destination_phone — the destination phone number in E.164 format (for example, +15551234567).

  • message_variables — an object mapping {{N}} placeholders to their values. Keys are the placeholder numbers as strings ("1", "2", …).

Optional parameters

  • header_attachment_url — if the template’s header is a media type (image, video, or document), include the public URL of the media file you want WhatsApp to attach to this send.

  • open_intercom_conversation — true to automatically open a new conversation in Intercom when the template is sent. (For HubSpot workspaces, the conversation is created in HubSpot regardless.)

  • intercom_teammate_id — the ID of the Intercom user who should appear as the sender of the conversation. Defaults to the channel’s default sender.

  • destination_user_name — a display name to associate with the destination phone number, used when Octopods creates a contact in your CRM.

Example request

curl -X POST \
  "https://api.octopods.io/api/v1/whatsapp/templates/order_confirmation_v1/messages" \
  -H "X-Octopods-Auth: <your-whatsapp-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_phone": "+15551234567",
    "message_variables": {
      "1": "Jane",
      "2": "ORD-9876",
      "3": "April 28"
    },
    "header_attachment_url": "https://example.com/invoices/ORD-9876.png",
    "open_intercom_conversation": true
  }'

The template body Hi {{1}}, your order {{2}} has shipped and should arrive by {{3}}. renders as:

Hi Jane, your order ORD-9876 has shipped and should arrive by April 28.

Response

On success, Octopods returns details about the queued send:

{
  "request_id": "req_01HT5Q...",
  "message_id": "msg_01HT5Q...",
  "message_status_url": "https://api.octopods.io/api/v1/whatsapp/messages/msg_01HT5Q...",
  "phone_number": "+15551234567",
  "channel_message_id": "wamid.HBgLM..."
}

Use the message_status_url to poll for delivery state — see Sending WhatsApp Template Messages via API for the response shape.

On failure, the response includes a numeric error code and an error description:

{
  "error_code": 4,
  "error": "Template 'order_confirmation_v1' is not approved."
}

Variable mapping rules

  • Every placeholder must be supplied. If your template body uses {{1}}, {{2}}, and {{3}}, the message_variables object must have keys "1", "2", and "3". Missing any of them causes the send to fail.

  • Values are strings. Numeric values should be formatted as strings ("42", not 42).

  • Line breaks inside a variable are not allowed. Meta rejects multi-line variable content.

  • URLs in variables must be valid. Meta validates URL placeholders at send time.

Delivery statuses

After sending, the conversation in your Intercom or HubSpot inbox reflects the message’s lifecycle:

  • Sent — Octopods handed the message to the provider.

  • Delivered — the provider confirmed delivery to the recipient’s phone.

  • Read — the recipient opened the message (only if the recipient has read receipts enabled).

  • Failed — the message was rejected by the provider. The conversation shows the failure reason (for example, recipient not on WhatsApp, template not approved for the recipient’s country).

Rate limits

The WhatsApp API is rate-limited per WhatsApp Business API Key. If you exceed the ceiling, Octopods returns HTTP 429 with a retry timestamp; pause sends until the timestamp passes.

WhatsApp itself also enforces per-phone-number sending tiers based on number quality. Quality degrades when recipients block your business or mark messages as spam. Keep your template content relevant and ensure you have opt-in consent from every recipient.

Common errors

  • Template not approved — the template hasn’t been approved by Meta yet, or has been deactivated. Wait for approval or pick a different template.

  • Invalid variables — a placeholder is missing, or a value contains a line break or invalid URL.

  • Recipient not on WhatsApp — the phone number isn’t registered on WhatsApp.

  • Rate limit exceeded — you’ve hit the API rate limit or the per-number send tier. Space out your sends.

  • Unauthorized — the X-Octopods-Auth header is missing, revoked, or belongs to a different channel.

For the full numeric error-code table, see API Error Reference.

What’s next

Did this answer your question?