> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar códigos de verificação via WhatsApp Use códigos de verificação do WhatsApp para cadastro, login, recuperação de conta e verificação adicional de ações sensíveis. Depois que o cliente escolhe o WhatsApp, seu sistema envia um modelo de mensagem de autenticação. O cliente copia ou preenche o código automaticamente, e seu back-end faz a validação. ## 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](/pt/documentation/whatsapp-business-platform/pricing-limits-and-quality/whatsapp-pricing) e [Preços da Meta](https://business.whatsapp.com/products/platform-pricing). ### 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 1. Faça login na [YCloud](https://www.ycloud.com/console/#/entry/login) e [conecte uma WABA e remetente](/pt/documentation/quick-start/connect-whatsapp-to-ycloud). 2. 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](/pt/documentation/integrations/channels/verify/index). 3. Prepare uma [chave de API no servidor](/pt/documentation/developer/manage-api-keys) e um [receptor de Webhook](/pt/documentation/developer/webhooks). 4. 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. 5. 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 | Experiência | Ação do cliente | O que você prepara | Quando escolher | | - | - | - | - | | **Copiar código** | Copia no WhatsApp e insere o código no seu site ou aplicativo. | Uma tela de entrada e verificação no back-end. | Sites, múltiplas plataformas e uma integração inicial. | | **Um toque / Preenchimento automático** | Toca em um botão que repassa o código para um aplicativo Android compatível. | Nome do pacote, hash de assinatura e integração de handshake. | Reduzir a troca de apps e a colagem no Android. | | **Zero toque** | Um aplicativo Android compatível recebe o código sem precisar alternar para o WhatsApp. | Integração com Android, verificações de elegibilidade e aceitação dos termos aplicáveis. | Reduzir ainda mais a interação quando você puder testar as condições compatíveis. | 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](/pt/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) e [Documentação de autenticação da Meta](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/). Exemplo de autenticação da Meta com uma seta curta apontando para Copiar código. Fonte: [Modelos de mensagem de autenticação da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates/). ## 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 como `login_verification`. Escolha o idioma do seu cliente e registre o nome exato aprovado e o código de idioma para envio. Consulte [Criar modelo](/pt/documentation/channels/whatsapp-accounts-management/template-management/create-template/index). ### 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 contrato `supported_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](/pt/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/index) para obter detalhes sobre o SDK para Android e handshake. ### Configure três configurações de expiração separadas | Configuração | O que ela controla | Exemplo de cinco minutos | | - | - | - | | Expiração do código no backend | Quando o 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, correspondendo à sua política real. | | Tempo de vida de entrega (TTL) | Por quanto tempo a entrega pode ser tentada. | Não superior ao tempo de vida útil restante do código, considerando o tempo entre a geração e o envio. | 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](https://newdocs.ycloud.com/openapi/endpoints/ycloud-api-v2.yaml). 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](/pt/documentation/whatsapp-business-platform/messaging/message-templates/template-review-and-lifecycle). 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: | Endpoint | Comportamento | | - | - | | `POST /v2/whatsapp/messages/sendDirectly` | Envie de forma síncrona para a WhatsApp Business API; útil quando o fluxo de OTP precisa do resultado do envio imediatamente. | | `POST /v2/whatsapp/messages` | Coloque a mensagem na fila para envio assíncrono. | 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 `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 parâmetro `externalId` ajuda na reconciliação, mas não garante a idempotência. Exemplo de corpo da solicitação Copy code. Substitua os marcadores de posição; `123456` é fictício e deve ser gerado pelo seu sistema de verificação em produção: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 utilize a estrutura padrão de botão de cupom de marketing. Consulte [Autenticação Copy code](/pt/documentation/whatsapp-business-platform/messaging/message-templates/authentication-message-templates/copy-code-authentication) e [Enviar uma mensagem do WhatsApp](/pt/api-reference/guides/whatsapp-platform/send-whatsapp-message). 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 evento `whatsapp.message.updated`. Siga o [Guia de Webhook](/pt/documentation/developer/webhooks) para verificar assinaturas, confirmações de recebimento e novas tentativas. Associe cada ID de mensagem à sua respectiva solicitação de verificação: | Status | Significado | Resposta do fluxo | | - | - | - | | `sent` | Enviada, sem confirmação de chegada no dispositivo do cliente. | Aguarde as 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` | Falha no envio ou na entrega. | Inspecione o erro antes de corrigir configurações, tentar novamente ou trocar de canal. | 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](/pt/documentation/channels/whatsapp-accounts-management/data-analysis/message-logs) 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. | Estratégia | Quando se aplica | Experiência | | - | - | - | | WhatsApp primeiro, fallback por SMS | Seus dados mostram que os clientes usam predominantemente o WhatsApp. | Identifique o primeiro canal; ofereça SMS em caso de falha ou atraso, ou envie de acordo com uma política de fallback estabelecida. | | O cliente escolhe | Mercados, dispositivos ou preferências variam. | Ofereça WhatsApp e SMS juntos e lembre-se das preferências apropriadas. | 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 | Situação | Ação recomendada | | - | - | | Falha explícita | Classifique o erro. Use SMS quando a política de fallback permitir e o número e o código continuarem válidos. Corrija erros de chave de API, modelo ou conta em vez de apenas mascará-los com o fallback. | | Envio sem confirmação de entrega em tempo hábil | Use um tempo de espera configurável antes de oferecer outro canal ou aplicar o fallback. A ausência de confirmação não é prova de não entrega. | | Entregue sem conclusão da verificação | Mantenha as opções de entrada e nova tentativa disponíveis; não reenvie continuamente apenas porque a verificação está incompleta. | | Verificação concluída ou código expirado | Interrompa novos envios para esta solicitação. | 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 | Teste | Resultado esperado | | - | - | | Verificação normal | Os valores do corpo e do botão coincidem; um código correto e não expirado é aceito com sucesso. | | 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 do código antigo e do novo segue 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 do Android não suportadas | Um fallback utilizável permite que o cliente continue. | | iOS e múltiplos dispositivos | Teste a notificação, cópia e preenchimento nos clientes reais; não presuma um comportamento idêntico. | | Callbacks duplicados, atrasados ou tempo limite de solicitação | Não gere resultados duplicados nem reenvios descontrolados. | | Fallback por SMS | Use o destino correto e um código válido; pare após a verificação bem-sucedida. | 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. ## Cenário adicional: verificação iniciada pelo cliente Em um fluxo de verificação iniciado pelo cliente, o cliente abre o WhatsApp a partir de um aplicativo, envia uma mensagem contendo informações para a verificação atual e, em seguida, retorna ao aplicativo. Avalie isso separadamente. Uma mensagem de entrada comum do WhatsApp não é suficiente por si só para autenticar alguém em um site ou aplicativo. Essa abordagem requer um desafio único (one-time challenge), vinculação de sessão, expiração, proteção contra repetição (replay protection) e confirmação do usuário. O material citado da YCloud não estabelece um recurso de login pronto para uso, portanto este guia não o apresenta como uma etapa padrão de integração. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.