Variáveis nas mensagens

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:

• 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 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:

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

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.

Maiúsculas e minúsculas

Ajustes de texto

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.

• 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.

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:

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:

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.

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.

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.

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.

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 e 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

Quando importa a partir de um ficheiro, 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.

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

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; 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.

Canais e comprimento

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.