---
title: "Create template"
method: POST
path: "/api/v1/templates"
tags: ["WhatsApp templates"]
---

# Create template

`POST /api/v1/templates`

Create a WhatsApp template and submit it for WhatsApp approval, which is asynchronous (~24–48h). Example (TEXT): `{ "name": "order_shipped", "language": "es", "category": "UTILITY", "contentType": "TEXT", "content": { "body": "Hola {{1}}, tu pedido ya salió." }, "variables": { "1": "Ana" } }`. Example with buttons (CALL_TO_ACTION): `{ "name": "order_shipped_cta", "language": "es", "category": "UTILITY", "contentType": "CALL_TO_ACTION", "content": { "body": "Hola {{1}}, tu pedido ya salió.", "actions": [{ "type": "URL", "title": "Ver pedido", "url": "https://example.com/orders/{{2}}" }] }, "variables": { "1": "Ana", "2": "12345" } }`. Example with reply buttons (QUICK_REPLY): `{ "name": "order_feedback", "language": "es", "category": "UTILITY", "contentType": "QUICK_REPLY", "content": { "body": "¿Te gustó tu compra?", "actions": [{ "title": "Sí", "id": "yes" }, { "title": "No", "id": "no" }] } }`. Example with a header and image (CARD): `{ "name": "order_shipped_card", "language": "es", "category": "UTILITY", "contentType": "CARD", "content": { "headerType": "media", "mediaUrl": "https://example.com/banner.jpg", "body": "Hola {{1}}, tu pedido ya salió.", "footer": "Gracias por tu compra", "actions": [{ "type": "URL", "title": "Ver pedido", "url": "https://example.com/orders/{{2}}" }] }, "variables": { "1": "Ana", "2": "12345" } }`. Example that is only an image (MEDIA): the image URL goes in `content.media` (an array), NOT in a variable — `{ "name": "promo_verano", "language": "es", "category": "MARKETING", "contentType": "MEDIA", "content": { "media": ["https://example.com/promo.png"], "body": "¡Hola {{1}}! Aprovecha nuestra promo de verano." }, "variables": { "1": "Ana" } }`.

## Request body

- object
  - `name` string, required — Template name, unique per WhatsApp number.
  - `language` string, required — WhatsApp language code, e.g. `es`, `en`. A regional variant like `es_MX` or `en_US` is normalized to its base code.
  - `category` 'UTILITY' | 'MARKETING' | 'AUTHENTICATION', required
  - `contentType` 'TEXT' | 'MEDIA' | 'QUICK_REPLY' | 'CALL_TO_ACTION' | 'CARD', required
  - `content` object, required — Message content. Shape depends on `contentType`: TEXT `{ body }`; MEDIA `{ body?, media: [url] }`; QUICK_REPLY `{ body, actions: [{ title, id }] }`; CALL_TO_ACTION `{ body, actions: [{ type: URL|PHONE_NUMBER, title, url|phone }] }`; CARD `{ headerType, headerText|mediaUrl, body, footer?, actions? }`. Use `{{1}}`, `{{2}}`… for variables. Example (TEXT): `{ "body": "Hola {{1}}, tu pedido está en camino" }`. Example (CALL_TO_ACTION, adds a button): `{ "body": "Hola {{1}}, tu pedido está en camino", "actions": [{ "type": "URL", "title": "Ver pedido", "url": "https://example.com/orders/{{2}}" }] }`. Example (QUICK_REPLY, adds reply buttons): `{ "body": "¿Te gustó tu compra?", "actions": [{ "title": "Sí", "id": "yes" }, { "title": "No", "id": "no" }] }`. Example (CARD, header + optional footer/button): `{ "headerType": "text", "headerText": "Pedido en camino", "body": "Hola {{1}}, tu pedido ya salió.", "footer": "Gracias por tu compra", "actions": [{ "type": "URL", "title": "Ver pedido", "url": "https://example.com/orders/{{2}}" }] }`.
  - `variables` object — Example values for placeholders, e.g. `{ "1": "Ana" }` for `{{1}}`. Required for every placeholder used.
  - `phoneNumbers` string[] — WhatsApp numbers (E.164) to create the template for. Omit to use the first active number connected to your organization.

## Response `201`

Success

- object
  - `data` object[], required — The created template(s) — one per WhatsApp account backing the chosen numbers.
    - `id` string, required — Template id.
    - `name` string, required — Template name (unique per WhatsApp number).
    - `language` string, required — WhatsApp language code the template was created for, e.g. `es_MX`.
    - `category` 'UTILITY' | 'MARKETING' | 'AUTHENTICATION', required
    - `contentType` 'TEXT' | 'MEDIA' | 'QUICK_REPLY' | 'CALL_TO_ACTION' | 'CARD', required
    - `content` unknown, required
    - `variables` object, nullable, required — Example values for `{{1}}`-style placeholders.
    - `phoneNumbers` string[], required — WhatsApp numbers this template can be sent from.
    - `status` 'DRAFT' | 'PENDING' | 'APPROVED' | 'REJECTED', required — DRAFT (not yet submitted), PENDING (in WhatsApp review, typically 24-48h), APPROVED, or REJECTED (see rejectionReason).
    - `rejectionReason` string, nullable, required
    - `createdAt` string, required — ISO 8601 timestamp.
    - `updatedAt` string, required — ISO 8601 timestamp.

## Other responses

- `400` — Validation failed or the request cannot proceed.
- `401` — Missing, malformed, or revoked API key.
- `404` — The resource does not exist in this organization.
- `409` — Conflicts with the current state (duplicates, wrong lifecycle state).
- `422` — The request is well-formed but semantically invalid.
- `429` — Rate limit exceeded — retry after `Retry-After`.
- `500` — Internal server error.
- `503` — Transient error — retry with a narrower request.

---

[API](https://skmtc.net/useboom/apis/boom-api.md) · [All operations](https://skmtc.net/useboom/apis/boom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useboom/boom-api/versions/00f873e07076/schema)