Envie códigos de verificação (OTP) pelo WhatsApp
Para enviar um código de verificação (OTP) pelo WhatsApp, a empresa cria um template de autenticação, o formato fixo da Meta "<código> é o seu código de verificação." com um botão de copiar código ou de um toque, e o seu backend envia esse template pela Cloud API com o código preenchido duas vezes, no corpo e no botão. Os códigos têm até 15 caracteres, e o aviso opcional de validade vai de 1 a 90 minutos.
O easyCoexistence conecta o seu número do WhatsApp Business à Cloud API da Meta pela Coexistência e dá ao seu backend o que ele precisa para enviar templates de autenticação: o endpoint de envio, o token de acesso e, pela sua IA, create_template e get_template_status.
Tamanho máximo do parâmetro aceito por um template de autenticação; URLs, mídia e emojis não são permitidos no conteúdo nem nos parâmetros.
Faixa de code_expiration_minutes, que acrescenta a linha "Este código expira em N minutos." à mensagem.
Tempo de vida (TTL) padrão de um template de autenticação; pode ser definido entre 30 segundos e 15 minutos.
Erro retornado quando um template de autenticação é enviado a um ID de usuário com escopo de negócio em vez de um número de telefone.
As mensagens de autenticação são entregues apenas no dispositivo principal do WhatsApp do usuário; os dispositivos vinculados mostram um aviso em vez da mensagem.
Throughput fixo de um número com Coexistência, o teto para um pico de códigos de login.
O que é um template de autenticação do WhatsApp?
É o único formato que a Meta permite para senhas de uso único e códigos de verificação: se um app oferece códigos pelo WhatsApp, precisa usar esse template, e templates de utilidade ou de marketing não podem levar códigos de acesso. O texto é fixo, "<código> é o seu código de verificação.", com duas linhas opcionais, "Para sua segurança, não compartilhe este código." e "Este código expira em <N> minutos." O que você escolhe é o botão. O WhatsApp desativa o encaminhamento dessas mensagens e, no iOS 26 ou posterior, o código também aparece como sugestão no teclado, sem nenhum esforço da sua parte.
Como criar o template de autenticação?
Selecione o template na Template Library do WhatsApp Manager ou envie-o pela API, algo que sua IA pode fazer com create_template e a categoria AUTHENTICATION. Você não envia texto de corpo: a Meta o escreve a partir das suas configurações, no idioma escolhido, e transforma o botão OTP em um botão de URL ao criar o template. É um template por idioma. O create_template do conector não passa message_send_ttl_seconds, então vale o tempo de vida (TTL) padrão de 10 minutos, a menos que você o altere pela API da Meta.
{
"connection_id": "<from list_numbers>",
"name": "login_code",
"language": "en_US",
"category": "AUTHENTICATION",
"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" }
]}
]
}Como o seu backend envia o código?
Com uma requisição por código ao endpoint /messages do número, usando o token de acesso obtido em get_api_credentials ou no card "Plug in your own system" do painel. O mesmo código vai duas vezes, no parâmetro do corpo e no parâmetro do botão de URL no índice 0, e o destinatário precisa ser um número de telefone. Antes do envio, o backend gera o código e armazena um hash dele com um horário de expiração e um contador de tentativas; depois, compara o que o usuário digita com esse hash.
POST https://graph.facebook.com/<VERSION>/<PHONE_NUMBER_ID>/messages
Authorization: Bearer <ACCESS_TOKEN>
{
"messaging_product": "whatsapp",
"to": "5511987654321",
"type": "template",
"template": {
"name": "login_code",
"language": { "code": "en_US" },
"components": [
{ "type": "body",
"parameters": [{ "type": "text", "text": "482913" }] },
{ "type": "button", "sub_type": "url", "index": "0",
"parameters": [{ "type": "text", "text": "482913" }] }
]
}
}Por que o código vem do seu backend e não de uma automação?
Porque o sistema que faz o login do usuário precisa criar o código, guardá-lo e verificá-lo, e só esse sistema sabe quando um código é necessário. As automações respondem às mensagens que os clientes enviam, e uma tela de login nunca manda mensagem para o seu número. O próprio template também impede o uso de automações: o botão OTP leva o código como variável de botão, e a etapa Send a template preenche apenas variáveis do corpo, então não consegue enviar um template de autenticação. Sua IA pode enviar um pelo send_template, que passa componentes de botão para a Meta, mas isso serve para testar, não para um fluxo de login.
O que torna um fluxo de OTP no WhatsApp seguro?
As boas práticas da Meta e os limites do formato levam à mesma lista de verificação. Nenhum item exige nada além do seu backend e da Cloud API:
- Confirme o número de WhatsApp com o usuário antes do primeiro código e avise que o código chegará pelo WhatsApp.
- Defina o tempo de vida (TTL) igual ou menor que a validade do código, para que uma entrega atrasada nunca mostre um código já vencido.
- Limite tentativas e reenvios por número e invalide cada código no primeiro uso.
- Não use o código do WhatsApp como único fator de recuperação de conta: números de telefone reciclados ainda podem acessar uma conta antiga do WhatsApp.
- Acompanhe o webhook de status e ofereça SMS ou e-mail quando um código não for entregue.
O que muda quando o número também é usado no app do WhatsApp Business?
O envio funciona como em qualquer número da Cloud API, com até 20 mensagens por segundo. A Meta espelha as mensagens enviadas pela API nas conversas do app, então, em um número com Coexistência, os códigos que você envia também aparecem nessas conversas no celular da empresa; deixe esse celular só com pessoas de confiança ou envie os códigos de um número separado. As boas práticas da Meta também pedem que cada empresa envie templates de autenticação do próprio número, nunca de um número compartilhado entre empresas. Autenticação é uma categoria de template paga, cobrada por mensagem entregue conforme o país do destinatário, com tarifas separadas de autenticação internacional em alguns mercados; o easyCoexistence não cobra margem.
Como configurar
- Connect the numberConnect your WhatsApp Business number to easyCoexistence through Meta's Coexistence flow, or use a separate number reserved for codes.
- Create the authentication templateAsk your AI to submit login_code with create_template, category AUTHENTICATION, a copy-code button and an expiry, then check get_template_status for APPROVED.
- Store the credentials on your serverCall get_api_credentials or open "Plug in your own system" in the dashboard, and put the Send endpoint and access token in your backend's secrets.
- Build generate, send and verifyGenerate the code, store its hash with an expiry, send the template with the code in the body and button, then check the user's entry against the hash.
- Handle failuresRead failed statuses from the number's webhook, then offer SMS or email and show the user which number the code went to.
Erros comuns
- Colocar o código em um template de utilidade, como "Seu código é {{1}}". A Meta só permite códigos de acesso em templates de autenticação e rejeita templates de utilidade ou de marketing que encontra com eles.
- Enviar o código apenas no corpo. O botão de copiar código precisa do mesmo valor como parâmetro; a Meta espera o código duas vezes na requisição.
- Manter um tempo de vida (TTL) de 30 dias em um template de autenticação antigo. Aí, um celular que fica offline por uma hora recebe um código já vencido; defina o TTL igual ou menor que a validade do código.
- Endereçar o código a um ID de usuário com escopo de negócio. Templates de autenticação só vão para números de telefone, e a Meta retorna o erro 131062.
O número é monitorado 24/7, então uma desconexão que interromperia os códigos de login chega até você por e-mail. De R$ 29,90 a R$ 3,90 por número por mês, com o preço caindo conforme você adiciona números, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
OTP pelo WhatsApp sai mais barato que código por SMS?
Depende do país. A Meta cobra cada mensagem de autenticação entregue pela tarifa do país do destinatário, com tarifas especiais em alguns mercados, e os preços de SMS variam por operadora e rota. Compare a tabela de tarifas da Meta com a do seu provedor de SMS nos seus principais países antes de trocar.
Isso é o mesmo que o PIN da verificação em duas etapas do WhatsApp?
Não. A verificação em duas etapas é o PIN de seis dígitos que protege o próprio número de WhatsApp da empresa. Um template de autenticação envia um código aos seus clientes para que o seu app ou site confirme quem eles são.
Os usuários precisam dar consentimento (opt-in) para receber os códigos?
Sim. A política da Meta exige permissão antes que uma empresa envie mensagens a alguém, e as orientações da Meta sobre OTP sugerem oferecer opções de canal, como WhatsApp, SMS ou e-mail. Escolher o WhatsApp na tela de login, ao lado do número, é essa permissão.
Uma agência pode enviar códigos de vários clientes por um único número?
Não. As boas práticas da Meta exigem que cada empresa tenha a própria conta do WhatsApp Business e o próprio número de telefone para templates de autenticação; compartilhar um número entre empresas viola os termos e a política da Meta. Em vez disso, conecte um número por cliente.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em