O que a estrutura do payload já diz (limite de caractere, tipos aceitos,
quantidade) está declarado no schema de Referência da API:
o playground mostra campo por campo. Esta página é para as regras que o
schema não expressa.
Limites de caractere
O nome aceita minúsculas, números e sublinhado, e não muda depois de criado.
Quebra de linha
Só a mensagem aceita quebra de linha. Cabeçalho, rodapé e texto de botão são de uma linha:\n, \r e tabulação ali são motivo de recusa, e o mesmo
vale para mais de quatro espaços seguidos.
Na mensagem, evite linha em branco no fim e mais de duas quebras seguidas.
Variáveis
É de longe o que mais gera recusa.A variável não pode abrir nem fechar o texto
2388299.
Toda variável precisa de exemplo
Sem oexample, a Meta recusa com missing expected field(s) (example),
código 2388043. O exemplo é o que o revisor lê para entender o template.
No posicional, a numeração é sequência e começa em 1
O exemplo viaja como lista, e a Meta casa cada item pela posição. Com{{1}} e {{3}}, o terceiro fica sem exemplo, e a recusa fala de campo
faltando sem citar numeração.
O cabeçalho aceita uma variável
Uma só. A segunda volta como “The Header field can only have up to 1 variable(s)”, código2388029.
O rodapé não aceita variável
A Meta trata o rodapé como texto puro: a variável ali não é substituída e vai literal para o cliente.Texto curto com muitas variáveis é recusado
A Meta compara a quantidade de variáveis com o tamanho do texto e recusa o que for desproporcional, com o código2388293. Ela não publica a fórmula. Pela
nossa medição, com duas variáveis ou mais, conte três palavras de texto para
cada variável, mais uma.
Botões
As respostas rápidas ficam todas juntas
A Meta não exige que elas venham primeiro: exige que os botões fiquem em dois grupos, o das respostas rápidas e o dos demais. Resposta rápida no meio de outros tipos é recusada.Formato do endereço e do telefone
O endereço precisa dehttp ou https. www.sualoja.com sem protocolo é
recusado, e o erro cita o índice do botão no payload.
O telefone vai em formato internacional, com o código do país:
+5511988881234. Sem o + e sem o país, a recusa é
(#192) ... is not a valid phone number.
Variável em botão
O botão de link aceita uma variável, e só no fim do endereço:Rótulos que a Meta escreve
Em catálogo, multi-produto, produto único, checkout, pedido e no código de autenticação, o texto do botão é da Meta. O campotext continua
obrigatório: o que muda é que o valor não é seu. Mandar outro é recusado com
o código 2388153, e a resposta diz qual era o certo.
O app do WhatsApp traduz o rótulo para o idioma de quem recebe, então o valor
que você manda na criação não é o que o cliente lê.
Carrossel
- De 2 a 10 cartões no de mídia. No de produto, exatamente 2 na criação, e até 10 no envio.
- Todos os cartões com os mesmos componentes. Em consequência: se um cartão tem texto, todos precisam ter; o conjunto de botões (tipo e ordem) é igual em todos. O que muda de um cartão para o outro é o texto do botão e o destino.
- No de mídia, todo cartão precisa de mídia.
- O cartão de produto tem cabeçalho
{"format": "PRODUCT"}e um único botão, sem texto de cartão. Mandar dois botões ou um corpo volta comocomponent of type BODY is required, código2388045, que não descreve a causa.
Mídia
No cabeçalho e nos cartões, a referência da mídia é o identificador obtido
em Enviar mídia, ou o link público do arquivo,
que convertemos para identificador antes de criar o template.
O link precisa abrir para um servidor, e não só no navegador. Loja e blog
costumam bloquear download automático, e aí a Meta responde
media download failed, código 380.
A imagem de cabeçalho é exibida em 1.91:1, deitada. O que sair dessa
proporção não é recusado: o WhatsApp corta as sobras para caber, e o corte é
pelo centro. Vale montar a arte já nessa medida, ou aceitar que as bordas
somem no aparelho do cliente.
Validade do envio
message_send_ttl_seconds tem faixa por categoria:
O valor
-1 é atalho de 30 dias. Em autenticação, a validade do envio não pode
ser menor que a do código: se a mensagem para de ser entregue antes, o cliente
perde as duas coisas.
Quantos templates cabem na conta
Os limites abaixo são da conta, e não do template que você está criando. Por isso a recusa deles confunde: ela não fala de nada que esteja no seu payload.
O nome é único por WABA e idioma: o mesmo nome em
pt_BR e em en_US são
dois templates, e são aceitos. Repetir nome e idioma na mesma conta volta como
already exists — inclusive quando o outro foi excluído há menos de 30 dias,
porque excluir reserva o nome por esse período.
Passar de 100 criações por hora não é erro de payload: é fila. Se você está
migrando um catálogo de templates de uma vez, crie em lotes e espere entre
eles, em vez de tentar de novo na hora.
Editar e excluir
- Template aprovado aceita até 10 edições em 30 dias, e uma a cada 24 horas. Recusado e pausado não têm esse teto.
- Só aprovado, recusado e pausado podem ser editados.
- Nome e idioma não mudam. Categoria de template aprovado também não.
- A edição substitui todos os componentes: mande o conjunto completo, porque o que ficar de fora é apagado.
- Depois de editar, o template volta para a fila de revisão sozinho.
- Excluir um template aprovado reserva o nome dele por 30 dias.
Erros da Meta, e o que cada um quer dizer
Quando a recusa vem da Meta, devolvemos a mensagem original dela junto do
traceId. Guarde os dois: é com eles que o suporte identifica o caso.