Variáveis que você escreve no texto ({{…}})
No SMS, WhatsApp e e-mail você usa placeholders no formato {{chave}}. Duas origens se misturam no envio:
- Variáveis “do template” — o que você digitou no conteúdo e que precisa de valor na API (
variablesnoPOST /v1/templates/send) ou valor padrão configurado no editor do template (variableDefaults). - Dados do contato — preenchidos automaticamente quando o destinatário existe como contato no workspace (ou parcialmente quando a API enriquece telefone/e-mail).
{{nome}} mas o sistema só injeta name (inglês), nada será substituído para nome a menos que você envie variables.nome ou defina um padrão para nome. Por isso use as chaves abaixo quando quiser dados do cadastro.
Chaves fixas do contato (use exatamente estes nomes)
Quando há contato resolvido para o destinatário, o backend preenche (se existir valor):| Chave no template | Significado |
|---|---|
name | Nome do contato |
email | |
phone | Telefone (E.164) |
telefone | Mesmo valor que phone (alias) |
preferences_link | URL de preferências / descadastro (relevante em campanhas de marketing com template configurado) |
nome em português: o campo do cadastro é exposto como name. Se preferir {{nome}} no texto, trate nome como variável livre e envie em variables ou cadastre valor padrão no template.
Ordem de prioridade no merge (resumo): padrões do template → dados do contato (e aliases acima) → propriedades personalizadas → objeto variables da requisição (API ou campanha) por cima.
Campos personalizados dos contatos
Sim: servem como variáveis. Cada definição tem uma chave técnica (key), em minúsculas, formato snake_case (ex.: cpf_cliente, plano). No template use {{cpf_cliente}} exatamente com essa chave.
Os valores vêm do armazenamento do contato; tipos número/boolean/data viram texto na hora da substituição. Defina e gerencie as chaves no painel em Contatos (definições de propriedades) ou pela API de contatos do app; na API pública de contatos v1 você trabalha com o contato como um todo conforme a documentação de Contatos.
Valores padrão no template (variableDefaults)
No painel (e no PATCH/POST da API de gestão) você pode enviar variableDefaults: se a requisição de envio não mandar aquela chave, o padrão do template entra antes de considerar “falta variável”. Contato + variables continuam podendo sobrescrever.
CRUD de templates na API v1
Além do envio (POST /v1/templates/send), a v1 expõe gestão no mesmo prefixo /v1/templates:
| Método | Caminho | Escopo |
|---|---|---|
GET | /v1/templates | templates:read |
GET | /v1/templates/{id} | templates:read |
POST | /v1/templates | templates:create |
PATCH | /v1/templates/{id} | templates:update |
DELETE | /v1/templates/{id} | templates:delete |
- Listagem: query
page,limit,search(busca por nome). - Corpo de criação/edição: use
channelscomsms,whatsappeemail(cada um com os campos do canal: texto, mídia, botões, HTML, etc.). É o mesmo conjunto de regras do painel (SMS mín. 9 caracteres, limites de WhatsApp/HTML, URLs HTTPS,variables+variableDefaults,marketingTopicIdpara MARKETING, …). No PATCH, envie só os canais ou campos que mudarem dentro dechannels. Integrações muito antigas com corpo plano no root ainda são aceitas pelo servidor, mas não devem ser usadas em projetos novos. - Envio (
POST /v1/templates/send) continua exigindo escopos de canal:whatsapp:send,sms:send,email:send— não os escopostemplates:*de CRUD.
openapi-templates.json) na pasta API Reference de Templates.
Ver também
- Introdução — visão geral e envio multicanal.
- Quick Start — exemplo de
POST /v1/templates/send.