🚧
API token & Name space
Please refer to this page to fine the API Token and the name space: https://developer.cequens.com/reference/whatsapp-business-ver2

💡
Tip: Looking for example requests? Click the dropdown in the top-right corner of the "Request body" section to see pre-built examples you can use.

Overview

WhatsApp message templates are pre-formatted messages that require approval from Meta before they can be used. Unlike regular messages, templates can be sent at any time, making them essential for:

Marketing: Promotional offers, product updates, event invitations
Utility: Order confirmations, appointment reminders, shipping updates, account notifications
Authentication: One-time passwords (OTP), verification codes, two-factor authentication

👍
✅ No 24-Hour Window Restriction
Template messages can be sent at any time, even if the customer hasn't messaged you recently.

Before You Start

Create and Register Templates: All templates must be created and approved in your WhatsApp Business Manager before use
Template Name Must Match: The template name in your API request must exactly match the approved template name
Understand Template Structure: Templates consist of an optional header, required body, optional footer, and optional buttons

❗️

Placeholder fields require mandatory input values.


   {
       "to": "123456798", //receipent phone number
       "type": "template",
       "template": {
           "language": {
               "policy": "deterministic",
               "code": "ar"
           },
           "name": "template_name",
           "components": [] //Ensure what parmaters need to be filled as per the sent template
       }
  }

📘
Looking for Carousel Templates?
For multi-card carousel templates that let you showcase multiple products or options, see the Carousel Template Messages API page.

🚧
Common Language Codes:

English (US): en_US

English (UK): en_GB

Arabic: ar

Spanish: es

French: fr

German: de

Template Components

Components allow you to populate dynamic content in your templates. Each component corresponds to a section of your template.

Component Types

Component Type	Description	Supports Variables
header	Top section - can contain text, media, or location	Yes
body	Main message content	Yes
footer	Bottom text (static only)	No
button	Interactive buttons	Yes (for URL buttons)

Component Structure

Each component object contains:

Parameter	Type	Description	Required
type	string	Component type: "header", "body", or "button"	Yes
parameters	array	Array of parameter objects with dynamic values	Yes
sub_type	string	For buttons: "url" or "quick_reply"	Required for buttons
index	string	For buttons: button index starting from "0"	Required for buttons

Header Components

Headers can contain text, images, videos, documents, or locations.

Text Header

{
    "type": "header",
    "parameters": [
        {
            "type": "text",
            "text": "Your Order #12345"
        }
    ]
}

Image Header

{
    "type": "header",
    "parameters": [
        {
            "type": "image",
            "image": {
                "link": "https://example.com/product-image.jpg"
            }
        }
    ]
}

Video Header

{
    "type": "header",
    "parameters": [
        {
            "type": "video",
            "video": {
                "link": "https://example.com/product-demo.mp4"
            }
        }
    ]
}

Document Header

{
    "type": "header",
    "parameters": [
        {
            "type": "document",
            "document": {
                "link": "https://example.com/invoice.pdf",
                "filename": "invoice.pdf"
            }
        }
    ]
}

Location Header

{
    "type": "header",
    "parameters": [
        {
            "type": "location",
            "location": {
                "latitude": 40.7589,
                "longitude": -73.9851,
                "name": "CEQUENS NYC Office",
                "address": "New York, NY"
            }
        }
    ]
}

Body Components

Body components contain text variables that replace placeholders in your template, numbered sequentially starting from 1.

Important: Parameters must be provided in the exact order as variables appear in your template.

{
    "type": "body",
    "parameters": [
        {
            "type": "text",
            "text": "John Doe"
        },
        {
            "type": "text",
            "text": "December 25, 2024"
        },
        {
            "type": "text",
            "text": "$150.00"
        }
    ]
}

👍
Example
If your template body contains three variables ({{1}}, {{2}}, and {{3}}), and you provide the parameters above, it will render with those values substituted in order.

Button Components

URL Buttons (Dynamic)

URL buttons with dynamic content require parameters. The template must define the static base URL, and you provide the dynamic suffix.

Template URL: https://example.com/order/ followed by a variable

Request:

{
    "type": "button",
    "sub_type": "url",
    "index": "0",
    "parameters": [
        {
            "type": "text",
            "text": "12345"
        }
    ]
}

Result: User sees button linking to https://example.com/order/12345

URL Buttons (Static)

Static URL buttons don't require parameters - they're defined entirely in the template.

Quick Reply Buttons

Quick reply buttons don't require parameters as they use static text defined in the template.

Note: When templates have multiple buttons, use the index field to specify which button you're providing parameters for (starting from "0").

Parameter Types Reference

Text Parameter

{
    "type": "text",
    "text": "Your text value here"
}

Currency Parameter

{
    "type": "currency",
    "currency": {
        "fallback_value": "$100.00",
        "code": "USD",
        "amount_1000": 100000
    }
}

Date/Time Parameter

{
    "type": "date_time",
    "date_time": {
        "fallback_value": "December 25, 2024"
    }
}

Image Parameter

{
    "type": "image",
    "image": {
        "link": "https://example.com/image.jpg"
    }
}

Video Parameter

{
    "type": "video",
    "video": {
        "link": "https://example.com/video.mp4"
    }
}

Document Parameter

{
    "type": "document",
    "document": {
        "link": "https://example.com/document.pdf",
        "filename": "document.pdf"
    }
}

Location Parameter

{
    "type": "location",
    "location": {
        "latitude": 40.7589,
        "longitude": -73.9851,
        "name": "Business Name",
        "address": "Full Address"
    }
}

Template Categories

Marketing Templates

Used for promotional content, special offers, product updates, and event invitations. Subject to more stringent approval guidelines.

Utility Templates

Used for transactional messages like order confirmations, appointment reminders, account updates, and shipping notifications.

Authentication Templates

Used specifically for one-time passwords (OTP) and verification codes. Support special copy code and autofill buttons.

Best Practices

Template Creation

Follow Meta's template guidelines to ensure approval
Use clear, concise language
Include all necessary information in the template body
Test templates thoroughly before production use

Variable Usage

Provide parameters in the exact order they appear in the template
Keep variable content concise and relevant
Avoid including sensitive information in templates
Use meaningful variable names when creating templates

Media Guidelines

Ensure all media URLs are publicly accessible via HTTPS
Optimize images and videos for mobile viewing
Keep file sizes within WhatsApp limits
Test media loads before sending to customers

Tracking and Monitoring

Use meaningful clientReferenceID values for better tracking
Monitor template performance and delivery rates
Set up webhooks to receive delivery notifications
Track button click-through rates for optimization

Performance Optimization

Cache approved template names in your application
Validate template parameters before sending
Handle template rejection errors gracefully
Monitor template quality ratings in WhatsApp Business Manager

Common Errors and Troubleshooting

Error	Cause	Solution
Template not found	Template name doesn't match the approved template	Verify the exact template name in WhatsApp Business Manager
Parameter mismatch	Wrong number or order of parameters	Check template structure and provide parameters in the correct order
Media download failed	Media URL not accessible	Ensure URL is publicly accessible via HTTPS
Language not supported	Template not approved for the specified language	Check approved languages for your template
Invalid namespace	Namespace doesn't match your WABA	Use the correct namespace from your WhatsApp Business Account