As mensagens Viber transacionais são enviadas através de modelos previamente aprovados pela Viber. O modelo é registado diretamente no portal: preenche o texto e as variáveis, o portal submete-o à Viber para aprovação e, depois de aprovado, pode utilizá-lo nos módulos e na API. A forma como os modelos são faturados está descrita na página [Tipos de mensagens Viber](https://www.bulkgate.com/pt/centro-de-ajuda/viber/tipos-de-mensagens-viber-business/).

## Antes de começar

Um modelo é sempre registado com um remetente Viber específico, pelo que primeiro precisa de um [remetente Viber registado](https://www.bulkgate.com/pt/centro-de-ajuda/viber/registo-de-remetente-viber/). Enquanto não o tiver, a secção de modelos mostra apenas um aviso em vez do formulário.

## Criar um modelo

1. No portal, abra **Mensagens SMS e Viber → Viber templates**.
2. Clique em **New template**.
3. Preencha o formulário de acordo com a tabela abaixo e, se necessário, acrescente [variáveis](#variaveis).
4. Clique em **Crio**. O portal submete o modelo à Viber para aprovação.

| Campo | O que preencher |
|:--|:--|
| Chave do modelo (Template key) | A sua própria designação do modelo, no máximo 64 caracteres. O portal guarda-a em minúsculas, sem diacríticos, e substitui os espaços e outros caracteres por hífenes. A forma exata aparece na lista de modelos por baixo do nome, com `@` no início — é assim que chama o modelo a partir da API |
| Nome | Nome do modelo, no máximo 64 caracteres. Só são permitidos letras, algarismos e espaços — o portal remove quaisquer outros caracteres |
| Remetente | O remetente Viber com o qual o modelo é aprovado e a partir do qual as mensagens são depois enviadas |
| Tipo | `Transactional` para notificações, `OTP` para códigos de verificação de utilização única |
| Língua | Língua do texto do modelo. Vem preenchida com a língua em que utiliza o portal |
| Mensagem de texto | Texto do modelo, no máximo 875 caracteres |

Para um mesmo remetente, a mesma chave não pode ter dois modelos na mesma língua. Outra língua para o mesmo modelo é acrescentada como [versão linguística](#versoes-linguisticas).

## Variáveis

Uma variável é um lugar no texto que, no momento do envio, é substituído por um valor concreto, por exemplo um número de encomenda.

- Uma variável é acrescentada com o botão **Add variable**. Um modelo pode ter no máximo 8.
- Para cada uma preenche o **Nome variável** (no máximo 50 caracteres) e um **Example value** (no máximo 125 caracteres). O exemplo é obrigatório — é submetido à Viber juntamente com o modelo para aprovação.
- No texto, uma variável escreve-se como `{{name}}`. Pode escrevê-la à mão ou inseri-la com o botão `{}` junto à variável — é inserida no fim do texto.

Exemplo de texto com duas variáveis, `number` e `date`:

> A sua encomenda {{number}} foi expedida e será entregue {{date}}. Obrigado pela sua compra.

### Regras para as variáveis

- Todas as variáveis da lista têm de ser utilizadas no texto.
- O texto não pode conter `{{…}}` com um nome que não esteja na lista de variáveis.
- Uma variável não pode estar no início do texto. No tipo `Transactional` também não pode estar no fim.

> [!TIP]
> Quando uma variável está no início ou no fim do texto, o portal não mostra nenhuma mensagem — o botão **Crio** simplesmente fica inativo. Se não for possível criar o modelo e não houver nenhum erro visível, verifique primeiro as extremidades do texto.

### Modelo OTP

No tipo `OTP`, o próprio portal acrescenta a variável `pin` com o valor de exemplo `0451`. Nela é inserido o código de verificação quando a mensagem é enviada. A variável `pin` não pode ser renomeada nem removida e tem de ser utilizada no texto. Ao contrário do que acontece num modelo transacional, também pode estar no fim do texto.

## Aprovação do modelo

Depois de criado, o modelo aparece na lista. Para cada versão linguística vê o seu texto, o seu estado e, junto ao estado, o ID do modelo na Viber.

- **Pendente** — a Viber ainda está a analisar o modelo.
- **Approved** — pode utilizar o modelo.
- Um modelo recusado não foi aprovado pela Viber e não pode ser utilizado.

O estado na lista muda por si só assim que a Viber analisa o modelo.

> [!IMPORTANT]
> Enquanto um modelo não estiver **Approved**, o portal não envia mensagens através dele nem o propõe nos módulos.

Nem um modelo aprovado nem um modelo recusado podem ser editados no portal. Para alterar o texto, elimine a versão linguística e crie-a novamente com a mesma chave — o novo texto volta a passar pela aprovação.

> [!NOTE]
> Um modelo criado para o seu remetente na Viber fora do portal é acrescentado automaticamente à lista e recebe uma chave gerada.

## Versões linguísticas

Um modelo pode ter o seu texto em várias línguas. Outra língua é acrescentada com o ícone ⊕ **Add language version** junto ao modelo na lista. A chave, o nome, o remetente e o tipo mantêm-se — só escolhe a língua, escreve o texto e preenche as variáveis.

Cada versão linguística é aprovada separadamente e tem o seu próprio estado. No envio, escolhe sempre uma versão linguística específica.

Uma versão linguística é eliminada com o ícone do caixote do lixo junto a ela. Após a confirmação, é eliminada tanto no portal como na Viber.

## Utilizar um modelo

### Nos módulos

Na secção **Módulos e APIs** abra as definições das notificações e, para o canal Viber, mude o texto da mensagem de texto livre para um modelo registado. Depois escolha-o na lista — só são propostos os modelos aprovados do remetente definido para a notificação, cada versão linguística em separado.

Para cada variável do modelo é apresentado um campo no qual pode inserir variáveis do módulo. Se deixar o campo vazio, é utilizado o valor da variável do módulo com o mesmo nome. O resultado pode ser visto na pré-visualização por baixo dos campos.

### Através da API

Na [API transacional avançada](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-viber-transacional/), o modelo é enviado no objeto `viber` com estes parâmetros:

| Parâmetro | Valor |
|:--|:--|
| `template_id` | Chave do modelo com `@` no início, p. ex. `@order-confirmation`, ou o ID do modelo na Viber indicado na lista de modelos |
| `template_language` | Código da versão linguística que pretende enviar. Se for omitido, é utilizado `en` |
| `template_parameters` | Valores de todas as variáveis do modelo com os respetivos nomes, p. ex. `{"number": "12345", "date": "na sexta-feira"}`. Cada um é cortado a 125 caracteres |

A maioria das línguas tem um código de duas letras (`cs`, `sk`, `en`, `de`…). As exceções são o francês `fr_FR`, o espanhol `es_ES`, o português `pt_BR` e `pt_PT` e o chinês `zh-Hans` e `zh-Hant`.

A API não envia a mensagem através do modelo quando o modelo não existe, não tem a versão linguística pedida, não está aprovado ou não recebe todas as suas variáveis.