> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/whatsapp-cloud-api/post-whatsapp-template-message.md).
# POST WhatsApp Template Message
### When should you use this?
Use this API when:
* You want to send approved WhatsApp template messages programmatically
* You need to trigger WhatsApp notifications from an external application
* You are trying to automate WhatsApp communication using approved Meta templates
***
### What is the POST WhatsApp Template Message API?
The POST WhatsApp Template Message API allows you to send approved WhatsApp templates directly to users through BotPenguin.
This API supports:
* Template variables
* Media headers
* Agent assignment
* Conversation tagging
* Dynamic personalization
***
### Benefits of the WhatsApp Template Message API
* 🚀 Automates WhatsApp outreach at scale
* 📩 Supports approved Meta template messages
* 🎯 Enables personalized communication using variables
* 🏷️ Allows automatic conversation tagging
* 👥 Supports assigning conversations to agents
***
### Expected Outcome
After using this API:
* Approved WhatsApp templates will be delivered to users
* Template variables will be dynamically populated
* Conversations can be automatically tagged
* Chats can be assigned to specific agents
{% hint style="info" %}
Tip: Ensure that the template is approved by Meta before attempting to send messages through this API.
{% endhint %}
***
### API Endpoint
```http
POST https://api.v7.botpenguin.com/whatsapp-automation/wa/send-template?apiKey={API_KEY}
```
***
### Request Headers
| Header | Value |
| ------------ | ---------------- |
| authType | Key |
| Content-Type | application/json |
***
### Query Parameters
| Parameter | Description |
| --------- | ----------------------- |
| apiKey | Your BotPenguin API Key |
***
### Request Parameters
| Parameter | Description |
| ---------- | ----------------------------------------------------- |
| userName | Name of the recipient |
| wa\_id | WhatsApp number including country code without + sign |
| templateId | Approved WhatsApp Template ID |
| assignTo | Email address of the assigned agent or custom user |
| params | Variables used inside the template |
| tags | Labels used to organize conversations |
***
### Template Variable Types
#### 1. Name-Based Variables
Select **"Name"** while creating the template if your variables are named.
Example variables:
* customer\_name
* lead\_name
* industry
* meeting\_day
For Name-based variables, every parameter must include a **parameter\_name** field matching the exact variable name configured in the template.
#### Example Parameter
```json
{
"type": "text",
"text": "John",
"parameter_name": "customer_name"
}
```
#### Example Request Body
```json
{
"userName": "John Doe",
"wa_id": "919876543210",
"templateId": "TEMPLATE_ID",
"params": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "John Doe",
"parameter_name": "customer_name"
},
{
"type": "text",
"text": "Healthcare",
"parameter_name": "domain"
},
{
"type": "text",
"text": "Monday",
"parameter_name": "meeting_day"
}
]
}
]
}
```
***
#### 2. Number-Based Variables
Select **"Number"** while creating the template if your variables are positional.
Examples:
* Variable 1
* Variable 2
* Variable 3
For Number-based variables, **parameter\_name** is not required.
Values are mapped based on their order within the template.
#### Example Request Body
```json
{
"params": [
{
"type": "header",
"parameters": [
{
"type": "document",
"document": {
"link": "https://your-file-url.pdf"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Value 1"
},
{
"type": "text",
"text": "Value 2"
}
]
}
],
"assignTo": "agent@example.com",
"tags": ["tag1"]
}
```
***
### Complete API Example
#### Request
```bash
curl --location --request POST 'https://api.v7.botpenguin.com/whatsapp-automation/wa/send-template?apiKey=YOUR_API_KEY' \
--header 'authType: Key' \
--header 'Content-Type: application/json' \
--data-raw '{
"userName": "Test",
"wa_id": "91885917XXXX",
"templateId": "63dba1617XXXX52face07078",
"params": [
{
"type": "header",
"parameters": [
{
"type": "document",
"document": {
"link": "https://www.africau.edu/images/default/sample.pdf"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Abc"
},
{
"type": "text",
"text": "Def"
},
{
"type": "text",
"text": "Monday"
}
]
}
],
"assignTo": "example@gmail.com",
"tags": [
"test"
]
}'
```
***
### Response Headers
| Header | Details |
| -------------------------------- | ------------------------------- |
| X-Powered-By | Express |
| Vary | Origin |
| Access-Control-Allow-Credentials | true |
| \_user | User ID |
| \_bot | Bot ID |
| whatsAppId | WhatsApp Account ID |
| Content-Type | application/json; charset=utf-8 |
| Content-Length | Response Length |
| Etag | Response ETag |
| Date | Response Date |
| Connection | keep-alive |
| Keep-Alive | timeout=5 |
***
### Best Practices
> 💡 Always use approved WhatsApp templates before sending messages.
> ⚠️ Ensure the WhatsApp number includes the country code and excludes the "+" symbol.
> 🚀 Use meaningful tags to organize conversations efficiently.
> 🎯 Validate template variables before making the API request.
***
### Troubleshooting
Message is not being delivered
Verify that:
* The template is approved by Meta.
* The recipient WhatsApp number is correct.
* The API key is valid and active.
* The WhatsApp channel is properly connected.
Invalid templateId error
Ensure the template ID exists and belongs to the connected WhatsApp Business Account.
Also verify that the template has not been deleted or rejected by Meta.
Variables are not populating correctly
For Name-based variables, verify that each parameter contains the correct **parameter\_name** matching the template variable.
For Number-based variables, ensure values are passed in the exact order expected by the template.
Agent assignment is not working
Ensure the email address provided in **assignTo** belongs to an existing BotPenguin user or agent.
Authentication failed
Verify:
* The API key is correct.
* The API key has not expired.
* The apiKey query parameter is included in the endpoint URL.
***
### FAQs
Does the template need Meta approval before sending?
Yes. Only approved WhatsApp templates can be sent using this API.
Can I send media inside template messages?
Yes. Media such as documents, images, and videos can be sent through template headers if configured in the template.
What is the difference between Name and Number variables?
Name variables use explicit variable names and require parameter\_name. Number variables use positional mapping and do not require parameter\_name.
Can I assign a conversation to an agent while sending the template?
Yes. Use the assignTo field and provide the email address of the desired agent.
Can I add tags to conversations?
Yes. Use the tags array to automatically apply labels to the conversation.
Is the country code required in wa_id?
Yes. The country code is mandatory and must be included without the "+" sign.
Can I send a template without variables?
Yes. For templates without variables, send an empty params array.
***
### Support
If you still have questions for our team, write to us at ****. We'll get back to you within 48 hours.