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.

​
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

​
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

​
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

1

Identify template variables

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

2

Prepare your data

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

3

Map data to variables

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

4

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

Need help?

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