--- title: "Create a WhatsApp template" method: POST path: "/v1/whatsapp/templates" tags: ["WhatsApp"] --- # Create a WhatsApp template `POST /v1/whatsapp/templates` ## Request - Base URL: `https://api.wavix.com` - URL: `https://api.wavix.com/v1/whatsapp/templates` - Auth: HTTP bearer Creates a WhatsApp template in one of your account's WhatsApp Business Accounts, submits it for review, and returns the new template. Every WhatsApp message you send uses a template, so new message content starts with a new template. **Behavior:** Returns `201` with the new template. Poll `whatsapp_templates_get` for the review outcome. Returns `409` when the WhatsApp Business Account already has a template with the same `name` and `language`. **Requires:** Your account must have WhatsApp and its templates capability enabled, must have a subscription plan, and must not be blocked or suspended. The WhatsApp Business Account must have a connected sender; when your account has more than one WhatsApp Business Account, specify `waba_id` or `sender`. ## Request body - WhatsAppTemplateCreateRequest: Attributes of a new WhatsApp template. Consumed by `whatsapp_templates_create`. - `name` string, required: Template name, made of lowercase letters, digits, and underscores, up to 512 characters. - `language` string, required: Template language code, such as `en` or `en_US`. - `category` 'marketing' | 'authentication' | 'utility', required: Template category. Possible values: - `marketing` — Promotions, offers, and other marketing content. - `authentication` — One-time passcodes for verifying a user. - `utility` — Transactional updates about an order or an account. - `components` WhatsAppTemplateComponentRequest[], required: Structural components of the template. Each component type can appear once, exactly one `body` component is required, and `type` and `format` values must be lowercase. - union: A header, body, footer, or buttons component of a new WhatsApp template. Consumed by `whatsapp_templates_create`. The `type` field selects the variant, and a `header` component is further selected by `format`. - WhatsAppTemplateTextHeaderComponentRequest: Text header of a new WhatsApp template. Requires `text`. Consumed by `whatsapp_templates_create`. - `type` 'header', required: Component type. - `format` 'text', required: Header content format. - `text` string, required: Header text, with an optional `{{1}}` placeholder. - `example` object: Sample for the `{{1}}` placeholder. - `header_text` string[], required: Sample value for the `{{1}}` placeholder in the header text. - WhatsAppTemplateMediaHeaderComponentRequest: Media header of a new WhatsApp template. Takes no `text`. Consumed by `whatsapp_templates_create`. - `type` 'header', required: Component type. - `format` 'image' | 'video' | 'document', required: Header content format. Possible values: - `image` — Image header. - `video` — Video header. - `document` — Document header. - `example` object: Sample media file. - `header_handle` string[], required: Public `http` or `https` URL of a sample media file. Meta's own API expects an upload handle here; Wavix sends the URL to the provider as the sample. - WhatsAppTemplateLocationHeaderComponentRequest: Location header of a new WhatsApp template. Takes neither `text` nor `example`. Consumed by `whatsapp_templates_create`. - `type` 'header', required: Component type. - `format` 'location', required: Header content format. - object: Body of a new WhatsApp template. Required, exactly once. Consumed by `whatsapp_templates_create`. - `type` 'body', required: Component type. - `text` string, required: Body text, with positional `{{n}}` placeholders. - `example` object: Sample values for the placeholders in the body text. - `body_text` array[], required: One set of sample values, one value per placeholder in order. - string[] - object: Footer of a new WhatsApp template. Consumed by `whatsapp_templates_create`. - `type` 'footer', required: Component type. - `text` string, required: Footer text. - object: Buttons component of a new WhatsApp template. Consumed by `whatsapp_templates_create`. - `type` 'buttons', required: Component type. - `buttons` WhatsAppTemplateButtonRequest[], required: Buttons, in display order. - union: A button in the `buttons` component of a new WhatsApp template. Consumed by `whatsapp_templates_create`. The `type` field selects the variant. - object: Button that sends its label back as a reply. Consumed by `whatsapp_templates_create`. - … - object: Button that opens a URL. Consumed by `whatsapp_templates_create`. - … - object: Button that calls a phone number. Consumed by `whatsapp_templates_create`. - … - object: Button that copies a code to the clipboard. Consumed by `whatsapp_templates_create`. - … - `waba_id` string: ID of the WhatsApp Business Account that owns the template, as returned in `waba.id` by `whatsapp_senders_list`. Required when your account has more than one, unless `sender` is set. When both are set, `sender` must belong to this WhatsApp Business Account. - `sender` string: Phone number of a connected sender whose WhatsApp Business Account owns the template, as an alternative to `waba_id`. When both are set, the sender must belong to `waba_id`. The leading `+` is optional. ## Response `201` The created WhatsApp template. - WhatsAppTemplateResponse: Returned by `whatsapp_templates_get` and `whatsapp_templates_create`. - `template` WhatsAppTemplate, required: A WhatsApp message template with its review status and components. Returned by `whatsapp_templates_list`, `whatsapp_templates_get`, and `whatsapp_templates_create`. - `uuid` string, uuid, required: ID of the template. Pass it to `whatsapp_templates_get` to check the review outcome. - `name` string, required: Template name. - `language` string, required: Template language code. - `category` 'marketing' | 'authentication' | 'utility', required: Template category. Possible values: - `marketing` — Promotions, offers, and other marketing content. - `authentication` — One-time passcodes for verifying a user. - `utility` — Transactional updates about an order or an account. - `status` 'draft' | 'pending' | 'approved' | 'rejected' | 'paused' | 'flagged' | 'disabled' | 'in_appeal' | 'pending_deletion' | 'deleted' | 'unknown', required: Template review status. Possible values: - `draft` — The template is created but not yet submitted to the provider. - `pending` — The provider is reviewing the template. - `approved` — The template is approved and can be sent. - `rejected` — The provider rejected the template. - `paused` — The provider paused the template. - `flagged` — The provider flagged the template. It can still be sent. - `disabled` — The template is disabled and can't be sent. - `in_appeal` — An appeal of the review decision is in progress. - `pending_deletion` — The template is being deleted. - `deleted` — The template was deleted. - `unknown` — The provider reported a status that Wavix doesn't recognize. - `quality_rating` 'high' | 'medium' | 'low' | 'unknown' | 'null', nullable, required: Template's messaging quality rating. Meta rates quality from customer feedback over the past seven days, such as blocks and reports. Possible values: - `high` — High quality. - `medium` — Medium quality. - `low` — Low quality. - `unknown` — Not rated yet. - `submitted_at` string, date-time: Date and time the template's state was last updated from WhatsApp, in ISO 8601 format. - `components` WhatsAppTemplateResponseComponent[], required: Structural components of the template. - `type` string, required: Component type: `header`, `body`, `footer`, `buttons`, or the lower-cased name of another section type carried over from an imported template, such as `carousel` or `limited_time_offer`. - `format` 'text' | 'image' | 'video' | 'document' | 'location': Header content format. Present on `header` components only. Possible values: - `text` — Text header. - `image` — Image header. - `video` — Video header. - `document` — Document header. - `location` — Location header. - `text` string: Component text, with `{{n}}` placeholders where applicable. - `example` object: Sample values for the component's placeholders, in the shape the provider expects. - `buttons` object[]: Button definitions. Present on `buttons` components only. - `waba` WhatsAppWaba, required: A WhatsApp Business Account linked to your account, embedded in senders and templates. - `id` string, required: ID of the WhatsApp Business Account. Pass it to `whatsapp_wabas_get` to retrieve the account. - `name` string, nullable, required: Name of the WhatsApp Business Account. - `created_at` string, date-time, required: Date and time the template was created, in ISO 8601 format. ## Other responses - `400`: The body is invalid. The JSON is malformed, a required field is missing or empty, `sender` doesn't belong to `waba_id`, or you have several WhatsApp Business Accounts and specified neither `waba_id` nor `sender`. The `detail` field says which. - `401`: Authentication failed or wasn't provided. - `403`: Returns when the account is suspended, blocked, or has no subscription plan, the API key has no access to the endpoint, or the templates capability is not enabled for the account. - `404`: WhatsApp isn't available for your account or isn't enabled yet. Or `waba_id` isn't linked to your account, or you have no WhatsApp Business Account and omitted `waba_id`. Or `sender` isn't 6–20 digits, isn't a sender of your account, or isn't connected. Or the WhatsApp Business Account has no connected sender. - `409`: A template with this name and language already exists for the WhatsApp Business Account. - `422`: The template content is invalid. A component or button has an unknown or missing key or an unknown type, `components` is empty, or `name`, `language`, or `category` has an invalid value. The `detail` field names the field that's wrong. - `429`: Returns when the account has exceeded its request rate limit. - `500`: Returns when an unexpected error occurs on the server; the request may be retried. - `503`: Returns when the service is temporarily unavailable; the request may be retried. ## Changes - **2026-10-07** `ea33150ace54`: 1 info - endpoint added [Operation history](https://skmtc.dev/wavix/apis/wavix-apis/changes/v1/whatsapp/templates/post.md) --- [API](https://skmtc.dev/wavix/apis/wavix-apis.md) - [All operations](https://skmtc.dev/wavix/apis/wavix-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/wavix/apis/wavix-apis/revisions/f2dde79f05ab?raw)