---
title: "Create a message template"
method: POST
path: "/api/messaging/whatsapp/templates"
tags: ["WhatsApp Templates"]
---

# Create a message template

`POST /api/messaging/whatsapp/templates`

Creates a WhatsApp message template under a connected Business Account and submits it to Meta for review. Use it when outbound content must be sent outside the 24-hour customer service window. Approval typically takes from a few minutes to a few hours; poll the template until `template_status` becomes `approved`, then send it through [Send a message](/docs/apis/rest/messages/create-message).

#### Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.

[Learn more about API scopes](/docs/platform/your-signalwire-api-space).

## Request body

- CreateWhatsAppTemplateRequest — Request body for creating a message template.
  - `whatsapp_business_id` string, uuid, required — Universal Unique Identifier.
  - `name` string, required — The template name. Maximum 512 characters; lowercase letters, numbers, and underscores only.
  - `language` string, required — The template language code.
  - `category` 'utility' | 'marketing' | 'authentication', required — The category of a WhatsApp message template.
  - `parameter_format` 'named' | 'positional', required — How a template's variable placeholders are referenced.
  - `components` WhatsAppTemplateComponent[], required — The template's components. Must include a `BODY` component. Each component is an object whose fields depend on its `type` — see the request example.
    - `type` string, required — The component type: `HEADER`, `BODY`, `FOOTER`, or `BUTTONS`.

## Response `201`

Response returned when a template is successfully created and submitted to Meta.

- WhatsAppTemplate — A WhatsApp message template.
  - `id` string, uuid, required — Universal Unique Identifier.
  - `name` string, required — The template name. Lowercase letters, numbers, and underscores only.
  - `category` 'utility' | 'marketing' | 'authentication', required — The category of a WhatsApp message template.
  - `components` WhatsAppTemplateComponent[], required — The template's components (header, body, footer, buttons).
    - `type` string, required — The component type: `HEADER`, `BODY`, `FOOTER`, or `BUTTONS`.
  - `language` string, required — The template language code.
  - `parameter_format` 'named' | 'positional', required — How a template's variable placeholders are referenced.
  - `template_id` string, required — Meta's identifier for the template.
  - `template_status` 'approved' | 'archived' | 'deleted' | 'disabled' | 'flagged' | 'in_appeal' | 'limit_exceeded' | 'locked' | 'paused' | 'pending' | 'reinstated' | 'pending_deletion' | 'rejected', required — The Meta approval status of a template. A template must be `approved` before it can be used to send messages.
  - `whatsapp_business_id` string, uuid, required — Universal Unique Identifier.
  - `created_at` string, required — The date and time when the template was created.
  - `updated_at` string, required — The date and time when the template was last updated.
  - `discarded_at` string — The date and time when the template was discarded, if applicable.

## Other responses

- `400` — The request is invalid.
- `401` — Access is unauthorized.
- `422` — The request contains invalid parameters. See errors for details.
- `500` — An internal server error occurred.

## Changes

> 138 revisions in range; 3 could not be searched.

- **2026-07-20** `14b262a4830d` — 1 info
  - endpoint added
- **2026-07-20** `6e5c9df70369` — 1 breaking
  - api path removed without deprecation
- **2026-07-16** `13da5e8c3990` — 1 info
  - endpoint added
- **2026-07-10** `0f65a5bc6e5c` — 1 breaking
  - api path removed without deprecation
- **2026-07-09** `99c7f247cc8a` — 1 breaking, 1 info
  - removed the success response with the status `200`
  - added the success response with the status `201`

[Full history](https://skmtc.dev/signalwire/apis/signalwire-rest-api/changes/api/messaging/whatsapp/templates/post.md)

---

[API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/signalwire/signalwire-rest-api/revisions/40cdd103d4fb/schema)