> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp templates > Create, sync, preview, and use WhatsApp-approved templates in Vocily. WhatsApp templates are pre-approved messages used when you need to start a conversation, restart a conversation outside the 24-hour customer-service window, or send a WhatsApp campaign. Templates are reviewed by Meta. Vocily helps you build the template, validate common formatting issues before submission, preview the message, and keep the local template list synced with Meta. ## When templates are used Use templates for: * Starting a new one-to-one WhatsApp conversation. * Restarting a thread after the 24-hour customer-service window closes. * Sending WhatsApp campaigns to contacts or groups. * Sending structured updates such as appointment reminders, account updates, and authentication codes. Inside the 24-hour customer-service window, operators can send non-template text replies from Monitoring. Outside that window, WhatsApp requires an approved template. ## Template ownership Templates belong to the WhatsApp Business Account that owns them. In Vocily, the operator experience stays phone-number-first: when you choose a WhatsApp number, Vocily only shows templates that can be sent from that number's connected account. This prevents using a template from one WhatsApp Business Account with a number from another account. ## Open Templates Open **WhatsApp → Manage → Templates**. The Templates view shows the templates synced into Vocily. From this page, you can: * Create a template. * Preview an existing template. * Edit a template when Meta allows the template state to be edited. * Duplicate a template into a new submission. * Delete a template from Meta when deletion is allowed. * Refresh templates from Meta. Template rows can include name, category, language, status, quality, last synced time, and the message components Meta returned. ## Create a template Select **Create template** from the Templates view. The builder opens as a full-page experience with three checkpoints: 1. **Setup** — define the template identity, choose the category and category path, then set language and label. 2. **Content** — write the message and configure header, body, footer, buttons, and delivery validity. 3. **Review** — inspect validation issues, preview the message, and submit it to Meta. The builder also has a sticky WhatsApp-style preview on the right. The preview replaces variables with the sample values you enter, so you can review the message the way a customer will see it. ## Setup fields The Setup checkpoint is where the path branches. Choose the category first, then choose the available path inside that category. The fields and validation in later steps change based on this choice. | Field | What it controls | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Template name** | The stable Meta template name. Use lowercase letters, numbers, and underscores only, such as `appointment_reminder_v1`. The name is disabled while editing because Meta treats name + language as the template identity. | | **Category** | The Meta category for review, policy behavior, and template pricing: **Marketing**, **Utility**, or **Authentication**. Meta can recategorize a submitted template if the content better matches another category. | | **Category path** | The available build path inside the selected category, such as **Custom Message** or **Copy Code**. Disabled paths can appear in the picker for context, but they cannot be selected or submitted from this builder. | | **Language** | The template language in Meta locale format, such as `en_US`, `hi`, or `pt_BR`. Language is disabled while editing because it is part of the template identity. | | **Template labels** | A short use-case label, usually two or three words, such as `appointment reminder` or `order update`. The builder requires this so the submission is clearly described before review. | ### What each category means | Category | Choose it when | Avoid using it for | In Vocily | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Marketing** | You want to promote, re-engage, announce, upsell, invite, or send an offer. This includes newsletters, product launches, coupons, and messages meant to drive interest. | Service updates, verification codes, or messages that should be treated as required account communication. | Marketing templates can include optional buttons, CTA buttons, or Marketing Opt-Out buttons. Marketing sends are also checked against marketing opt-out state. | | **Utility** | You are sending information connected to a customer action or relationship, such as appointment reminders, booking updates, order updates, ticket updates, account alerts, or operational notifications. | Promotions, offers, general engagement, or verification-code login use cases. | Utility templates use the Custom Message path. The builder validation requires at least one button and can show the message validity period controls. | | **Authentication** | You are sending a verification code or login/security code that helps a customer access an account or complete an authentication step. | Marketing copy, service updates, long explanations, or anything unrelated to the code. | Authentication templates use the Copy Code path. Keep the message short, code-focused, and non-promotional. | Meta reviews the submitted content and can place the template in a different category if the copy better matches another category. ### Available category paths | Category | Path shown in Vocily | Availability | Use it for | | ------------------ | --------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- | | **Marketing** | **Custom Message** | Enabled | Promotions, offers, product announcements, and engagement messages. | | **Marketing** | Product Message, Carousel, Limited time offer, Flow | Disabled | These can appear in the picker, but are not configurable from this builder. | | **Utility** | **Custom Message** | Enabled | Account updates, order updates, ticket updates, appointment reminders, alerts, and important information. | | **Utility** | Flow | Disabled | This can appear in the picker, but is not configurable from this builder. | | **Authentication** | **Copy Code** | Enabled | Verification-code messages that help customers access their accounts. | | **Authentication** | Autofill, Zero-Tap | Disabled | These can appear in the picker, but are not configurable from this builder. | Changing the category resets the selected path to the default enabled path for that category. For example, choosing **Authentication** selects **Copy Code**, while choosing **Marketing** or **Utility** selects **Custom Message**. See [WhatsApp pricing and charges](/whatsapp/pricing-charges) for Vocily's current template rates by category. ## Category paths Use this section before filling the Content checkpoint. It explains what each enabled category path asks you to configure. | Path | Fields you configure | Important behavior | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Marketing → Custom Message** | Header, body, footer, optional buttons, optional marketing opt-out buttons. | Buttons are optional. If you add Marketing Opt-Out buttons, Vocily asks you to acknowledge that your business is responsible for stopping marketing messages when customers opt out. | | **Utility → Custom Message** | Header, body, footer, buttons, optional message validity period. | Utility templates are for service updates. The builder validation requires at least one button before submission. | | **Authentication → Copy Code** | Verification-code body, optional header/footer fields if you keep them, sample value for the code variable, optional message validity period. | The preview shows a **Copy code** action. Review the validation panel before submission and fix any required fields it flags. | The builder only submits enabled category paths. Disabled paths are shown so teams can understand the broader Meta template family; those paths are coming soon. ## Content fields The Content checkpoint builds the Meta `components` array: header, body, footer, buttons, and optional message validity. The common fields are below, followed by the fields that change by template path. | Field group | Marketing Custom Message | Utility Custom Message | Authentication Copy Code | | --------------------------- | ----------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Header** | Optional. None, Text, Image, Video, or Document. | Optional. None, Text, Image, Video, or Document. | Optional in this builder. Keep it simple for verification-code messages. | | **Body** | Required. Promotional or engagement message text. | Required. Service-update message text. | Required. Verification-code text, usually with the code variable such as `{{1}}`. | | **Footer** | Optional. Useful for opt-out or compliance copy. | Optional. Useful for short context. | Optional. Keep it short if used. | | **Buttons** | Optional Quick Reply, CTA, or Marketing Opt-Out mode. | Required by builder validation; use Quick Reply or CTA. | The preview shows Copy code. Use Review to resolve any button validation shown by the builder. | | **Message validity period** | Not shown. | Shown. Optional custom validity from 1 to 30 days. | Shown. Optional custom validity from 1 to 30 days. | ### Marketing category fields Use this path for promotional or engagement messages. | Field | How to fill it | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Header** | Optional. Choose **None** if you do not want a title or media header. If you keep **Text** selected, enter header text before continuing. | | **Body** | Required. Write the marketing message, offer, announcement, or engagement copy. Include variables only where you will provide values at send time. | | **Footer** | Optional. Commonly used for short opt-out or compliance copy. | | **Buttons** | Optional. Choose one mode: Quick Reply, Call to action, or Marketing Opt-Out. | | **Marketing Opt-Out acknowledgement** | Required only when you add Marketing Opt-Out buttons. It confirms that your business is responsible for honoring opt-outs. | ### Utility category fields Use this path for service updates that are tied to an existing customer action, account, ticket, order, booking, or alert. | Field | How to fill it | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Header** | Optional. Choose **None**, **Text**, **Image**, **Video**, or **Document**. If you use media, upload the file and wait for **Ready**. | | **Body** | Required. Write the service-update message. Keep the reason for the update clear so Meta can review the template correctly. | | **Footer** | Optional. Use short supporting context only. | | **Buttons** | Required by the builder validation. Use Quick Reply for simple responses or Call to action for URL/phone actions. | | **Message validity period** | Optional. Enable it only when you want Meta to stop delivery attempts before the standard 30-day period. | ### Authentication category fields Use this path for verification-code messages. | Field | How to fill it | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Body** | Required. Keep the message focused on the code, usually with a code variable such as `{{1}}`. | | **Variable sample input** | Required when the body has a variable. Use a realistic sample code such as `123456` so the preview and Meta review are clear. | | **Header** | Optional in this builder. For verification-code messages, prefer no header or a very short text header. | | **Footer** | Optional. Keep it short and non-promotional. | | **Copy code action** | Shown in the preview for the Authentication path. | | **Message validity period** | Optional. Use it when the code should expire before the standard delivery window. | ## Header Headers are optional. Set **Header type** to one of: | Header type | What it does | | ------------ | ---------------------------------------- | | **None** | Sends the template without a header. | | **Text** | Adds a short text header above the body. | | **Image** | Adds an image media header. | | **Video** | Adds a video media header. | | **Document** | Adds a document media header. | For a **Text** header: * Maximum length is 60 characters. * Only one variable is supported. * If you use a variable, provide a sample value so Meta can review the template. For a media header: * Upload the media file from the builder. * Image headers accept JPEG or PNG files. * Video headers accept MP4 files. * Document headers accept PDF files. * Wait until the upload shows **Ready** before submitting. For an **Image** header, the image uploaded during template creation is saved as the default media for that template. To edit it, open **WhatsApp → Campaigns → Templates** and choose **Action → Replace header media**. The uploaded file is used for the template's initial Meta submission and review. Replacing the image later with **Action → Replace header media** does not require template approval again. ## Body The body is required and is the main WhatsApp message. | Field | What it controls | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Variable format** | Choose **Numbered variables** for `{{1}}`, `{{2}}`, and so on, or **Named variables** for names such as `{{first_name}}`. | | **Body editor** | Write the template message in the selected language. The body can be up to 1024 characters. | | **Variable sample inputs** | Each variable used in the body gets an inline sample-value field below the editor. Samples are required before submission. | The body editor supports WhatsApp-style formatting: | Formatting | How to write it | | ------------------- | -------------------------------------- | | **Bold** | `*text*` | | **Italic** | `_text_` | | **Strikethrough** | `~text~` | | **Inline code** | `` `text` `` | | **Monospace block** | ` ```text``` ` | | **Bulleted list** | Start a line with `- ` | | **Numbered list** | Start a line with `1. ` | | **Quote** | Start a line with `> ` | | **Emoji** | Use the emoji picker or your keyboard. | Variable rules: * Numbered variables must be sequential: `{{1}}`, `{{2}}`, `{{3}}`. * Numbered mode does not allow named variables. * Named variables must start with a lowercase letter and can include lowercase letters, numbers, and underscores. * Variables should not be adjacent. * The body should not start or end with a variable. * Add enough fixed text around variables so Meta can understand the message during review. ## Footer Footers are optional and work best for short compliance or opt-out copy. | Rule | Limit | | -------------- | ------------- | | Maximum length | 60 characters | | Variables | Not supported | Use the footer for simple lines such as opt-out reminders or brief context. Put the main message in the body, not the footer. ## Buttons Buttons are configured from the **Buttons** card in the Content checkpoint. What you can use depends on the path you chose in Setup: | Path | Button behavior | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | **Marketing → Custom Message** | Buttons are optional. You can choose Quick Reply, Call to action, or Marketing Opt-Out mode. | | **Utility → Custom Message** | The builder validation requires at least one button. Use Quick Reply or Call to action. | | **Authentication → Copy Code** | The preview shows a Copy code action for the customer. If Review flags a button issue, follow the validation message before submitting. | You cannot mix quick replies, call-to-action buttons, and marketing opt-out buttons in the same template. Choose one button mode. ### Quick Reply Use **Quick Reply** when the customer should tap a simple response. | Field | What it controls | | -------------------- | --------------------------------------------------------------------------- | | **Quick reply text** | The label shown on the button. Each quick reply can be up to 25 characters. | Rules: * You can add up to 10 quick reply buttons. * Each quick reply needs text. ### Call to action Use **Add CTA** when the button should open a URL or call a phone number. | Field | What it controls | | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | **CTA type** | Choose **URL** or **Phone**. | | **Button text** | The label shown on the button, such as `View details` or `Call us`. Maximum 25 characters. | | **URL** | The link opened by a URL button. Dynamic URLs can include a variable, such as `https://example.com/orders/{{1}}`. | | **Phone number** | The number called by a Phone button. Use E.164 format, such as `+14155550100`. | Rules: * CTA buttons support at most 2 URL buttons. * CTA buttons support at most 1 phone button. * A URL button needs a URL. * A phone button needs a valid E.164 phone number. ### Marketing Opt-Out Marketing templates can use **Marketing Opt-Out** buttons. | Field | What it controls | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **Opt-In Button** | The positive response button, such as `Of course`. Maximum 25 characters. | | **Opt-Out Button** | The opt-out response button, such as `Stop promotions`. Maximum 25 characters. | | **Acknowledgement checkbox** | Confirms that your business understands it is responsible for stopping marketing messages to customers who opt out. | Vocily also tracks marketing opt-outs by phone number. Marketing templates and campaigns should not be sent to contacts who have opted out. ### Copy Code Authentication templates use the **Copy Code** category path. | Field | What it controls | | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Body code variable** | The verification code placeholder in the body, usually `{{1}}`. | | **Sample value** | The example code shown in preview and sent to Meta for review. Use a realistic 3- to 8-digit sample such as `123456`. | | **Copy code action** | The action shown in the preview for Authentication templates. The customer uses it to copy the code from the message. | Keep Authentication copy short and focused on the code. Do not use marketing language in an Authentication template. ## Message validity period In Vocily, the **Message validity period** section appears for Utility and Authentication templates. Meta calls this time-to-live, or TTL. It controls how long WhatsApp keeps retrying delivery if the message cannot be delivered right away. | Field | What it controls | | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | | **Set custom validity period** | Enables a custom delivery retry window for the template. | | **Validity days** | The retry window shown in the builder. Meta validates the final TTL by category when the template is submitted. | If you do not set a custom validity period, Meta applies the category default. Meta recommends setting Authentication TTL close to the actual code expiration time so a customer does not receive a code after it is no longer usable. ## Review and submit The Review checkpoint shows: * Whether the template is ready to submit. * Any validation issues that still need attention. * Name. * Language. * Category. * Selected category path. * Variable count. * Button count. * Marketing compliance reminders for Marketing templates. If there are validation issues, select the issue to jump back to the section that needs attention. When the template is ready, select **Submit to Meta**. Vocily sends the template name, language, category, variable format, optional validity period, and components to Meta. Meta remains the final authority for approval, category, quality, pauses, and rejection. After submission, the template usually appears as pending until Meta finishes review. ## Edit, duplicate, and delete templates Existing templates can be managed from the Templates view. | Action | What it does | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Preview** | Opens the WhatsApp-style preview for the selected template. | | **Edit** | Opens the builder for a template that Meta allows to be edited. Name and language stay locked. | | **Duplicate** | Copies the selected template into a new submission. The copied name is normalized into a new name, such as adding `_copy`. | | **Delete** | Deletes the template from Meta when deletion is allowed. | | **Refresh** | Syncs template state from Meta into Vocily. | When editing, Vocily sends the updated category, variable format, optional validity period, and components to Meta. Meta can reject an update even if the builder validation passes. ## Status and quality Template status comes from Meta and is shown in Vocily after sync or webhook updates. | Status | What it means | | ------------ | ----------------------------------------------------------------------------------------------------- | | **Pending** | Submitted to Meta and waiting for review. | | **Approved** | Approved by Meta and available for sending. | | **Rejected** | Rejected by Meta. Review the reason, duplicate or edit where allowed, and submit a corrected version. | | **Paused** | Temporarily paused by Meta, commonly because of quality or policy signals. | | **Disabled** | Disabled by Meta. It cannot be sent. | Quality score also comes from Meta. It helps you understand how customers are responding to the template. Low-quality templates can be paused or disabled by Meta. ## Sync and lifecycle updates Vocily syncs templates from Meta and receives template lifecycle updates from Meta. These updates keep the local template list aligned when Meta approves, rejects, pauses, reinstates, recategorizes, changes quality score, or changes template components. If a template was changed in Meta and the Vocily list has not updated yet, select **Refresh** from the Templates view. ## Use templates Approved templates can be used in: * [Monitoring and inbox](/whatsapp/monitoring-inbox) for one-to-one replies outside the 24-hour customer-service window. * [WhatsApp campaigns](/whatsapp/campaigns) for outbound sends to groups. If the template has variables, provide values at send time. If the template has an image header, Vocily uses the saved default image. You can replace it from **WhatsApp → Campaigns → Templates → Action → Replace header media** before sending. ## What's next * Add audiences in [Contacts and groups](/whatsapp/contacts-groups). * Send templates at scale in [WhatsApp campaigns](/whatsapp/campaigns). * Use templates one-to-one in [Monitoring and inbox](/whatsapp/monitoring-inbox).