Variáveis, campos personalizados e CRUD

Escreva {{chave}} no texto, na hora do envio a Notifique preenche com padrões do template, dados do contato e variables da requisição (nessa ordem de prioridade, com variables por cima).

Em poucas palavras

Escreva {{chave}} no texto. Na hora do envio a Notifique preenche com padrões, contato e variables da requisição.
Chaves do cadastro: use name, email, phone. Prefira inglês nas chaves embutidas.
Gestão e envio usam escopos diferentes. Veja Escopos da API Key.

Canais no template

Cada template escolhe quais canais estão ativos (de 1 a 7): sms, whatsapp, telegram, email, rcs, push, voice. Na API, use no root um bloco por canal:

"sms": { "enabled": true, "payload": { "content": "..." } },
"rcs": { "enabled": false, "payload": {} }

No envio, channels deve ser subconjunto de enabledChannels. Canal pedido mas desligado gera 400 (TEMPLATE_CHANNEL_NOT_ENABLED).

Payloads por canal (criação / edição)

Canal	Campos principais em `payload`
`sms`	`content` (texto final 9 a 160 após variáveis)
`whatsapp`	`content`, opcional `mediaUrl`, `buttons` (`label` + `url` HTTPS)
`telegram`	`content`, opcional `mediaUrl`, `buttons`
`email`	`subject`, `html` e/ou `text`, opcional `buttons`
`rcs`	`messageType` (`BASIC` \| `CARD` \| `CAROUSEL` \| `FILE`), `message`, e conforme o tipo: `cardImage`, `cardTitle`, `cardMessage`, `buttons`, `cards`, `file`, `fileName`
`push`	`title`, `body`, opcional `url`, `icon`, `image`, `data` (mapa de strings)
`voice`	`speakText`, opcional `speakVoice`, opcional `gather` (`prompt`, `maxDigits`, `timeoutSecs`, `voice`)

Variáveis {{…}} também entram em strings aninhadas do RCS, título/corpo do push e speakText da voz.

Variáveis no texto (`{{…}}`)

Duas fontes se misturam no envio:

Do template com placeholders que você digitou. Precisam de valor em variables ou em variableDefaults.
Do contato preenchidos automaticamente quando o destinatário existe no workspace (exceto destinatário só Telegram).

Ordem de prioridade: padrões do template → dados do contato → campos personalizados → variables da requisição (por cima de tudo).

Chaves fixas do contato

Chave no template	Significado
`name`	Nome do contato
`email`	E-mail
`phone`	Telefone (E.164)
`telefone`	Mesmo que `phone`
`url`	URL do contato (quando cadastrada)
`preferences_link`	Link de preferências / descadastro (marketing)

Prefira {{name}}. Em alguns fluxos internos nome pode ser preenchido junto com name, mas o contrato estável da API e do editor é name. Envie variables.nome só se o texto usar essa chave de propósito.

Destinatários só Telegram (chat_id ou @username): merge automático de nome/e-mail não roda. Preencha via variables ou padrões.

Formatos aceitos

Nomeadas: {{pedido}} → variables: { "pedido": "123" }
Posicionais: {{1}}, {{2}} → chaves "1", "2"
Campos personalizados: mesma chave técnica do CRM, ex. {{plano_atual}}

Campos personalizados

Cada campo tem uma chave técnica (snake_case, ex.: plano_atual). No template: {{plano_atual}} com a mesma chave. Defina no painel (Contatos → Campos personalizados) ou pela API de contatos. Depois do merge, o valor também entra em RCS, Push e Voz.

Valores padrão (`variableDefaults`)

Se o envio não mandar uma chave, o padrão do template entra antes de falhar por variável faltando. Contato e variables da requisição ainda podem sobrescrever.

Marketing e preferências

Em templates com categoria MARKETING:

marketingTopicId: liga o envio a um tópico de comunicação
appendPreferencesLink (padrão true): a plataforma preenche {{preferences_link}} por destinatário

Fora de marketing, preferences_link pode ficar vazio: não dependa dele como único CTA.

Traduções (`localeTranslations`)

Você pode guardar traduções por locale dos campos dos canais habilitados. No envio, a API escolhe o texto com base na preferência de idioma do contato (quando disponível). Os placeholders {{…}} da tradução devem bater com o template principal.

Gestão na API

Operação	Escopo
Listar templates	`templates:read`
Buscar template	`templates:read`
Criar template	`templates:create`
Atualizar template	`templates:update`
Excluir template	`templates:delete`

Listagem: query page, limit, search (nome). Exemplo mínimo só com SMS:

{
  "name": "lembrete",
  "sms": {
    "enabled": true,
    "payload": { "content": "Olá {{name}}, lembrete do seu agendamento." }
  },
  "whatsapp": { "enabled": false, "payload": {} },
  "telegram": { "enabled": false, "payload": {} },
  "email": { "enabled": false, "payload": {} },
  "rcs": { "enabled": false, "payload": {} },
  "push": { "enabled": false, "payload": {} },
  "voice": { "enabled": false, "payload": {} },
  "variableDefaults": { "name": "Cliente" }
}

Escopos templates:* são para gestão. No envio, cada canal exige o escopo de envio correspondente (incluindo voice:call para voz).

Templates oficiais Meta (`WHATSAPP_OFFICIAL`)

POST /v1/templates e PATCH /v1/templates/:id usam as mesmas validações do painel:

mídia obrigatória em header/carrossel (META_TEMPLATE_MEDIA_REQUIRED)
cards do carrossel com a mesma estrutura (META_TEMPLATE_CAROUSEL_INCONSISTENT)
estrutura rica só em oficial (TEMPLATE_META_STRUCTURE_REQUIRES_OFFICIAL)

No envio (POST /v1/templates/send ou type: "template" nas rotas de cada canal) com sk_live_, a API também valida token Meta, metaName, mídia e carrossel antes de enfileirar quando o canal for WhatsApp oficial. Com sk_test_, esses gates Meta não rodam (ver Sandbox). Cada rota de canal (POST /v1/sms/messages, /v1/email/messages, /v1/whatsapp/messages, etc.) aceita type: "template" + payload.templateId e dispara apenas aquele canal, útil quando você já está no contrato nativo do canal. O name interno pode diferir do metaName (nome Graph). Sem metaName resolvível → META_TEMPLATE_NOT_FOUND. Códigos completos: Respostas de erro (accordion Meta Cloud / templates oficiais) e Templates oficiais Meta. Schemas completos: referência da API na aba Templates.

​Em poucas palavras

​Canais no template

​Payloads por canal (criação / edição)

​Variáveis no texto ({{…}})

​Chaves fixas do contato

​Formatos aceitos

​Campos personalizados

​Valores padrão (variableDefaults)

​Marketing e preferências

​Traduções (localeTranslations)

​Gestão na API

​Templates oficiais Meta (WHATSAPP_OFFICIAL)

​Ver também

Em poucas palavras

Canais no template

Payloads por canal (criação / edição)

Variáveis no texto (`{{…}}`)

Chaves fixas do contato

Formatos aceitos

Campos personalizados

Valores padrão (`variableDefaults`)

Marketing e preferências

Traduções (`localeTranslations`)

Gestão na API

Templates oficiais Meta (`WHATSAPP_OFFICIAL`)

Ver também