> ## Documentation Index > Fetch the complete documentation index at: https://docs.alcmeon.ai/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp templates: approval, structure, and Meta sync > How WhatsApp templates work in Simio: Meta approval, categories (Marketing, Utility, Carousel), structure, buttons, media, and click tracking. WhatsApp templates are Meta-approved message formats that let Simio send messages outside the 24-hour customer service window. Every template in Simio is created, edited, and synced through Alcmeon; Simio never talks directly to Meta's template APIs. This page covers the full lifecycle, categories, structure rules, buttons, media, click tracking, and syncing behavior. ## What a template is and why it exists WhatsApp requires businesses to get certain messages pre-approved by Meta before sending them. A template defines the structure of a message (its header, body text, footer, and buttons) and, once approved, can be sent to a contact at any time, including outside an active conversation. Templates exist because WhatsApp restricts free-form messaging: a business can only send free-form text to a contact within a 24-hour window after that contact last messaged them. Outside that window (to start a new conversation, launch a marketing campaign, or send an order update the contact hasn't asked about), the business must use an approved template. This is why every campaign in Simio starts with a template as its entry point. Templates are managed in Simio but are not created directly with Meta. All template operations (create, edit, list, sync) are relayed through Alcmeon, Simio's WhatsApp Business API provider. ## Marketing vs utility: how Meta classifies templates Meta assigns every template to a category based on its content and intent. This affects both what content is allowed and how the message is billed. See [Conversation billing](/simio/channels/whatsapp/conversation-billing) for the pricing side. ### Utility templates Purely functional, transactional messages tied to a specific interaction with the customer. No promotional content. Examples: order confirmations, delivery updates, appointment reminders, payment notifications, review requests. ### Marketing templates Promotional messages with more flexibility in tone and content. Examples: new product announcements, special offers, event invitations, welcome or closing messages, drive-to-store. ### How the classification is made Meta reviews each template individually and decides the category. A company cannot force a classification; Meta looks at: * **Message content**: any promotional element, even small, pushes the template into the Marketing category. * **Message purpose**: informing about an existing transaction reads as Utility; encouraging a new action reads as Marketing. Template category is decided by Meta. The review is automated, so a template written as Utility can still be classified as Marketing. If that happens, you can edit the template's content and submit it again for review. Meta will then reassess its category. See [Conversation billing](/simio/channels/whatsapp/conversation-billing). ## The approval lifecycle Every template has a status that reflects where it stands with Meta's review process. | Status | Meaning | | - | - | | Submitted | Sent to Meta but not yet picked up for review | | Pending | Under review by Meta | | Approved | Meta has approved the template; it can be sent to contacts | | Rejected | Meta declined the template (usually for policy or formatting reasons) | | Archived | The template has been retired on Meta's side and can no longer be used | | Other Meta statuses (disabled, in appeal, flagged, paused) | Meta can also apply these statuses; Simio keeps track of them but they behave as "not currently sendable" | Status changes happen on Meta's side and are reflected back into Simio in two ways: 1. **Real-time update**: whenever Meta notifies Alcmeon that a template's status changed, Simio updates its own record immediately (this covers any status change, not just archiving). 2. **Periodic sync**: Simio also periodically re-checks every template's status with Meta as a safety net, in case a real-time notification was ever missed. There is no live push to an already-open browser tab. If a product person has the template list open when a status changes, they will see the new status only after the page reloads the list (for example, by reopening it or triggering a manual sync). Once a template is archived, it stays archived in Simio even if a later sync still sees an "approved" status coming back from Meta momentarily. Archived status always wins locally, so an archived template can never silently reappear as usable. Archived templates are automatically excluded from the "select a template" dropdown anywhere in the product (for example, when building a campaign or chatbot flow), so users can't accidentally pick a template that's no longer usable. ## Template categories in Simio Meta requires every template to declare a category. Simio currently supports: | Category | Purpose | | - | - | | Utility | Transactional, account-related, or service messages (e.g. order confirmations, appointment reminders) | | Marketing | Promotional messages, offers, announcements | | Carousel | A template that displays multiple swipeable cards side by side, each with its own image/video, text, and buttons. It's actually a Marketing template. | A category called "Authentication" also exists on Meta's side (used for one-time-passcode style messages), but it is not currently supported by Simio's template builder. ### An important technical nuance about Carousel Meta does not actually have a native "Carousel" category. A carousel template is technically stored and approved by Meta under the "Marketing" category. Since its setup is quite different, Simio has perfered to put Carousel in a category of its own. Product-wise, this is invisible to the end user (Simio always displays "Carousel" correctly in the UI), but it explains why a carousel template, if inspected on Meta's own side, will show up as "Marketing." ## Creating and editing templates Templates are created and edited through Simio's own template editor, which then submits the request to Alcmeon for approval by Meta. It is displayed within the scenario builder. Fill in the template fields (name, category, language, header, body, footer, buttons) and submit. This is sent to Meta as a brand-new template. Once a template has been submitted at least once and has a Meta-assigned identifier, further edits are sent as an update to that same template rather than a new submission. Only the content of the header / body / footer) can be changed this way; the name, category, and language of an existing template cannot be changed once submitted (this is a Meta constraint, not a Simio limitation). Moreover, the buttons can't be edited. The language field becomes read-only once a template exists. After submitting a new or edited template, Simio shows a submission dialog that polls for the resulting status (checking roughly every 5 seconds) until the template comes back **Approved** or **Rejected**, or until about 90 seconds have passed without a resolution (in which case the user is told to check back later, since Meta review can take longer than that). ### Template name rules * Lowercase letters, digits, and underscores only. * Maximum 512 characters. ### Multiple languages A template with the same name can exist in multiple languages; each language variant is treated as its own separate template record. Simio's backend maintains the list of WhatsApp-supported languages, and the template editor's language dropdown is driven from that list. When picking an existing template to use (e.g. in a campaign), the specific language variant matters and must be selected explicitly, since two templates can share a name but differ only by language. ### Editing content without resubmitting for approval Some elements can be changed without triggering a new Meta review, because they are not part of what Meta approved. For example, once a template is approved, its header image or video can be swapped for a different piece of media within a specific campaign or flow, without needing to resubmit the template itself. ## Structure of a template A template is made up of optional and required components: | Component | Required? | Notes | | - | - | - | | Header | Optional (0 or 1) | Text, image, or video. Document and location headers exist on Meta's side but are not offered by Simio's editor. | | Body | Required (exactly 1) | The main message text. | | Footer | Optional (0 or 1) | Small text shown below the body. Not allowed on Carousel templates. | | Buttons | Optional | Up to 10 buttons total, several types available (see below). | ### Header limits * Text: up to 60 characters. Can include a single `{{1}}` placeholder. * Image: JPG or PNG, maximum 5 MB. * Video: MP4 or 3GPP format, maximum 16 MB. * Document (not yet supported in the builder): PDF only, maximum 100 MB. * Not allowed at all on Carousel templates (carousel headers live on each card instead, not at the template level). ### Body limits * Maximum 1024 characters. * Can include numbered placeholders like `{{1}}`, `{{2}}`, etc., which get replaced with real values (such as a contact's name) at send time. These must be numbered sequentially starting at 1 with no gaps, each number used exactly once, and two placeholders can never sit directly next to each other (there must be at least one character or space between them). * A template must use either all-numbered placeholders or all-named placeholders, never a mix. Simio's builder only uses the numbered style. * Every placeholder needs an example value provided at submission time, since Meta requires a sample so reviewers can see what a filled-in message looks like. * On Carousel templates, this top-level body text is still required (it's the intro text shown above the card strip), even though each individual card also has its own optional body text. ### Footer limits * Maximum 60 characters. * Cannot contain placeholders/variables. * Not allowed on Carousel templates. ### Button limits | Button type | Max per template | Notes | | - | - | - | | Quick Reply | Meta allows up to 10; Simio's builder caps the practical limit at 3 | Text max 25 characters, no duplicate text within a template | | URL (Visit website) | 2 | Text max 25 characters; if the URL contains a placeholder it must be a single `{{1}}` at the very end. Use the **+ Var** control in the editor to insert the placeholder. | | Phone number | 1 | Text max 25 characters | Buttons also have a grouping rule: quick-reply buttons and URL/phone buttons cannot be interleaved. They must form two contiguous blocks. The editor exposes this with a **Place URL button(s) below quick replies** checkbox that flips the order between "call-to-action first" and "quick replies first." **Display note**: WhatsApp only shows the first 3 buttons directly in the chat; any additional buttons are collapsed behind a "See all options" control. ### Carousel-specific rules * Between 2 and 10 cards. * Each card requires its own header (image or video only, no text/document headers) and its own body text is optional. * All cards must have the identical set of buttons: same number, same types, same order. Meta rejects a carousel where cards have mismatched buttons. (Simio's builder keeps buttons in sync across cards automatically when adding/removing a button slot, so this generally can't happen through normal use.) * Each card can have 1-2 buttons, and each card's button routes independently in a campaign flow. That means, for example, clicking "Yes" on card 1 can lead a contact down a different path than clicking "Yes" on card 2. * A card's URL button, when clicked, is tracked through Simio's link-redirect/click-tracking mechanism rather than being treated as an automatic flow step. * Test-sends are supported for Carousel templates in Simio (this was previously unsupported in the older version of the product). ## Media in templates (images, video, documents) When a header uses an image or video, that media needs to be uploaded and eventually turned into something Meta will accept: * The product accepts JPG, PNG, or MP4 files, up to 50 MB, when uploading media for a template. * Uploaded files are stored by Simio and made available through a Simio-hosted link. * At the moment a template is actually submitted to Meta (not at the moment of upload), Simio automatically converts that link into a genuine Meta-recognized media reference behind the scenes. This step is necessary because Meta's template system rejects a plain web link for the example media shown during approval; it insists on a proper upload through its own media pipeline. This conversion is invisible to the end user; if it happens to fail, the original link is kept as a fallback and Meta will show a clear error rather than the submission silently failing. * This conversion only applies to the "example" media shown during creation/approval. Once a template is approved and is actually being sent to a contact (e.g. in a live campaign), a different, simpler mechanism is used to serve the real media, and a plain link is perfectly valid there. * If a template was created directly on Meta's own Business Manager (bypassing Simio entirely) and only ever synced into Simio, some detail fields (like the original, human-readable text behind a URL button) may not display correctly the first time, until Simio's sync logic has a chance to recover that information from the synced data. This has been addressed for URL buttons specifically; the underlying destination the button was approved with is always honored either way, only the human-readable prefill in the editor could previously be missing. ## URL buttons and click tracking When a template includes a URL/"visit website" button, Simio automatically rewrites the link that actually gets submitted to Meta into a special tracked redirect link, so that clicks on that button can be measured. The original, human-typed link that the template author entered is preserved separately so it can be shown back to the user when they revisit the template, rather than showing the technical tracking link. ## Syncing template status from Meta Simio's template list can be refreshed from Meta (via Alcmeon) in two ways: 1. **Full sync**: pulls the complete current list of templates and their statuses from Meta, and merges it into Simio's local records. This happens automatically the first time a user opens the template list for a given WhatsApp account in a session. 2. **Local refresh**: subsequent actions like toggling a status or language filter only re-query Simio's own stored data, without going back out to Meta, to keep the list fast and responsive. This full sync is a synchronous, blocking network call to Meta (through Alcmeon), so it can take a moment the first time a user opens the template list. ## The template list Templates are listed in **Settings → Messages → Message templates**. The list shows up to 30 templates per page with these columns: * **Name**: the template's Meta-registered name. * **Category**: Utility, Marketing, or Carousel. * **Status**: Approved, Rejected, Pending, Submitted, or Archived (plus other Meta statuses). * **Language**: the language variant of the template. * **Actions**: includes a **View on Meta** link that opens the template directly in Meta Business Manager. A phone-number selector at the top of the list switches which WhatsApp Business account's templates are displayed. The list can be filtered by **Status** and **Language** using the filter icons on those column headers. Filtering by **Category** is not yet available. When picking a template for certain contexts (like replying to a customer inside the live conversation inbox), the list is automatically narrowed further: only Approved, Marketing-category templates without quick-reply buttons and without a carousel structure are offered, because quick-reply templates require an active guided flow to handle the reply, and carousel templates aren't supported for that particular send path. ## Company-level template configuration Each company has some template-related configuration accessible via settings: * Default fallback sample images/videos used as placeholders when a header's media hasn't been customized. * The list of WhatsApp-supported languages available for authoring templates. * The company's own public web address, used to construct properly tracked redirect/click-tracking links inside templates. ## Known limitations * Document and location headers exist on Meta's platform but are not offered by Simio's editor. * Authentication-category templates (used for one-time codes) are not currently supported. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.