O que é
Os modelos do WhatsApp são estruturas de mensagens pré-aprovadas usadas para iniciar ou continuar conversas fora da janela de atendimento ao cliente. Um modelo é identificado por WABA, nome e idioma. Use este guia para gerenciar o ciclo de vida da API e manter os recursos de modelo estáveis em produção entre equipes, versões e localidades.Antes de começar
- Conecte a WABA que será a proprietária do modelo.
- Escolha a categoria do modelo, idioma compatível, nome e componentes.
- Prepare exemplos representativos de variáveis e mídias necessários para a análise.
- Siga as políticas da Meta para conteúdo de autenticação, utilidade e marketing.
- Configure um endpoint de webhook capaz de receber eventos de
whatsapp.template.reviewed.
Como funciona
- Crie o modelo em uma WABA.
- Armazene seu nome, idioma, categoria e o
statusatual. - Aguarde a aprovação quando a análise for necessária.
- Recupere ou liste os modelos para acompanhar as mudanças de status.
- Envie apenas modelos válidos para o caso de uso de destino e que estejam em um estado que permita envio.
- Edite ou exclua o modelo quando o conteúdo ou o ciclo de vida mudar.
MARKETING, você pode adicionar ou atualizar o Preço Máximo por meio de bidSpec. Ao editar, omita bidSpec ou envie null para preservar o preço, ou envie {} para limpá-lo. Consulte o guia de integração do Preço Máximo para saber mais sobre valores, multiplicadores por país e exemplos completos de edição.
Requisição
POST /whatsapp/templates
Resposta
PENDING não significa que o modelo já pode ser enviado.
Definir uma identidade de recurso estável
Trate cada combinação de WABA, nome do modelo e idioma como um recurso único. Mantenha um registro de recursos com awabaId proprietária, nome estável, código de localidade exato, finalidade, responsável, contrato de variáveis, status atual na API, estado de lançamento e versão de substituição.
Use um nome previsível, como <domain>_<purpose>_v<major>:
auth_login_otp_v1orders_pickup_ready_v2growth_summer_offer_v3
Escolha a categoria antes de redigir o conteúdo
Escolha a categoria com base no motivo pelo qual o cliente receberá a mensagem.
Se um modelo combinar informações transacionais com uma promoção, projete-o como marketing ou divida as finalidades em modelos separados.
Congele o contrato de variáveis
Defina as variáveis como um contrato de API antes que redatores ou tradutores comecem a trabalhar. Para cada variável, registre sua posição, significado semântico, formato, origem, exemplo representativo e comportamento de fallback. Por exemplo,Order {{0}} is ready at {{1}}. pode usar este contrato:
Mantenha o significado de cada posição estável entre versões e localidades. Crie uma nova versão caso precise reordenar ou redefinir a finalidade das variáveis.
Antes de enviar para análise:
- Forneça uma amostra segura e representativa para cada variável de corpo ou cabeçalho de texto.
- Valide URLs, formatos e tamanhos de arquivo dos cabeçalhos de mídia.
- Mantenha no máximo uma variável em um cabeçalho de texto e inclua sua amostra.
- Confirme se as variáveis de botão de URL aparecem apenas onde a API permite e inclua uma URL de exemplo completa.
- Nunca utilize credenciais, códigos de uso único, dados pessoais ou mídias privadas em exemplos de análise.
Organize localidades em uma única versão
Reutilize o mesmo nome versionado para todas as localidades em uma versão, mas gerencie cada par dename e language como um recurso separado. Mantenha os significados das variáveis e as ações dos botões consistentes, mesmo se a ordem das palavras mudar.
Aprove e lance cada localidade de forma independente. Nunca encaminhe um usuário para outro idioma apenas porque essa localidade está aprovada. Use o código exato da localidade (diferenciando maiúsculas e minúsculas) em solicitações de criação, recuperação, edição, exclusão e envio.
Condicione os envios ao status do modelo
Use consultas ou webhooks dewhatsapp.template.reviewed para processar aprovação, rejeição, pausa, desativação, arquivamento e outras alterações do ciclo de vida. Mantenha exatamente o mesmo nome e idioma usados nas solicitações de mensagem.
Armazene o status da API separadamente do seu estado de rollout. Encaminhe envios de produção apenas para um modelo cujo status atual seja APPROVED e cujo estado de rollout esteja ativo.
Uma resposta de criação ou edição bem-sucedida não autoriza envios de produção.
Sincronizar estado
Use Webhooks para atualizações rápidas e APIs de consulta ou listagem para reconciliação:- Verifique a assinatura de cada evento
whatsapp.template.reviewed. - Desduplique entregas pelo
iddo evento. - Resolva o recurso por
wabaId,nameelanguage. - Armazene tanto o evento de atualização quanto o
statusatual. - Interrompa o roteamento imediatamente quando o status atual não for
APPROVED. - Consulte o modelo quando um evento estiver ausente, atrasado ou em conflito com um estado de registro mais recente.
- Execute uma reconciliação agendada e paginada da listagem para detectar discrepâncias.
Comportamento de edição e exclusão
- Edite apenas modelos em um estado compatível com o endpoint.
- Inclua o conjunto completo de componentes desejados em uma solicitação de edição.
- Excluir por nome remove todos os idiomas associados a esse nome.
- Excluir por nome e idioma remove apenas o modelo localizado correspondente.
- Modelos arquivados ainda podem aparecer nos resultados de listagem e consulta.
Lançar, reverter e descontinuar versões
Dê preferência a uma versão paralela para alterações significativas:- Crie um novo nome com controle de versão para cada localidade necessária. Mantenha inalterada a versão aprovada atual.
- Aguarde até que cada localidade de destino esteja
APPROVEDe, em seguida, valide suas variáveis, mídias, botões, categoria e conteúdo renderizado. - Direcione uma parcela controlada dos envios elegíveis para a nova versão e monitore entregas, qualidade, respostas e atualizações de status.
- Migre o tráfego restante apenas após a nova versão atender aos seus critérios de rollout.
Limites e solução de problemas
- Uma solicitação de envio falha quando o modelo não está aprovado ou quando seus componentes não coincidem com os parâmetros da mensagem.
- Modelos de autenticação utilizam estruturas predefinidas restritas.
- A categoria e o conteúdo do modelo devem estar em conformidade com as políticas da Meta.
- Analise os detalhes da rejeição antes de recriar o mesmo conteúdo.
- Use um novo nome quando um modelo excluído ou significativamente alterado não puder ser restaurado com segurança.
Checklist de ativação
- O nome, finalidade, responsável, categoria e versão estão registrados.
- Cada variável possui um significado, formato, exemplo seguro e regra de fallback definidos.
- Mídias e botões foram aprovados nas verificações de formato, destino e exemplos.
- Cada localidade necessária está independentemente
APPROVED. - O fluxo de envio rejeita qualquer status diferente de
APPROVED. - O processamento de Webhook foi validado, é idempotente e reconciliado com a consulta.
- O processo de rollout pode restaurar uma versão aprovada anteriormente.
- Filas, campanhas, configurações, testes e runbooks utilizam a versão pretendida.
Idiomas suportados
Selecione o código exato de idioma e localidade regional para um modelo.
Exemplos de criação de modelo
Adapte modelos de autenticação, marketing, utilidade, comércio, Flow e chamadas.
API de criação de modelo
Inspecione o esquema completo de componentes.
Webhooks de análise de modelos
Gerencie alterações de estado de análise e ciclo de vida.

