Como preparar um template para aprovação no WhatsApp

Para enviar uma mensagem de template, crie um rascunho que descreva uma comunicação real, salve a versão que será enviada e submeta-a para análise. Em produção, o fluxo só segue para envio quando a versão correspondente estiver com status aprovado; submeter não é o mesmo que ter uma aprovação. Se a sua conta ainda precisa concluir a conexão, comece pela página de conexão com a Meta.

Templates são corpos de mensagem pré-aprovados. Eles servem para mensagens que precisam usar um texto definido antes do envio. O trabalho mais útil acontece antes do botão de submeter: escolher uma finalidade clara, escrever a mensagem como o destinatário a lerá e conferir que os dados dinâmicos têm exemplos e formato compatíveis.

O que precisa estar pronto antes de submeter um template?

Comece pelo contexto da mensagem. Diga internamente qual evento a dispara, quem a recebe, qual informação é fixa e qual informação muda por destinatário. Uma atualização de pedido, por exemplo, costuma precisar de um identificador do pedido e do nome da pessoa; uma campanha pode precisar de um cupom ou link. Esse inventário evita que o texto seja genérico demais ou que o payload de envio invente parâmetros depois.

Depois, escolha a categoria e o idioma como valores explícitos. A API usa uma string de idioma do WhatsApp, como pt_BR, e não o formato de objeto aninhado. Para o texto, decida entre parâmetros posicionais, como {{1}}, e parâmetros nomeados, como {{customer_name}}. O formato padrão compatível é POSITIONAL; para NAMED, cada variável de BODY ou de HEADER de texto precisa ter um exemplo com o mesmo nome. O guia de templates descreve esses formatos e os componentes aceitos.

Escreva o BODY como uma frase completa. Em templates de marketing ou utilidade, uma variável válida não pode ser o primeiro nem o último conteúdo do BODY. Em vez de começar com {{customer_name}}, seu pedido..., use Olá, {{customer_name}}. Seu pedido.... Essa checagem acontece antes da submissão e aponta o componente que precisa de ajuste, o que torna a correção mais direta do que descobrir o problema depois.

Também vale separar a redação da configuração de botões. Os tipos documentados incluem resposta rápida, URL, telefone, OTP e COPY_CODE, mas cada categoria aceita combinações próprias. Não transforme um cupom curto em um payload de pagamento: o contrato de COPY_CODE é diferente do fluxo de pagamento. Se o template for de autenticação, trate-o como um formato próprio, com componentes OTP fixos, em vez de reaproveitar um BODY livre de uma mensagem de utilidade.

Como criar uma versão que a API consegue validar?

Há dois caminhos: gerar um rascunho a partir de uma descrição para inspeção ou criar diretamente o template que será persistido. A geração não cria um identificador de template; ela devolve um rascunho para você revisar. Para persistir, use POST /v1/templates e guarde a resposta, incluindo o identificador retornado.

O exemplo abaixo usa parâmetros nomeados e exemplos correspondentes. Defina a chave de idempotência uma vez para esta criação lógica. Se a chamada precisar ser repetida com o mesmo payload, reutilize a mesma chave; uma nova criação lógica deve receber outra chave.

IDEMPOTENCY_KEY="template-order-tracking-<stable-uuid>"

curl https://api.tyxter.com/v1/templates \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -d '{
    "name": "order_tracking_update",
    "language": "pt_BR",
    "category": "utility",
    "parameter_format": "NAMED",
    "components": [
      {
        "type": "BODY",
        "text": "Olá, {{customer_name}}. Pedido {{order_id}} em acompanhamento.",
        "example": {
          "body_text_named_params": [
            { "param_name": "customer_name", "example": "Ana" },
            { "param_name": "order_id", "example": "ORD-123" }
          ]
        }
      }
    ]
  }'

O snippet não é uma promessa de que uma revisão externa terá um resultado específico. Ele mostra uma forma documentada de criar um template com a estrutura que a API entende. Antes de avançar, confira o nome, o idioma, a categoria, todos os componentes e os exemplos no retorno. A referência da API de templates também explica o que é persistido, atualizado, duplicado e submetido.

Como submeter e acompanhar o estado correto?

Depois de criar o template, envie POST /v1/templates/{id}/submit, substituindo {id} pelo identificador persistido. A submissão cria a versão que o envio vai consultar. Para uma campanha ou envio direcionado, a checagem importante é a combinação de nome e idioma ter uma versão aprovada; uma versão em rascunho, rejeitada, pausada ou desativada não satisfaz essa condição.

Não trate uma resposta de submissão como recibo de entrega e nem como decisão final de revisão. São etapas distintas: a API aceita a operação de submissão, enquanto o status do template informa se aquela versão pode ser usada no fluxo de envio. Essa separação também melhora o tratamento de falhas: quando o envio retorna template_not_approved, o próximo passo é inspecionar a versão e o idioma solicitados, não repetir cegamente a mesma mensagem.

Em sandbox, o comportamento tem uma finalidade diferente. Não há análise real da Meta: um template de sandbox válido é autoaprovado ao ser submetido. Isso é útil para exercitar o caminho técnico, inclusive cenários de recusa simulada, mas não representa uma revisão em produção. A documentação de sandbox explica o que é simulado e por que esse ambiente não alcança telefones reais.

Quais revisões reduzem retrabalho antes da submissão?

Faça uma leitura como destinatário e outra como integrador. Na primeira, confirme que o texto explica o motivo do contato sem depender de um nome de variável para começar ou terminar a frase. Na segunda, compare cada token com o payload que sua aplicação consegue fornecer. Em NAMED, um nome divergente entre o texto e os exemplos torna o template inválido; em POSITIONAL, mantenha a sequência {{1}}, {{2}} sem espaços dentro das chaves.

Revise também alterações posteriores. Um PATCH pode ser avaliado contra o template resultante da combinação entre o que já existe e o que foi atualizado. Portanto, uma mudança aparente de categoria ou de formato pode revelar um BODY antigo que precisa ser corrigido. Duplicar uma variante é uma boa forma de experimentar uma redação diferente sem perder a referência da versão anterior, mas cada variante ainda precisa seguir a estrutura de parâmetros que declara.

Por fim, mantenha a automação preparada para estados em vez de prazos. Consulte a lista ou o recurso do template, decida pelo status observado e registre o identificador que foi submetido. Esse desenho deixa claro qual versão sua aplicação tentou usar e facilita distinguir um erro de autoria de um template ainda indisponível para envio.

Quais são as dúvidas mais comuns sobre aprovação de templates?

Posso enviar logo depois de criar o template?

Não. Criar persiste o template; para produção, o fluxo documentado é criar, submeter, aguardar o estado aprovado e então enviar a versão aprovada.

Posso usar {{nome}} sem configurar o formato nomeado?

Não. Um BODY, HEADER de texto ou URL dinâmica com parâmetro nomeado precisa de parameter_format: "NAMED" e dos exemplos exigidos para os componentes aplicáveis.

O sandbox confirma que a Meta aprovou meu texto?

Não. O sandbox autoaprova templates válidos para testar o ciclo técnico e não executa uma revisão real da Meta.

Por que uma tentativa de envio diz que o template não está aprovado?

Verifique o nome, o idioma e o status da versão resolvida pelo envio. A condição de uso é uma versão aprovada para aquela combinação, não apenas a existência de um rascunho.

Quando o texto, os parâmetros e o estado estiverem claros, inicie a conta e transforme esse roteiro em um fluxo repetível para cada nova comunicação.