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

# Templates and broadcasts

> Author versioned message templates, preview them with real data, and send targeted broadcasts.

**Operations → Communications → Templates → `/message-templates`** <sup>Beta</sup>

Every message the platform sends is rendered from a **template**. Templates make outbound
communication consistent, reviewable and translatable — and they are what a
[collection strategy](/guides/collections/strategies) step or a broadcast actually sends.

## The pages

| Page           | Route                             | Purpose                                  |
| -------------- | --------------------------------- | ---------------------------------------- |
| **Templates**  | `/message-templates`              | The template library.                    |
| **New**        | `/message-templates/new`          | Create a template.                       |
| **Edit**       | `/message-templates/:id/edit`     | Author content.                          |
| **Versions**   | `/message-templates/:id/versions` | Version history.                         |
| **Preview**    | `/message-templates/:id/preview`  | Render with sample or real data.         |
| **Categories** | `/message-templates/categories`   | Group templates by purpose.              |
| **Variables**  | `/message-templates/variables`    | The placeholders available to templates. |
| **Broadcasts** | `/message-templates/broadcasts`   | Bulk sends built on templates.           |

## Templates

A template carries:

| Field             | Purpose                                                        |
| ----------------- | -------------------------------------------------------------- |
| **Name and code** | Identity. The code is what other modules reference.            |
| **Category**      | What the template is for — invoicing, collections, operations. |
| **Channel**       | SMS, email, WhatsApp or push.                                  |
| **Language**      | Templates can exist per language.                              |
| **Content**       | Subject and body, with variables.                              |
| **Version**       | Published versions are what get sent.                          |
| **Status**        | Draft or published.                                            |

### Variables

Templates interpolate variables — tenant name, amounts, due dates, unit, paybill, officer name,
promise date. The **Variables** page lists what is available; the editor inserts them so you do not
have to remember the exact token.

<Warning>
  A variable that does not resolve renders as an empty space in a message a customer reads. Always
  run a **preview** before publishing, and prefer variables the context genuinely provides — a
  collections template cannot use a variable that only exists on an invoice.
</Warning>

### Preview and test

* **Render preview** shows the template with sample or mock data.
* **Send test** delivers a real message to a test recipient and reports the queued status and the
  communication reference, so you can follow it in the
  [Delivery Tracker](/guides/communications).

### Versioning and publishing

Templates are versioned. The **published** version is what modules render; drafts are not sent.
Publishing can require [approval](/guides/approvals), so a message that will reach thousands of
residents is reviewed by someone other than its author.

<Steps>
  <Step title="Draft the content">
    Write for the channel. An SMS is not a shortened email — it should stand alone in 160
    characters where possible.
  </Step>

  <Step title="Insert variables">
    From the editor, so tokens are correct.
  </Step>

  <Step title="Preview">
    Check every variable resolves and the message reads correctly with real values.
  </Step>

  <Step title="Send a test">
    To yourself, on the actual channel. Line breaks and encoding problems only show up on a real
    handset.
  </Step>

  <Step title="Publish">
    Through approval where configured.
  </Step>
</Steps>

## Broadcasts

A broadcast is an operator-initiated bulk send built on a template — a notice of a water shutdown,
a service-charge change, a seasonal message.

| Element      | Purpose          |
| ------------ | ---------------- |
| **Template** | What is sent.    |
| **Audience** | Who receives it. |
| **Channel**  | How it goes.     |
| **Schedule** | When it goes.    |

### Choosing an audience

Audiences are built from your data rather than from a pasted list: residents, leases, owners, or a
filtered subset — for example leases in a block, or accounts above a **minimum balance**. Because
the audience is a query, it is current at send time rather than as of whenever someone exported a
spreadsheet.

<Steps>
  <Step title="Define the audience narrowly first">
    Then widen. It is much easier to add a block than to apologise to one.
  </Step>

  <Step title="Check the recipient count">
    A count far larger or smaller than you expected means the filter is not doing what you think.
  </Step>

  <Step title="Preview against a real recipient">
    Not against mock data.
  </Step>

  <Step title="Send, then watch the tracker">
    Filter the [Delivery Tracker](/guides/communications) by the batch and check the failure rate.
  </Step>
</Steps>

<Warning>
  Broadcast is for **operator-initiated bulk**. Per-case messaging — dunning reminders, promise
  reminders — belongs in [collection strategies](/guides/collections/strategies), which respect
  contact-frequency caps and case state. Sending a bulk arrears blast alongside an active dunning
  ladder is how tenants receive four messages in a day.
</Warning>

## Categories

Categories group templates by purpose and are what other modules filter on when offering you a
template — a collections ladder step lists collections templates, not every template in the
organisation.

## Common problems

| Symptom                                                | Cause                                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Module cannot find a template                          | It is still a draft, or in the wrong category or channel.                       |
| Message sent with a blank space where a name should be | An unresolved variable. Preview before publishing.                              |
| Broadcast reached the wrong people                     | The audience filter. Check the recipient count next time.                       |
| SMS arrived split into three                           | Length. Preview shows the rendered length.                                      |
| Test message never arrived                             | Follow the communication reference in the Delivery Tracker for the real reason. |