Modelos de autenticação

Use um modelo de autenticação para enviar uma senha descartável (OTP) para verificação de identidade, como login, recuperação de conta ou um desafio de confirmação de transação. A Meta exige modelos de autenticação para essa finalidade. Não envie códigos de verificação de identidade por meio de modelos de marketing ou de utilidade. O conteúdo de autenticação usa um formato restrito em vez de uma mensagem promocional geral.

​

Escolha uma experiência de entrega de código

Escolha a experiência mais simples que o seu aplicativo possa suportar de forma confiável. Não escolha one-tap ou zero-tap apenas porque o editor de modelos oferece a opção. Dispositivos não compatíveis ou falhas nas verificações de elegibilidade podem usar o fallback de cópia de código. A Meta também documenta sugestões nativas de teclado para OTP no iOS 26 e posteriores, a partir de 15 de junho de 2026; esse comportamento do cliente é diferente da integração de one-tap e zero-tap no Android. Teste a combinação real de dispositivo e aplicativo do cliente antes do lançamento.

​

Entenda o conteúdo do modelo

O formato de autenticação inclui o código de verificação, uma ação de entrega do código e textos de segurança ou de expiração compatíveis. Ele não se destina a mídias, textos de marketing ou notificações gerais de conta. Fonte: Exemplo oficial da Meta. O botão Copiar código de um cupom é um formato de marketing; não é um modelo de autenticação. Consulte as configurações de modelo de autenticação da YCloud e o guia da API de modelos para obter os campos compatíveis.

​

Mantenha três tipos de expiração separados

Exibir um aviso de expiração não faz com que seu backend rejeite um código expirado. Configure o próprio sistema de verificação. Escolha uma validade de entrega adequada ao tempo de vida útil do código. Uma mensagem atrasada contendo um código expirado gera uma experiência ruim de login, mesmo que a mensagem seja entregue com sucesso.

​

Configure um código que permaneça útil ao ser entregue

Na YCloud, escolha Autenticação, selecione a experiência de entrega do código e configure as opções compatíveis de segurança e expiração. O texto da mensagem é restrito; não cole um modelo comum de marketing nesta categoria. Para um código hipotético válido por cinco minutos: O contrato atual de modelos da YCloud suporta valores de messageSendTtlSeconds de autenticação de 30 a 900 segundos, com um padrão de 10 minutos para modelos de autenticação recém-criados. Modelos antigos podem ter padrões diferentes; inspecione a configuração armazenada em vez de assumir que todos os modelos existentes sejam idênticos. A opção de expiração exibida suporta 1–90 minutos, mas essa configuração de exibição não estende o intervalo permitido de validade de entrega. Um TTL de cinco minutos não é uma promessa de cinco minutos restantes após o recebimento: o tempo já começou a contar desde a emissão do código. O seu aplicativo deve exibir o tempo de vida restante real.

​

Mantenha os detalhes de integração do Android atualizados

O toque único (one-tap) e o zero-touch (zero-tap) exigem correspondência da identidade do app e um handshake em funcionamento. O contrato de modelo atual da YCloud usa supported_apps; os campos de nível superior mais antigos package_name e signature_hash estão descontinuados. A documentação de autenticação atual da Meta anuncia 15 de outubro de 2026 como o prazo final de migração para o handshake mais antigo PendingIntent e recomenda o SDK Android de OTP. Se o seu app usa esse fluxo mais antigo, trate a migração como uma tarefa de desenvolvimento no aplicativo, e não uma simples edição no texto do modelo. Consulte a documentação atual de toque único (one-tap) e zero-touch (zero-tap) antes do lançamento.

​

Teste os caminhos de falha

Teste um código expirado, uma segunda solicitação de código, o código incorreto, um dispositivo offline, um cliente incompatível e uma incompatibilidade de assinatura do app Android. Decida se a emissão de um novo código invalida o anterior e ajuste a interface para refletir essa decisão. Nunca deduza o sucesso da autenticação a partir de delivered ou read. Apenas o seu backend de verificação pode determinar se o código enviado é válido para o usuário e a ação pretendidos.

​

Desenvolva o fluxo de verificação

1. Permita que o cliente solicite um código e confirme o destino.
2. Explique que o código chegará pelo WhatsApp.
3. Gere e valide o código no seu sistema de verificação.
4. Envie o modelo aprovado com os parâmetros obrigatórios.
5. Monitore a entrega da mensagem separadamente da verificação bem-sucedida.
6. Ofereça uma nova tentativa controlada ou uma rota alternativa quando apropriado.

Aplique limites de taxa (rate limits) e controles de nova tentativa às solicitações de código. Nunca trate uma confirmação de entrega ou leitura do WhatsApp como prova de que o cliente passou na autenticação. Não registre códigos de verificação utilizáveis em logs gerais do aplicativo.

​

Preços e disponibilidade

Mensagens de autenticação têm tarifas próprias, e tarifas de autenticação internacional podem ser aplicadas em circunstâncias qualificadas. Consulte os preços do WhatsApp. Um cliente que solicita um código não está dando permissão para ações futuras de marketing não relacionadas. Mantenha o consentimento e o objetivo da mensagem alinhados com a verificação solicitada.

​

Guias de implementação

• Autenticação com cópia de código
• Autenticação com toque único (one-tap)
• Autenticação zero-touch (zero-tap)
• Envie códigos de verificação com a YCloud

Para conhecer o comportamento upstream, consulte os modelos de autenticação da Meta.

​

Perguntas frequentes