Template Message - WhatsAble Documentation

Templates enable personalized communication while ensuring compliance with WhatsApp’s business policies. This API lets you send template-based messages to your customers with dynamic content.

WhatsApp requires businesses to use pre-approved templates for initiating conversations. This API allows you to send template messages with personalized variables, media attachments, and interactive components to your customers.

Overview

The Send Template Message API enables you to:

Send WhatsApp messages using your pre-approved templates
Dynamically replace variables with personalized content
Attach media (images, videos, documents) when supported by the template
Include interactive elements like buttons and quick replies
Track delivery status through WhatsApp response information

Try it in the API Reference

Experiment with the Send Template Message API and view responses in real-time

Send Template Message

Send a personalized WhatsApp template message to a specific phone number.

Endpoint

POST https://api.insightssystem.com/api:hFrjh8a1/send_template_message

Authentication

All API requests require authentication using your API key. Never share your API keys in client-side code.

Include your API key in all requests using Bearer authentication:

Authorization: Bearer YOUR_API_KEY

Request Body

template_id

string

required

The unique identifier of the template to use. You can retrieve this from the Get Templates API.

phone_number

string

required

The recipient’s phone number in international format with country code (e.g., “+123456789012”).

variables

object

required

Object containing key-value pairs for template variables. The keys must match the variable names defined in your template.

Show Variable Types

body{n}

string

Text variables that replace placeholders in the message body (e.g., body1, body2, etc.)

header{n}

string

Text variables that replace placeholders in the message header

media

string

Public URL to media content (image, video, or document) for templates with media support

button{n}

string

Text or URL for dynamic buttons in interactive templates

language

string

default:"en"

The language code for the template. Must match one of the languages your template is approved for.

Response

The API returns a detailed response indicating whether the message was accepted for delivery and provides WhatsApp message identifiers for tracking.

success

boolean

Indicates if the request was successfully processed

whatsapp_response_info

object

Details from the WhatsApp Business API about the message delivery

Show WhatsApp Response Fields

messaging_product

string

Always “whatsapp” for WhatsApp messages

contacts

array

Information about the message recipient

input

string

The phone number that was provided in the request

wa_id

string

WhatsApp’s unique identifier for the recipient

messages

array

Details about the sent message

string

Unique message identifier (wamid) for tracking status

message_status

string

Initial status of the message (typically “accepted”)

error

object

Present only when an error occurs

code

string

Error code identifier

message

string

Human-readable error description

Example Request

curl -X POST \
  https://api.insightssystem.com/api:hFrjh8a1/send_template_message \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "template_id": "6f6e4113-cc8a-4fbe-b98d-2c631d299c6b",
    "phone_number": "+123456789012",
    "variables": {
      "body1": "John Doe",
      "body2": "Premium Subscription",
      "body3": "$49.99",
      "media": "https://storage.googleapis.com/your-public-bucket/offer-image.jpg",
      "button1": "https://example.com/special-offer"
    },
    "language": "en"
  }'

Example Response

{
  "success": true,
  "whatsapp_response_info": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "+123456789012",
        "wa_id": "123456789012"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgLMTIzNDU2Nzg5MDEyFQIAERgSNUU2RjM4NzM1M0Q5OEIwQTQwAA==",
        "message_status": "accepted"
      }
    ]
  }
}

Response Codes

200: Success

400: Bad Request

401: Unauthorized

403: Forbidden

404: Not Found

The template specified doesn’t exist.

{
  "success": false,
  "error": {
    "code": "template_not_found",
    "message": "Template with ID '6f6e4113-cc8a-4fbe-b98d-2c631d299c6b' not found"
  }
}

422: Unprocessable Entity

429: Too Many Requests

500: Server Error

Something went wrong on our end. Please contact support if the issue persists.

{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "An internal server error occurred"
  }
}

Working with Template Variables

Templates contain placeholders that are replaced with dynamic content when sending messages. Understanding how to map your data to these variables is essential.

Variable Types

Text Variables

Body and header variables replace text placeholders in your template. They are named body1, body2, etc., or header1, header2, etc.

Media Variables

Media variables allow you to attach images, videos, or documents to your template. Provide a public URL in the media property.

Button Variables

Used for dynamic buttons in interactive templates. Can be URLs or text, depending on the button type.

Quick Reply Variables

For templates with quick reply buttons, provide the text to display on each button.

Variable Mapping

Identify template variables

Examine your template structure to identify which variables are required. You can find this information using the Get Templates API.

Prepare your data

Format your data to match the expected variable structure. Ensure values meet any length or format requirements.

Map data to variables

Create a variables object with keys matching your template’s variable names and values from your data.

Handle media properly

For media templates, ensure your media URL is publicly accessible and in a WhatsApp-supported format.

Media Guidelines

When including media in your templates, follow these guidelines for optimal delivery:

Images

Supported formats: JPG, JPEG, PNG
Max size: 5MB
Recommended aspect ratio: 1.91:1

Videos

Supported formats: MP4, 3GPP
Max size: 16MB
Max duration: 1 minute

Documents

Supported formats: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX
Max size: 100MB

URLs

Must be publicly accessible
Direct file links (no redirects)
HTTPS required

Media URLs must be publicly accessible without requiring authentication. For security, we recommend using signed URLs with limited-time access.

Best Practices

Error Handling

Implement comprehensive error handling to manage API failures gracefully. Always check the success field in responses and handle various error scenarios.

Message Tracking

Store the returned message_id values to track delivery status using the Message Status API.

Throttling

Implement request throttling when sending to multiple recipients to avoid hitting rate limits and ensure reliable delivery.

Template Testing

Test your templates with various inputs to ensure variables are correctly replaced and messages appear as expected.

FAQs

Why was my message not delivered?

Can I send to non-WhatsApp users?

How do I know if my message was delivered?

Can I edit a message after sending?

Need help?

Our support team is available 24/7 to assist with template issues, API integration, or any other questions.

On this page

Overview
Send Template Message
Endpoint
Authentication
Request Body
Response
Example Request
Example Response
Response Codes
Working with Template Variables
Variable Types
Variable Mapping
Media Guidelines
Best Practices
FAQs

Templates enable personalized communication while ensuring compliance with WhatsApp’s business policies. This API lets you send template-based messages to your customers with dynamic content.

Overview

The Send Template Message API enables you to:

Send WhatsApp messages using your pre-approved templates
Dynamically replace variables with personalized content
Attach media (images, videos, documents) when supported by the template
Include interactive elements like buttons and quick replies
Track delivery status through WhatsApp response information

Try it in the API Reference

Experiment with the Send Template Message API and view responses in real-time

Send Template Message

Send a personalized WhatsApp template message to a specific phone number.

Endpoint

POST https://api.insightssystem.com/api:hFrjh8a1/send_template_message

Authentication

All API requests require authentication using your API key. Never share your API keys in client-side code.

Include your API key in all requests using Bearer authentication:

Authorization: Bearer YOUR_API_KEY

Request Body

template_id

string

required

The unique identifier of the template to use. You can retrieve this from the Get Templates API.

phone_number

string

required

The recipient’s phone number in international format with country code (e.g., “+123456789012”).

variables

object

required

Object containing key-value pairs for template variables. The keys must match the variable names defined in your template.

Show Variable Types

body{n}

string

Text variables that replace placeholders in the message body (e.g., body1, body2, etc.)

header{n}

string

Text variables that replace placeholders in the message header

media

string

Public URL to media content (image, video, or document) for templates with media support

button{n}

string

Text or URL for dynamic buttons in interactive templates

language

string

default:"en"

The language code for the template. Must match one of the languages your template is approved for.

Response

The API returns a detailed response indicating whether the message was accepted for delivery and provides WhatsApp message identifiers for tracking.

success

boolean

Indicates if the request was successfully processed

whatsapp_response_info

object

Details from the WhatsApp Business API about the message delivery

Show WhatsApp Response Fields

messaging_product

string

Always “whatsapp” for WhatsApp messages

contacts

array

Information about the message recipient

input

string

The phone number that was provided in the request

wa_id

string

WhatsApp’s unique identifier for the recipient

messages

array

Details about the sent message

string

Unique message identifier (wamid) for tracking status

message_status

string

Initial status of the message (typically “accepted”)

error

object

Present only when an error occurs

code

string

Error code identifier

message

string

Human-readable error description

Example Request

curl -X POST \
  https://api.insightssystem.com/api:hFrjh8a1/send_template_message \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "template_id": "6f6e4113-cc8a-4fbe-b98d-2c631d299c6b",
    "phone_number": "+123456789012",
    "variables": {
      "body1": "John Doe",
      "body2": "Premium Subscription",
      "body3": "$49.99",
      "media": "https://storage.googleapis.com/your-public-bucket/offer-image.jpg",
      "button1": "https://example.com/special-offer"
    },
    "language": "en"
  }'

Example Response

{
  "success": true,
  "whatsapp_response_info": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "+123456789012",
        "wa_id": "123456789012"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgLMTIzNDU2Nzg5MDEyFQIAERgSNUU2RjM4NzM1M0Q5OEIwQTQwAA==",
        "message_status": "accepted"
      }
    ]
  }
}

Response Codes

200: Success

400: Bad Request

401: Unauthorized

403: Forbidden

404: Not Found

The template specified doesn’t exist.

{
  "success": false,
  "error": {
    "code": "template_not_found",
    "message": "Template with ID '6f6e4113-cc8a-4fbe-b98d-2c631d299c6b' not found"
  }
}

422: Unprocessable Entity

429: Too Many Requests

500: Server Error

Something went wrong on our end. Please contact support if the issue persists.

{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "An internal server error occurred"
  }
}

Working with Template Variables

Templates contain placeholders that are replaced with dynamic content when sending messages. Understanding how to map your data to these variables is essential.

Variable Types

Text Variables

Body and header variables replace text placeholders in your template. They are named body1, body2, etc., or header1, header2, etc.

Media Variables

Media variables allow you to attach images, videos, or documents to your template. Provide a public URL in the media property.

Button Variables

Used for dynamic buttons in interactive templates. Can be URLs or text, depending on the button type.

Quick Reply Variables

For templates with quick reply buttons, provide the text to display on each button.

Variable Mapping

Identify template variables

Examine your template structure to identify which variables are required. You can find this information using the Get Templates API.

Prepare your data

Format your data to match the expected variable structure. Ensure values meet any length or format requirements.

Map data to variables

Create a variables object with keys matching your template’s variable names and values from your data.

Handle media properly

For media templates, ensure your media URL is publicly accessible and in a WhatsApp-supported format.

Media Guidelines

When including media in your templates, follow these guidelines for optimal delivery:

Images

Supported formats: JPG, JPEG, PNG
Max size: 5MB
Recommended aspect ratio: 1.91:1

Videos

Supported formats: MP4, 3GPP
Max size: 16MB
Max duration: 1 minute

Documents

Supported formats: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX
Max size: 100MB

URLs

Must be publicly accessible
Direct file links (no redirects)
HTTPS required

Media URLs must be publicly accessible without requiring authentication. For security, we recommend using signed URLs with limited-time access.

Best Practices

Error Handling

Implement comprehensive error handling to manage API failures gracefully. Always check the success field in responses and handle various error scenarios.

Message Tracking

Store the returned message_id values to track delivery status using the Message Status API.

Throttling

Implement request throttling when sending to multiple recipients to avoid hitting rate limits and ensure reliable delivery.

Template Testing

Test your templates with various inputs to ensure variables are correctly replaced and messages appear as expected.

FAQs

Why was my message not delivered?

Can I send to non-WhatsApp users?

How do I know if my message was delivered?

Can I edit a message after sending?

Need help?

Our support team is available 24/7 to assist with template issues, API integration, or any other questions.

On this page

Overview
Send Template Message
Endpoint
Authentication
Request Body
Response
Example Request
Example Response
Response Codes
Working with Template Variables
Variable Types
Variable Mapping
Media Guidelines
Best Practices
FAQs

​Overview

Try it in the API Reference

​Send Template Message

​Endpoint

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Response Codes

​Working with Template Variables

​Variable Types

Text Variables

Media Variables

Button Variables

Quick Reply Variables

​Variable Mapping

​Media Guidelines

Images

Videos

Documents

URLs

​Best Practices

Error Handling

Message Tracking

Throttling

Template Testing

​FAQs

Need help?

API Documentation

WhatsAble API

Notifier by WhatsAble

Notifier System

​Overview

Try it in the API Reference

​Send Template Message

​Endpoint

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Response Codes

​Working with Template Variables

​Variable Types

Text Variables

Media Variables

Button Variables

Quick Reply Variables

​Variable Mapping

​Media Guidelines

Images

Videos

Documents

URLs

​Best Practices

Error Handling

Message Tracking

Throttling

Template Testing

​FAQs

Need help?

Overview

Send Template Message

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Response Codes

Working with Template Variables

Variable Types

Variable Mapping

Media Guidelines

Best Practices

FAQs

Overview

Send Template Message

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Response Codes

Working with Template Variables

Variable Types

Variable Mapping

Media Guidelines

Best Practices

FAQs