Gerenciar modelos do WhatsApp

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 modelos de produção estáveis entre equipes, versões e localidades.

Antes de começar

Conecte a WABA proprietária do modelo.
Escolha a categoria do modelo, o idioma compatível, o nome e os componentes.
Prepare exemplos representativos de variáveis e mídias necessários para a análise.
Siga as políticas da Meta para conteúdos 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 status atual.
Aguarde a aprovação quando a análise for necessária.
Recupere ou liste 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 apto para envio.
Edite ou exclua o modelo quando o conteúdo ou o ciclo de vida mudar.

A edição substitui o conteúdo do modelo existente. Inclua todos os componentes que devem permanecer após a edição.

Requisição

POST /whatsapp/templates

curl --request POST https://api.ycloud.com/v2/whatsapp/templates \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wabaId": "WABA_ID",
    "name": "order_ready",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Order {{0}} is ready for pickup.",
        "example": {
          "body_text": [["A-10001"]]
        }
      }
    ]
  }'

Os nomes dos modelos devem ser identificadores de aplicativo estáveis. Use variáveis apenas nas posições aceitas pelo componente selecionado.

Resposta

{
  "wabaId": "WABA_ID",
  "name": "order_ready",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING",
  "components": [
    {
      "type": "BODY",
      "text": "Order {{0}} is ready for pickup."
    }
  ]
}

A resposta confirma a criação do modelo e seu estado atual. PENDING não significa que o modelo já possa ser enviado.

Defina uma identidade de recurso estável

Trate cada combinação de WABA, nome de modelo e idioma como um único recurso. Mantenha um registro de recursos com o wabaId proprietário, nome estável, código de localidade exato, finalidade, responsável, contrato de variáveis, status atual da API, estado de implantação 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 quando uma alteração afetar as posições das variáveis, tipos de componentes, botões, categoria ou o significado da mensagem. Mantenha os nomes independentes de nomes de equipes e datas.

Escolha a categoria antes de escrever o conteúdo

Escolha a categoria com base no motivo pelo qual o cliente receberá a mensagem.

Categoria	Use quando
`AUTHENTICATION`	Você autenticar um usuário com uma senha descartável para verificação, recuperação ou um desafio de integridade.
`UTILITY`	Você atender a uma solicitação específica do usuário ou fornecer uma atualização sobre uma transação acordada.
`MARKETING`	Você enviar uma oferta, promoção, convite ou outro conteúdo que não se qualifique como autenticação ou utilidade.

Se um modelo mesclar informações transacionais com uma promoção, crie-o como marketing ou divida as finalidades em modelos separados.

Defina e congele o contrato de variáveis

Defina as variáveis como um contrato de API antes que redatores ou tradutores comecem. 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:

Posição	Significado	Formato	Exemplo de revisão
`{{0}}`	`order_reference`	String curta visível ao cliente	`A-10001`
`{{1}}`	`pickup_location`	Nome da loja localizado	`Central Store`

Mantenha o significado de cada posição estável entre versões e localidades. Crie uma nova versão se precisar reordenar ou alterar a finalidade das variáveis. Antes do envio para análise:

Forneça um exemplo seguro e representativo para cada variável do corpo ou do cabeçalho de texto.
Valide URLs de cabeçalho de mídia, formatos e tamanhos de arquivo.
Limite o cabeçalho de texto a no máximo uma variável e inclua sua amostra.
Confirme que as variáveis de botão de URL apareçam apenas onde a API permitir e inclua um URL de exemplo completo.
Nunca use credenciais, códigos de uso único, dados pessoais ou mídias privadas em exemplos de análise.

Organize localidades como um único lançamento

Reutilize o mesmo nome versionado para cada localidade em um lançamento, 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 quando a ordem das palavras mudar. Aprove e lance cada localidade de forma independente. Nunca redirecione um usuário para outro idioma apenas porque essa localidade foi aprovada. Use o código exato da localidade (diferenciando maiúsculas de 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 de ciclo de vida. Mantenha o nome e o idioma exatos usados pelas solicitações de mensagens. Armazene o status da API separadamente do seu estado de implantação. Apenas encaminhe envios de produção para um modelo cujo status atual seja APPROVED e cujo estado de implantação esteja ativo.

Status	Ação de produção
`PENDING`	Bloqueie envios enquanto a análise estiver em andamento.
`APPROVED`	Permita envios após aprovação nos testes de contrato e no rollout.
`REJECTED`	Bloqueie envios, inspecione o motivo e corrija o conteúdo ou o contrato.
`PAUSED` ou `DISABLED`	Interrompa novos envios e use um fallback aprovado quando disponível.
`IN_APPEAL`	Mantenha os envios bloqueados até que o status mude para `APPROVED`.
`ARCHIVED` ou `DELETED`	Remova o modelo de mensagem do roteamento.

Uma resposta de criação ou edição bem-sucedida não autoriza envios em produção.

Sincronizar estado

Use Webhooks para atualizações rápidas e APIs de recuperação ou listagem para reconciliação:

Verifique a assinatura de cada evento whatsapp.template.reviewed.
Elimine entregas duplicadas pelo id do evento.
Resolva o recurso por wabaId, name e language.
Armazene tanto o evento de atualização quanto o status atual.
Interrompa o roteamento imediatamente quando o status atual não for APPROVED.
Recupere o modelo de mensagem quando um evento estiver ausente, atrasado ou em conflito com um estado de registro mais recente.
Execute uma reconciliação agendada e paginada de listagem para detectar divergê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 de mensagem em um estado suportado pelo endpoint.
Inclua o conjunto completo de componentes desejados na solicitação de edição.
A exclusão por nome remove todos os idiomas com esse nome.
A exclusão por nome e idioma remove apenas aquele modelo de mensagem localizado.
Modelos de mensagem arquivados ainda podem aparecer nos resultados de listagem e recuperação.

Lançar, reverter e desativar versões

Prefira uma versão paralela para alterações significativas:

Crie um novo nome com versão para cada localidade necessária. Mantenha a versão atual aprovada inalterada.
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.
Direcione uma parcela controlada de envios qualificados para a nova versão e monitore a entrega, a qualidade, as respostas e as atualizações de status.
Migre o tráfego restante somente depois que a nova versão atender aos seus critérios de rollout.

Reverta alternando o roteamento para o nome e idioma aprovados anteriormente. Não use uma edição de emergência como rollback. Desative a versão anterior somente quando filas, campanhas, configurações, testes e janelas de rollback não fizerem mais referência a ela.

Limites e solução de problemas

Uma solicitação de envio falha quando o modelo de mensagem não está aprovado ou seus componentes não correspondem aos parâmetros da mensagem.
Modelos de mensagem de autenticação usam estruturas predefinidas e restritas.
A categoria e o conteúdo do modelo de mensagem devem estar alinhados com as políticas da Meta.
Revise os detalhes da rejeição antes de recriar o mesmo conteúdo.
Use um novo nome quando um modelo de mensagem excluído ou significativamente alterado não puder ser restaurado com segurança.

Checklist para entrada em produção

O nome, finalidade, proprietário, categoria e versão estão registrados.
Cada variável possui apenas um significado, formato, exemplo seguro e regra de fallback.
Mídias e botões passaram nas verificações de formato, destino e exemplo.
Cada localidade necessária está independentemente APPROVED.
O fluxo de envio rejeita qualquer status diferente de APPROVED.
O processamento de Webhook é verificado, idempotente e reconciliado com a recuperação.
O rollout pode restaurar uma versão aprovada anteriormente.
Filas, campanhas, configurações, testes e runbooks utilizam a versão pretendida.

Idiomas suportados

Selecione o idioma exato e o código de localidade regional para um modelo de mensagem.

Exemplos de criação de modelos de mensagem

Adapte modelos de mensagem de autenticação, marketing, utilidade, comércio, Flow e chamadas.

API de criação de modelo de mensagem

Inspecione o esquema completo de componentes.

Webhooks de análise de modelos de mensagem

Processe alterações de análise e de ciclo de vida.

Primeiros passos

Guias

Endpoints

Webhooks

Gerenciar modelos do WhatsApp

O que é

Antes de começar

Como funciona

Requisição

Resposta

Defina uma identidade de recurso estável

Escolha a categoria antes de escrever o conteúdo

Defina e congele o contrato de variáveis

Organize localidades como um único lançamento

Condicione os envios ao status do modelo

Sincronizar estado

Comportamento de edição e exclusão

Lançar, reverter e desativar versões

Limites e solução de problemas

Checklist para entrada em produção

Idiomas suportados

Exemplos de criação de modelos de mensagem

API de criação de modelo de mensagem

Webhooks de análise de modelos de mensagem

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Defina uma identidade de recurso estável

​Escolha a categoria antes de escrever o conteúdo

​Defina e congele o contrato de variáveis

​Organize localidades como um único lançamento

​Condicione os envios ao status do modelo

​Sincronizar estado

​Comportamento de edição e exclusão

​Lançar, reverter e desativar versões

​Limites e solução de problemas

​Checklist para entrada em produção

Idiomas suportados

Exemplos de criação de modelos de mensagem

API de criação de modelo de mensagem

Webhooks de análise de modelos de mensagem

O que é

Antes de começar

Como funciona

Requisição

Resposta

Defina uma identidade de recurso estável

Escolha a categoria antes de escrever o conteúdo

Defina e congele o contrato de variáveis

Organize localidades como um único lançamento

Condicione os envios ao status do modelo

Sincronizar estado

Comportamento de edição e exclusão

Lançar, reverter e desativar versões

Limites e solução de problemas

Checklist para entrada em produção