Saltar para o conteúdo principal

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

  1. Crie o modelo em uma WABA.
  2. Armazene seu nome, idioma, categoria e o status atual.
  3. Aguarde a aprovação quando a análise for necessária.
  4. Recupere ou liste os modelos para acompanhar as mudanças de status.
  5. Envie apenas modelos válidos para o caso de uso de destino e que estejam em um estado que permita envio.
  6. Edite ou exclua o modelo quando o conteúdo ou o ciclo de vida mudar.
A edição substitui o conteúdo existente do modelo. Inclua todos os componentes que devem permanecer após a alteração. Para modelos 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
Os nomes dos modelos devem ser identificadores de aplicativo estáveis. Use variáveis apenas nas posições aceitas pelo componente selecionado.

Resposta

A resposta confirma a criação do modelo e seu estado atual. 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 a wabaId 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_v1
  • orders_pickup_ready_v2
  • growth_summer_offer_v3
Incremente a versão principal (major) quando uma alteração afetar as posições das variáveis, os tipos de componentes, os botões, a categoria ou o sentido da mensagem. Mantenha os nomes independentes de datas e nomes de equipes.

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 de name 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 de whatsapp.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:
  1. Verifique a assinatura de cada evento whatsapp.template.reviewed.
  2. Desduplique entregas pelo id do evento.
  3. Resolva o recurso por wabaId, name e language.
  4. Armazene tanto o evento de atualização quanto o status atual.
  5. Interrompa o roteamento imediatamente quando o status atual não for APPROVED.
  6. Consulte o modelo quando um evento estiver ausente, atrasado ou em conflito com um estado de registro mais recente.
  7. Execute uma reconciliação agendada e paginada da listagem para detectar discrepâncias.
Não use Webhooks como seu único inventário e não faça polling antes de cada mensagem.

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:
  1. Crie um novo nome com controle de versão para cada localidade necessária. Mantenha inalterada a versão aprovada atual.
  2. Aguarde até que cada localidade de destino esteja APPROVED e, em seguida, valide suas variáveis, mídias, botões, categoria e conteúdo renderizado.
  3. Direcione uma parcela controlada dos envios elegíveis para a nova versão e monitore entregas, qualidade, respostas e atualizações de status.
  4. Migre o tráfego restante apenas após a nova versão atender aos seus critérios de rollout.
Faça a reversão alternando o roteamento para o nome e idioma aprovados anteriormente. Não use uma edição de emergência como reversão. Descontinue a versão anterior apenas depois que filas, campanhas, configurações, testes e janelas de reversão não fizerem mais referência a ela.

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.