WhatsApp Template API Guide

Get Template Payload Info

Endpoint

GET /whatsapp/template/payload-info

Description

Returns the expected payload structure for WhatsApp templates based on template type (marketing, utility, authentication). This endpoint helps frontend developers understand what data structure is required when sending template messages.

Query Parameters

Parameter	Type	Required	Description
`template_name`	string	Yes	The slug/name of the template
`template_language`	string	Yes	Language code (e.g., `en`, `es`, `fr`)

Example Request

HTTP

GET /whatsapp/template/payload-info?template_name=welcome_message&template_language=en
Authorization: Bearer <ACCESS_TOKEN>

Success Responses

Marketing Template

Status Code: 200 OK

JSON

{
  "success": true,
  "data": {
    "template": {
      "name": "spring festival sale",
      "slug": "spring_festival_sale",
      "language_code": "en",
      "category_name": "marketing",
      "is_carousel": false
    },
    "broadcast_title": {
      "type": "text",
      "value_required": false,
      "valid_extensions": []
    },
    "main_body_variables": [
      {
        "variable": "{{1}}",
        "type": "text",
        "example_value": "Italy"
      },
      {
        "variable": "{{2}}",
        "type": "currency",
        "example_value": "5",
        "currency_code": "KWD"
      },
      {
        "variable": "{{3}}",
        "type": "text",
        "example_value": "SPRING35"
      },
      {
        "variable": "{{4}}",
        "type": "date_time",
        "example_value": "2026-02-28 12:15:00"
      }
    ],
    "button_variables": [
      {
        "button_index": 0,
        "button_type": "url",
        "variables": [
          {
            "variable": "{{1}}",
            "type": "text",
            "example_value": "italy"
          }
        ]
      },
      {
        "button_index": 1,
        "button_type": "url",
        "variables": [
          {
            "variable": "{{1}}",
            "type": "text",
            "example_value": "italy"
          }
        ]
      },
      {
        "button_index": 2,
        "button_type": "copy_code",
        "example": "SPRING35",
        "variables": []
      },
      {
        "button_index": 3,
        "button_type": "phone_number",
        "variables": []
      },
      {
        "button_index": 4,
        "button_type": "quick_reply",
        "variables": []
      },
      {
        "button_index": 5,
        "button_type": "quick_reply",
        "variables": []
      },
      {
        "button_index": 6,
        "button_type": "quick_reply",
        "variables": []
      },
      {
        "button_index": 7,
        "button_type": "quick_reply",
        "variables": []
      },
      {
        "button_index": 8,
        "button_type": "quick_reply",
        "variables": []
      },
      {
        "button_index": 9,
        "button_type": "quick_reply",
        "variables": []
      }
    ],
    "header_components": [
      {
        "variable": "{{1}}",
        "type": "text",
        "example_value": "Mega"
      }
    ],
    "carousel_info": null,
    "example_payload": {
      "template_name": "spring_festival_sale",
      "template_language": "en",
      "contacts": [
        "+15550185"
      ],
      "components": {
        "broadcast_title_type": "text",
        "broadcast_title_value": "",
        "variables": [
          {
            "variable": "{{1}}",
            "type": "text",
            "value": "Italy",
            "is_user": false
          },
          {
            "variable": "{{2}}",
            "type": "currency",
            "value": "5",
            "currency_code": "KWD"
          },
          {
            "variable": "{{3}}",
            "type": "text",
            "value": "SPRING35",
            "is_user": false
          },
          {
            "variable": "{{4}}",
            "type": "date_time",
            "value": "2026-02-28 12:15:00"
          }
        ],
        "button_variables": [
          {
            "type": "url",
            "variables": [
              {
                "variable": "{{1}}",
                "type": "text",
                "value": "italy"
              }
            ]
          },
          {
            "type": "url",
            "variables": [
              {
                "variable": "{{1}}",
                "type": "text",
                "value": "italy"
              }
            ]
          },
          {
            "type": "copy_code",
            "example": "SPRING35"
          },
          {
            "type": "phone_number",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          }
        ],
        "header_components": [
          {
            "variable": "{{1}}",
            "type": "text",
            "value": "Mega"
          }
        ]
      }
    }
  }
}

Utility Template

Status Code: 200 OK

JSON

{
  "success": true,
  "data": {
    "template": {
      "name": "Booking Confirmation",
      "slug": "booking_confirmation",
      "language_code": "en",
      "category_name": "utility",
      "is_carousel": false
    },
    "broadcast_title": {
      "type": "document",
      "value_required": true,
      "valid_extensions": [
        "txt",
        "pdf",
        "doc",
        "docx",
        "xls",
        "xlsx",
        "ppt",
        "pptx",
        "zip"
      ],
      "max_size_mb": 100
    },
    "main_body_variables": [
      {
        "variable": "{{1}}",
        "type": "text",
        "example_value": "Alex"
      },
      {
        "variable": "{{2}}",
        "type": "currency",
        "example_value": "1",
        "currency_code": "USD"
      },
      {
        "variable": "{{3}}",
        "type": "date_time",
        "example_value": "2025-11-20 10:30:00"
      }
    ],
    "button_variables": [
      {
        "button_index": 0,
        "button_type": "url",
        "variables": [
          {
            "variable": "{{1}}",
            "type": "text",
            "example_value": "12345"
          }
        ]
      },
      {
        "button_index": 1,
        "button_type": "phone_number",
        "variables": []
      },
      {
        "button_index": 2,
        "button_type": "quick_reply",
        "variables": []
      }
    ],
    "header_components": null,
    "carousel_info": null,
    "example_payload": {
      "template_name": "booking_confirmation",
      "template_language": "en",
      "contacts": [
        "+15550185"
      ],
      "components": {
        "broadcast_title_type": "document",
        "broadcast_title_value": "https://example.com/document.pdf",
        "variables": [
          {
            "variable": "{{1}}",
            "type": "text",
            "value": "Alex",
            "is_user": false
          },
          {
            "variable": "{{2}}",
            "type": "currency",
            "value": "1",
            "currency_code": "USD"
          },
          {
            "variable": "{{3}}",
            "type": "date_time",
            "value": "2025-11-20 10:30:00"
          }
        ],
        "button_variables": [
          {
            "type": "url",
            "variables": [
              {
                "variable": "{{1}}",
                "type": "text",
                "value": "12345"
              }
            ]
          },
          {
            "type": "phone_number",
            "variables": []
          },
          {
            "type": "quick_reply",
            "variables": []
          }
        ]
      }
    }
  }
}

Authentication Template

Status Code: 200 OK

JSON

{
  "success": true,
  "data": {
    "template": {
      "id": null,
      "name": "OTP Verification",
      "slug": "otp_verification",
      "language_code": "en",
      "language_name": null,
      "category_name": "authentication",
      "status": "approved",
      "is_carousel": false,
      "whatsapp_template_id": null,
      "created_at": null
    },
    "broadcast_title": {
      "type": "none",
      "value_required": false,
      "valid_extensions": [],
      "max_size": null,
      "max_size_mb": null
    },
    "main_body_variables": [
      {
        "variable": "{{1}}",
        "type": "text",
        "example_value": "0914"
      }
    ],
    "button_variables": [],
    "header_components": null,
    "carousel_info": null,
    "example_payload": {
      "template_name": "otp_verification",
      "template_language": "en",
      "contacts": [
        "+15550185"
      ],
      "components": {
        "broadcast_title_type": "none",
        "broadcast_title_value": "",
        "variables": [
          {
            "variable": "{{1}}",
            "type": "text",
            "value": "0914",
            "is_user": false
          }
        ]
      }
    }
  }
}

Error Responses

Template Not Found

Status Code: 422 Unprocessable Entity

JSON

{
  "success": false,
  "message": "Template not found"
}

Missing Required Parameters

Status Code: 422 Unprocessable Entity

JSON

{
  "success": false,
  "message": "The template name field is required.",
  "errors": {
    "template_name": [
      "The template name field is required."
    ]
  }
}

Authentication Error

Status Code: 401 Unauthorized

JSON

{
  "success": false,
  "message": "Unauthenticated"
}

Server Error

Status Code: 500 Internal Server Error

JSON

{
  "success": false,
  "message": "Failed to get template payload info",
  "error": "Internal server error details"
}

Get Logs by Request ID

Endpoint

GET /api/whatsapp/logs/request-id

Description

Returns WhatsApp API request/response logs using a request ID. This endpoint provides comprehensive information about a batch message request, including statistics, contact statuses, and error logs for failed messages.

Query Parameters

Parameter	Type	Required	Description
`request_id`	string	Yes	Unique identifier for the API request

Example Request

HTTP

GET /api/whatsapp/logs/request-id?request_id=req_abc123xyz789
Authorization: Bearer <ACCESS_TOKEN>

Success Response

Standard Response

Status Code: 200 OK

JSON

{
  "success": true,
  "data": {
    "request_id": "req_abc123xyz789",
    "statistics": {
      "request_id": "req_abc123xyz789",
      "total_contacts": 100,
      "sent_count": 85,
      "failed_count": 10,
      "pending_count": 5,
      "status": "completed",
      "success_rate": 85,
      "template_id": "TEMPLATE_ID",
      "template_name": "TEMPLATE_NAME",
      "metadata": {
        "<any_key>": "<any_value>"
      },
      "completed_at": "2025-02-05 15:30:00",
      "created_at": "2025-02-05 15:25:00"
    },
    "template": {
      "id": "TEMPLATE_ID",
      "name": "NAME",
      "slug": "TEMPLATE_NAME",
      "category_name": "CATEGORY",
      "language_name": "LANGUAGE_NAME",
      "language_code": "LANGUAGE_CODE",
      "category_type": "CATEGORY_TYPE",
      "status": "approved",
      "option": null,
      "whatsapp_template_id": "WHATSAPP_TEMPLATE_ID",
      "metas": [],
      "template_components": [],
      "created_at": "2025-11-07 10:04:55"
    },
    "contacts": [
      {
        "id": 1,
        "request_id": "req_abc123xyz789",
        "contact_id": 101,
        "contact": {
          "id": 101,
          "name": "John Doe",
          "phone_number": "+15550185",
          "email": "[email protected]",
          "country_code": "+1"
        },
        "phone_number": "+15550185",
        "contact_index": 0,
        "status": "sent",
        "message_type": "template",
        "message_id": "wamid.abc123",
        "is_delivered": true,
        "processed_at": "2025-02-05 15:26:00",
        "created_at": "2025-02-05 15:25:00"
      }
    ],
    "total_contacts": 100,
    "failed_logs": {
      "total": 10,
      "logs": []
    }
  }
}

Error Responses

Missing Request ID Parameter

Status Code: 422 Unprocessable Entity

JSON

{
  "success": false,
  "message": "request_id parameter is required"
}

Authentication Error

Status Code: 401 Unauthorized

JSON

{
  "success": false,
  "message": "Unauthenticated"
}

Server Error

Status Code: 500 Internal Server Error

JSON

{
  "success": false,
  "message": "Internal server error message"
}

Common Response Payload

This is the standard async response structure for all WhatsApp message send APIs. All send APIs will return this consistent response format upon successful submission of the request.

JSON

{
  "success": true,
  "message": "SUCCESS_MESSAGE",
  "data": {
    "request_id": "req_abc123xyz789",
    "total_contacts": "TOTAL_CONTACTS",
    "message_type": "MESSAGE_TYPE"
  }
}

Notes

Authentication

All endpoints require authentication via Bearer token in the Authorization header.

Template Types

Supported template categories are:

MARKETING - Marketing messages
UTILITY - Utility messages (order updates, notifications)
AUTHENTICATION - OTP and verification messages

Variable Types

Template variables can be of type:

text - Plain text
currency - Currency with code (e.g., USD, EUR)
date_time - Date and time values
is_user - Boolean field for text variables - indicates the variable will be automatically populated with the contact name from our system

Date/Time Variables

For date_time type variables, always pass dates in UTC format.

UTC Format

All date and time values should be provided in UTC (Coordinated Universal Time) format.

Auto Conversion

The system will automatically convert UTC dates to the recipient's local timezone based on their country.

Currency Variables

For currency type variables, always pass valid currency codes.

Currency Code

Provide valid ISO currency codes (e.g., USD, EUR, GBP, INR, KWD) along with the numeric value.

Auto Symbol Conversion

WhatsApp will automatically convert the currency code to the proper currency symbol when displaying the message to the recipient.

is_user Field

The `is_user` field is a boolean property for text variables that indicates the variable will be automatically populated with the contact name from our system.

Auto-filled

When set to `true`, the variable will be automatically populated with the contact name that is registered in our system.

Important

If you're expecting to capture the contact's name using this field, keep in mind that the name will only be saved after the user sends their first reply to your message. Until then, the name from their profile will not be available.

Carousel Templates

Templates with `is_carousel: true` contain multiple cards, each with its own header, body variables, and button variables.

Request Status

Request statuses can be:

processing - Request is being processed
completed - All messages processed (may have some failures)
failed - All messages failed
unknown - Status cannot be determined

Contact Status

Individual contact statuses can be:

sent - Message successfully sent
failed - Message failed to send
pending - Message not yet processed

Media Types

Broadcast title and carousel headers support:

image - JPG, JPEG, PNG, WEBP
video - MP4, 3GP
document - PDF, DOC, DOCX, etc.

Phone Number Format

WHATSAPP_USER_PHONE_NUMBER should be provided in international format starting with '+'. If '+' or country code is not provided, the number will be considered as a default US number.

+15550185 - Recommended format: + followed by country code and number