Por que usar o WhatsApp para verificação?
Adicione outro canal de envio junto com o SMS
O WhatsApp recebe mensagens por meio de uma conexão com a internet. Ele oferece aos clientes outra maneira de receber um código quando o Wi-Fi está disponível, mas o recebimento de SMS não é confiável. O destinatário ainda precisa ter o WhatsApp e uma conexão com a internet funcionando.Reduza as etapas de inserção de código
Botões de copiar código reduzem a transcrição manual. Experiências com um toque (one-tap) e sem toque (zero-tap) podem diminuir a troca de aplicativos em apps Android compatíveis e integrados. Para clientes que já usam o WhatsApp, essas opções podem facilitar a verificação. Avalie o efeito na taxa de conclusão em seu próprio fluxo.Otimize o custo de uma verificação concluída
Avalie o WhatsApp como uma forma potencial de reduzir os custos de verificação por mercado. Compare tarifas de autenticação e de autenticação internacional aplicáveis, tarifas da YCloud, custos de fallback por SMS e taxas de conclusão. Use o total de cobranças do canal de verificação dividido pelas verificações bem-sucedidas como uma métrica prática. A Meta cobra por mensagens entregues; uma mensagem não entregue não gera a respectiva taxa de mensagem da Meta. Outras cobranças dependem do seu plano da YCloud. Consulte Preços do WhatsApp e Preços da Meta.Identifique abandonos no fluxo de verificação
Monitore a aceitação da solicitação, a entrega da mensagem e a verificação bem-sucedida separadamente. Isso ajuda você a distinguir problemas de envio de problemas de recebimento ou de inserção do código. O WhatsApp transporta o código. Seu sistema de verificação ainda é responsável por decidir se ele é válido, está expirado, já foi utilizado e está autorizado para a ação solicitada.Antes de começar
- Faça login na YCloud e conecte uma WABA e remetente.
- Prepare a lógica de solicitação, geração, armazenamento e validação de código. Este guia utiliza a API de mensagens do WhatsApp; seu sistema gerencia o ciclo de vida do código. Para o serviço de verificação da YCloud, consulte Verify.
- Prepare uma chave de API no servidor e um receptor de Webhook.
- Utilize um destinatário de teste que tenha solicitado o código. A solicitação de um código não constitui permissão para comunicações posteriores de marketing.
- Configure e teste um canal de SMS caso precise de fallback. A API de mensagens do WhatsApp não envia SMS automaticamente pelo simples fato de seguir as recomendações deste guia.
1. Escolha a experiência de código
O método de um toque ou sem toque pode recorrer a outra experiência, como copiar código, quando os requisitos de dispositivo ou aplicativo não forem atendidos. Dê suporte a esse fallback. Selecionar a opção no editor não integra seu aplicativo cliente.
A Meta também documenta sugestões de teclado para OTP a partir de notificações no iOS 26 ou posterior. Isso é separado do one-tap e zero-tap no Android; teste-os separadamente. Consulte Modelos de autenticação e Documentação de autenticação da Meta.
Meta example: the customer copies the verification code and enters it in your app. The code and expiry shown are demonstration values.
2. Crie um modelo de mensagem de autenticação
Selecione a WABA, o nome e o idioma
Abra Modelos para a WABA pretendida na YCloud, selecione Adicionar modelo e escolha Autenticação. Use letras minúsculas, dígitos e sublinhados para um nome comologin_verification. Escolha o idioma do seu cliente e registre o nome exato aprovado e o código de idioma para envio. Consulte Criar modelo.
Configure o conteúdo e a ação do código
A autenticação usa texto de código predefinido, com avisos compatíveis de segurança e expiração. Não insira textos promocionais comuns, URLs, mídias ou emojis no corpo da mensagem. Escolha Copy code, Autofill ou Zero Tap. Para Autofill e Zero Tap, insira o nome real do pacote Android e o hash de assinatura e conclua a integração do aplicativo. O Zero Tap também requer a aceitação dos termos aplicáveis. Para a configuração da API, use o contratosupported_apps atual em vez de exemplos de nível superior mais antigos com package_name e signature_hash. Siga os guias de integração de autenticação para obter detalhes sobre o SDK para Android e handshake.
Configure três configurações de expiração separadas
O contrato atual da YCloud suporta valores regulares e personalizados de TTL de autenticação de 30 a 900 segundos, com um padrão de 10 minutos para novos modelos. Padrões históricos podem diferir; inspecione o
messageSendTtlSeconds salvo. O aviso de expiração exibido suporta de 1 a 90 minutos , mas não altera a expiração no backend nem estende o intervalo regular do TTL de entrega.
O contrato também suporta -1, que define um TTL personalizado de 30 dias. Isso não é recomendado para códigos de curta duração e não significa expiração imediata ou desativação de novas tentativas. Consulte o contrato OpenAPI da YCloud.
Por exemplo, um código gerado às 10:00 e que expira às 10:05 tem um minuto restante se chegar às 10:04. O recebimento não reinicia seu tempo de vida. A expiração do TTL interrompe tentativas de entrega pendentes; ela não recolhe uma mensagem já entregue no dispositivo do cliente.
Envie e verifique a disponibilidade
Envie o modelo e inspecione seu status de análise real. Envie apenas depois que ele for aprovado e estiver utilizável. Se for rejeitado, inspecione o motivo e siga a seção Análise e ciclo de vida de modelos. Não dependa de um tempo fixo de aprovação.3. Envie por meio da API
Envie imediatamente após o cliente solicitar um código. Escolha o comportamento de envio necessário para o seu fluxo:
O nome do endpoint
sendDirectly descreve o timing de envio. Ele é separado do recurso Utility Direct Send, que lida com a geração de modelos. Esse fluxo ainda usa um modelo de mensagem de autenticação aprovado.
Prepare a solicitação
- Autentique no lado do servidor com
X-API-Key. - Use números no formato E.164, incluindo os códigos de país, para
frometo. - Defina
typecomotemplatee use o nome e idioma aprovados para a WABA selecionada. - Forneça o mesmo código no corpo e nos parâmetros do botão de OTP.
- Associe sua solicitação de verificação ao ID de mensagem da YCloud. O parâmetro
externalIdajuda na reconciliação, mas não garante a idempotência.
123456 é fictício e deve ser gerado pelo seu sistema de verificação em produção:
sub_type: url; não utilize a estrutura padrão de botão de cupom de marketing. Consulte Autenticação Copy code e Enviar uma mensagem do WhatsApp. Você também pode selecionar Mais → Copiar como cURL em um modelo aprovado e verificar os parâmetros gerados com relação à sua configuração.
Uma resposta de API bem-sucedida não confirma a entrega. Se uma solicitação atingir o tempo limite, inspecione os registros de mensagens disponíveis e os callbacks antes de enviar novamente.
4. Receba atualizações de entrega
Em Desenvolvedores → Webhooks, crie um endpoint, insira o seu URL de callback e assine o eventowhatsapp.message.updated. Siga o Guia de Webhook para verificar assinaturas, confirmações de recebimento e novas tentativas.
Associe cada ID de mensagem à sua respectiva solicitação de verificação:
Marque a verificação como concluída apenas quando seu back-end validar o código. Trate callbacks duplicados e atrasados sem permitir que um status anterior sobrescreva um posterior. Use os Logs de mensagens para investigação manual.
5. Projetar a interface e o fallback por SMS
Deixe claro o canal de recebimento
Antes do envio, informe que o código chegará pelo WhatsApp. Após o envio, exiba o destino mascarado, mensagem de espera, contagem regressiva para reenvio e alternativas disponíveis. Permita que os clientes voltem e corrijam o número.
Onde o sistema operacional permitir, seu aplicativo pode usar a detecção de disponibilidade do WhatsApp para sugerir um canal. A instalação não comprova que o número inserido está registrado ou acessível. Um resultado negativo não descarta o recebimento em outro dispositivo. Não use a detecção de instalação como verificação de número.
Trate falhas e atrasos separadamente
O intervalo de 15 a 60 segundos do guia original pode ser uma faixa de espera experimental. Ajuste-o usando a latência observada e o abandono. Não é um requisito do WhatsApp nem uma promessa de entrega.
Para o mesmo desafio, você pode enviar o mesmo código ainda válido pelo canal de fallback. Se gerar um novo código, invalide o anterior de acordo com sua política e explique o comportamento. O fallback não deve estender o tempo de vida de um código antigo.
Use uma única solicitação de verificação para controlar as tentativas de canal, o tempo de espera (cooldown) e a conclusão. Toques repetidos ou callbacks duplicados e atrasados não devem acionar várias mensagens SMS. Se o WhatsApp e o SMS forem entregues, cada canal poderá gerar cobranças.
6. Testar antes do lançamento
Após o lançamento, compare a taxa de entrega, latência de entrega, conclusão da verificação, proporção de fallback por SMS e custo por verificação bem-sucedida por mercado, canal e dispositivo. Use esses resultados para ajustar a prioridade de canal e os limites de espera em vez de prometer que o WhatsApp é sempre mais rápido ou mais barato que o SMS.