Send Template Message

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 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

200: Success

400: Bad Request

401: Unauthorized

403: Forbidden

404: Not Found

422: Unprocessable Entity

429: Too Many Requests

500: Server Error

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.

Sending to Multiple Recipients

While this API is designed for sending to a single recipient, you can efficiently send to multiple recipients by implementing a batch process in your application:

async function sendToMultipleRecipients(templateId, recipients, baseVariables) {
  const results = [];
  
  for (const recipient of recipients) {
    // Customize variables for each recipient if needed
    const variables = {
      ...baseVariables,
      body1: recipient.name,
      // Other recipient-specific variables
    };
    
    try {
      const response = await sendTemplateMessage(templateId, recipient.phone, variables);
      results.push({ recipient: recipient.phone, success: true, response });
    } catch (error) {
      results.push({ recipient: recipient.phone, success: false, error });
    }
    
    // Add a small delay to avoid rate limiting
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return results;
}

Rate Limiting

This API endpoint is subject to the following rate limits:

Plan	Rate Limit
Free	50 messages per day
Pro	1,000 messages per day
Enterprise	Custom limits

If you exceed your rate limit, the API will return a 429 status code. Implement exponential backoff and retries in your code to handle rate limiting gracefully.

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.

2024-04-15

v2.1.0

Enhanced Template Messaging

Added support for rich text formatting in templates
Improved error reporting with more specific error codes
New language parameter for multi-language template support

2024-01-22

v2.0.0

Major API Upgrade

Simplified variable handling for easier integration
Added support for all interactive message components
Improved media handling with support for more file types
Enhanced security with better input validation

Get Started

WhatsAble

Notifier by WhatsAble

Notifyer System

Send Template Message

Overview

Try it in the API Reference