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

# Sender IDs, templates and stamps

> How to request SMS sender IDs and templates, how a message is matched against a template, and how optional stamps are switched on, set by sender ID and template, and changed for a single send.

Before an SMS goes out, your provider may check two things: that it comes from an
**approved sender ID**, and that its wording matches an **approved template**. You
request both in OMNI; your provider reviews them.

Both screens say at the top how strictly your account is checked:

| What the screen says | What it means |
| :- | :- |
| Only approved sender IDs can send on your account. / Messages must match an approved template on your account. | Anything unapproved is refused. |
| Your provider is noting messages without approved sender IDs (or templates), but not refusing them yet. | Unapproved messages go out, and are noted. |
| Any sender ID is accepted on your account — approval is optional. / Any wording is accepted on your account — templates are optional. | Nothing is checked. |

## Sender IDs

A **sender ID** is the name people see your SMS come from.

**1. Start a request**

Open **SMS → Sender IDs** and choose **Request sender ID**.

**2. Enter the sender ID**

Exactly as recipients will see it — casing counts. Use up to 11 letters or digits,
or a phone number.

**3. Add a label and a reason (optional)**

The **label** is for you and is never matched against anything. **Why you need it**
is read by whoever reviews it; a good reason is answered faster.

**4. Send request**

It shows as **Waiting for approval** and can send once it is approved.

![The Sender IDs list with statuses In use and Waiting for approval](https://mintcdn.com/fire-flo-omno/8-Y7SR-mD57tBFpq/images/channels/sms-senders.png?fit=max\&auto=format\&n=8-Y7SR-mD57tBFpq\&q=85\&s=b31aec2af72d0e0a08ba3c4718264167)

Sender IDs, with each one's status.

### What a sender ID can be

* Letters, digits and ordinary punctuation, with no spaces at the start or end — it is
  matched exactly.
* At most 64 characters. Longer than 21 won't reach most carriers, and names longer than
  11 characters are cut or refused by some carriers. The form warns you as you type.

### Its status

| Status | Meaning |
| :- | :- |
| **In use** | Approved. It can send. |
| **Waiting for approval** | With your provider. You can **Withdraw** the request. |
| **Not approved** | Turned down, with the reason underneath. |
| **Withdrawn** | You withdrew the request. You can request it again later. |

> [!WARNING]
>
> Changing an **In use** sender ID, or its reason, sends it back for approval — and
> messages from it are refused until your provider approves it again. OMNI asks you to
> confirm first.

## Templates

A **template** is approved wording with **blanks** for the parts that change: a code, a
name, an amount.

**1. Start a template**

Open **SMS → Templates** and choose **New template**.

**2. Name it**

What you and your provider call it.

**3. Write the wording**

Use **Insert a blank** to add the parts that change. Under the box, OMNI shows an
example message the template would accept, with its number of segments.

**4. Submit for approval**

Add a **note for the reviewer** if it helps — a registration reference, for example.

![The SMS Templates list](https://mintcdn.com/fire-flo-omno/8-Y7SR-mD57tBFpq/images/channels/sms-templates.png?fit=max\&auto=format\&n=8-Y7SR-mD57tBFpq\&q=85\&s=fc1c9ad7d8503798206a06bacf83cba2)

SMS templates, with their blanks drawn as chips.

### Blanks

| Blank | Accepts |
| :- | :- |
| `{#var#}` | anything |
| `{#num#}` | digits only |
| `{#alp#}` | letters, spaces, apostrophes and hyphens |

```text theme={null}
Hi {#alp#}, order {#var#} is out for delivery.
```

### How a message is matched

**Everything around a blank is matched exactly** — every word, space and punctuation
mark. Only the blanks change. Wording with no blank approves exactly one message.

When you send with **Use a template**, OMNI shows a box for each blank and won't send
until every blank holds something its kind accepts.

OMNI refuses wording that could never match safely:

* more than 2,000 characters;
* a blank in the wrong case or spelling, such as `{#VAR#}` or `{#code#}`;
* `{{1}}` — that is WhatsApp's blank, not SMS's;
* a template that is nothing but a blank, which would accept every message;
* two blanks with nothing between them, which can't be told apart.

> [!WARNING]
>
> Changing the name or wording of an **In use** template sends it back for approval, and
> messages using it are refused until it is approved again. To keep sending meanwhile,
> submit the new wording as a separate template.

## Many at once

The **⋯** menu on both screens imports and exports the list as a CSV or Excel file. An
export has exactly the columns an import reads, so a downloaded list is a working file.
After an import, OMNI says how many rows were submitted and how many refused, and lets
you download the refused rows with their reasons.

## Stamps

A **stamp** is an extra value an SMS carries alongside its text: a tagged parameter, such
as a registration reference a provider, a regulator or a carrier asks for. Stamps are
entirely optional.

### Switch stamping on

Stamping is one switch: **SMS → Settings → Stamps → Stamp SMS with TLVs**.

* **Off** (the default): no stamp is added to any SMS, including stamps saved on sender IDs
  and templates. They stay saved and are simply not sent.
* **On**: every SMS carries the stamps that apply to it.

### Where stamps are set

| Where you set it | It goes on |
| :- | :- |
| **SMS → Settings → Stamps → Stamp on every SMS** | every SMS from your account |
| A sender ID's **Stamps** | every SMS sent from that sender ID |
| A template's **Stamps** | every SMS sent with that template |

To add one, open the sender ID or template, choose **Add a stamp**, and enter a **tag**
and a **value**. **Remove stamp** takes one off. The Sender IDs and Templates lists show
each one's stamps in a **Stamps** column.

If a registry gives you identifiers to send with each message — an ID for your business,
an ID for each registered template — add them as stamps under the tags your provider
names: the business's on each sender ID (or on every SMS), the template's on each template.

* **Sender ID and template stamps apply once they're approved.** A request still waiting
  for approval shows its stamps with **Applied once approved**. Changing stamps doesn't
  send an approved sender ID or template back for approval.
* **Every SMS, however it's sent, carries them** while stamping is on: the Send page,
  scheduled sends, broadcasts, Inbox replies, AI agents, fallback from other channels and
  verification codes.
* **The most specific value wins.** When two sources set the same tag, the template's
  value beats the sender ID's, which beats your account's.

### Change the stamps of one send

With stamping on, **Send SMS** and **New broadcast** show **Stamps on this send**: the
stamps the message will carry, from your settings, the sender ID and the template. For
that one send you can change a value, remove a stamp or add one. **Reset to the saved
stamps** undoes your changes. Nothing saved in settings, on the sender ID or on the
template is changed.

With stamping off, the send pages show no stamps and the message carries none.

Through the OMNI API, the stamps you name on a request are your own and are sent whether
stamping is on or off.

**Tags and values:**

* Write a tag in hex, like `0x1501` (at most `0xFFFF`). A bare number such as `5120` is
  refused, with the hex to use instead (`0x1400`).
* On a sender ID or a template, the tag is plain hex. The every-SMS stamp, and a stamp
  edited on a send, can also name a type, such as `name_0x1600:Int4`, and then its value
  must be a whole number that fits that type.
* A value is up to 255 characters.

> [!NOTE]
>
> Stamps travel to your provider as your own parameters. Your provider may set its own
> value for a sender ID or template, which takes the place of yours, and a carrier passes
> on only the tags it accepts.

> [!TIP]
>
> Write tags as hex, like `0x1401`. A bare number is read as decimal, and the carrier
> would quietly ignore it — the form refuses it.

## From your own software

The OMNI API lists, requests and withdraws [sender IDs](https://omni.fireflo.au/api-reference/sms/list-senders.md)
and [templates](https://omni.fireflo.au/api-reference/sms/list-templates.md), with the same rules.

## Who may

Requesting, editing and withdrawing sender IDs and templates needs the permission to
**manage sender IDs and template registrations** — the **Owner** and **Admin** roles by
default; the same permission sets their stamps. Switching stamping on and setting the
every-SMS stamp is in SMS settings, which needs the permission to **configure channel
modules** (Owner and Admin by default). Anyone who may send SMS may change the stamps of
a send they make.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.