Guide: Constructing WhatsApp Template Send Requests
Learn how to properly format and send WhatsApp template messages through the 8x8 API using both manual and automated approaches. This guide covers everything from basic template structure to advanced scripting for bulk template preparation.
Overview
WhatsApp Business templates are pre-approved message formats that allow businesses to initiate conversations with customers. This guide demonstrates two methods for sending these templates via the 8x8 API:
Method | Description | Best For |
---|---|---|
Manual | Step-by-step process using curl and JSON payloads | One-off messages, learning the API |
Scripted | Automated generation of ready-to-use cURL commands | Multiple templates, production workflows |
Prerequisites
- 8x8 API credentials (Account ID, Channel ID, Subaccount ID, API Key)
- WhatsApp recipient phone number (E.164 format, e.g., +14155551212)
- curl installed
- For scripted method: Node.js (v16+),
npm install dotenv axios
Manual Method
1. Fetch Templates
Run the following command in a terminal
curl -s -X GET "https://chatapps.8x8.com/api/v1/accounts/{your_account_id}/channels/{your_channel_id}/templates" \
-H "Authorization: Bearer {your_api_key}" \
-H "Accept: application/json" > templates.json
2. Extract Template Details
Open templates.json
in a text editor. Note:
templateName
as per the GET Templates response (orname
) in the corresponding Send message we're trying to composelanguage
components
(for required parameters)
3. Base API Request Structure
Every WhatsApp template message request to the 8x8 API must include the following fields:
{
"user": { "msisdn": "{{recipientPhoneNumber}}" },
"type": "template",
"content": {
"template": {
"name": "your_template_name",
"language": "template_language_code",
"components": [ /* see examples below */ ]
}
}
}
user.msisdn
: The recipient's phone number in E.164 format.type
: Always"template"
for template messages.content.template.name
: The template name as shown in your templates list.content.template.language
: The language code (e.g.,"en"
).content.template.components
: An array of components (see examples below).
4. Compose the Message Payload
Below are examples of the full payload for different template types. Replace the components
array as needed.
Simple Template (No Parameters)
{
"user": { "msisdn": "{{recipientPhoneNumber}}" },
"type": "template",
"content": {
"template": {
"name": "your_template_name",
"language": "en",
"components": []
}
}
}
Media Template Example
{
"user": { "msisdn": "{{recipientPhoneNumber}}" },
"type": "template",
"content": {
"template": {
"name": "your_template_name",
"language": "en",
"components": [
{
"type": "header",
"parameters": [
{ "type": "image", "url": "{{header_image_url}}" }
]
}
]
}
}
}
Body Parameters Example
{
"user": { "msisdn": "{{recipientPhoneNumber}}" },
"type": "template",
"content": {
"template": {
"name": "your_template_name",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "{{body_text_1}}" }
]
}
]
}
}
}
AUTHENTICATION Template Example
{
"user": { "msisdn": "{{recipientPhoneNumber}}" },
"type": "template",
"content": {
"template": {
"name": "your_template_name",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "{{otpCode}}" }
]
},
{
"type": "Button",
"subType": "url",
"index": 0,
"parameters": [
{ "type": "text", "text": "{{otpCode}}" }
]
}
]
}
}
}
5. Send the Message
Save your payload to message.json
and run the command below in the terminal, or directly run it in any API client (like Postman):
SUBACCOUNT_ID="your_subaccount_id"
API_TOKEN="your_api_token"
curl -X POST "https://chatapps.8x8.com/api/v1/subaccounts/$SUBACCOUNT_ID/messages" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d @message.json
Scripted Method
1. Setup
- Place generate-curl-scripts.js in your project directory.
- Install dependencies:
npm install dotenv axios
- Create a
.env
file:
API_BASE_URL=https://chatapps.8x8.com # replace with endpoint associated with your DC region https://developer.8x8.com/connect/docs/data-center-region#api-endpoints-and-data-center-region
ACCOUNT_ID=your_account_id
CHANNEL_ID=your_channel_id
SUBACCOUNT_ID=your_subaccount_id
API_KEY=your_api_key
2. Generate cURL Scripts
node generate-curl-scripts
- This creates a
generated_curl_scripts
directory with.sh
files for each template.
3. Use the Generated Scripts
- Edit the
.sh
file:- Replace
YOUR_API_TOKEN
with your token. - Replace placeholders (e.g.,
{{recipientPhoneNumber}}
,{{otpCode}}
) with real values.
- Replace
- Run the script:
./your_template_en.sh
Tips & Best Practices
- Always replace placeholders with real values before sending.
- Test with a non-production recipient first.
- From time to time, Meta might not deliver messages to maintain a healthy ecosystem, so you can try sending it to a secondary non-production recipient (Error Code: 131049 and similar) or try again later
- Review API responses for errors or message IDs.
Updated 1 day ago