> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Template
> Create a WhatsApp message template through the ChatSyncs API and submit it to WhatsApp for approval — a normal marketing or utility message, a one-time-passcode (OTP) message, or a carousel. Use when a developer asks how to create a template programmatically, which fields each template type takes, what the #placeholders# mean, or why a template creation call was refused.
Creates a [WhatsApp message template](/learn/chatsyncs-message-templates/creating-a-whatsapp-message-template-in-chatsyncs) 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](/developer-api/whatsapp/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](/developer-api/whatsapp/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.
```bash theme={null}
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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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](/learn/chatsyncs-message-templates/template-variables-vs-custom-variables-whats-the-difference-with-chatsyncs)
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
```json theme={null}
{
"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](/developer-api/whatsapp/send-template-message)
takes as its `template_id`. **`template_id`** is WhatsApp's long number, which [Template Status](/developer-api/whatsapp/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](/developer-api/whatsapp/get-template-list)
for the name; sending the same name again is answered with *WhatsApp template name already exists.*
## Frequently asked
WhatsApp has to approve it first. It starts as `Submitted`. Poll [Template Status](/developer-api/whatsapp/template-status) until it
reads `APPROVED`. One-time-passcode templates are often approved within seconds; marketing templates and carousels can take
longer.
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.
`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](/learn/chatsyncs-message-templates/guidelines-for-utility-and-marketing-templates-in-chatsyncs).
The `verification_code` placeholder you chose when you created the template. Send it as a template variable value through
[Send Template Message](/developer-api/whatsapp/send-template-message).
[Template Status](/developer-api/whatsapp/template-status) returns `rejected_reason`. See
[Why Templates Get Rejected and How to Fix Them](/learn/chatsyncs-message-templates/why-templates-get-rejected-and-how-to-fix-them-in-chatsyncs).
Yes. The ChatSyncs [MCP server](/mcp/tools) 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.
## OpenAPI
````yaml POST /whatsapp/template/create
openapi: 3.1.0
info:
title: ChatSyncs Developer API
version: 1.0.0
description: >-
REST API for sending WhatsApp messages and managing subscribers through
ChatSyncs.
**Authentication.** Send your key as the `apiToken` parameter, or as
`Authorization: Bearer ` — both work on every endpoint **except Custom
Fields List**, which only accepts the `apiToken` parameter (a Bearer header
alone is answered with *The api token field is required.*). A wrong key
returns HTTP 401 `{"status":"0","message":"Unauthenticated."}`; no key at
all redirects to the login page.
**Methods.** Every endpoint accepts both GET and POST with the same
parameters, except Upload Media, which is POST-only. Use POST for anything
that changes data.
**Errors.** Failures usually come back as HTTP 200 with `"status":"0"` and
the reason in `message`, so always check `status`. `status` is the string
`"1"` or `"0"` on most endpoints and a boolean on a few.
**Lists.** Endpoints that return rows put them in `message` as a list; there
is no `data` field (Custom Fields List is the exception and uses `data`).
servers:
- url: https://platform.chatsyncs.com/api/v1
security: []
paths:
/whatsapp/template/create:
post:
tags:
- WhatsApp API
summary: Create Template
description: >-
Creates a WhatsApp message template and submits it to WhatsApp for
approval. The template **cannot be sent until WhatsApp approves it** —
check progress with [Template
Status](/developer-api/whatsapp/template-status).
Three kinds of template go through this one endpoint, chosen by
`template_type` (and `category`):
- **A normal message** (`mixed`, or `wp` for WordPress) — `MARKETING` or
`UTILITY`. Send `body_text`, and optionally `header`, `footer_text` and
`buttons`.
- **A one-time passcode** (`authentication`) — `AUTHENTICATION`. Send
`verification_code`, and optionally `add_security_recommendation` and
`code_expiration_minutes`. WhatsApp fixes the layout of these messages,
so do not send `body_text`, `header` or `buttons`.
- **A carousel** (`carousel`) — `MARKETING`. Send `bubble_body_text` and
`cards`.
In any text you can write placeholders: `#field_name#` fills from a
subscriber's custom field, `#!variable_name!#` is a template variable
whose value you supply each time you send, and `#LEAD_USER_FIRST_NAME#`
is the contact's first name. The reply's `variable_map` shows how each
placeholder was read.
The body is JSON (`Content-Type: application/json`). Send `Accept:
application/json` too, so failures come back as JSON. The response's
`id` is ChatSyncs' own number for the template — the one [Send Template
Message](/developer-api/whatsapp/send-template-message) takes — and
`template_id` is WhatsApp's long number, which Template Status takes.
operationId: createTemplate
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
apiToken:
type: string
description: >-
Your ChatSyncs API key (not a WhatsApp/Meta access token).
Leave it out of the body if you send it as `Authorization:
Bearer ` instead — both work. [Where to find
it](/developer-api/finding-ids#api-token-apitoken).
example: API-KEY
phone_number_id:
type: string
description: >-
The WhatsApp account's phone number ID. [Where to find
it](/developer-api/finding-ids#phone-number-id-phone_number_id).
example: PHONE-NUMBER-ID
name:
type: string
description: >-
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
category:
type: string
enum:
- MARKETING
- UTILITY
- AUTHENTICATION
description: >-
`MARKETING` for promotions, offers and announcements.
`UTILITY` for messages about something the customer did or
asked for (an order, a booking, a receipt). `AUTHENTICATION`
for one-time passcodes only. Carousels must be `MARKETING`.
WhatsApp can re-categorise or reject a template filed in the
wrong one.
example: MARKETING
language:
type: string
description: >-
The template's language code. Defaults to `en_US`. Examples:
`en_US`, `en_GB`, `hi_IN`, `bn_BD`, `pt_BR`.
example: en_US
default: en_US
template_type:
type: string
enum:
- mixed
- wp
- authentication
- carousel
- carousel_product
description: >-
Which kind of template this is. `mixed` (the default) is a
normal message, `wp` is a WordPress template,
`authentication` is a one-time-passcode message, `carousel`
is swipeable image or video cards, and `carousel_product` is
a carousel built from catalog products. The fields below
depend on it.
default: mixed
body_text:
type: string
description: >-
**Normal messages (`mixed`, `wp`) — required.** The message
text, up to 1,024 characters when WhatsApp reviews it (each
`#placeholder#` counts as one character). Not used by
authentication or carousel templates.
example: >-
Hi #LEAD_USER_FIRST_NAME#, get #discount#% off using code
#coupon#!
header:
type: object
description: >-
**Normal messages — optional.** A header shown above the
message.
properties:
type:
type: string
enum:
- text
- image
- video
- document
description: The header kind.
text:
type: string
description: >-
For `text` headers: the header text, up to 60
characters.
media_url:
type: string
description: >-
For `image`, `video` and `document` headers: a public
`https://` link to the file.
required:
- type
footer_text:
type: string
description: >-
**Normal messages — optional.** Small grey text under the
message, up to 60 characters. Static: it takes no
placeholders.
example: Valid till Sunday
buttons:
type: array
description: >-
**Normal messages — optional.** Up to 10 buttons, at most
one `copy_code`. `quick_reply` is a tappable reply, `url`
opens a link, `phone_number` starts a call, and `copy_code`
copies a coupon code.
items:
type: object
properties:
type:
type: string
enum:
- quick_reply
- url
- phone_number
- copy_code
description: >-
The button kind: `quick_reply`, `url`, `phone_number`
or `copy_code`.
text:
type: string
description: >-
The label on the button, up to 20 characters. Not used
by `copy_code`.
url:
type: string
description: >-
For `url` buttons: the web address. It can end in a
placeholder, e.g.
`https://example.com/order/#!OrderID!#`.
phone_number:
type: string
description: >-
For `phone_number` buttons: the number with country
code and a leading `+`, e.g. `+919876543210`.
code:
type: string
description: >-
For `copy_code` buttons: the code the customer copies,
e.g. `SAVE20` or a placeholder such as `#coupon#`. A
template can have only one.
required:
- type
verification_code:
type: string
description: >-
**Authentication templates — required.** The placeholder
that carries the one-time code: a template variable such as
`#!system_otp!#`, or a custom field such as `#otp_field#`.
example: '#!system_otp!#'
add_security_recommendation:
type: boolean
description: >-
**Authentication templates — optional.** `true` adds
WhatsApp's line "For your security, do not share this code."
example: true
code_expiration_minutes:
type: integer
minimum: 1
maximum: 90
description: >-
**Authentication templates — optional.** How long the code
stays valid, from 1 to 90 minutes. It is shown in the
footer.
example: 5
bubble_body_text:
type: string
description: >-
**Carousels — required.** The introduction text shown above
the cards, up to 1,024 characters.
example: >-
Hey #LEAD_USER_FIRST_NAME#, check out our top trending
collection!
cards:
type: array
description: >-
**Carousels — required.** The cards, 2 to 10 of them. Every
card must use the same `media_type` and the same buttons in
the same order.
items:
type: object
properties:
media_type:
type: string
enum:
- image
- video
description: The card's media. The same on every card.
media_url:
type: string
description: A public `https://` link to the image or video.
body_text:
type: string
description: The card's text, up to 160 characters.
buttons:
type: array
description: >-
1 or 2 buttons — `url` or `quick_reply`. The same
kinds in the same order on every card.
items:
type: object
properties:
type:
type: string
enum:
- quick_reply
- url
description: 'The button kind: `quick_reply` or `url`.'
text:
type: string
description: >-
The label on the button, up to 20 characters.
Not used by `copy_code`.
url:
type: string
description: >-
For `url` buttons: the web address. It can end
in a placeholder, e.g.
`https://example.com/order/#!OrderID!#`.
required:
- type
required:
- media_type
- media_url
- body_text
- buttons
required:
- phone_number_id
- name
- category
examples:
marketing:
summary: Marketing message with an image header and three buttons
value:
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'
utility:
summary: Utility message with a tracking link
value:
phone_number_id: PHONE-NUMBER-ID
name: order_shipped
category: UTILITY
language: en_US
body_text: >-
Hi #LEAD_USER_FIRST_NAME#, your order #!OrderID!# has
shipped.
buttons:
- type: url
text: Track order
url: https://example.com/track/#!OrderID!#
authentication:
summary: One-time passcode
value:
phone_number_id: PHONE-NUMBER-ID
name: login_otp_verification
category: AUTHENTICATION
language: en_US
template_type: authentication
verification_code: '#!system_otp!#'
add_security_recommendation: true
code_expiration_minutes: 5
carousel:
summary: Carousel of two image cards
value:
phone_number_id: PHONE-NUMBER-ID
name: summer_shoes_carousel
category: MARKETING
language: en_US
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
responses:
'200':
description: >-
Standard ChatSyncs response. `status` is `"1"` when the template was
created and submitted, and `"0"` on failure. Read the failure reason
from `message`.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: '`"1"` = created and submitted, `"0"` = failure.'
message:
type: string
description: Human-readable result, or the failure reason.
data:
type: object
description: The new template. Present on success.
properties:
id:
type: integer
description: >-
ChatSyncs' own number for the template. [Send Template
Message](/developer-api/whatsapp/send-template-message)
takes this as `template_id`.
template_id:
type: string
description: >-
WhatsApp's long template ID. [Template
Status](/developer-api/whatsapp/template-status) takes
this.
template_name:
type: string
template_type:
type: string
category:
type: string
language:
type: string
status:
type: string
description: >-
`Submitted` straight after creation. It becomes
`Approved` or `Rejected` once WhatsApp reviews it.
variable_map:
type: object
description: >-
How each placeholder was read, by position. Carousels
also list `cards`, one entry per card.
examples:
success:
summary: Created and submitted
value:
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#'
carousel:
summary: A carousel's variable_map lists each card
value:
status: '1'
message: >-
Template has been created and submitted to WhatsApp
successfully. It needs to be approved by WhatsApp before
use.
data:
id: 186
template_id: '129847192847198'
template_name: summer_shoes_carousel
template_type: carousel
category: MARKETING
language: en_US
status: Submitted
variable_map:
body:
'1': '#LEAD_USER_FIRST_NAME#'
cards:
- body:
'1': '#price_1#'
- body:
'1': '#price_2#'
duplicate:
summary: The name is already used on this account
value:
status: '0'
message: WhatsApp template name already exists.
missing:
summary: Required fields left out
value:
status: '0'
message: >-
The phone number id field is required., The name field is
required., The category field is required.
badName:
summary: The name has capitals, spaces or symbols
value:
status: '0'
message: >-
The template name can only contain lowercase alphanumeric
characters and underscores.
badCategory:
summary: The category is not one of the three
value:
status: '0'
message: >-
The category must be MARKETING, UTILITY, or
AUTHENTICATION.
noBody:
summary: A normal message with no body_text
value:
status: '0'
message: component of type BODY is missing expected field(s) (text)
noCards:
summary: A carousel with no cards
value:
status: '0'
message: >-
Carousel template requires a "cards" array with 1 to 10
cards.
otpCode:
summary: An authentication template without a code
value:
status: '0'
message: Authentication template requires verification_code.
carouselLimit:
summary: The plan's carousel limit is used up
value:
status: '0'
message: WhatsApp Carousel module limit has been exceeded.
badNumber:
summary: The phone_number_id is not one of this account's numbers
value:
status: '0'
message: WhatsApp Bot access token not found.
'401':
description: >-
`apiToken` is wrong or missing. Send `Accept: application/json` to
get this JSON answer; without it the API redirects to the login page
with HTTP 302 instead.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
unauthenticated:
summary: Wrong apiToken
value:
message: Unauthenticated.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.