Envie códigos de verificação pelo WhatsApp

Use códigos de verificação do WhatsApp para cadastro, login, recuperação de conta e verificação adicional de ações confidenciais. Depois que o cliente escolhe o WhatsApp, seu sistema envia um modelo de autenticação. O cliente copia ou preenche automaticamente o código, e seu back-end faz a validação.

Por que usar o WhatsApp para verificação?

Adicione outro canal de entrega junto ao SMS

O WhatsApp permite que os clientes recebam códigos pela internet quando a recepção de SMS não for confiável. Eles precisam do WhatsApp e de uma conexão ativa com a internet.

Reduza as etapas de inserção do código

Botões de copiar código reduzem a transcrição manual. As experiências de um toque (one-tap) e zero toque (zero-tap) podem reduzir a troca de aplicativos em apps Android compatíveis e integrados.

Otimize o custo de uma verificação concluída

Compare os custos totais do canal por verificação bem-sucedida por mercado, incluindo tarifas de autenticação, tarifas internacionais de autenticação aplicáveis, cobranças da YCloud e fallback para SMS. 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 os preços do WhatsApp e os preços da Meta.

Identifique o abandono no fluxo de verificação

Rastreie o aceite da API, a entrega da mensagem e a verificação bem-sucedida separadamente para localizar onde ocorre o abandono. Seu back-end deve rejeitar códigos expirados, reutilizados ou inválidos.

Antes de começar

Faça login na YCloud e conecte uma WABA e um remetente.
Prepare a lógica de solicitação, geração, armazenamento e validação de códigos. Este guia utiliza a API de mensagens do WhatsApp; o 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. Uma solicitação de código não concede permissão para ações de marketing posteriores.
Configure um canal de SMS e implemente as regras de fallback no seu back-end.

1. Escolha a experiência com o código

Experiência e integração	Exemplo
Copiar código Copie no WhatsApp e cole no seu site ou app. Funciona em várias plataformas. Entrada de código e validação no back-end.
Um toque / Preenchimento automático Toque em Preenchimento automático para enviar o código ao seu app Android. Integre o SDK Android de OTP da Meta e configure o nome do seu pacote e o hash da chave de assinatura do app.
Zero toque Seu app Android recebe o código sem alternar para o WhatsApp ou tocar em um botão. Integre o SDK Android de OTP da Meta, configure o nome do seu pacote e o hash da chave de assinatura do app e aceite os termos do zero-tap.	Tela ilustrativa de entrada de código. O zero toque requer Android.

Ofereça suporte a fallback para cópia de código quando os requisitos de um toque ou zero toque no Android não forem atendidos. Para sugestões do teclado no iOS, consulte as Perguntas frequentes abaixo.

2. Crie um modelo de autenticação

Selecione a WABA, o nome e o idioma

Abra Modelos para a WABA desejada na YCloud, selecione Add Template e escolha Authentication. Use letras minúsculas, dígitos e sublinhados para um nome como login_verification. Escolha o idioma do seu cliente e registre o nome exato aprovado e o código de idioma para o 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 de segurança e expiração compatíveis. 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 exige o aceite dos termos aplicáveis. Para configuração da API, use o contrato atual de supported_apps em vez de exemplos mais antigos de nível superior com package_name e signature_hash. Siga os guias de integração de autenticação para obter detalhes sobre o SDK do Android e o handshake.

Configure três parâmetros de expiração separados

Configuração	O que ela controla	Exemplo de cinco minutos
Expiração do código no back-end	Quando seu servidor rejeita o código.	Cinco minutos após a geração.
Aviso de expiração exibido	O que é informado ao cliente.	Cinco minutos, de acordo com a sua política real.
Tempo de vida útil (TTL) de entrega	Por quanto tempo a entrega pode ser tentada.	Não mais longo que o tempo de vida útil restante do código, considerando o intervalo entre a geração e o envio.

Recomendamos definir o TTL de entrega do OTP (messageSendTtlSeconds) como 30 a 60 segundos no seu modelo de autenticação. Mantenha-o dentro do tempo de vida útil restante do código. A YCloud suporta 30 a 900 segundos, com um padrão de 10 minutos para novos modelos. O aviso de expiração exibido suporta 1 a 90 minutos e não impõe a expiração no back-end. O TTL de entrega interrompe as tentativas de entrega pendentes; ele não recolhe mensagens que já foram entregues. Consulte o contrato da API da YCloud.

Envie e verifique a disponibilidade

Envie o modelo e verifique seu status real de análise. Envie apenas depois que ele estiver aprovado e utilizável. Se for rejeitado, verifique o motivo e siga a seção Análise e ciclo de vida do modelo. 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 de que seu fluxo precisa:

Endpoint	Comportamento
`POST /v2/whatsapp/messages/sendDirectly`	Envia sincronicamente para a WhatsApp Business API; útil quando o fluxo de OTP precisa do resultado do envio imediatamente.
`POST /v2/whatsapp/messages`	Coloca a mensagem na fila para envio assíncrono.

Use um modelo de autenticação aprovado com qualquer um dos endpoints.

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 from e to.
Defina type como template e 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 externalId ajuda na reconciliação, mas não garante idempotência.

Exemplo de corpo de solicitação para copiar código. Substitua os marcadores; 123456 é fictício e deve ser gerado pelo seu sistema de verificação em produção:

{
  "from": "BUSINESS_PHONE_NUMBER",
  "to": "CUSTOMER_PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "APPROVED_TEMPLATE_NAME",
    "language": { "code": "APPROVED_LANGUAGE_CODE" },
    "components": [
      {
        "type": "body",
        "parameters": [{ "type": "text", "text": "123456" }]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [{ "type": "text", "text": "123456" }]
      }
    ]
  },
  "externalId": "VERIFICATION_REQUEST_REFERENCE"
}

Os parâmetros de envio para o botão de OTP usam sub_type: url; não use uma estrutura comum de botão de código de cupom de marketing. Consulte Autenticação com cópia de código e Enviar uma mensagem de WhatsApp. Você também pode selecionar Mais → Copiar como cURL em um modelo aprovado e verificar os parâmetros gerados em relação à sua configuração. Uma resposta de sucesso da API não confirma a entrega. Se uma solicitação expirar por tempo limite, verifique os registros de mensagens disponíveis e os retornos de chamada antes de tentar enviar novamente.

4. Receba atualizações de entrega

Em Desenvolvedores → Webhooks, crie um endpoint, insira sua URL de callback e assine whatsapp.message.updated. Siga o Guia de Webhook para verificação de assinatura, confirmações de recebimento e novas tentativas. Associe cada ID de mensagem à sua solicitação de verificação:

Status	Significado	Resposta do fluxo
`sent`	Enviado, sem confirmação de chegada ao dispositivo do cliente.	Aguarde atualizações de entrega ou falha.
`delivered`	Entregue ao destinatário.	Aguarde a validação bem-sucedida do código.
`read`	Uma confirmação de leitura foi recebida.	Não marque a verificação como concluída nem trate recibos ausentes como falha.
`failed`	O envio ou a entrega falhou.	Analise o erro antes de corrigir a configuração, tentar novamente ou trocar de canal.

Marque a verificação como concluída apenas quando seu back-end validar o código. Trate retornos de chamada duplicados e atrasados sem permitir que um status anterior sobrescreva um posterior. Use os Logs de mensagens para investigação manual.

5. Projete 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, uma mensagem de espera, a contagem regressiva para reenvio e as alternativas disponíveis. Permita que os clientes voltem e corrijam o número.

Estratégia e experiência	Exemplo de frontend
WhatsApp primeiro, fallback por SMS Comece com o WhatsApp e ofereça SMS caso a entrega falhe ou demore demais.
O cliente escolhe Ofereça WhatsApp e SMS antes de enviar e, em seguida, mostre uma contagem regressiva para reenvio e a tela de inserção de código.

Configure o fallback por SMS

Defina o TTL de entrega do OTP como 30 a 60 segundos no seu modelo de autenticação do WhatsApp e alinhe o temporizador de fallback por SMS a esse intervalo.

Disparador	Regra de fallback para SMS
O envio via API falha explicitamente	Envie o SMS imediatamente e investigue o erro da API. Um tempo limite (timeout) de requisição por si só não é uma rejeição explícita; verifique os registros de mensagens e callbacks.
Um Webhook `whatsapp.message.updated` informa `failed`	Envie o SMS imediatamente e inspecione o erro. Um código comum é `131026` (mensagem não entregável): o número pode não estar cadastrado no WhatsApp, mas outras causas são possíveis.
O TTL de entrega expirou e você tem uma confirmação de `sent`, mas nenhuma confirmação de `delivered` ou `read`	Envie o SMS se a solicitação de verificação ainda estiver ativa. Acompanhe o prazo de entrega no seu back-end; não reinicie o TTL quando um Webhook atrasado chegar.
O WhatsApp foi entregue, a verificação foi concluída ou o código expirou	Não acione o fallback automático para SMS nesta solicitação.

A Meta cobra por mensagens do WhatsApp entregues. Uma mensagem que expira sem ser entregue não gera cobrança de mensagem da Meta; as tarifas de SMS ainda se aplicam. A ausência de um Webhook de entrega por si só não comprova a não entrega, portanto, ambos os canais podem ser cobrados se o WhatsApp tiver sido entregue antes de expirar. Consulte preços do WhatsApp. Envie SMS no máximo uma vez por solicitação de verificação, mesmo se os callbacks forem duplicados ou chegarem atrasados. Reutilize o mesmo código não expirado ou invalide o código antigo ao emitir um novo. O fallback não deve estender o tempo de vida do código.

6. Testar antes do lançamento

Teste	Resultado esperado
Verificação normal	Os valores do corpo e do botão coincidem; um código correto e não expirado é bem-sucedido.
Código incorreto, expirado ou reutilizado	O back-end o rejeita de acordo com a política e a interface explica o resultado.
Solicitação de novo código	A validade dos códigos antigo e novo segue a sua política.
Destinatário offline ou com atraso	O TTL de entrega permanece separado do tempo de vida do código; o tempo de espera e o fallback seguem a configuração.
Condições de preenchimento automático não compatíveis no Android	Um fallback utilizável permite que o cliente continue.
iOS e múltiplos dispositivos	Teste notificações, cópia e preenchimento nos clientes reais; não presuma um comportamento idêntico.
Callbacks duplicados, callbacks atrasados, tempo limite de requisição	Não crie resultados duplicados nem reenvios descontrolados.
Fallback para SMS	Use o destino correto e um código válido; interrompa após uma verificação bem-sucedida.

Após o lançamento, compare taxa de entrega, latência de entrega, conclusão da verificação, proporção de fallback para SMS e custo por verificação bem-sucedida por mercado, canal e dispositivo. Use esses resultados para ajustar a prioridade dos canais e os limites de espera.

Cenário adicional: verificação iniciada pelo cliente

Em um fluxo de verificação iniciado pelo cliente, ele abre o WhatsApp a partir de um aplicativo, envia uma mensagem contendo informações para a verificação atual e retorna ao aplicativo. Essa abordagem exige um desafio de uso único, vinculação de sessão, expiração, proteção contra repetição e confirmação do usuário.

Perguntas frequentes

Como posso verificar se o WhatsApp está instalado no Android ou iOS?

No Android, declare com.whatsapp e com.whatsapp.w4b nas consultas de pacotes (package queries) do manifesto e, em seguida, use o método isWhatsAppInstalled(context) do OTP Android SDK da Meta em uma instância de WhatsAppOtpHandler. No iOS, use UIApplication.shared.canOpenURL(URL(string: "whatsapp://otp")!) e configure as permissões de consulta de URL scheme exigidas pelo seu aplicativo. As verificações de instalação ajudam a sugerir um canal no dispositivo atual. Elas não confirmam se o número de telefone inserido está cadastrado no WhatsApp. Permita que os clientes confirmem o número do WhatsApp e escolham outro canal. Consulte as verificações de instalação no Android e iOS da Meta.

O iOS oferece suporte a preenchimento automático com um toque (one-tap) ou sem toque (zero-tap)?

O iOS 26 e posterior habilita sugestões de teclado por padrão para todos os modelos de autenticação. O iOS detecta o código na notificação push do WhatsApp e oferece uma sugestão de preenchimento automático com um toque no teclado. Não são necessárias alterações na integração. Versões anteriores do iOS não oferecem suporte a essa experiência de preenchimento automático; use modelos para copiar código. A integração de botão de um toque do Android e o zero-tap são experiências distintas; o zero-tap é exclusivo do Android. Consulte as sugestões de teclado da Meta.

Os clientes podem ler códigos de verificação em dispositivos conectados?

Os códigos de autenticação estão disponíveis apenas no dispositivo principal do WhatsApp do cliente. Os dispositivos conectados exibem uma mensagem mascarada solicitando que o cliente verifique seu dispositivo principal. Esse recurso de segurança da Cloud API é habilitado por padrão, não requer alterações de código e não pode ser configurado ou personalizado. Consulte a documentação sobre segurança de dispositivos vinculados da Meta.

​Por que usar o WhatsApp para verificação?

​Adicione outro canal de entrega junto ao SMS

​Reduza as etapas de inserção do código

​Otimize o custo de uma verificação concluída

​Identifique o abandono no fluxo de verificação

​Antes de começar

​1. Escolha a experiência com o código

​2. Crie um modelo de autenticação

​Selecione a WABA, o nome e o idioma

​Configure o conteúdo e a ação do código

​Configure três parâmetros de expiração separados

​Envie e verifique a disponibilidade

​3. Envie por meio da API

​Prepare a solicitação

​4. Receba atualizações de entrega

​5. Projete a interface e o fallback por SMS

​Deixe claro o canal de recebimento

​Configure o fallback por SMS

​6. Testar antes do lançamento

​Cenário adicional: verificação iniciada pelo cliente

​Perguntas frequentes

​Como posso verificar se o WhatsApp está instalado no Android ou iOS?

​O iOS oferece suporte a preenchimento automático com um toque (one-tap) ou sem toque (zero-tap)?

​Os clientes podem ler códigos de verificação em dispositivos conectados?