WhatsApp Templates are pre-approved message formats required for sending business-initiated WhatsApp messages.
This page explains what WhatsApp Templates are, how they work in InstaMessage, how placeholders map to parameters, and how to send a template message via the API.
A WhatsApp Template is a structured message that must be:
- Created in advance
- Submitted to Meta for approval
- Categorised (Marketing, Utility, Authentication)
Template categories are defined by Meta and determine how messages are classified and billed.
Once a customer replies, a 24-hour customer service window opens and you may send free-form messages without templates.
| Scenario | Template required |
|---|---|
| Business sends first message | ✅ Yes |
| Customer replies (within 24h) | ❌ No |
| Sending marketing notifications | ✅ Yes |
| Transactional updates (outside 24h window) | ✅ Yes |
If you attempt to send a free-form WhatsApp message outside the 24-hour window, the API will return an error.
You can create and manage WhatsApp Templates in InstaMessage from the Template screen.
You can:
- Create new Templates
- Define placeholder variables
- Choose a category
- Submit templates for Meta approval
- View approval status
Template creation is handled in the UI rather than via the API.
Templates may contain numbered placeholders, for example:
Hi {{1}}, your order {{2}} has been confirmed.Key rules:
- Placeholders are positional
- They are numbered starting from {{1}}
- The order matters
When sending a Template message via the API, you must supply a parameters array.
Parameters:
- Are ordered
- Must match the placeholders exactly
- Are mapped by position, not name
Template:
Hi {{1}}, your order {{2}} has been confirmed.API parameters:
"parameters": ["Alex", "12345"]Resulting message:
Hi Alex, your order 12345 has been confirmed.
WhatsApp Templates are sent using the unified Messages API.
Endpoint
POST https://api.instamessage.co.uk/v1/messagesIf a WhatsApp Journey sends the first message in a conversation, that message must also be a Template.
| Field | Description |
|---|---|
channel | Must be "whatsapp" |
to | Recipient number in E.164 format |
message_type | Must be "template" |
template_id | Approved template id |
template_parameters | Ordered array of values |
curl -X POST "https://api.instamessage.co.uk/v1/messages" \
-H "Authorization: Bearer $IM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"to": "+447123456789",
"message_type": "template",
"template": {
"id": "PfjZ****************",
"parameters": ["Alex", "12345"]
}
}'| Feature | Template parameters | injected_fields |
|---|---|---|
| Used with WhatsApp Templates | ✅ Yes | ❌ No |
| Ordered values | ✅ Yes | ❌ No |
| Stored on contact | ❌ No | ❌ No |
| Used in free-form messages | ❌ No | ✅ Yes |
| Requires Meta approval | ✅ Yes | ❌ No |
injected_fieldscannot be used inside WhatsApp Templates.
Missing parameters
{
"error": "missing_template_parameters",
"message": "Template requires 2 parameters but only 1 was provided"
}Template not approved
{
"error": "template_not_approved",
"message": "The template 'order_confirmation' is not approved"
}- Templates are mandatory for business-initiated WhatsApp messages
- Placeholders are positional, not named
- Parameters must be supplied in the correct order
- Free-form WhatsApp messages are only allowed inside the 24-hour window
- Templates are created and approved in the UI, not via API
- Send messages → Send a Message
- WhatsApp rules → Getting Started – WhatsApp
- Receive replies → Inbound Messages & Replies
- Track delivery → Delivery Receipts & Message Status
WhatsApp Templates ensure compliance with Meta policies while enabling reliable, scalable outbound messaging.