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

# Variáveis: os campos que mudam

> Como criar campos personalizáveis num modelo do Pombo, os tipos prontos, as regras de nome e exemplo, e como as variáveis viram colunas da planilha no envio em lote.

Uma **variável** é um espaço em branco dentro do modelo, preenchido a cada envio. No painel elas
aparecem como **campos personalizáveis**.

Assim, um modelo só:

> Prezado(a) **\[nome]**, informamos que o débito de **\[valor]** vence em **\[data]**.

serve para todos os destinatários.

## Criar uma variável

Duas formas.

<Tabs>
  <Tab title="Pelo botão">
    **Adicionar campo**, no editor da mensagem. O Pombo oferece tipos prontos:

    | Tipo                            | Exemplo                   |
    | ------------------------------- | ------------------------- |
    | Nome do destinatário            | Maria Silva               |
    | Documento do destinatário       | 123.456.789-00            |
    | Número do processo / expediente | 0001234-56.2024.8.26.0100 |
    | Data                            | 15/03/2025                |
    | Valor em reais                  | R\$ 1.500,00              |
    | Outro dado personalizado        | você escolhe o nome       |
  </Tab>

  <Tab title="Escrevendo direto no texto">
    Escreva o campo entre chaves ou colchetes no meio da mensagem (`{{nome}}`, `{nome}`,
    `[nome]` ou `<<nome>>`) e o Pombo detecta.

    Aparece então o aviso **Encontramos campos personalizáveis no texto**, com a opção de
    **Converter** cada um, ou **Converter tudo**.

    <Warning>
      Detectar não basta: é preciso **converter**. Um campo detectado e não convertido impede
      salvar o modelo, porque sairia como texto literal na mensagem: o destinatário receberia
      `[nome]` em vez do nome.
    </Warning>
  </Tab>
</Tabs>

## O exemplo é obrigatório

Toda variável precisa de um **exemplo de valor**, e não é burocracia:

* No **WhatsApp**, o exemplo é exigido para a aprovação. É por ele que o revisor entende o que vai
  no campo.
* No **e-mail**, é o valor mostrado na pré-visualização.

<Tip>
  Use um exemplo realista, do mesmo formato do dado real. Para valor, `R$ 1.500,00`, não `123`.
  Um exemplo que não parece com o dado verdadeiro aumenta a chance de recusa no WhatsApp.
</Tip>

## Regras de nome

O Pombo normaliza o nome que você digita: tudo em minúsculas, sem acentos, com `_` no lugar de
espaços e caracteres especiais. `Valor Total` vira `valor_total`.

| Regra            | Detalhe                                                           |
| ---------------- | ----------------------------------------------------------------- |
| Tamanho          | até 50 caracteres                                                 |
| Repetição        | dois campos não podem ter o mesmo nome                            |
| Nomes reservados | `remetente`, `documento` e `contato` são do rodapé, escolha outro |

## Onde as variáveis não podem ficar

Estas três regras derrubam a maioria das tentativas, então vale decorar:

<Warning>
  1. **A mensagem não pode começar com uma variável.** Comece com texto fixo.
  2. **Duas variáveis não podem ficar lado a lado.** Ponha texto entre elas.
  3. No WhatsApp, é preciso **texto fixo antes e depois** dos campos.
</Warning>

Na prática, escreva a frase inteira em português e só depois substitua as partes que mudam. O
resultado naturalmente respeita as três.

Não há número máximo de variáveis. O que limita é o tamanho da mensagem (cada uma ocupa espaço
com o valor real), e o editor mostra a contagem de caracteres enquanto você escreve.

## HTML dentro de uma variável (e-mail)

O valor de uma variável de e-mail pode conter formatação. Se contiver, o editor mostra
**Como vai aparecer:** com o resultado já renderizado.

Dentro de um bloco de HTML, só a forma com chaves duplas é reconhecida: escreva
`{{nome_do_campo}}`. As outras formas viram texto literal.

A lista de marcações permitidas está em [Criar um modelo](/modelos/criar-modelo).

## No envio em lote, cada variável é uma coluna

Um modelo com `nome`, `valor` e `data_vencimento` exige três colunas na planilha, além dos campos
do destinatário. Não monte esse arquivo à mão.

<CardGroup cols={2}>
  <Card title="Preparar a planilha" icon="table" href="/envios/preparar-planilha">
    O botão **Baixe o modelo** já gera as colunas com os nomes certos.
  </Card>

  <Card title="Criar um modelo" icon="plus" href="/modelos/criar-modelo">
    Onde as variáveis entram na mensagem.
  </Card>
</CardGroup>