Modelos de autenticação do WhatsApp: como enviar OTPs pelo WhatsApp

Resumo: Os modelos de autenticação são a categoria específica da plataforma WhatsApp Business para OTPs e códigos de verificação. O texto da mensagem é definido pelo WhatsApp, você fornece apenas o código e escolhe um botão de OTP (copiar código, preenchimento automático com um toque ou sem toque). Eles costumam ser aprovados quase instantaneamente, raramente são pausados e só são cobrados quando entregues. Este guia explica como eles diferem de outros modelos, quando usá-los, como criar e enviar um (pelo painel e pela API), como a expiração do código difere do TTL da mensagem e quais práticas recomendadas evitam a maioria dos problemas em produção.

Introdução

Se o seu app envia OTPs por SMS, você já conhece os problemas: custos crescentes, mensagens atrasadas ou filtradas e usuários que nunca veem o código. Os modelos de autenticação do WhatsApp oferecem outra opção. Os códigos chegam em um app que as pessoas já conferem o tempo todo e, no Android, você pode oferecer o preenchimento automático com um toque, que insere o código diretamente no seu app.

Este guia explica o que são modelos de autenticação, como eles diferem dos modelos de Marketing e Utilidade, quando você pode (e não pode) usá-los e como criar e enviar um, tanto pelo painel do Chakra quanto pela API.

O que são modelos de autenticação?

Os modelos de autenticação são uma das três categorias de modelos da plataforma WhatsApp Business, junto com Marketing e Utilidade. Eles têm uma única finalidade: enviar senhas de uso único e códigos de verificação para confirmar a identidade de um usuário.

O que os diferencia:

• O conteúdo é padronizado. Você não pode escrever um texto personalizado para o corpo da mensagem. O WhatsApp o gera no idioma do modelo ("{{1}} é seu código de verificação") e você fornece apenas o código.
• É obrigatório incluir um botão de OTP. Copiar código ou preenchimento automático com um toque é obrigatório. Também é possível escolher a opção sem toque, que não exibe nenhum botão. Esses tipos de botão existem apenas nesta categoria.
• O texto de expiração é opcional. Você pode adicionar um rodapé, como "Este código expira em 5 minutos."
• A aprovação costuma ser instantânea, já que o conteúdo é predefinido e não promocional. A Meta também observa que os modelos de autenticação com botões de OTP têm um risco muito menor de serem pausados do que os de outras categorias.

Estrutura de um modelo de autenticação

O que o usuário vê:

482913 é seu código de verificação. Para sua segurança, não compartilhe este código.

Este código expira em 5 minutos.

[ Copiar código ]

Tipos de botão: copiar código, preenchimento automático com um toque ou sem toque

O comportamento alternativo é importante. Um modelo com um toque ou sem toque ainda exige que você forneça o rótulo do botão de copiar código. Se a Meta não conseguir validar a comunicação de preenchimento automático (por exemplo, se o app não estiver instalado), a mensagem exibirá um botão para copiar o código. Portanto, você não cria dois botões, "preenchimento automático e copiar código": o modelo tem um único botão de OTP, e a opção alternativa de copiar o código já vem integrada.

Uma observação sobre o iPhone. As opções com um toque e sem toque são recursos do Android. Separadamente, a documentação da Meta informa que, a partir de June 15, 2026, no iOS 26 e versões posteriores, as sugestões do teclado permitem o preenchimento automático nativo de OTP a partir da notificação push, sem necessidade de integração da sua parte.

Sobre o hash de assinatura. Para as opções com um toque e sem toque, você fornece o nome do pacote do seu app Android e um hash de assinatura de 11 caracteres, derivado do certificado de assinatura do seu app. Uma divergência é o motivo mais comum para o preenchimento automático voltar silenciosamente à opção de copiar código; por isso, teste em um dispositivo real antes de lançar. O SDK de OTP para Android da Meta simplifica essa comunicação e vale a pena usar.

Quando usar modelos de autenticação

Use-os apenas para códigos de verificação:

• Login e cadastro (verificação de um número de telefone)
• Autenticação de dois fatores
• Recuperação de conta e redefinição de senha
• Confirmação de identidade antes de alterações confidenciais na conta
• Nova verificação em um dispositivo novo ou após um período de inatividade

Quando não usar

Os modelos de autenticação são exclusivos para códigos. Usá-los para qualquer outra finalidade faz com que sejam rejeitados ou reclassificados:

• Atualizações de pedidos e notificações de entrega devem ficar na categoria Utilidade.
• Promoções, ofertas e ações para reconquistar clientes devem ficar na categoria Marketing.
• Qualquer conteúdo que não seja um código de verificação não deve ser usado aqui.

O erro inverso é igualmente comum: não coloque um OTP em um modelo de Utilidade para evitar o formato fixo. A Meta detecta conteúdo de OTP e vai reclassificá-lo ou rejeitá-lo. Se sua mensagem contém um código, ela deve ser enviada em um modelo de Autenticação, o que também determina como será cobrada.

Requisitos e limites

Para a empresa

• Uma conta WhatsApp Business ativa na WhatsApp Business Platform, disponível por meio de provedores como Chakra.
• Copiar código e preenchimento com um toque não exigem aprovação especial. Para usar o preenchimento sem toque, é necessário aceitar os termos de zero-tap da Meta ao criar o modelo.

Para o modelo

• O texto do corpo é fixo. Não é possível personalizar o texto nem adicionar variáveis além do código.
• Exatamente um botão de OTP.
• Texto do rótulo do botão: no máximo 25 caracteres.
• Hash de assinatura (um toque e zero-tap): exatamente 11 caracteres.
• Validade do código (opcional): de 1 a 90 minutos.
• Mantenha os códigos no padrão de 4 a 8 dígitos, para o qual os fluxos de preenchimento automático foram desenvolvidos.

Para o destinatário

• O número precisa estar associado a uma conta ativa do WhatsApp. Caso contrário, a entrega falha (você verá o erro 131026); por isso, usar o SMS como alternativa é uma medida de segurança sensata para fluxos críticos.
• De acordo com a documentação da Meta, as mensagens de autenticação são entregues somente no dispositivo principal do usuário no WhatsApp.
• O preenchimento automático com um toque também exige que seu app esteja instalado em um dispositivo Android.

Como criar um modelo de autenticação

Opção 1: pelo Chakra Dashboard

O gerenciamento de modelos do Chakra permite criar modelos em todas as categorias, incluindo Autenticação, e cuida do envio para a Meta e da sincronização do status de aprovação.

1. Abra o gerenciamento de modelos e crie um novo modelo.
2. Escolha a categoria Autenticação .
3. Dê um nome ao modelo (letras minúsculas, números e sublinhados) e selecione o idioma.
4. Escolha o tipo de botão: copiar código ou preenchimento automático com um toque.
5. Para a opção de um toque, insira o nome do pacote Android e o hash de assinatura.
6. Ative ou desative a recomendação de segurança ("Para sua segurança, não compartilhe este código").
7. Defina a validade do código (de 5 a 10 minutos é o padrão para fluxos de login).
8. Envie. A aprovação costuma ser instantânea.

Opção 2: pela API

Crie um modelo de cópia de código:

json

POST https://graph.facebook.com/v{version}/{WABA_ID}/message_templates

{
"name": "login_otp_copy_code",
"language": "en_US",
"category": "AUTHENTICATION",
"message_send_ttl_seconds": 300,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" }
]
}
]
}

Crie um modelo de preenchimento automático com um toque (o rótulo de copiar código é a alternativa integrada):

json

{
"name": "login_otp_autofill",
"language": "en_US",
"category": "AUTHENTICATION",
"message_send_ttl_seconds": 300,
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "ONE_TAP",
"text": "Copy Code",
"autofill_text": "Autofill",
"package_name": "com.yourcompany.app",
"signature_hash": "K8a/AINcGX7"
}
]
}
]
}

Referência dos campos

Vários idiomas. O mesmo nome de modelo pode existir em vários idiomas. O endpoint upsert da Meta permite criar um modelo de autenticação em vários idiomas em uma única chamada, em vez de repetir a solicitação para cada idioma.

Como enviar o código

Com o SDK do Chakra

O SDK TypeScript do Chakra tem um parâmetro OTP, então você não precisa montar os componentes manualmente:

javascript

await client.whatsapp.templateMessages.send({
pluginId: "YOUR_PLUGIN_ID",
toPhoneNumber: "919999999999",
whatsappPhoneNumberId: "YOUR_PHONE_NUMBER_ID",
templateName: "login_otp",
otpCode: "496093",
});

Os números de telefone devem incluir o código do país, sem + nem caracteres de formatação.

Com o endpoint no formato da Meta

Se você prefere o payload bruto da Meta pelo endpoint pass-through da Chakra, atenção a um detalhe que costuma confundir: o código precisa aparecer duas vezes, uma no corpo e outra no componente do botão.

bash

curl --request POST \
'https://api.chakrahq.com/v1/ext/plugin/whatsapp/{pluginId}/api/v19.0/{whatsappPhoneNumberId}/messages' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "919999999999",
"type": "template",
"template": {
"name": "login_otp",
"language": { "code": "en_US" },
"components": [
{
"type": "body",
"parameters": [ { "type": "text", "text": "482913" } ]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [ { "type": "text", "text": "482913" } ]
}
]
}
}'

Deixar de fora o parâmetro do botão é uma causa comum de falha no envio de OTP. Use uma versão atual da Graph API na URL e consulte a referência da API da Chakra para ver detalhes de autenticação e da solicitação.

A validade do código e o TTL da mensagem são configurações diferentes

É fácil confundir estas duas configurações:

• code_expiration_minutes controla o texto exibido para o usuário ("Este código expira em X minutos"). Ele informa por quanto tempo o código é válido.
• message_send_ttl_seconds controla por quanto tempo a Meta tenta entregar a mensagem. Para modelos de autenticação, o padrão é 10 minutos, mas você pode reduzir esse prazo. Se a entrega não acontecer dentro desse período, a Meta descarta a mensagem, e mensagens não entregues não são cobradas.

Defina ambos intencionalmente e alinhe-os ao período de validade no seu servidor. Se o TTL expirar e você não tiver recebido um webhook de entrega, considere a mensagem descartada; esse é o momento natural para acionar uma alternativa por SMS.

O fluxo de OTP de ponta a ponta

1. O usuário informa o número de telefone no seu app ou site.
2. Seu backend gera um código e chama a API de envio.
3. O WhatsApp entrega o modelo de autenticação.
4. O usuário toca em preenchimento automático (Android) ou copia e cola o código.
5. Seu backend verifica o código e autentica o usuário.
6. Seu webhook recebe o status da entrega, para que você possa acionar uma alternativa se a mensagem não chegar.

Preços

• As mensagens de autenticação são cobradas por mensagem entregue, de acordo com a tarifa de autenticação do país do destinatário (consulte os preços por país). Alguns mercados também têm uma tarifa internacional de autenticação separada para empresas elegíveis.
• Mensagens não entregues, inclusive as descartadas após o TTL, não são cobradas.
• As tarifas variam por país e mudam com o tempo, então consulte a tabela de tarifas atual da Meta antes de fazer previsões.
• A Chakra não aplica nenhuma margem sobre mensagens de modelo: você paga a tarifa vigente da Meta pelas mensagens entregues com sucesso.

Boas práticas

• Comece com a opção de copiar o código. Ela funciona para todos os usuários. Adicione a opção de um toque apenas se você tiver um app Android e puder manter o hash de assinatura.
• Mantenha o prazo de validade curto, normalmente de 5 a 10 minutos, e ajuste o TTL para corresponder a ele.
• Adicione uma alternativa por SMS para destinatários que não conseguem receber mensagens pelo WhatsApp (131026) e para mensagens sem confirmação de entrega dentro do TTL.
• Limite a frequência das solicitações de OTP no seu servidor, com intervalos entre reenvios, para evitar abusos e spam acidental. Considere também os limites de taxa da API nos picos de tráfego (a Chakra limita a 200 chamadas por minuto).
• Crie uma versão para cada idioma atendido, usando o mesmo nome de modelo sempre que possível.
• Monitore os webhooks de status (enviada, entregue, lida, com falha) para identificar problemas de entregabilidade logo no início.
• Nunca use modelos de autenticação para conteúdo que não seja OTP. Esse é o caminho mais rápido para a recategorização.
• Teste o preenchimento automático em um dispositivo Android real antes do lançamento. Problemas com o hash de assinatura só aparecem nele.

Perguntas frequentes

Posso personalizar o texto do corpo de um modelo de autenticação? Não. O corpo é padronizado. As únicas partes de texto que você pode controlar são o aviso de segurança, a linha de validade e os rótulos dos botões.

Os modelos de autenticação precisam de aprovação? Eles passam pelo processo normal de envio, mas, como o conteúdo é predefinido, normalmente são aprovados quase imediatamente.

O que acontece se eu enviar um OTP em um modelo de Utility? A Meta detecta o conteúdo de OTP e o recategoriza como autenticação ou o rejeita. Use a categoria correta desde o início.

O preenchimento automático com um toque funciona no iPhone? Não. As opções de um toque e zero toque são recursos do Android. Os usuários de iPhone têm o fluxo de copiar o código e, no iOS 26 ou posterior, segundo a Meta, as sugestões do teclado podem preencher o código automaticamente a partir da notificação.

Posso enviar o mesmo modelo em vários idiomas? Sim. Um nome de modelo pode ter uma versão aprovada separada para cada idioma, e você escolhe o código do idioma ao enviar.

Quantos dígitos o código pode ter? Use de 4 a 8 dígitos, o padrão para o qual os fluxos de preenchimento automático foram criados.

Conclusão

Os modelos de autenticação são uma das categorias mais simples de configurar corretamente: conteúdo fixo, aprovação instantânea e um botão de OTP adequado à sua plataforma. Se você está criando fluxos de login, cadastro ou autenticação de dois fatores, vale a pena adicioná-los ao lado do SMS ou usá-los como seu principal canal de OTP quando seus usuários já se comunicam pelo WhatsApp. Para consultar o modelo completo e as instruções de envio, veja a documentação de modelos de autenticação da Meta e a documentação da API da Chakra.