> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Manage WhatsApp templates > Create, version, review, release, and retire WhatsApp message templates safely. ## What it is WhatsApp templates are pre-approved message structures used to initiate or continue conversations outside the customer service window. A template is identified by WABA, name, and language. Use this guide to manage the API lifecycle and keep production template assets stable across teams, versions, and locales. ## Before you begin * Connect the WABA that will own the template. * Choose the template category, [supported language](/en/api-reference/guides/whatsapp-platform/supported-whatsapp-template-languages), name, and components. * Prepare representative variable and media examples required for review. * Follow Meta policy for authentication, utility, and marketing content. * Configure a webhook endpoint that can receive `whatsapp.template.reviewed` events. ## How it works 1. Create the template in a WABA. 2. Store its name, language, category, and current `status`. 3. Wait for approval when review is required. 4. Retrieve or list templates to observe status changes. 5. Send only a template that is valid for the target use case and in a sendable state. 6. Edit or delete the template when its content or lifecycle changes. Editing replaces the existing template contents. Include every component that must remain after the edit. ## Request `POST /whatsapp/templates` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/whatsapp/templates \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup.", "example": { "body_text": [["A-10001"]] } } ] }' ``` Template names should be stable application identifiers. Use variables only in positions supported by the selected component. ## Response ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "status": "PENDING", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup." } ] } ``` The response confirms template creation and its current state. `PENDING` does not mean the template can already be sent. ## Define a stable asset identity Treat each WABA, template name, and language combination as one asset. Keep an asset registry with the owning `wabaId`, stable name, exact locale code, purpose, owner, variable contract, current API status, rollout state, and replacement version. Use a predictable name such as `__v`: * `auth_login_otp_v1` * `orders_pickup_ready_v2` * `growth_summer_offer_v3` Increment the major version when a change affects variable positions, component types, buttons, category, or the meaning of the message. Keep names independent of team names and dates. ## Choose the category before writing content Choose the category from the customer's reason for receiving the message. | Category | Use it when | | - | - | | `AUTHENTICATION` | You authenticate a user with a one-time passcode for verification, recovery, or an integrity challenge. | | `UTILITY` | You fulfill a specific user request or provide an update about an agreed transaction. | | `MARKETING` | You send an offer, promotion, invitation, or other content that does not qualify as authentication or utility. | If a template mixes transactional information with a promotion, design it as marketing or split the purposes into separate templates. ## Freeze the variable contract Define variables as an API contract before copywriters or translators begin. For each variable, record its position, semantic meaning, format, source, representative example, and fallback behavior. For example, `Order {{0}} is ready at {{1}}.` can use this contract: | Position | Meaning | Format | Review example | | - | - | - | - | | `{{0}}` | `order_reference` | Short customer-facing string | `A-10001` | | `{{1}}` | `pickup_location` | Localized store name | `Central Store` | Keep each position's meaning stable across versions and locales. Create a new version if you need to reorder or repurpose variables. Before submission: * Provide a safe, representative sample for every body or text-header variable. * Validate media header URLs, formats, and file sizes. * Keep a text header to at most one variable and include its sample. * Confirm URL-button variables appear only where the API allows them, and include a complete sample URL. * Never use credentials, one-time codes, personal data, or private media in review examples. ## Organize locales as one release Reuse the same versioned name for every locale in one release, but manage each `name` and `language` pair as a separate asset. Keep variable meanings and button actions consistent even when word order changes. Approve and release each locale independently. Never route a user to another language only because that locale is approved. Use the exact, case-sensitive locale code in create, retrieve, edit, delete, and send requests. ## Gate sends on template status Use retrieval or `whatsapp.template.reviewed` webhooks to process approval, rejection, pause, disable, archive, and other lifecycle changes. Preserve the exact name and language used by message requests. Store the API `status` separately from your rollout state. Only route production sends to a template whose current status is `APPROVED` and whose rollout state is active. | Status | Production action | | - | - | | `PENDING` | Block sends while review is in progress. | | `APPROVED` | Allow sends after contract tests and rollout approval pass. | | `REJECTED` | Block sends, inspect the reason, and correct the content or contract. | | `PAUSED` or `DISABLED` | Stop new sends and use an approved fallback when available. | | `IN_APPEAL` | Keep sends blocked until the status becomes `APPROVED`. | | `ARCHIVED` or `DELETED` | Remove the template from routing. | A successful create or edit response does not authorize production sends. ## Synchronize state Use Webhooks for prompt updates and retrieval or list APIs for reconciliation: 1. Verify the signature of each `whatsapp.template.reviewed` event. 2. Deduplicate deliveries by event `id`. 3. Resolve the asset by `wabaId`, `name`, and `language`. 4. Store both the update event and current `status`. 5. Stop routing immediately when the current status is not `APPROVED`. 6. Retrieve the template when an event is missing, delayed, or conflicts with a newer registry state. 7. Run a scheduled, paginated list reconciliation to detect drift. Do not use Webhooks as your only inventory, and do not poll before every message. ## Edit and delete behavior * Edit only templates in a state supported by the endpoint. * Include the complete desired component set in an edit request. * Deleting by name removes every language with that name. * Deleting by name and language removes only that localized template. * Archived templates can still appear in list and retrieval results. ## Release, roll back, and retire versions Prefer a parallel version for material changes: 1. Create a new versioned name for every required locale. Keep the current approved version unchanged. 2. Wait until each target locale is `APPROVED`, then validate its variables, media, buttons, category, and rendered content. 3. Route a controlled share of eligible sends to the new version and monitor delivery, quality, replies, and status updates. 4. Move the remaining traffic only after the new version meets your rollout criteria. Roll back by switching routing to the previous approved name and language. Do not use an emergency edit as a rollback. Retire the previous version only after queues, campaigns, configuration, tests, and rollback windows no longer refer to it. ## Limits and troubleshooting * A send request fails when the template is not approved or its components do not match the message parameters. * Authentication templates use restricted preset structures. * Template category and content must align with Meta policy. * Review rejection details before recreating the same content. * Use a new name when a deleted or materially changed template cannot be restored safely. ## Go-live checklist * [ ] The name, purpose, owner, category, and version are recorded. * [ ] Every variable has one meaning, format, safe example, and fallback rule. * [ ] Media and buttons pass format, destination, and example checks. * [ ] Every required locale is independently `APPROVED`. * [ ] The send path rejects every status other than `APPROVED`. * [ ] Webhook processing is verified, idempotent, and reconciled with retrieval. * [ ] The rollout can restore a previous approved version. * [ ] Queues, campaigns, configuration, tests, and runbooks use the intended version. Select the exact language and regional locale code for a template. Adapt authentication, marketing, utility, commerce, Flow, and calling templates. Inspect the complete component schema. Handle review and lifecycle state changes. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.