🚧

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

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

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

Template Components

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

Component Types

Component Structure

Each component object contains:

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"
        }
    ]
}

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