Criar e aprovar um template

Template aprovado pela Meta é um contrato: a Meta aprova uma vez e você envia quantas vezes precisar, sem revisão por mensagem. Em troca, o uso precisa ficar dentro da categoria e do conteúdo aprovados. Se você ainda não sabe o que é um template, comece por O que é um template. Esta página reúne as regras de criação, o que costuma reprovar e como manter o template aprovado.

Antes de começar

Uma chave de API com permissão TEMPLATES_WRITE.
Conta ativa. Com a conta ainda em ativação, criar e listar templates responde 403 ACCOUNT_NOT_ACTIVATED.

Onde criar

Canal	Como
Dashboard	app.ararahq.com, seção Templates.
API	`POST /v1/templates`, como no exemplo abaixo.
Biblioteca da Meta	`POST /v1/templates/library`: templates UTILITY da Meta que já nascem aprovados. Disponível para contas com número conectado ativo.
MCP	Ferramenta `create_template` do MCP.
Gerenciador da Meta	Template criado direto na Meta entra na Arara com `POST /v1/templates/sync`.

Criar um template pela API

curl -X POST https://api.ararahq.com/v1/templates \
  -H "Authorization: Bearer ara_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedido_confirmado",
    "category": "UTILITY",
    "language": "pt_BR",
    "body": "Oi {{1}}, seu pedido {{2}} foi confirmado. Total: R$ {{3}}.",
    "footer": "Acompanhe pelo nosso site",
    "samples": { "1": "João", "2": "12345", "3": "147,90" }
  }'

A resposta é 201 Created, com o template e o status atual no provedor (providerStatus). Todos os campos, respostas e erros estão em API: Templates.

Campo	Descrição
`name`	Identificador em `snake_case`, único por conta WhatsApp Business (WABA). É o nome que você usa no envio (`templateName`).
`category`	`MARKETING`, `UTILITY` ou `AUTHENTICATION`.
`language`	Padrão `pt_BR`.
`body`	Texto com variáveis `{{n}}`. Obrigatório.
`header` / `headerType`	Texto ou URL de mídia; `headerType`: `text`, `media` ou `document`.
`footer`	Rodapé opcional.
`buttons`	Lista de botões.
`samples`	Um exemplo por variável: `{ "1": "João" }`.
`carouselCards`	Cards do carrossel (`mediaUrl`, `body`, `buttons`).

Para criar a partir da biblioteca da Meta:

# Listar templates da biblioteca
curl "https://api.ararahq.com/v1/templates/library?languageCode=pt_BR" \
  -H "Authorization: Bearer ara_live_xxx"

# Criar a partir de um template da biblioteca
curl -X POST https://api.ararahq.com/v1/templates/library \
  -H "Authorization: Bearer ara_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "confirmacao_pedido", "libraryTemplateName": "<nome_do_template>", "languageCode": "pt_BR" }'

As 3 categorias e quando usar cada

UTILITY

Notificação sobre algo que o cliente espera: pedido confirmado, entrega, lembrete de consulta, status de pagamento.

MARKETING

Promoção, oferta, lançamento, reengajamento, recuperação de carrinho. O cliente precisa ter consentido em receber marketing.

AUTHENTICATION

Só códigos de verificação (OTP/2FA), no formato restrito que a Meta define para essa categoria.

A categoria define o preço por mensagem. Valores em Preços. Na dúvida entre UTILITY e MARKETING, escolha MARKETING.

Marketing enviado como UTILITY não passa despercebido. A Meta pode reclassificar o template depois de aprovado. Quando isso acontece, a Arara atualiza a categoria, cria um alerta no dashboard, envia o evento template.category_changed (name, old, new) e os envios seguintes são cobrados na categoria nova.

Variáveis

Cada {{n}} é uma variável posicional, preenchida no envio pelo array templateVariables, na ordem das variáveis:

{
  "receiver": "+5511999999999",
  "templateName": "pedido_confirmado",
  "templateVariables": ["João", "ARA-123", "147,90"]
}

Regras validadas na criação:

O corpo não pode começar nem terminar com variável. Coloque texto antes do primeiro {{ e depois do último }}.
Cada variável precisa de um exemplo em samples, que o revisor da Meta vê.
A variável que preenche a URL de um botão não pode ter exemplo com espaço.

Boas práticas:

Evite variáveis coladas: {{1}} {{2}} em sequência tende a ser reprovado.
Use variável só para o que muda (nome, valor, data) e mantenha texto fixo suficiente para o template fazer sentido sozinho.
Mande exemplos realistas.

Exemplo ruim: {{1}} {{2}} {{3}} Exemplo bom: Olá {{1}}, seu pedido {{2}} foi confirmado. Previsão de entrega: {{3}}. No envio, a quantidade de valores precisa bater com a do template. Se não bater, a API responde 422 TEMPLATE_VARIABLES_MISMATCH.

Header de mídia

O template pode ter imagem, vídeo ou documento como header (headerType + header com a URL). Formatos e tamanhos aceitos são definidos pela Meta; confira a documentação da Meta antes de subir mídia pesada. No envio, a URL pública da mídia vai como primeiro elemento do array templateVariables, antes das variáveis do corpo:

"templateVariables": [
  "https://meusite.com/imagem.jpg",
  "João",
  "ARA-123"
]

O campo mediaUrl no envio está descontinuado. Use a primeira posição de templateVariables. Ver Mensagens.

Botões

Tipo	Descrição
`QUICK_REPLY`	Resposta rápida. O clique chega como mensagem recebida no webhook.
`URL`	Abre uma URL. Aceita variável (`https://meusite.com/pedido/{{1}}`), sem espaço no valor.
`PHONE_NUMBER`	Liga para um número fixo.
`SMART_LINK`	Link curto da Arara com rastreamento de clique. Conta no limite de botões de link. Ver Smart Links.
`COPY_CODE`	Copia um código. Usado em AUTHENTICATION.

Limites aplicados na criação: até 10 botões no total, até 2 de link (URL ou SMART_LINK), até 1 PHONE_NUMBER e texto de botão com até 20 caracteres.

Carrossel

De 2 a 10 cards, cada um com mídia e texto e até 2 botões, com os mesmos tipos de botão em todos os cards.

O que a Arara valida antes de submeter

Em POST /v1/templates, a API recusa a criação quando:

Regra	Detalhe
Nome já existe na mesma conta WhatsApp Business (WABA)	Template com o mesmo nome em `FAILED` ou `REJECTED` é substituído; nos outros estados, a criação é recusada
Corpo vazio	`body` é obrigatório
Categoria inválida	Use `MARKETING`, `UTILITY` ou `AUTHENTICATION`
Corpo começa ou termina com variável	Coloque texto antes do primeiro `{{` e depois do último `}}`
Variável sem exemplo	Cada `{{n}}` precisa de exemplo em `samples`
Header de texto com caracteres especiais	Header de texto aceita letras, números e pontuação. Para mídia, use uma URL
Botões demais ou texto de botão longo	Ver limites em Botões
Exemplo com espaço em variável de URL	A variável que preenche a URL de um botão não pode ter espaço
Carrossel fora do formato	Ver Carrossel

Além disso, a Arara faz uma moderação de conteúdo em templates MARKETING e UTILITY e recusa textos com discurso de ódio, ameaça, conteúdo sexual explícito e frases típicas de golpe (como “lucro garantido” ou “você foi sorteado”).

A Arara não bloqueia por caixa alta, emoji ou link encurtado. Essas regras são da política de conteúdo da Meta: quem decide é a Meta, e a Arara reflete a decisão no status do template.

O que costuma reprovar

Evite	Por quê
Texto todo em maiúsculas, “URGENTE”, “ÚLTIMA CHANCE”	Aparência de spam, aumenta bloqueio
Promessa de retorno garantido	Política de conteúdo da Meta
Pedido de senha, dados de cartão ou documentos	Phishing
Cobrança ameaçadora	Conduta abusiva, gera denúncia
Termos de saúde sensíveis (“cura”, “milagre”)	Política comercial da Meta
Muitas variáveis e pouco texto fixo	Dificulta a revisão da Meta
Categoria que não corresponde ao conteúdo	A Meta reprova ou reclassifica

Template de autenticação (código de verificação)

A categoria AUTHENTICATION é a mais restrita do WhatsApp. A Arara monta o template no formato fixo que a Meta exige: corpo padrão com o código e botão Copiar código. Não dá para escrever um corpo próprio nessa categoria.

Quem pode criar

A Meta só libera a criação de templates de autenticação quando a conta cumpre os três requisitos:

Requisito	Onde conferir
Empresa verificada na Meta	business.facebook.com → Configurações → Informações da empresa
Limite de mensagens do número em 2.000 ou mais conversas iniciadas pela empresa em 24 horas	WhatsApp Manager → Limites de mensagens
Conta sem restrição ou banimento	WhatsApp Manager → Visão geral

Número novo ou que ainda está no limite de 250 não consegue criar template de autenticação, mesmo com a empresa verificada. Templates UTILITY e MARKETING continuam funcionando normalmente.

Erro “does not have permission to create message template”

Quando algum requisito não é cumprido, o template de autenticação volta com status FAILED e o motivo:

This WhatsApp business account does not have permission to create message template

Não é problema de redação, de plano da Arara nem de coexistência com o app do WhatsApp Business. Reescrever o texto não muda o resultado. O caminho é:

Verificar a empresa na Meta, se ainda não estiver verificada.
Enviar conversas de boa qualidade com templates UTILITY ou MARKETING até o número chegar ao limite de 2.000. A Meta sobe o limite sozinha conforme o uso.
Criar o template de autenticação de novo. A Meta libera a categoria automaticamente quando os requisitos são cumpridos.

Código de verificação em outra categoria

A Meta não aceita código de verificação em template UTILITY ou MARKETING. Esses templates são recusados, em geral com o motivo vazio (rejectionReason: null).

Enviar código enquanto a categoria não é liberada

Use a janela de atendimento: quando o usuário manda uma mensagem para o seu número (por exemplo, por um link “receber meu código”), abre uma janela de 24 horas em que você pode enviar o código como mensagem de texto comum, sem template.

Aprovação e status

Quem aprova é a Meta. Templates da biblioteca já nascem aprovados; os demais levam de minutos a algumas horas, e às vezes mais. Não submeta template crítico na véspera de uma campanha. Acompanhe o status de duas formas:

Webhook template.updated, com status e rejectionReason.
GET /v1/templates/{id}/status, usando o id (UUID) do template.

Status	Pode enviar?	Resposta da API no envio
`APPROVED`	Sim
`PENDING`	Não	`422 TEMPLATE_NOT_SENDABLE`
`REJECTED`	Não	`422 TEMPLATE_NOT_SENDABLE`
`DISABLED`	Não	`422 TEMPLATE_NOT_SENDABLE`
`PAUSED`	Não	`422 TEMPLATE_PAUSED`

Enviar com um nome que não existe na organização é recusado com 409 CONFLICT.

Templates pausados

Mesmo aprovado, um template pode ser pausado pela Meta por baixa qualidade, geralmente por bloqueios e denúncias dos destinatários. Quando um envio falha por template pausado, a Arara marca o template como PAUSED e envia template.updated. A Meta também informa mudanças de qualidade do template, que chegam como template.quality_updated (name, quality). Use o código TEMPLATE_PAUSED para interromper uma campanha. Para voltar a enviar, revise o conteúdo e a base para quem o template foi enviado, e edite o texto ou crie um template novo. Reenviar o mesmo conteúdo tende a ser pausado de novo. Para listar os pausados:

curl "https://api.ararahq.com/v1/templates?status=PAUSED" \
  -H "Authorization: Bearer ara_live_xxx"

Idiomas

Cada template é criado em um idioma (campo language, padrão pt_BR). O envio escolhe o template pelo nome, sem parâmetro de idioma. Para falar com o mesmo cliente em mais de um idioma, crie um template por idioma, com nomes diferentes: pedido_confirmado (pt_BR) e pedido_confirmado_en (en_US).

Manutenção e limites

Listar: GET /v1/templates (paginado, filtros name e status).
Desempenho: GET /v1/templates/{id}/analytics.
Remover: DELETE /v1/templates/{id}.
Nomes: prefira nomes descritivos (confirmacao_pedido, lembrete_pagamento) a template1 ou teste.
Quantidade: os planos atuais não limitam a quantidade de templates. Contas no plano Free legado têm teto de 3 templates aprovados (pendentes e reprovados não contam) e, no teto, a criação responde 403 PLAN_LIMIT_REACHED.

Próximos passos

API: Templates

Endpoints completos de CRUD.

Webhooks

Receba mudanças de status em tempo real.

Marketing no WhatsApp

Como usar templates em campanha.

Início

Conceitos

Antes de começar

Onde criar

Criar um template pela API

As 3 categorias e quando usar cada

UTILITY

MARKETING

AUTHENTICATION

Variáveis

Header de mídia

Botões

Carrossel

O que a Arara valida antes de submeter

O que costuma reprovar

Template de autenticação (código de verificação)

Quem pode criar

Erro “does not have permission to create message template”

Código de verificação em outra categoria

Enviar código enquanto a categoria não é liberada

Aprovação e status

Templates pausados

Idiomas

Manutenção e limites

Próximos passos

API: Templates

Webhooks

Marketing no WhatsApp

​Antes de começar

​Onde criar

​Criar um template pela API

​As 3 categorias e quando usar cada

UTILITY

MARKETING

AUTHENTICATION

​Variáveis

​Header de mídia

​Botões

​Carrossel

​O que a Arara valida antes de submeter

​O que costuma reprovar

​Template de autenticação (código de verificação)

​Quem pode criar

​Erro “does not have permission to create message template”

​Código de verificação em outra categoria

​Enviar código enquanto a categoria não é liberada

​Aprovação e status

​Templates pausados

​Idiomas

​Manutenção e limites

​Próximos passos

API: Templates

Webhooks

Marketing no WhatsApp

Antes de começar

Onde criar

Criar um template pela API

As 3 categorias e quando usar cada

Variáveis

Header de mídia

Botões

Carrossel

O que a Arara valida antes de submeter

O que costuma reprovar

Template de autenticação (código de verificação)

Quem pode criar

Erro “does not have permission to create message template”

Código de verificação em outra categoria

Enviar código enquanto a categoria não é liberada

Aprovação e status

Templates pausados

Idiomas

Manutenção e limites

Próximos passos