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.
Authentication
Once your WhatsApp Business API is approved and provisioned, we generate an API Key for your account to be used.
You can retrieve your API Key directly from our Octopods App by selecting your approved and provisioned WhatsApp Business API account.
You need to use your API Key by adding a header as the following:
X-Octopods-Auth: YOUR_API_KEY
API Endpoints
Retrieve Message Template(s)
You can filter the templates retrieved by this endpoint using any of the query parameters below
Query Parameters
Parameter | Possible Values | Description | Required |
active | ["true", "false"] | Filters the templates by their active status | No |
lang | e.g. | Filters the templates by the language | No |
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'
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"
},
{
"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"
}
]
The templates_components object containers the different components of a message template and is always compliant with Facebook's own format.
Request (in cURL)
curl --location --request GET 'https://app.octopods.io/api/v1/whatsapp/templates/019S7WT' \
--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": 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"
}
Send a Message Template
Payload must be in JSON.
Request (in cURL)
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"
}'Parameter | Possible Values | Description | Required |
destination_phone | any e164 valid phone | the destination phone to send a message template to | Yes |
message_variables* | object | has possible properties "header" and "body" to specify message template variables | Yes, if your message template has variables |
message_variables.header | array | if your message template's header has variables like {{1}} and {{2}} , you can specify your variables here | Yes, if your message template has header variables |
message_variables.body | array | if your message template's body has variables like {{1}} and {{2}} , you can specify your variables here | Yes, if your message template has body variables |
message_variables.buttons | array | if your message template's button has a dynamic URL variable at the end of it, you can specify your variable here | Yes, if your message template has a dynamic URL button variable |
open_intercom_conversation | true or false | if you want Octopods to create an Intercom conversation in your Inbox | No |
header_attachment_url | string | URL to a media file, used for templates with media headers | Yes, if your template has a media header |
intercom_teammate_id** | string | Intercom teammate ID assigned to this message. | No |
*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.
**In case this proactive message created a new conversation with the end-user, 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.
Response (Created 201)
201 Created
{
"message_id": 42,
"phone_number": "353838000000",
"request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
}Errors
Example:
{
"request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
"error_code": 4,
"error": "Your Message Template has 2 variables which you must supply."
}
Get a Sent Message Status
Request (in cURL)
curl --location --request GET
'https://app.octopods.io/api/v1/whatsapp/messages/42' \--header
'X-Octopods-Auth: YOUR_API_KEY' \--header 'Content-Type: application/json'
The ID parameter is the message_id returned when sending messages via API. Please take a look at the send-a-message-template response example above for more information.
Response (200 OK)
201 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",
}201 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",
}*Expected statuses: SENT, DELIVERED, READ, FAILED, DELETED.
**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.
Get a List of Sent Messages
Request (in cURL)
curl --location --request GET
'https://app.octopods.io/api/v1/whatsapp/messages?limit=100' \--header
'X-Octopods-Auth: YOUR_API_KEY' \--header 'Content-Type: application/json'
The Limit parameter is optional (default & max 100).
Response (200 OK)
201 OK
[
{
"user_phone_number": "01234567890",
"created_at": "2000-01-01T04:20:00.000Z",
"message_content": "Hello World"
}
]
Phone Number Format
Your phone number should be in the E164 format in order to avoid receiving an Invalid Phone number error.
Rate Limiting
API Rate Limits are implemented to ensure high performance and continuous availability for Octopods services. These rate limits are in place to safeguard our databases from API traffic spikes and prevent hitting our providers’ rate limits.
Each channel connection would have a default rate limit of 330 requests per minute evenly distributed into 10 seconds sections. This means that each channel connection is limited to 55 requests per 10 seconds.
When the number of API requests sent from a single channel connection exceeds the mentioned rate limit, this channel connection will be put on a cool-down period of 5 minutes. Any requests beyond the rate limit or within the cool-down period will receive a response of '429 Too Many Requests' with a message indicating the time at which the cool-down period will end.