API Reference v1.0

Send Template Message

Send a pre-approved WhatsApp template message to any user, regardless of the 24-hour service window. Template messages are the primary way to initiate conversations with customers.

POST https://whatsbizapi.com/api/wpbox/sendtemplatemessage

Sends a pre-approved template message to a recipient. Templates can include dynamic variables in the header, body, and buttons. This is the only message type that can be sent outside the 24-hour customer service window.

✓

No 24-Hour Restriction: Template messages are the only message type that can be sent outside the 24-hour customer service window. Templates must be pre-approved by Meta before use. You can manage templates from your dashboard or via the Templates API.

Parameters

Parameter	Type	Description
token required	string	Your API authentication token.
phone required	string	Recipient phone number with country code. E.g., `+919876543210`.
template_name required	string	The exact name of the approved template as registered with Meta. Case-sensitive.
template_language required	string	Language code of the template. Common values: `en`, `en_US`, `hi`, `es`, `pt_BR`.
components optional	array	Array of component objects to fill template variables. Required if your template contains dynamic placeholders (`1`, `2`, etc.).
carousel optional	object	Only for carousel templates. `{"cards": [...]}` — one entry per card, in card order. Each card accepts `header_url` (public image/video URL), `body_params` (values for the card's own variables) and `buttons` (`{"index": 0, "payload": "..."}` for a quick reply, `{"index": 1, "text": "..."}` for a URL button with a variable). Every field is optional: card media falls back to the media the template was created with, and a quick reply payload falls back to the button label.

Component Format

The components array allows you to pass dynamic values into your template's header, body, and button placeholders. Each component targets a specific section of the template.

Body Variables

Replace 1, 2, etc. in the template body with dynamic text values.

Body Component Structure

{
  "type": "body",
  "parameters": [
    {
      "type": "text",
      "text": "John"
    },
    {
      "type": "text",
      "text": "Order #12345"
    }
  ]
}

Header Image

Provide a dynamic image for templates with an image header.

Header Image Component

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

Button Variables

Provide dynamic values for URL buttons that contain a variable suffix (e.g., a tracking URL).

Button Component Structure

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

Examples

1. Simple Template (No Variables)

Send a template that has no dynamic placeholders, such as a static greeting or opt-in confirmation.

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendtemplatemessage \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "template_name": "hello_world",
    "template_language": "en_US"
  }'

Request Body

{
  "token": "YOUR_API_TOKEN",
  "phone": "+919876543210",
  "template_name": "hello_world",
  "template_language": "en_US"
}

Response 200

{
  "status": "success",
  "message_id": 456,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSQUI3..."
}

2. Template with Body Variables

Send a template that contains dynamic placeholders in the body, such as a customer name and order number.

Example template body: Hi 1, your 2 has been shipped and will arrive by 3.

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendtemplatemessage \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "template_name": "order_shipped",
    "template_language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "text": "John"},
          {"type": "text", "text": "Order #12345"},
          {"type": "text", "text": "March 15, 2025"}
        ]
      }
    ]
  }'

Request Body

{
  "token": "YOUR_API_TOKEN",
  "phone": "+919876543210",
  "template_name": "order_shipped",
  "template_language": "en",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        },
        {
          "type": "text",
          "text": "Order #12345"
        },
        {
          "type": "text",
          "text": "March 15, 2025"
        }
      ]
    }
  ]
}

Response 200

{
  "status": "success",
  "message_id": 457,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSRDc5..."
}

3. Template with Header Image + Body Variables + Button

Send a rich template that includes a dynamic header image, body variables, and a URL button with a variable suffix.

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendtemplatemessage \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "template_name": "order_confirmation",
    "template_language": "en",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/products/shoe-banner.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {"type": "text", "text": "John"},
          {"type": "text", "text": "Order #12345"},
          {"type": "text", "text": "$129.99"}
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {"type": "text", "text": "order-12345"}
        ]
      }
    ]
  }'

Request Body

{
  "token": "YOUR_API_TOKEN",
  "phone": "+919876543210",
  "template_name": "order_confirmation",
  "template_language": "en",
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "image",
          "image": {
            "link": "https://example.com/products/shoe-banner.jpg"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        },
        {
          "type": "text",
          "text": "Order #12345"
        },
        {
          "type": "text",
          "text": "$129.99"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [
        {
          "type": "text",
          "text": "order-12345"
        }
      ]
    }
  ]
}

Response 200

{
  "status": "success",
  "message_id": 458,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSRjk2..."
}

4. Carousel Template

A carousel template sends one message bubble followed by 2–10 swipeable cards. Pass a carousel object instead of building the nested carousel component by hand — the card media, quick reply payloads and URL button values are filled in for you.

ℹ

Send "carousel": {} (or omit it entirely) to reuse the card media the template was created with. Templates imported from Meta have no stored media, so those need an explicit header_url per card.

Request

curl -X POST https://whatsbizapi.com/api/wpbox/sendtemplatemessage \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "+919876543210",
    "template_name": "summer_collection_carousel",
    "template_language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Priya" }
        ]
      }
    ],
    "carousel": {
      "cards": [
        {
          "header_url": "https://example.com/media/card-1.jpg",
          "body_params": ["999"],
          "buttons": [
            { "index": 0, "payload": "BUY_CARD_1" },
            { "index": 1, "text": "card-1" }
          ]
        },
        {
          "header_url": "https://example.com/media/card-2.jpg",
          "body_params": ["1299"],
          "buttons": [
            { "index": 0, "payload": "BUY_CARD_2" },
            { "index": 1, "text": "card-2" }
          ]
        }
      ]
    }
  }'

Response 200

{
  "status": "success",
  "message_id": 612,
  "message_wamid": "wamid.HBgNOTE5ODc2NTQzMjEwFQIAERgSRjk2..."
}

Rules Meta enforces on carousel templates: 2–10 cards, every card using the same media type (image or video), the same number and order of buttons on every card (1 or 2), a card body of at most 160 characters, and the MARKETING category.

Error Responses

Error - Invalid Template 400

{
  "status": "error",
  "message": "Template 'my_template' not found or not approved."
}

Error - Missing Variables 400

{
  "status": "error",
  "message": "Template requires 3 body parameters but 1 was provided."
}

Error - Authentication 401

{
  "status": "error",
  "message": "Invalid API token."
}

Notes

⚠

Template Approval Required: All templates must be submitted to and approved by Meta before they can be used. Approval typically takes a few minutes to 24 hours. You can check template status in your dashboard or via the Templates API.

ℹ

Variable Order Matters: The parameters in the components array are positional. The first parameter replaces 1, the second replaces 2, and so on. Ensure parameters are passed in the correct order.

ℹ

Header Media: For templates with media headers, the image URL must be publicly accessible. Supported formats: JPEG and PNG. Maximum file size: 5 MB. The URL must use HTTPS.

✗

Rate Limiting: WhatsApp applies per-template rate limits. If a template is flagged for low quality or high block rates, Meta may pause or disable it. Monitor template quality ratings in your dashboard.