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

# Variáveis, campos personalizados e CRUD

> Placeholders {{…}}, merge com contato, valores padrão, payloads por canal e gestão de templates pela API.

<Tip>
  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).
</Tip>

## 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](/template-api/como-funciona/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:

```json theme={null}
"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:

1. **Do template** com placeholders que você digitou. Precisam de valor em `variables` ou em **`variableDefaults`**.
2. **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) |

<Note>
  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.
</Note>

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

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

```json theme={null}
{
  "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" }
}
```

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

## 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](/guides/sandbox/index)).

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](/guides/conceitos/resposta-de-erros) (accordion **Meta Cloud / templates oficiais**) e [Templates oficiais Meta](/template-api/como-funciona/templates-oficiais-meta).

Schemas completos: **referência da API** na aba Templates.

***

## Ver também

* [Introdução](/template-api/como-funciona/introducao)
* [Quick Start](/template-api/como-funciona/quick-start)
* [Respostas de erro](/guides/conceitos/resposta-de-erros)
* [Templates oficiais Meta](/template-api/como-funciona/templates-oficiais-meta)