Uma variável é um marcador de posição no texto de uma mensagem. Cada destinatário recebe no seu lugar o seu próprio valor — um nome, o nome de uma empresa, um número de encomenda. Assim, envia um único texto a milhares de pessoas e cada uma delas lê uma mensagem escrita para si. As variáveis escrevem-se da mesma forma numa campanha e na API.

## Como escrever uma variável

Uma variável é um nome entre parênteses angulares, por exemplo `<first_name>`. Quando a mensagem é enviada, é substituída pelo valor que tem para esse destinatário:

| texto da mensagem | o que o destinatário recebe |
|:--|:--|
| `Olá <first_name>, a sua encomenda está a caminho.` | `Olá Pedro, a sua encomenda está a caminho.` |

- **O nome tem de corresponder exatamente.** As maiúsculas, as minúsculas e os espaços contam — nem `<First_Name>` nem `< first_name >` são substituídos pelo valor de `first_name`.
- **Um valor vazio equivale a nenhum valor.** Um texto vazio ou composto apenas por espaços conta como valor em falta — o que acontece nesse caso está descrito em [Quando o valor está em falta](#quando-o-valor-esta-em-falta).

> [!WARNING]
> Tudo o que estiver escrito como `<algo:algo>`, `<algo=número>` ou `<algo|filtro>` é sempre tratado como variável, mesmo que não tenha nenhuma variável com esse nome, e altera-se na mensagem enviada. Escrevê-lo como `&lt;` também não ajuda. Um `<` isolado ou `<b>` mantém-se tal como está.

## Quando o valor está em falta

Quando não tem um valor para um destinatário, a variável fica na mensagem **literalmente** — o destinatário recebe `Olá <first_name>, …`. Evita isso com um valor predefinido escrito a seguir a dois pontos:

| notação | o que recebe um destinatário sem valor |
|:--|:--|
| `<first_name>` | literalmente `<first_name>` |
| `<first_name:cliente>` | o texto alternativo `cliente` |
| `<first_name:>` | nada — a variável é omitida |

Um destinatário para quem tem um valor recebe o seu próprio valor nos três casos.

> [!TIP]
> Utilize uma variável sem valor predefinido apenas quando tiver dados para todos os destinatários. Caso contrário, acrescente um texto alternativo ou deixe que a variável seja omitida.

## Filtros

Um filtro ajusta o valor que é preenchido — converte-o em maiúsculas, remove espaços, cria uma forma de tratamento a partir de um nome ou controla o seu comprimento. Escreve-se a seguir a uma barra vertical, logo depois do nome da variável: `<first_name|upper>`. Pode escrever vários filtros seguidos e são aplicados da esquerda para a direita: `<city|trim|capitalize>` — mais informações em [Encadeamento de filtros](#encadeamento-de-filtros).

### Maiúsculas e minúsculas

| notação | o que o filtro faz | exemplo |
|:--|:--|:--|
| `<last_name\|upper>` | converte todo o valor em maiúsculas | `João Silva` → `JOÃO SILVA` |
| `<last_name\|lower>` | converte todo o valor em minúsculas | `João Silva` → `joão silva` |
| `<last_name\|first_upper>` | coloca a primeira letra em maiúscula e deixa o resto inalterado | `joão silva` → `João silva` |
| `<last_name\|capitalize>` | começa cada palavra com maiúscula, todas as outras letras ficam em minúsculas | `jOÃO sILVA` → `João Silva` |

### Ajustes de texto

| notação | o que o filtro faz | exemplo |
|:--|:--|:--|
| `<last_name\|trim>` | remove os espaços no início e no fim | `" João Silva "` → `"João Silva"` |
| `<last_name\|ascii>` | remove os diacríticos | `Šťastný` → `Stastny` |
| `<city\|webalize>` | converte o valor num formato para endereço web — sem diacríticos, em minúsculas, com as palavras unidas por hífen | `Ústí nad Labem` → `usti-nad-labem` |
| `<company_name\|word:1>` | escolhe uma palavra pela sua posição; quando o valor não tem tantas palavras, nada é preenchido | `Kytary Novák` → `Kytary` |
| `<company_name\|initial>` | iniciais — a primeira letra de cada palavra, em maiúscula e seguida de ponto final | `Kytary Novák` → `K. N.` |

### Nome e forma de tratamento

Dois filtros trabalham com nomes checos: `vocative` cria a forma de tratamento no caso vocativo checo e `gender` escolhe um texto para um homem ou para uma mulher com base no nome. Seguem as mesmas regras que as variáveis `<first_name_vokativ>` e `<last_name_vokativ>` — a forma como o vocativo é criado está descrita em [Vocativo checo](https://www.bulkgate.com/pt/centro-de-ajuda/ferramentas/vocativo-checo/).

| notação | o que o filtro faz | exemplo |
|:--|:--|:--|
| `<first_name\|vocative>` | converte cada palavra do valor para o vocativo | `Petr Novák` → `Petře Nováku` |
| `<first_name\|gender:Milý,Milá>` | preenche o primeiro texto para um nome masculino e o segundo para um nome feminino — o valor em si não é preenchido | `Jana` → `Milá` |

- **Vocativo a partir de qualquer variável.** Ao contrário de `<first_name_vokativ>`, o filtro `vocative` pode ser utilizado em qualquer variável — por exemplo, num nome completo guardado num único campo ou num valor que envia na API.
- **O género e o tipo de nome** são reconhecidos pelo próprio filtro `vocative` a partir da terminação. Quando se engana, defina-os com parâmetros: o primeiro é `man` ou `woman`, o segundo `first` (nome próprio) ou `last` (apelido), por exemplo `<last_name|vocative:woman,last>`. O valor predefinido de ambos os parâmetros, `auto`, deixa a decisão ao filtro.
- **Maiúsculas e minúsculas.** Cada palavra no vocativo começa com maiúscula e as restantes letras ficam em minúsculas: `NOVÁK` → `Nováku`.
- **O valor predefinido também é declinado**, por isso escreva-o no nominativo: um destinatário sem nome recebe `Zákazníku` a partir de `<first_name:zákazník|vocative>`.
- **O texto do género substitui o valor**, por isso escreva a variável duas vezes no texto: `<first_name|gender:Milý,Milá> <first_name|vocative>` dá `Milý Petře` ou `Milá Jano`. O texto também pode ser apenas o final de uma palavra: `Vážen<first_name|gender:ý pane,á paní>` dá `Vážený pane` ou `Vážená paní`. Ambos os textos são obrigatórios, mas podem estar vazios; não podem conter `<`, `>`, `|` nem vírgula.
- **Sem nome**, o género é decidido a partir do valor predefinido — `<first_name:zákazníku|gender:Milý,Milá>` dá `Milý` a um destinatário sem nome. Um valor predefinido vazio dá sempre o texto para um homem.

> [!WARNING]
> Ambos os filtros seguem as regras do checo, independentemente da origem do nome. O nome inglês John fica na forma `Johne`. Utilize-os apenas em mensagens para destinatários checos e verifique o resultado para nomes pouco comuns com uma mensagem de teste.

### Limite de comprimento

Os filtros com um número controlam o número máximo de caracteres que o valor pode ter. São úteis para valores longos, como o nome de uma empresa ou um endereço, que de outra forma alongariam a mensagem para mais uma parte SMS. O filtro decide o que acontece a um valor mais longo:

| notação | o que acontece a um valor mais longo | “Kytary Novák” com um limite de 8 |
|:--|:--|:--|
| `<company_name\|cut:8>` | cortado no limite — em palavras inteiras sempre que possível | `Kytary` |
| `<company_name\|truncate:8>` | cortado e completado com `...`, cabendo ambos dentro do limite | `Kytar...` |
| `<company_name\|ellipsis:8>` | substituído por `(...)` | `(...)` |
| `<company_name\|empty:8>` | omitido | nada |
| `<company_name:a sua empresa\|fallback:8>` | substituído pelo valor predefinido da variável; quando não o tem, omitido | `a sua empresa` |

Um valor que cabe dentro do limite é inserido por completo.

Com `truncate`, `ellipsis` e `fallback` pode escrever o seu próprio texto a seguir a uma vírgula, que é utilizado em vez do predefinido:

| notação | “Kytary Novák” com um limite de 8 |
|:--|:--|
| `<company_name\|truncate:8,…>` | `Kytary…` |
| `<company_name\|ellipsis:8,a sua empresa>` | `a sua empresa` |
| `<company_name\|fallback:8,a sua empresa>` | `a sua empresa` |

O seu próprio texto não pode conter `<`, `>`, `|` nem vírgula. Um texto vazio (`truncate:8,`) corta o valor sem sufixo.

### Encadeamento de filtros

Pode combinar filtros livremente — basta escrevê-los uns a seguir aos outros, cada um depois da sua própria barra vertical. São aplicados sucessivamente da esquerda para a direita e cada filtro recebe o resultado do anterior. Assim, pode combinar um limite de comprimento com uma alteração de maiúsculas e minúsculas e com a remoção de espaços.

| notação | valor do contacto | o que o destinatário recebe |
|:--|:--|:--|
| `<last_name\|lower\|first_upper>` | `SILVA` | `Silva` |
| `<city\|trim\|capitalize>` | `"  nova iorque  "` | `Nova Iorque` |
| `<company_name\|trim\|truncate:8,…\|upper>` | `"  Kytary Novák "` | `KYTARY…` |
| `<first_name\|word:1\|vocative>` | `Petr Pavel` | `Petře` |

No terceiro exemplo, `trim` remove primeiro os espaços, `truncate:8,…` corta o valor para `Kytary…` e `upper` converte-o por fim em maiúsculas.

- **A ordem importa.** Os mesmos filtros noutra ordem dão um resultado diferente. Para o valor `"  Ústí nad Labem  "`, `<city|trim|cut:4>` dá `Ústí`, enquanto `<city|cut:4|trim>` corta primeiro o valor até aos espaços iniciais e depois remove-os — não sobra nada.
- **O valor predefinido vem antes dos filtros** e toda a cadeia também o ajusta: um destinatário sem nome próprio recebe `CLIENTE` a partir de `<first_name:cliente|trim|upper>`.
- **Cada ocorrência de uma variável tem os seus próprios filtros.** Pode utilizar a mesma variável várias vezes no texto, de cada vez de forma diferente: a partir de `Olá <first_name|first_upper>, <first_name|upper>`, um destinatário com o valor `joão` recebe `Olá João, JOÃO`.
- **No editor de campanhas**, a cadeia segue a ordem dos filtros na caixa de diálogo da variável e altera-a arrastando-os. Cada filtro só pode ser utilizado uma vez.

> [!TIP]
> Coloque `trim` antes dos filtros que limitam o comprimento. Caso contrário, os espaços iniciais também contam para o limite: a partir do valor `"  Kytary Novák "`, `<company_name|cut:8>` dá apenas `"  Kytary"`, enquanto `<company_name|trim|cut:8>` dá `Kytary`.

### A que deve prestar atenção

Escreva o nome do filtro em minúsculas e sem espaços, e o número apenas com algarismos.

> [!IMPORTANT]
> Nem um filtro nem um limite impedem que uma variável sem valor fique no texto. Um destinatário para quem não tem valor recebe literalmente `<company_name>` a partir de `<company_name|cut:8>`. Se quiser um texto alternativo, escreva-o a seguir a dois pontos, antes dos filtros: `<company_name:a sua empresa|cut:8>`.

> [!WARNING]
> Um erro de escrita num filtro invalida a variável. Um filtro desconhecido ou um número em falta — `<first_name|bold>`, `<first_name|cut>` — faz com que a notação deixe de ser uma variável e fique literalmente no texto, mesmo para os destinatários que têm nome próprio. Quando a variável tem um valor predefinido, o filtro errado passa a fazer parte do texto alternativo: `<first_name:cliente|Upper>` preenche o nome próprio ou `cliente|Upper`.

### Notação obsoleta com sinal de igual

Antigamente, o comprimento era limitado com um atalho: o limite escrevia-se a seguir a um sinal de igual, seguido de uma letra que definia o que acontece a um valor mais longo. **Esta notação está obsoleta** — utilize filtros nas novas mensagens. As mensagens que a contêm continuam a funcionar e o editor de campanhas reescreve-a como filtro.

| notação obsoleta | substitua pelo filtro |
|:--|:--|
| `<company_name=8>` ou `<company_name=8c>` | `<company_name\|cut:8>` |
| `<company_name=8t>` | `<company_name\|truncate:8>` |
| `<company_name=8s>` | `<company_name\|ellipsis:8>` |
| `<company_name=8e>` | `<company_name\|empty:8>` |
| `<company_name:a sua empresa=8d>` | `<company_name:a sua empresa\|fallback:8>` |

O atalho é aplicado como primeiro filtro, mesmo quando lhe seguem outros filtros: `<company_name=8|upper>` é o mesmo que `<company_name|cut:8|upper>`.

## Variáveis numa campanha

Uma campanha obtém os valores dos contactos que lhe adiciona — da agenda de contactos, de uma importação de ficheiro e de números introduzidos manualmente.

1. **Adicione primeiro os destinatários.** O menu de variáveis mostra apenas os campos que pelo menos um destinatário da campanha tem preenchidos. Sem destinatários, está vazio.
2. No editor de texto, clique no ícone `Adicionar variável` ou escreva simplesmente `@`. Ao escrever um nome, o menu é filtrado.
3. Escolha a variável. Para cada uma vê que percentagem de destinatários tem dados para ela.

A variável aparece no texto como uma etiqueta com o nome do campo e a sua cor indica como estão os seus dados:

- **sem destaque** — todos os destinatários têm os dados ou está definido um valor predefinido,
- **aviso** — 30 a 99 % dos destinatários têm os dados,
- **erro** — menos de 30 % dos destinatários têm os dados ou esse campo não existe.

Clique na etiqueta para ver um resumo da variável, incluindo os filtros ativos pela ordem em que são aplicados, e edite-a a partir daí:

- **Quando o valor está em falta** — acrescente um texto alternativo, deixe que a variável seja omitida ou mantenha-a no texto.
- **Filtros** — adicione-os um a um a partir de um menu dividido em maiúsculas e minúsculas, ajustes de texto, nome e forma de tratamento, e comprimento. Nos filtros com parâmetro, preencha um número ou um texto, ou escolha uma opção. Altera a ordem arrastando a pega — os filtros são aplicados de cima para baixo — e elimina um filtro de que não precisa. Um valor de exemplo mostra o que o filtro faz.

O editor guarda a variável na mesma notação descrita em [Quando o valor está em falta](#quando-o-valor-esta-em-falta) e [Filtros](#filtros), por exemplo `<company_name:a sua empresa|trim|cut:8>`. Um atalho mais antigo com sinal de igual é reescrito como filtro pelo caminho.

### Que campos pode utilizar

| variável | o que contém |
|:--|:--|
| `<first_name>`, `<last_name>` | nome próprio e apelido |
| `<first_name_vokativ>`, `<last_name_vokativ>` | nome próprio e apelido no caso vocativo checo — preenchidos automaticamente, consulte [Vocativo checo](https://www.bulkgate.com/pt/centro-de-ajuda/ferramentas/vocativo-checo/) |
| `<title_before>`, `<title_after>` | título antes e depois do nome |
| `<company_name>` | nome da empresa |
| `<company_number>`, `<company_vat>` | número de registo da empresa e número de IVA |
| `<email>` | e-mail |
| `<url>` | endereço web |
| `<street1>`, `<street2>`, `<city>`, `<zip>`, `<state>`, `<country>` | endereço — rua, cidade, código postal, estado, país |
| `<phone_mobile>` | número de telefone |
| `<note>` | nota |
| `<custom_field_0>` a `<custom_field_9>` | campos personalizados |

Quando [importa a partir de um ficheiro](https://www.bulkgate.com/pt/centro-de-ajuda/campanhas/importar-contactos-de-csv-excel/), associa cada coluna a um destes campos. Uma coluna que não corresponde a nenhum deles — um número de encomenda, o valor de um desconto — vai para um campo personalizado e, no texto, utiliza então, por exemplo, `<custom_field_0>`.

### Canais, comprimento e pré-visualização

- **Canais.** As variáveis funcionam no texto das mensagens SMS, Viber e RCS e, no RCS, também no título.
- **Comprimento e preço.** O contador de caracteres no editor conta com os valores do contacto selecionado na pré-visualização. No entanto, cada destinatário pode ter valores de comprimento diferente — por isso, o número de partes SMS e o preço são calculados para cada destinatário separadamente, depois de os valores serem preenchidos.
- **Unicode.** Os diacríticos de um valor preenchido mudam a SMS para Unicode apenas quando o tem ativado nas definições do texto.
- **Pré-visualização.** Tanto a pré-visualização da mensagem como `Enviar mensagem de teste` preenchem os valores do contacto selecionado na pré-visualização — assim, vê como fica o texto antes de ser enviado. Os filtros `vocative` e `gender` são a exceção: a pré-visualização no editor não declina o nome, apenas o assinala com 🗣️, e para `gender` mostra ambos os textos, por exemplo `Milý/Milá`. O contador de caracteres também conta com estas formas. O resultado real vê-o numa mensagem de teste.

## Variáveis na API

Na API, envia os valores diretamente no pedido, no parâmetro `variables`: um objeto cuja chave é o nome da variável e cujo valor é o que deve ser preenchido. O texto utiliza a mesma notação, incluindo valores predefinidos e [filtros](#filtros).

```json
{
	"number": "420777777777",
	"text": "Olá <first_name:cliente>, a encomenda <order> está a caminho.",
	"variables": {"first_name": "Pedro", "order": "12345"}
}
```

O destinatário recebe `Olá Pedro, a encomenda 12345 está a caminho.` Pode dar à variável o nome que quiser — `<order>` no exemplo não é um campo do contacto, apenas uma chave de `variables`.

### Onde colocar as variáveis

| API | onde colocar `variables` |
|:--|:--|
| [Advanced API – transacional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-transactional/2.0/) | com toda a mensagem; na versão 2.0 também com cada número em `number` separadamente — os valores junto do número têm prioridade |
| [Advanced API – promocional](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-promotional/2.0/) | com cada número em `number` separadamente; `variables` para toda a mensagem não é utilizado |
| [Advanced API – grupos da agenda de contactos](https://www.bulkgate.com/pt/documentacao/advanced-api/advanced-promotional-envio-para-grupos-da-agenda-de-contactos/) | não é enviado — são preenchidos os campos dos contactos da agenda, com os mesmos nomes que numa [campanha](#que-campos-pode-utilizar) |
| [Integration API](https://www.bulkgate.com/pt/documentacao/integration-api/integration-transactional/) | com cada mensagem |

### Que valores enviar

- **Texto ou um número.** Os números são preenchidos tal como estão (`12` → `12`).
- **`null`, `false` e texto vazio** contam como valor em falta — aplica-se o [valor predefinido](#quando-o-valor-esta-em-falta); caso contrário, a variável fica literalmente no texto.
- **Um array ou um objeto como valor** não é aceite pela Advanced API, que devolve o erro `invalid_input_parameters`.
- **As chaves adicionais** que não estão no texto são ignoradas.
- **Caso vocativo.** A partir de `first_name` e `last_name`, a Advanced API calcula por si `first_name_vokativ` e `last_name_vokativ` — substitui os seus próprios valores destas duas chaves. A Integration API não calcula o vocativo. O funcionamento está descrito em [Vocativo checo](https://www.bulkgate.com/pt/centro-de-ajuda/ferramentas/vocativo-checo/).

### Canais e comprimento

| canal | onde as variáveis são preenchidas |
|:--|:--|
| SMS | texto |
| Viber | texto, legenda do botão e ligação |
| RCS | texto, título e descrição do cartão |
| Voz | texto |

O número de partes SMS e o preço são ambos calculados a partir do texto depois de os valores serem preenchidos. Os diacríticos de um valor preenchido mudam a SMS para Unicode apenas com `"unicode": true`. O texto Viber, RCS e WhatsApp que ultrapassa o limite do canal depois de os valores serem preenchidos (Viber 1 000 caracteres, RCS e WhatsApp 5 000) é cortado.

> [!NOTE]
> Os plugins de e-shop têm o seu próprio conjunto de variáveis, por exemplo `<customer_firstname>`. Estão descritos em [SMS para clientes](https://www.bulkgate.com/pt/centro-de-ajuda/integracoes/modulos-de-e-commerce/sms-para-clientes/).