Create WhatsApp Template

Create WhatsApp message templates on the OneXtel platform — Authentication, Utility, Marketing, Limited Time Offer, Carousel, Product Message, Flows, and Order templates.

Use this endpoint to submit a new WhatsApp message template for Meta approval. Templates are reusable message layouts (body, header, footer, buttons) that must be approved before they can be sent to recipients via the Send Template Message API.

Endpoint

POST /wa/templates

Send this request as multipart/form-data. Pass the template JSON in a data form field and the WhatsApp Business Account ID in a waba_id form field.

Headers

apikey · string · required

API key generated for the TUC (telecom user connection) associated with the sending WhatsApp phone number. Example: 7pvxoA4c.

accept · string

application/json

Request body (multipart/form-data)

data · string · required

JSON-encoded string containing the template payload (name, category, language, components, etc. — see below). Sent as a form field, not raw JSON.

waba_id · string · required

WhatsApp Business Account ID the template is created under.

update_by · string

Free-text string.

Common fields inside data

Every template category shares this envelope:

name · string · required

Unique template name in the Meta Cloud API. Should be descriptive of the template’s purpose (e.g. zero_tap_authentication_temp_3).

category · string · required

Template category: AUTHENTICATION, UTILITY, or MARKETING.

language · string · required

Template language code per ISO (e.g. en_US).

components · array · required

Array of component objects — combinations of HEADER, BODY, FOOTER, BUTTONS, LIMITED_TIME_OFFER, and CAROUSEL, depending on template type. See the tabs below.

parameter_format · string

Determines how body/header variables are referenced. POSITIONAL (default, e.g. {{1}}) or NAMED (e.g. {{customer_name}}).

message_send_ttl_seconds · integer

Time-to-live for the message in seconds. Range varies by category: Authentication 30 seconds–15 minutes; Utility 30 seconds–12 hours; Marketing/LTO/Carousel 12 hours–30 days (30-day maximum applies only for MM Lite).

sub_category · string

Only used for ORDER_STATUS and ORDER_DETAILS utility templates — see those tabs.

cURL

curl --location 'https://api.onexaura.com/wa/templates' \
--header 'accept: application/json' \
--header 'apiKey: YOUR_API_KEY' \
--form 'data="{
  \"name\": \"utility_image_2\",
  \"category\": \"UTILITY\",
  \"language\": \"en_US\",
  \"components\": [
    {
      \"type\": \"HEADER\",
      \"format\": \"IMAGE\",
      \"example\": { \"media_id\": \"(Media_ID)\" }
    },
    {
      \"text\": \"Hello {{1}}, your account balance is {{2}} as of now Please check your latest statement.\",
      \"type\": \"BODY\",
      \"example\": { \"body_text\": [[\"customer_name\", \"amount\"]] }
    },
    {
      \"text\": \"Welcome To OneXtel LTD\",
      \"type\": \"FOOTER\"
    }
  ],
  \"parameter_format\": \"POSITIONAL\"
}"' \
--form 'waba_id="YOUR_WABA_ID"' \
--form 'update_by="string"'

Media headers accept either "example": {"media_id": "..."} (generated via the Media Upload API) or "example": {"url": "..."} for a remote file.

Response

{
  "status": 200,
  "description": {
    "message": "success"
  }
}

status · integer

HTTP-style status code. 200 on success.

description · object

Wrapper object for the result message.

Show description

description.message · string

"success" on success, or an error description on failure, such as "Required fields are missing, or the template does not exist." on a 400 response.

Template types

Authentication

Used for OTP delivery. Reference: Meta authentication templates.

Components: BODY (optional, add_security_recommendation), FOOTER (optional, code_expiration_minutes), BUTTONS (required — one OTP button).

components[].add_security_recommendation · boolean

Adds a security note below the OTP message (recommended). Set on the BODY component.

components[].code_expiration_minutes · integer

OTP code validity in minutes. Set on the FOOTER component; required only if the OTP has an expiry.

buttons[].otp_type · string · required

ZERO_TAP, ONE_TAP, or COPY_CODE.

buttons[].text · string · required

Button label, e.g. "Copy Code".

buttons[].autofill_text · string

Autofill button label. Used with ONE_TAP / ZERO_TAP.

buttons[].package_name · string

Android app package identifier the OTP is generated for. Required for ONE_TAP / ZERO_TAP (recommended).

buttons[].signature_hash · string

Base64 or URL-encoded app signature hash used to verify app integrity. Required for ONE_TAP / ZERO_TAP (recommended).

buttons[].zero_tap_terms_accepted · boolean

Only for ZERO_TAP.

Template type	otp_type	Extra params	Expiry	Description
Zero Tap AutoFill	ZERO_TAP	package_name, signature_hash, cta_display_name	Recommended	Automatically fills OTP when device matches app signature.
One Tap AutoFill	ONE_TAP	package_name, signature_hash, cta_display_name	Recommended	Autofill available after user taps once in the UI.
Copy Code	COPY_CODE	None	Recommended	User copies OTP manually to enter in the app.

Example — Zero Tap AutoFill (with expiry)

{
  "name": "zero_tap_authentication_temp_3",
  "category": "AUTHENTICATION",
  "language": "en_US",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "url": "https://www.whatsapp.com/otp/code/?otp_type=ZERO_TAP&cta_display_name=Autofill&package_name=com.example.authentication&signature_hash=123456789qw&code_expiration_minutes=10&code=otp{{1}}",
          "text": "Copy Code",
          "type": "URL",
          "example": [
            "https://www.whatsapp.com/otp/code/?otp_type=ZERO_TAP&cta_display_name=Autofill&package_name=com.example.authentication&signature_hash=123456789qw&code_expiration_minutes=10&code=otp123456"
          ]
        }
      ]
    }
  ],
  "parameter_format": "POSITIONAL",
  "message_send_ttl_seconds": 600
}

An Authentication payload can also use a shorter OTP button shape:

{
  "name": "xx",
  "language": "en_US",
  "category": "authentication",
  "components": [
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "otp",
          "otp_type": "copy_code",
          "text": "xx"
        }
      ]
    }
  ]
}

Utility

Reference: Meta utility templates.

Components: HEADER (optional — text, location, or media), BODY (required), FOOTER (optional), BUTTONS (optional, max 10; quick-reply and non-quick-reply buttons must be grouped separately or the API returns an invalid-combination error).

Supported button types: URL (requires url, text), PHONE_NUMBER (requires phone_number, text), QUICK_REPLY (requires text), FLOW (requires flow_id, flow_action, navigate_screen), ORDER_STATUS (requires text), ORDER_DETAILS (requires text).

Header variants

// Text header
{ "type": "header", "format": "text", "text": "xx", "example": { "header_text": ["xx"] } }

// Location header (no example needed)
{ "type": "header", "format": "location" }

// Media header (image, video, or document — media_id or url)
{ "type": "header", "format": "image", "example": { "url": "xx" } }

Body with header image and buttons — full example

{
  "name": "image_utility_with_params",
  "category": "UTILITY",
  "language": "en",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": { "media_id": "<Media_ID>" }
    },
    {
      "text": "Hello {{1}}, your order #{{2}} has been placed successfully. It will be delivered by {{3}}. Track your order anytime from our app or website.",
      "type": "BODY",
      "example": {
        "body_text": [["Customer_name", "order_id", "date"]]
      }
    },
    {
      "text": "Welcome To OneXtel LTD",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "url": "https://fdqn/<URL>", "text": "Visit website", "type": "URL" },
        { "text": "Quick Reply", "type": "QUICK_REPLY" }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

Parameter format examples

// Positional – Header
"example": { "header_text": ["xx"] }

// Named – Header
"example": { "header_text_named_params": [{ "param_name": "xx", "example": "xx" }] }

// Positional – Body
"example": { "body_text": ["xx"] }

// Named – Body
"example": { "body_text_named_params": [{ "param_name": "xx", "example": "xx" }] }

// Positional – URL Button
"example": ["xx"]

// Named – URL Button
"example": [{ "param_name": "xx", "example": "xx" }]

Marketing

Reference: Meta custom marketing templates.

Components: header (optional — text, location, or media), body (required), footer (optional), buttons (optional, max 10, same quick-reply grouping rule as Utility).

Button types include PHONE_NUMBER, URL, QUICK_REPLY, and COPY_CODE.

{
  "name": "image_marketing",
  "category": "MARKETING",
  "language": "en_US",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": { "media_id": "<Media_ID>" }
    },
    {
      "text": "Hi {{1}}, exciting news! Your Fresh Basket shopping unlocks a special treat. Enjoy {{2}} exclusive discount on your next order and keep the savings rolling.",
      "type": "BODY",
      "example": { "body_text": [["name", "offer"]] }
    },
    {
      "text": "Fresh Basket - Freshness with Rewards",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "text": "Call phone number", "type": "PHONE_NUMBER", "phone_number": "+91**********" }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

message_send_ttl_seconds for Marketing ranges 12 hours to 30 days (30-day maximum applies only for MM Lite).

Limited Time Offer

Reference: Meta limited-time offer templates.

Components: header (optional — image or video only), limited_time_offer (mandatory), buttons (fixed shape — one copy_code and one url button). Do not include a footer component for LTO templates.

components[].limited_time_offer.text · string · required

Display text for the offer banner.

components[].limited_time_offer.has_expiration · boolean

Whether the offer expires. Defaults to false.

{
  "name": "lto_template_1",
  "language": "en_US",
  "category": "LTO",
  "parameter_format": "POSITIONAL",
  "message_send_ttl_seconds": 600,
  "components": [
    {
      "type": "header",
      "format": "image",
      "example": { "url": "https://example.com/offer-image.jpg" }
    },
    {
      "type": "limited_time_offer",
      "limited_time_offer": {
        "text": "Get 20% off on all products until midnight!",
        "has_expiration": true
      }
    },
    {
      "type": "buttons",
      "buttons": [
        { "type": "copy_code", "example": "OFFER20" },
        {
          "type": "url",
          "text": "Shop Now",
          "url": "https://example.com/shop",
          "example": ["https://example.com/shop?offer=OFFER20"]
        }
      ]
    }
  ]
}

LTO templates take either "category": "LTO" or "category": "marketing". Confirm which value your WABA setup accepts before you submit.

Media Card Carousel

Reference: Meta media card carousel templates.

Components: body (required), carousel (required — at least 2 cards). Each card must have the same button type across all cards (Quick Reply, URL, or Phone Number), 1–2 buttons per card, and an Image or Video header per card.

cards · array · required

Array of card objects, each with its own components (header + buttons).

cards[].components[].format · string · required

image or video for the card header.

{
  "name": "template_name",
  "language": "en_US",
  "category": "MARKETING",
  "parameter_format": "POSITIONAL",
  "message_send_ttl_seconds": 43200,
  "components": [
    {
      "type": "body",
      "text": "xx",
      "example": { "body_text": ["xx"] }
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": { "url": "xx" }
            },
            {
              "type": "buttons",
              "buttons": [
                { "type": "quick_reply", "text": "xx" },
                { "type": "url", "text": "xx", "url": "xx", "example": ["xx"] },
                { "type": "phone_number", "text": "xx", "phone_number": "xx" }
              ]
            }
          ]
        }
        // Additional cards follow the same structure
      ]
    }
  ]
}

Single Product Message

Reference: Meta SPM templates.

Components: header (mandatory, format: "product"), body (required), footer (optional), buttons (fixed — one spm button).

{
  "name": "spm_marketing",
  "category": "MARKETING",
  "language": "en_US",
  "components": [
    {
      "text": "Use code {{1}} to get {{2}} off our newest succulent!",
      "type": "BODY",
      "example": { "body_text": [["offer_code", "offer_discount"]] }
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "components": [
            { "type": "HEADER", "format": "PRODUCT" },
            { "type": "BUTTONS", "buttons": [{ "text": "View", "type": "SPM" }] }
          ]
        },
        {
          "components": [
            { "type": "HEADER", "format": "PRODUCT" },
            { "type": "BUTTONS", "buttons": [{ "text": "View", "type": "SPM" }] }
          ]
        }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

You can also submit a Single Product Message without a carousel, with the PRODUCT header, BODY, and SPM button as top-level components:

{
  "name": "xx",
  "category": "marketing",
  "language": "xx",
  "parameter_format": "POSITIONAL",
  "components": [
    { "type": "HEADER", "format": "PRODUCT" },
    {
      "type": "BODY",
      "text": "xx",
      "example": { "body_text": [["xx"]] }
    },
    {
      "type": "BUTTONS",
      "buttons": [{ "type": "SPM", "text": "xx" }]
    }
  ]
}

Confirm which shape your WABA accepts before you submit.

Multi Product Message

Components: HEADER (format: "TEXT", with caption text), BODY (required), FOOTER (optional), BUTTONS (fixed — one MPM button).

{
  "name": "mpm_marketing_02",
  "category": "MARKETING",
  "language": "en_US",
  "components": [
    {
      "text": "your catlog",
      "type": "HEADER",
      "format": "TEXT"
    },
    {
      "text": "Hi {{1}}, explore our exclusive collection of {{2}} just for you! Browse through our handpicked items and find the perfect choice today.",
      "type": "BODY",
      "example": {
        "body_text": [["customer", "product"]]
      }
    },
    {
      "text": "Tap below to view our full collection",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "text": "View items", "type": "MPM" }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

Flows

Components: BODY (required), FOOTER (optional), BUTTONS (fixed — one FLOW button).

buttons[].flow_id · string · required

Flow ID issued by Meta.

buttons[].flow_action · string · required

NAVIGATE or LAUNCH.

buttons[].navigate_screen · string

Screen identifier to navigate to (used with NAVIGATE).

Utility category

{
  "name": "flows_template_utility_02",
  "category": "UTILITY",
  "language": "en_US",
  "components": [
    {
      "text": "Hi {{1}}, your registration is pending. Please complete it",
      "type": "BODY",
      "example": { "body_text": [["customer"]] }
    },
    {
      "text": "We will share the details of the application soon.",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "text": "View Flow",
          "type": "FLOW",
          "flow_id": "805389128575872",
          "flow_action": "NAVIGATE",
          "navigate_screen": "JOIN_NOW"
        }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

Marketing category

{
  "name": "flows_template_marketing",
  "category": "MARKETING",
  "language": "en_US",
  "components": [
    {
      "text": "Hi {{1}}, complete your registration in just a few steps!",
      "type": "BODY",
      "example": { "body_text": [["customer"]] }
    },
    {
      "text": "Join now and get exclusive benefits.",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "text": "View Flow",
          "type": "FLOW",
          "flow_id": "805389128575872",
          "flow_action": "NAVIGATE",
          "navigate_screen": "RECOMMEND"
        }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

Complete Flow

A complete flow is a MARKETING category flow template. It uses the same shape as the Marketing example in the Flows tab.

{
  "name": "flows_template_marketing",
  "category": "MARKETING",
  "language": "en_US",
  "components": [
    {
      "text": "Hi {{1}}, complete your registration in just a few steps!",
      "type": "BODY",
      "example": { "body_text": [["customer"]] }
    },
    {
      "text": "Join now and get exclusive benefits.",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "text": "View Flow",
          "type": "FLOW",
          "flow_id": "805389128575872",
          "flow_action": "NAVIGATE",
          "navigate_screen": "RECOMMEND"
        }
      ]
    }
  ],
  "parameter_format": "POSITIONAL"
}

Order Status

UTILITY category with "sub_category": "ORDER_STATUS". Components: BODY (required), FOOTER (optional). No buttons required in the create payload — the ORDER_STATUS button type is used at send time, not creation time.

sub_category · string · required

Must be ORDER_STATUS.

{
  "name": "order_status_test1",
  "category": "UTILITY",
  "language": "en_US",
  "components": [
    {
      "text": "Hello {{1}}, your order #{{2}} is currently {{3}}. We will notify you once it is updated.",
      "type": "BODY",
      "example": {
        "body_text": [["firdous", "1234", "booked"]]
      }
    },
    {
      "text": "thank you for shopping with us",
      "type": "FOOTER"
    }
  ],
  "sub_category": "ORDER_STATUS",
  "parameter_format": "POSITIONAL"
}

Order Details

UTILITY category with "sub_category": "ORDER_DETAILS". Components: BODY (required), FOOTER (optional), BUTTONS (one ORDER_DETAILS button, labeled e.g. “Review and Pay”).

sub_category · string · required

Must be ORDER_DETAILS.

buttons[].type · string · required

ORDER_DETAILS.

{
  "name": "order_details_test",
  "category": "UTILITY",
  "language": "en",
  "components": [
    {
      "text": "Hello {{1}}, thank you for your purchase! Here are the details of your order #{{2}}: Product: {{3}} Quantity: {{4}} Total Price: {{5}} We will notify you once your order is ready for shipping.",
      "type": "BODY",
      "example": {
        "body_text": [["customer_name", "order_id", "product", "quantity", "price"]]
      }
    },
    {
      "text": "thank you",
      "type": "FOOTER"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "text": "Review and Pay", "type": "ORDER_DETAILS" }
      ]
    }
  ],
  "sub_category": "ORDER_DETAILS",
  "parameter_format": "POSITIONAL"
}

Next steps

• If your template uses a media header, upload the file first via Media Upload to obtain a media_id.
• After submission, poll Fetch Template to confirm the template reaches Approved status before sending it.
• Send the approved template via Send Template Message.