Templates are reusable messages that you can send to your customers, with a few variables that you can customize. These are useful for notifications, and can be sent directly from the Octopods Intercom Inbox app/widget.

Once the 24-hour customer service window has expired, Message Templates are the only way you'll be able to reestablish contact with your customer. Click here for more information on the customer service window.

Through Octopods, you can use our Message Templates API to programmatically send Message Templates to your Users directly for Intercom & HubSpot.

Authentication

Once your WhatsApp Business API is approved and provisioned, we generate an API Key for your account. You can retrieve your API Key from the Octopods dashboard by selecting your approved WhatsApp Business API account.

Using Your API Key

Include your API key in all requests as a header:

X-Octopods-Auth: YOUR_API_KEY

API Endpoints

1. Retrieve Message Template(s)

Get a list of all available message templates or retrieve a specific template.

Get All Templates

HTTP GET

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

Query Parameters

Parameter	Type	Values	Description	Required
`active`	boolean	`true`, `false`	Filters templates by active status	No
`status`	string	`pending`, `under_review`, `needs_modification`, `rejected`, `accepted`, `deleted`	Filters templates by WhatsApp approval status	No
`lang`	string	ISO 639-1 codes (e.g., `en`, `pt`, `ar`)	Filters templates by language	No

Example Request (in cURL)

curl --location --request GET 'https://app.octopods.io/api/v1/whatsapp/templates/' \
--header 'X-Octopods-Auth: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Example Response (in JSON)

[
  {
    "created_at": "2021-09-24T14:29:32.000Z",
    "template_id": 539,
    "template_name": "account_update_1",
    "template_body": "go here: {{1}} to check your updated information.",
    "template_components": [
        {
            "text": "go here: {{1}} to check your updated information.",
            "type": "BODY"
        }
    ],
    "account_phone_number": "+353894876742",
    "template_status": "Accepted"
  },
  {
    "created_at": "2021-09-24T14:29:32.000Z",
    "template_id": 537,
    "template_name": "appointment_1",
    "template_body": "Hello {{1}}, here is the appointment link: {{2}} Thank you",
    "template_components": [
        {
            "format": "TEXT",
            "text": "Welcome to our online shoe store {{1}}!",
            "type": "HEADER"
        },
        {
            "text": "Hello {{1}}, here is the appointment link: {{2}} Thank you",
            "type": "BODY"
        },
        {
            "text": "Thank you so much!",
            "type": "FOOTER"
        },
        {
            "buttons": [
                {
                    "text": "Call us",
                    "type": "QUICK_REPLY"
                },
                {
                    "text": "Speak to a human now",
                    "type": "QUICK_REPLY"
                }
            ],
            "type": "BUTTONS"
        }
    ],
    "account_phone_number": "+353894876742",
    "template_status": "Rejected"
  }
]

Note: The templates_components object containers the different components of a message template and is always compliant with Facebook's own format.

Get Single Template

HTTP GET

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

Path Parameters

Parameter	Type	Description
`TEMPLATE_ID`	integer	The Template ID returned when fetching templates or in Octopods URL for the Template page*

*Octopods Template ID is the last digits in the URL in your telegram show page. It should look like this https://app.octopods.io/me/accounts/*/workspaces/*/channels/*/templates/<TEMPLATE_ID>

Example Request (in cURL)

curl --location --request GET 'https://app.octopods.io/api/v1/whatsapp/templates/19S7' \
--header 'X-Octopods-Auth: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Response (in JSON)

{
  "created_at": "2021-09-24T14:29:32.000Z",
  "template_id": 1987,
  "template_name": "account_update_1",
  "template_body": "go here: {{1}} to check your updated information.",
  "template_components": [
      {
          "text": "go here: {{1}} to check your updated information.",
          "type": "BODY"
      }
  ],
  "account_phone_number": "+353894876742",
  "template_status": "Accepted"
}

2. Send a Message Template

Send a message template to a recipient with customized variables.

HTTP POST

https://app.octopods.io/api/v1/whatsapp/templates/:TEMPLATE_ID/messages

Path Parameters

Parameter	Type	Description
`TEMPLATE_ID`	integer	The Template ID to be sent.

Request Parameters

Parameter	Type	Description	Required
`destination_phone`	string	Recipient's phone number in E.164 format	Yes
`message_variables`	object	Contains `header`, `body`, and `buttons` arrays for template variables	Yes*
`message_variables.header`	array	Values for header variables like `{{1}}`, `{{2}}`	Yes*
`message_variables.body`	array	Values for body variables like `{{1}}`, `{{2}}`	Yes*
`message_variables.buttons`	array	Values for dynamic URL button variables or Copy Code buttons	Yes*
`header_attachment_url`	string	URL to media file for templates with media headers	Yes**
`destination_user_name`	string	Name for new contacts (if they don't exist)	No

*Required if your template contains variables
**Required if your template has a media header

Note: The message_variables object has been updated recently, it was previously only an array, we still support that format for body variables only, but if your template contains header variables, you will have to use the new format.

Platform-Specific Parameters

Parameter	Platform	Type	Description	Required
`open_intercom_conversation`	Intercom	boolean	Creates an Intercom conversation in your Inbox	No
`intercom_teammate_id`	Intercom	string	Assigns conversation to specific Intercom teammate	No

Note: in case this proactive message created a new conversation with the end-user on Intercom, we will start & assign this teammate-initiated conversation to the admin ID equal to the specified intercom_teammate_id. If blank, we resolve to the workspace admin.

Example Request (in cURL)

Payload must be in JSON.

curl --location --request POST 'https://app.octopods.io/api/v1/whatsapp/templates/019S7WT/messages' \
--header 'X-Octopods-Auth: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "destination_phone": "+353838000000",
  "message_variables": {
    "header": ["variable1"],
    "body": [ "variable1", "variable2"]
  },
  "header_attachment_url": "url_to_image",
  "open_intercom_conversation": false,
  "intercom_teammate_id": "5173352"
}'

Example Response

201 Created

{
  "message_id": 42,
  "phone_number": "353838000000",
  "request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
}

3. Get Message Status

Check the delivery status of a sent message.

HTTP GET

https://app.octopods.io/api/v1/whatsapp/messages/:MESSAGE_ID

Path Parameters

Parameter	Type	Description
`MESSAGE_ID`	integer	The message ID returned when sending the Template

Example Request (in cURL)

curl --location --request GET 
'https://app.octopods.io/api/v1/whatsapp/messages/42' \
--header 'X-Octopods-Auth: YOUR_API_KEY'

Example Response - Success

200 OK

{
  "message_id": 42,
  "status": "DELIVERED",
  "status_message": "Your message has been delivered successfully.",
  "intercom_conversation_id": "<Intercom_Conversation_ID>",
  "intercom_conversation_part_id": "<Intercom Conversation Message ID>",
  "last_updated": "2023-07-07T11:15:46.000Z",
  "request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
}

Example Response - Failed

200 OK

{
  "message_id": 42,
  "status": "FAILED",
  "status_message": "Your message has failed to be sent.",
  "intercom_conversation_id": "<Intercom_Conversation_ID>",
  "intercom_conversation_part_id": "",
  "failure_reason": {
        "code": "63003",
        "description": "Channel could not find To address"
  },
  "last_updated": "2023-07-07T11:15:46.000Z",
  "request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
}

Possible Status Values

SENT - Message sent to WhatsApp
DELIVERED - Message delivered to recipient
READ - Message read by recipient
FAILED - Message failed to send
DELETED - Message was deleted

Note: Intercom Conversation ID with Intercom Conversation Part ID points to the message in Intercom - Intercom Conversation Part ID will be blank if the message failed to sent.

4. Get List of Sent Messages

Retrieve a paginated list of messages you've sent.

HTTP GET

https://app.octopods.io/api/v1/whatsapp/messages

Query Parameters

Parameter	Type	Description	Default	Max
`limit`	integer	Number of messages to return	100	100

Example Request (in cURL)

curl --location --request GET 
'https://app.octopods.io/api/v1/whatsapp/messages?limit=100' \
--header 'X-Octopods-Auth: YOUR_API_KEY'

Example Response

200 OK

[
  {
    "user_phone_number": "01234567890",
    "created_at": "2000-01-01T04:20:00.000Z",
    "message_content": "Hello World",
"message_status": {
            "channel_message_id": "<ID>",
            "message_status": "DELIVERED",
            "failure_reason": ""
        }
  },
  {
    "user_phone_number": "01234567890",
    "created_at": "2000-01-01T04:20:00.000Z",
    "message_content": "Hello World",
    "message_status": {
            "channel_message_id": "<ID>",
            "message_status": "FAILED",
            "failure_reason": {
                "code": 131049,
                "description": "This message was not delivered to maintain healthy ecosystem engagement."
            }
        }
  },

]

Error Handling

All errors follow a consistent format and include a request_id & error message for debugging.

Error Response Format

{
  "request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
  "error_code": 4,
  "error": "Your Message Template has 2 variables which you must supply."
}

Common Error Codes

HTTP Status	Error Code	Description
400	1	Argument missing.
400	2	Type mismatch.
400	3	Message Template not found.
400	4	Missing required template variables
404	5	Invalid Phone number.
401	-	Unauthorized.

Phone Number Format

All phone numbers must be in E.164 format:

Start with + followed by country code
No spaces, dashes, or parentheses
Example: +14155552671

Common Mistakes to Avoid

❌ 14155552671 (missing +)
❌ +1 (415) 555-2671 (contains spaces and parentheses)
✅ +14155552671 (correct format)

Rate Limiting

To ensure optimal performance, API rate limits are enforced per channel connection.

Rate Limit Details

330 requests per minute (distributed evenly across 10-second intervals)
Effectively 55 requests per 10 seconds
Cool-down period of 5 minutes if limit exceeded
HTTP 429 response when rate limited

Best Practices

Test with a Single Template First - Validate your integration with one template before scaling
Handle Errors Gracefully - Always check response status and handle failures appropriately
Respect Rate Limits - Implement exponential backoff when receiving 429 responses
Use E.164 Format - Always validate phone numbers before sending
Monitor Message Status - Poll the status endpoint to track delivery
Keep API Keys Secure - Never expose API keys in client-side code or public repositories
Use Descriptive Names - When creating contacts, provide meaningful destination_user_name values

Need Help?

If you have questions or need assistance with the API, please contact our support team.

WhatsApp Message Templates API Reference

Authentication

Using Your API Key

API Endpoints

1. Retrieve Message Template(s)

Get All Templates

Get Single Template

2. Send a Message Template

3. Get Message Status

4. Get List of Sent Messages

Error Handling

Phone Number Format

Rate Limiting

Best Practices

Need Help?