Create Template

POST

template

create

curl --request POST \
  --url https://platform.chatsyncs.com/api/v1/whatsapp/template/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number_id": "PHONE-NUMBER-ID",
  "name": "summer_promo_2026",
  "category": "MARKETING",
  "language": "en_US",
  "template_type": "mixed",
  "header": {
    "type": "image",
    "media_url": "https://example.com/banner.jpg"
  },
  "body_text": "Hi #LEAD_USER_FIRST_NAME#, get #discount#% off using code #coupon#!",
  "footer_text": "Valid till Sunday",
  "buttons": [
    {
      "type": "copy_code",
      "code": "#coupon#"
    },
    {
      "type": "url",
      "text": "Shop Now",
      "url": "https://example.com/shop"
    },
    {
      "type": "phone_number",
      "text": "Call Us",
      "phone_number": "+1234567890"
    }
  ]
}
'

{
  "status": "1",
  "message": "Template has been created and submitted to WhatsApp successfully. It needs to be approved by WhatsApp before use.",
  "data": {
    "id": 184,
    "template_id": "129847192847192",
    "template_name": "summer_promo_2026",
    "template_type": "mixed",
    "category": "MARKETING",
    "language": "en_US",
    "status": "Submitted",
    "variable_map": {
      "body": {
        "1": "#LEAD_USER_FIRST_NAME#",
        "2": "#discount#",
        "3": "#coupon#"
      }
    }
  }
}

Creates a WhatsApp message template and submits it to WhatsApp for review — the same thing the Create button does in Chatbot Manager → Message Templates, from your own code. Once WhatsApp approves it you can send it with Send Template Message.

Creating a template does not make it sendable. It starts as Submitted, and WhatsApp reviews it before it can be used. Check progress with Template Status. There is no edit or delete endpoint: to change a template, create a corrected copy under a new name.

Example Request

The body is JSON. The key goes in the Authorization header, so it stays out of the body and out of logs.

curl --request POST \
  --url 'https://platform.chatsyncs.com/api/v1/whatsapp/template/create' \
  --header 'Authorization: Bearer API-KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "phone_number_id": "PHONE-NUMBER-ID",
    "name": "summer_promo_2026",
    "category": "MARKETING",
    "language": "en_US",
    "header": { "type": "image", "media_url": "https://example.com/banner.jpg" },
    "body_text": "Hi #LEAD_USER_FIRST_NAME#, get #discount#% off using code #coupon#!",
    "footer_text": "Valid till Sunday",
    "buttons": [
      { "type": "copy_code", "code": "#coupon#" },
      { "type": "url", "text": "Shop Now", "url": "https://example.com/shop" }
    ]
  }'

Send Accept: application/json. Without it, a wrong or missing key is answered with a redirect to the login page (an HTML page) instead of a JSON 401 {"message":"Unauthenticated."}.

The three kinds of template

One endpoint takes three shapes. Which one you get is set by template_type and category; if you leave template_type out it is mixed.

Kind	`category`	`template_type`	What you send
A normal message	`MARKETING` or `UTILITY`	`mixed` (default) or `wp` for a WordPress template	`body_text`, plus optionally `header`, `footer_text` and `buttons`
A one-time passcode	`AUTHENTICATION`	`authentication`	`verification_code`, plus optionally `add_security_recommendation` and `code_expiration_minutes`
A carousel	`MARKETING`	`carousel`	`bubble_body_text` and `cards`

WhatsApp fixes the layout of a one-time-passcode message, with its Copy code button. Do not send body_text, header or buttons for an AUTHENTICATION template. A carousel built from catalog products (carousel_product) needs a connected store; create those from Chatbot Manager → Message Templates → Create → Carousel Product Template.

Normal messages

{
  "phone_number_id": "PHONE-NUMBER-ID",
  "name": "order_shipped",
  "category": "UTILITY",
  "body_text": "Hi #LEAD_USER_FIRST_NAME#, your order #!OrderID!# has shipped.",
  "buttons": [
    { "type": "url", "text": "Track order", "url": "https://example.com/track/#!OrderID!#" }
  ]
}

A header can be text ({"type":"text","text":"Order update"}) or media (image, video or document, with a public media_url). Buttons are one of four kinds:

Button `type`	Needs	What it does
`quick_reply`	`text`	A tappable reply that comes back to your bot
`url`	`text`, `url`	Opens a web address. The address can end in a placeholder
`phone_number`	`text`, `phone_number` (with country code, e.g. `+919876543210`)	Starts a call
`copy_code`	`code`	Copies a coupon code. A template can have only one

One-time passcodes

{
  "phone_number_id": "PHONE-NUMBER-ID",
  "name": "login_otp_verification",
  "category": "AUTHENTICATION",
  "template_type": "authentication",
  "verification_code": "#!system_otp!#",
  "add_security_recommendation": true,
  "code_expiration_minutes": 5
}

verification_code is the placeholder that carries the code each time you send. code_expiration_minutes is from 1 to 90 and is shown in the footer. add_security_recommendation adds WhatsApp’s line For your security, do not share this code.

Carousels

{
  "phone_number_id": "PHONE-NUMBER-ID",
  "name": "summer_shoes_carousel",
  "category": "MARKETING",
  "template_type": "carousel",
  "bubble_body_text": "Hey #LEAD_USER_FIRST_NAME#, check out our top trending collection!",
  "cards": [
    {
      "media_type": "image",
      "media_url": "https://example.com/shoes1.jpg",
      "body_text": "Nike Air Max - Deal: #price_1#",
      "buttons": [{ "type": "url", "text": "Buy Now", "url": "https://example.com/buy/1" }]
    },
    {
      "media_type": "image",
      "media_url": "https://example.com/shoes2.jpg",
      "body_text": "Adidas Boost - Deal: #price_2#",
      "buttons": [{ "type": "url", "text": "Order Online", "url": "https://example.com/buy/2" }]
    }
  ]
}

bubble_body_text is the text above the cards. Each card has an image or video, its own text, and one or two url or quick_reply buttons. WhatsApp needs at least 2 cards and allows 10, and every card must use the same media_type and the same buttons in the same order. Carousel templates count against your plan’s carousel allowance.

Placeholders

Anywhere you write text, you can put a placeholder that ChatSyncs fills in when the template is sent:

Write	It is filled from
`#field_name#`	A subscriber’s custom field of that name, e.g. `#city#`
`#!variable_name!#`	A template variable, whose value you supply each time you send, e.g. `#!OrderID!#`
`#LEAD_USER_FIRST_NAME#`	The contact’s first name

The reply’s variable_map shows how each placeholder was read, by position: {"body": {"1": "#LEAD_USER_FIRST_NAME#"}}. Read Template Variables vs Custom Variables for when to use which.

Limits

Part	Limit
`name`	Lowercase letters, numbers and underscores only
`body_text` and `bubble_body_text`	1,024 characters. A placeholder counts as one character
Header text and `footer_text`	60 characters. A footer takes no placeholders
Button `text`	20 characters
Card `body_text`	160 characters
Buttons on a normal message	10, with at most one `copy_code`
Buttons on a card	2
Cards	2 to 10
`code_expiration_minutes`	1 to 90

The response

{
  "status": "1",
  "message": "Template has been created and submitted to WhatsApp successfully. It needs to be approved by WhatsApp before use.",
  "data": {
    "id": 184,
    "template_id": "129847192847192",
    "template_name": "summer_promo_2026",
    "template_type": "mixed",
    "category": "MARKETING",
    "language": "en_US",
    "status": "Submitted",
    "variable_map": { "body": { "1": "#LEAD_USER_FIRST_NAME#", "2": "#discount#", "3": "#coupon#" } }
  }
}

The reply carries two IDs. id is ChatSyncs’ own short number, which Send Template Message takes as its template_id. template_id is WhatsApp’s long number, which Template Status takes. Keep both.

Errors

A failure comes back as HTTP 200 with "status": "0", so always check status. The message is the reason:

`message`	What to do
`The phone number id field is required., The name field is required., …`	Every missing field is listed, comma-separated. Add them
`The template name can only contain lowercase alphanumeric characters and underscores.`	Use letters, numbers and underscores only, with no capitals or spaces
`The category must be MARKETING, UTILITY, or AUTHENTICATION.`	Use one of the three, in capitals
`WhatsApp template name already exists.`	The name is taken on this account. Pick a new one
`component of type BODY is missing expected field(s) (text)`	A normal message needs `body_text`
`Authentication template requires verification_code.`	Add `verification_code`
`Carousel template requires a "cards" array with 1 to 10 cards.`	Add `cards`
`WhatsApp Carousel module limit has been exceeded.`	Your plan’s carousel allowance is used up
`WhatsApp Bot access token not found.`	`phone_number_id` is not one of this account’s numbers

If a request times out, look before you retry. The template may have been created. Check Bot Template Get for the name; sending the same name again is answered with WhatsApp template name already exists.

Frequently asked

Why can't I send the template I just created?

WhatsApp has to approve it first. It starts as Submitted. Poll Template Status until it reads APPROVED. One-time-passcode templates are often approved within seconds; marketing templates and carousels can take longer.

Can I edit a template after creating it?

Not through this API. Create a corrected copy under a new name and stop using the old one. A rejected template can never be sent as it is.

Should I pick MARKETING or UTILITY?

UTILITY is for a message about something the customer did or asked for: an order update, a booking, a receipt. A promotion, an offer or an announcement is MARKETING, even if it mentions an order. WhatsApp re-categorises or rejects a template filed in the wrong one, and a marketing message costs more to send. See Guidelines for Utility and Marketing Templates.

Where do I put the OTP code when I send?

The verification_code placeholder you chose when you created the template. Send it as a template variable value through Send Template Message.

Why was my template rejected?

Template Status returns rejected_reason. See Why Templates Get Rejected and How to Fix Them.

Can I create the template with an AI assistant instead?

Yes. The ChatSyncs MCP server has a create_template ability that checks the template against these limits before it submits it, and a get_template_status ability to follow it afterwards.

Body

application/json

phone_number_id

string

required

The WhatsApp account's phone number ID. Where to find it.

Example:

"PHONE-NUMBER-ID"

name

string

required

The template's name. Lowercase letters, numbers and underscores only — no spaces or capitals. It must be unique on the WhatsApp account, and it is permanent.

Example:

"summer_promo_2026"

Response

Standard ChatSyncs response. status is "1" when the template was created and submitted, and "0" on failure. Read the failure reason from message.

status

string

"1" = created and submitted, "0" = failure.

message

string

Human-readable result, or the failure reason.

data

object

The new template. Present on success.

Show child attributes

curl --request POST \
  --url https://platform.chatsyncs.com/api/v1/whatsapp/template/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number_id": "PHONE-NUMBER-ID",
  "name": "summer_promo_2026",
  "category": "MARKETING",
  "language": "en_US",
  "template_type": "mixed",
  "header": {
    "type": "image",
    "media_url": "https://example.com/banner.jpg"
  },
  "body_text": "Hi #LEAD_USER_FIRST_NAME#, get #discount#% off using code #coupon#!",
  "footer_text": "Valid till Sunday",
  "buttons": [
    {
      "type": "copy_code",
      "code": "#coupon#"
    },
    {
      "type": "url",
      "text": "Shop Now",
      "url": "https://example.com/shop"
    },
    {
      "type": "phone_number",
      "text": "Call Us",
      "phone_number": "+1234567890"
    }
  ]
}
'

{
  "status": "1",
  "message": "Template has been created and submitted to WhatsApp successfully. It needs to be approved by WhatsApp before use.",
  "data": {
    "id": 184,
    "template_id": "129847192847192",
    "template_name": "summer_promo_2026",
    "template_type": "mixed",
    "category": "MARKETING",
    "language": "en_US",
    "status": "Submitted",
    "variable_map": {
      "body": {
        "1": "#LEAD_USER_FIRST_NAME#",
        "2": "#discount#",
        "3": "#coupon#"
      }
    }
  }
}

Get Started

WhatsApp API

Subscriber API

Label API

Catalog API

User API

Example Request

The three kinds of template

Normal messages

One-time passcodes

Carousels

Placeholders

Limits

The response

Errors

Frequently asked

Body

Response

​Example Request

​The three kinds of template

​Normal messages

​One-time passcodes

​Carousels

​Placeholders

​Limits

​The response

​Errors

​Frequently asked

Body

Response

Example Request

The three kinds of template

Normal messages

One-time passcodes

Carousels

Placeholders

Limits

The response

Errors

Frequently asked