Templates oficiais Meta

Template oficial é uma carta-modelo aprovada pela Meta. No Notifique ele convive com SMS, e-mail e outros canais no mesmo template, sem duplicar por canal.

Em poucas palavras

Na linha oficial, fora da janela de 24h, só entra mensagem com template aprovado pela Meta.
Existem templates internos (ZENVIO) e oficiais (WHATSAPP_OFFICIAL) espelhados na WABA.
Você pode trazer da Meta, vincular a um interno existente ou publicar um interno na Meta e aguardar aprovação.
A Meta avisa mudanças de status; o Notifique propaga via webhooks template.*.

Instância oficial: Quick Start WhatsApp (aba Conexão oficial). Visão geral: Introdução Templates.

Por que isso importa?

Na linha oficial, a Meta divide a conversa em dois momentos:

Situação	O que enviar
Cliente respondeu há menos de 24h	Texto ou mídia livre
Primeiro contato ou conversa parada	Template aprovado

Na linha não oficial, use templates internos ou texto livre. Detalhes: Modos de conexão.

Interno × oficial no Notifique

O template do Notifique é uma pasta com um bloco por canal.

	Interno	Oficial (Meta)
`source`	`ZENVIO` (ou null)	`WHATSAPP_OFFICIAL`
Uso típico	Linha não oficial	Linha oficial
Aprovação	Imediata no Notifique	Meta: `PENDING` → `APPROVED`
Campos Meta	,	`metaId`, `metaName`, `metaWabaId`, `components`

O nome interno (alerta_pedido) pode diferir do metaName na Meta (order_update). No envio oficial, a Meta valida o modelo aprovado no catálogo dela.

Um template, vários canais

Exemplo: você já tem confirmacao_pedido com SMS e e-mail. Na linha oficial, vincula o WhatsApp a um modelo aprovado na Meta.

SMS e e-mail não mudam
O bloco WhatsApp passa a usar a estrutura oficial aprovada
Um único POST /v1/templates/send dispara todos os canais habilitados

Variáveis e CRUD: Variáveis e CRUD.

Sincronização: três caminhos

Requer instância oficial ativa. No painel: instância → Sincronizar templates com a Meta.

A, Trazer da Meta (sincronizar)

Use quando os templates já existem na conta Business.

Clique em Sincronizar templates com a Meta
O painel lista o catálogo da Meta e os templates locais
Para cada modelo da Meta, escolha Vincular a um interno ou Criar novo
Confirme a sincronização

Efeito do vínculo: o template local vira oficial no WhatsApp, guarda metaId, metaName e components, e mantém SMS/e-mail/outros canais.

Se já existir interno com mesmo nome/idioma, o sync não sobrescreve sozinho, escolha o vínculo no diálogo.

B, Ligar um interno a um da Meta

Fluxo mais comum quando você já tem templates no Notifique.

Rode a sincronização (caminho A)
No mapeamento, associe cada modelo Meta ao template interno certo
Salve

O nome interno permanece. O envio WhatsApp oficial usa o conteúdo aprovado na Meta. Sincronizar em qualquer número oficial da mesma WABA atualiza o catálogo do workspace.

C, Publicar um interno na Meta (enviar para aprovação)

Use quando o modelo nasce no Notifique e ainda não existe na Meta.

Crie ou edite o template (estrutura oficial: cabeçalho, corpo, botões…)
Na instância oficial: Enviar para a Meta / Publicar na Meta
A Meta recebe com status PENDING
Quando aprovar → APPROVED, você pode enviar

Template APPROVED: até 1 edição a cada 24h e 10 em 30 dias na Meta. Se o push automático falhar, use Atualizar na Meta… no editor.

Aprovação, status e webhooks

Acompanhe no painel ou automatize com webhooks:

Status	Significado
`PENDING`	Meta analisando
`APPROVED`	Pode enviar na linha oficial
`REJECTED`	Recusado, ajuste e publique de novo
`PAUSED`	Pausado por qualidade
`IN_APPEAL`, `DISABLED`, `DELETED`, …	Ver evento `template.status_changed`

Evento webhook	Quando dispara
`template.submitted`	Template enviado/publicado na Meta
`template.status_changed`	Status local muda (`APPROVED`, `REJECTED`, …)
`template.category_changed`	Categoria muda (ex.: MARKETING ↔ UTILITY)

Guia com payloads: Eventos dos webhooks. Para entrega da mensagem (enviado, entregue, lido, falha), use webhooks do WhatsApp, são eventos message.*, não template.*.

Enviar um template oficial

Pré-requisitos:

Instância oficial ativa e pagamento Meta ok
Template com status APPROVED e source: WHATSAPP_OFFICIAL
metaName preenchido (rode sync/vínculo se vazio)

Multicanal (WhatsApp + SMS no mesmo disparo):

POST /v1/templates/send
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "template": "confirmacao_pedido",
  "channels": ["whatsapp", "sms"],
  "to": ["5511999999999"],
  "variables": { "codigo": "482910", "name": "Maria" },
  "instanceId": "ID_DA_INSTANCIA_OFICIAL"
}

Resposta esperada: 202

{
  "success": true,
  "data": {
    "messageIds": ["clxx789..."],
    "smsIds": ["clxx790..."],
    "status": "QUEUED",
    "count": 2
  }
}

Com sk_test_, gates da Meta não rodam, envio simulado no Sandbox. Aprovação real e cobrança de conversa só em sk_live_.

Qual instância aceita qual template?

Instância	Templates no WhatsApp
Oficial	Oficiais (`WHATSAPP_OFFICIAL`) APPROVED
Não oficial	Internos (`ZENVIO`), texto/imagem simples

Botões, cabeçalho ou carrossel Meta não funcionam na linha não oficial.

Erros comuns

Código	O que significa	O que fazer
`META_TEMPLATE_REQUIRED`	Fora da janela 24h sem template	Envie template aprovado ou espere resposta
`META_TEMPLATE_NOT_FOUND`	Nome/idioma não bate com a Meta	Sync/vínculo; confira `metaName`
`TEMPLATE_NOT_ALLOWED_FOR_INSTANCE`	Template de um modo na instância do outro	Oficial na oficial; interno na não oficial
`META_PAYMENT_METHOD_REQUIRED`	Sem cartão na conta Meta	Cadastre pagamento no WhatsApp Manager
`META_TOKEN_EXPIRED` / `META_TOKEN_INVALID`	Linha oficial desconectada	Reconecte a instância

Catálogo: Respostas de erro (accordion Meta Cloud / templates oficiais).

Próximos passos

Quick Start: criar e disparar multicanal
Eventos dos webhooks: template.*
Modos de conexão: oficial × não oficial
Eventos WhatsApp: entrega message.*

​Em poucas palavras

​Por que isso importa?

​Interno × oficial no Notifique

​Um template, vários canais

​Sincronização: três caminhos

​Aprovação, status e webhooks

​Enviar um template oficial

​Qual instância aceita qual template?

​Erros comuns

​Próximos passos

Em poucas palavras

Por que isso importa?

Interno × oficial no Notifique

Um template, vários canais

Sincronização: três caminhos

Aprovação, status e webhooks

Enviar um template oficial

Qual instância aceita qual template?

Erros comuns

Próximos passos