Transactional Viber messages are sent through templates approved by Viber in advance. You register a template directly in the portal: you fill in the wording and variables, the portal submits it to Viber for approval and once approved you can use it in modules and in the API. How templates are billed is described on the [Viber message types](https://www.bulkgate.com/en/helpdesk/viber/viber-message-types/) page.

## Before you start

A template is always registered under a specific Viber sender, so first you need a [registered Viber sender](https://www.bulkgate.com/en/helpdesk/viber/sender-registration-viber/). Until you have one, the templates section shows only a notice instead of the form.

## Creating a template

1. In the portal open **SMS & Viber messaging → Viber templates**.
2. Click **New template**.
3. Fill in the form according to the table below and add [variables](#variables) if needed.
4. Click **Create**. The portal submits the template to Viber for approval.

| Field        | What to fill in                                                                                                                                                                                                                                     |
|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Template key | Your own label for the template, max. 64 characters. The portal stores it in lowercase, without diacritics, and replaces spaces and other characters with hyphens. You will see the exact form in the template list under the name, with `@` at the start — this is how you call the template from the API |
| Name         | Template name, max. 64 characters. Only letters, digits and spaces are allowed — the portal removes any other characters                                                                                                                           |
| Sender       | The Viber sender under which the template is approved and from which the messages are then sent                                                                                                                                                    |
| Type         | `Transactional` for notifications, `OTP` for one-time verification codes                                                                                                                                                                           |
| Language     | Language of the template wording. It is prefilled with the language you use the portal in                                                                                                                                                         |
| Message text | Template wording, max. 875 characters                                                                                                                                                                                                              |

For one sender, the same key cannot have two templates in the same language. You add another language to the same template as a [language version](#language-versions).

## Variables

A variable is a place in the text that is replaced with a specific value when the message is sent, for example an order number.

- You add a variable with the **Add variable** button. A template can have at most 8.
- For each one you fill in the **Variable name** (max. 50 characters) and an **Example value** (max. 125 characters). The example is mandatory — it is submitted to Viber together with the template for approval.
- In the text a variable is written as `{{name}}`. You can type it by hand or insert it with the `{}` button next to the variable — it is inserted at the end of the text.

Example text with two variables `number` and `date`:

> Your order {{number}} has been shipped and we will deliver it {{date}}. Thank you for your purchase.

### Rules for variables

- Every variable in the list must be used in the text.
- The text must not contain `{{…}}` with a name that is not in the list of variables.
- A variable must not stand at the very beginning of the text. For the `Transactional` type it must not stand at the very end either.

> [!TIP]
> When a variable stands at the beginning or at the end of the text, the portal shows no message — the **Create** button just stays inactive. If the template cannot be created and no error is visible, check the edges of the text first.

### OTP template

For the `OTP` type the portal itself adds the `pin` variable with the example value `0451`. The verification code is filled into it when the message is sent. The `pin` variable cannot be renamed or removed and it must be used in the text. Unlike in a transactional template, it may also stand at the end of the text.

## Template approval

Once created, the template appears in the list. For every language version you see its text, its status and, next to the status, the template ID at Viber.

- **Pending** — Viber is still reviewing the template.
- **Approved** — you can use the template.
- A declined template was not approved by Viber and cannot be used.

The status in the list changes by itself as soon as Viber reviews the template.

> [!IMPORTANT]
> Until a template is **Approved**, the portal will not send a message through it and will not offer it in modules.

Neither an approved nor a declined template can be edited in the portal. To change the wording, delete the language version and create it again with the same key — the new wording goes through approval again.

> [!NOTE]
> A template created for your sender at Viber outside the portal is added to the list automatically and gets a generated key.

## Language versions

One template can have its wording in several languages. You add another language with the ⊕ **Add language version** icon next to the template in the list. The key, name, sender and type stay the same — you only choose the language, write the text and fill in the variables.

Each language version is approved separately and has its own status. When sending, you always choose a specific language version.

You delete a language version with the bin icon next to it. After confirmation it is deleted both in the portal and at Viber.

## Using a template

### In modules

In the **Modules & APIs** section open the notification settings and for the Viber channel switch the message text from free text to a registered template. Then pick it from the list — only approved templates of the sender set for the notification are offered, each language version separately.

For every template variable a field is shown into which you can insert module variables. If you leave the field empty, the value of the module variable with the same name is used. You will see the result in the preview below the fields.

### Through the API

In the [Advanced transactional API](https://www.bulkgate.com/en/docs/advanced-api/advanced-viber-transactional/) a template is sent in the `viber` object with these parameters:

| Parameter             | Value                                                                                                                              |
|:----------------------|:-----------------------------------------------------------------------------------------------------------------------------------|
| `template_id`         | Template key with `@` at the start, e.g. `@order-confirmation`, or the template ID at Viber from the template list                |
| `template_language`   | Code of the language version you want to send. If omitted, `en` is used                                                           |
| `template_parameters` | Values of all template variables under their names, e.g. `{"number": "12345", "date": "on Friday"}`. Each is cut to 125 characters |

Most languages have a two-letter code (`cs`, `sk`, `en`, `de`…). The exceptions are French `fr_FR`, Spanish `es_ES`, Portuguese `pt_BR` and `pt_PT`, and Chinese `zh-Hans` and `zh-Hant`.

The API will not send the message through the template when the template does not exist, has no requested language version, is not approved, or does not receive all of its variables.