> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables & Media

> Reference for template variables, media headers, and buttons.

This page is the deep reference for the parts of a template — variables in the body and text header, media headers, and buttons.

If you're creating your first template, read [Create a Template](/templates/create-template) first.

## Variables reference

Template variables use numbered placeholders that are replaced at send time.

### Format

```
{{1}}  {{2}}  {{3}}  …
```

* Double braces on each side.
* **Digits only** — no names, no spaces.
* Start at `{{1}}` and number sequentially.

<Warning>
  Template variables use `{{1}}` style — indexed numbers.

  Bot Flows use a **different** syntax — `{variable_name}` with single braces and a name.

  Don't confuse them. Template variables are always numeric and double-braced.
</Warning>

### Where variables are allowed

| Location                            | Variables allowed                    |
| ----------------------------------- | ------------------------------------ |
| Text header                         | Yes — up to 1                        |
| Body                                | Yes — sequential, practical max \~10 |
| Footer                              | No                                   |
| Media header (image/video/document) | No (the sample file is separate)     |
| Quick-reply button label            | No                                   |

### Variable rules

* Every variable must have a **sample value** supplied when you create the template.
* Variables must be numbered sequentially — no gaps.
* The body cannot start or end with a bare variable — wrap them in fixed text.
* The same variable number can be reused multiple times in the body.

### Good vs. bad variable use

| Good                            | Bad                                       |
| ------------------------------- | ----------------------------------------- |
| `Hi {{1}}, thanks!`             | `{{1}}` as the entire body                |
| `Order #{{1}} is ready.`        | `{{1}}` alone at the very end of the body |
| Short values: names, dates, IDs | Long values: paragraphs of marketing copy |

See [Dynamic Templates](/templates/dynamic-templates) for how variables get values at send time.

## Media headers

You can put an image, video, or document at the top of a template message. Pick the header type when creating the template; supply the actual file when sending each campaign or message.

### Header types

Xobito supports four header format options:

| Format   | File formats                     |
| -------- | -------------------------------- |
| TEXT     | Plain text (supports 1 variable) |
| IMAGE    | JPG, PNG                         |
| VIDEO    | MP4                              |
| DOCUMENT | PDF                              |

### Media size limits

WhatsApp enforces its own upload size limits. Practical guidelines:

| Header type | Typical ceiling                | Recommended                                |
| ----------- | ------------------------------ | ------------------------------------------ |
| Image       | A few MB                       | Compress well under 1 MB for fast delivery |
| Video       | Tens of MB                     | Keep under 30 seconds                      |
| Document    | Larger PDFs allowed but slower | Under 10 MB for fast delivery              |

<Warning>
  Oversized files can fail silently — the message text arrives but the media doesn't. Always test a template with a real phone before doing a large campaign.
</Warning>

### Uploading the sample file

When you create a template with an IMAGE, VIDEO, or DOCUMENT header, you upload **one sample file**. Meta uses this sample during their review. It doesn't have to be the file you will ultimately send to recipients — it just has to represent the template's purpose.

* For an order-confirmation template: upload a sample receipt image.
* For a welcome-video template: a short branded intro clip.
* For a terms template: a sample terms PDF.

### Sending the real file at send time

When you later send the template in a campaign or chat, Xobito asks for the actual media file for this send. You can use a different file each time, as long as it matches the declared header type.

### Image best practices

<AccordionGroup>
  <Accordion title="Use 16:9 framing">
    WhatsApp displays header images in a landscape-ish crop on most devices. Square or tall images may crop awkwardly.
  </Accordion>

  <Accordion title="Keep file size small">
    Smaller images load instantly on slow networks. Tools like Squoosh or TinyPNG can compress without visible quality loss.
  </Accordion>

  <Accordion title="Put important text in the body, not on the image">
    Text inside an image is small, unsearchable, and often hard to read. Use the image for visuals, the body for words.
  </Accordion>

  <Accordion title="Test on a real phone">
    What looks good on a desktop monitor may be unreadable on a 5-inch screen.
  </Accordion>
</AccordionGroup>

### Video best practices

<AccordionGroup>
  <Accordion title="Keep it short">
    WhatsApp users scroll fast. 15–30 seconds is a good ceiling.
  </Accordion>

  <Accordion title="Use MP4 with common codecs">
    H.264 video + AAC audio is the most compatible combination across phones.
  </Accordion>

  <Accordion title="Add captions">
    Most video on WhatsApp gets watched with the sound off. Burn captions into the video.
  </Accordion>

  <Accordion title="Start with a hook">
    The first two seconds decide whether someone watches on.
  </Accordion>
</AccordionGroup>

### Document best practices

<AccordionGroup>
  <Accordion title="Stick to PDF">
    Other formats may not display predictably on all devices.
  </Accordion>

  <Accordion title="Name the file meaningfully">
    Recipients see the filename. `Invoice-April-2026.pdf` is clearer than `doc_final_v3.pdf`.
  </Accordion>

  <Accordion title="Flatten form fields">
    If the PDF has editable fields or comments, flatten them before sending to avoid unexpected edits.
  </Accordion>
</AccordionGroup>

## Buttons

Xobito's template builder currently supports **Quick Reply** buttons explicitly. Quick Reply buttons are tappable buttons that send a preset reply back to your WhatsApp number.

<Note>
  Meta's wider template platform also supports URL and Phone Number buttons. Xobito's current builder implementation is focused on QUICK\_REPLY handling; if your workspace has URL or phone button options available, use them per the in-product labels. Otherwise, include links or phone numbers as plain text in the body.
</Note>

### Quick Reply buttons

* **Purpose:** send a preset text reply back to your workspace when tapped.
* **Label:** short, action-oriented — `Confirm`, `Cancel`, `Yes, please`.
* **Good use cases:**
  * Order confirmation: `Confirm` / `Change delivery`.
  * Appointment reminder: `I'll be there` / `Reschedule`.
  * Quick survey: `Good` / `Bad`.

When a recipient taps a Quick Reply button, your bot flow or inbox can branch on that reply to continue the conversation automatically.

## Formatting in the body

WhatsApp supports basic rich formatting inside the body:

| Markup           | Result                          |
| ---------------- | ------------------------------- |
| `*bold*`         | **bold**                        |
| `_italic_`       | *italic*                        |
| `~strike~`       | strikethrough                   |
| Triple backticks | monospace                       |
| Line breaks      | press Enter                     |
| Emojis           | paste or type directly: 👋 🎉 ✅ |

<Tip>
  Use bold for order numbers and totals — they stand out and make confirmations easy to scan. Don't bold everything; it defeats the purpose.
</Tip>

## Character limits

| Part          | Limit                                                        |
| ------------- | ------------------------------------------------------------ |
| Template name | 512 characters (keep it short for readability)               |
| Text header   | Short (WhatsApp caps it)                                     |
| Body          | Meta's body limit applies — aim for 1024 characters or fewer |
| Footer        | Short single line                                            |

The builder flags over-limit fields before submission.

## Next steps

<CardGroup cols={2}>
  <Card title="Create a template" icon="file-pen" href="/templates/create-template">
    Step-by-step walkthrough with screenshots.
  </Card>

  <Card title="Dynamic templates" icon="wand-magic-sparkles" href="/templates/dynamic-templates">
    How to fill variable values at send time.
  </Card>

  <Card title="Meta approval" icon="circle-check" href="/templates/meta-approval">
    Avoid rejection with our rejection-reason guide.
  </Card>

  <Card title="Custom fields" icon="file-pen" href="/contacts/custom-fields">
    Store the data you'll merge into templates.
  </Card>
</CardGroup>