Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Enviar códigos de verificação (OTP) no WhatsApp

Para enviar um código de verificação (OTP) no WhatsApp, a empresa cria um template de autenticação, o formato fixo da Meta "<code> is your verification code.", com um botão de copiar código ou de um toque, e o seu backend envia-o pela Cloud API com o código preenchido duas vezes, no corpo e no botão. Os códigos podem ter até 15 caracteres, e o aviso opcional de validade vai de 1 a 90 minutos.

A easyCoexistence liga o seu número de WhatsApp Business à Cloud API da Meta através da Coexistence e dá ao seu backend o que precisa para enviar templates de autenticação: o endpoint de envio, o token de acesso e, através da sua IA, create_template e get_template_status.

15 characters

O parâmetro mais longo que um template de autenticação aceita; URL, multimédia e emojis não são permitidos no conteúdo nem nos parâmetros.

1 to 90 minutes

Intervalo de code_expiration_minutes, que acrescenta à mensagem a linha "This code expires in N minutes."

10 minutes

Tempo de vida (TTL) predefinido de um template de autenticação; pode ser definido entre 30 segundos e 15 minutos.

131062

Erro devolvido quando um template de autenticação é enviado para um ID de utilizador com âmbito de empresa, em vez de um número de telefone.

Primary device

As mensagens de autenticação são entregues apenas ao dispositivo principal do WhatsApp do utilizador; os dispositivos associados veem um aviso em vez disso.

20 msg/s

Throughput fixo de um número Coexistence, o teto para uma rajada de códigos de início de sessão.

O que é um template de autenticação do WhatsApp?

O único formato permitido pela Meta para palavras-passe de utilização única e códigos de verificação: se uma aplicação oferece códigos pelo WhatsApp, tem de usar um destes, e os templates de utilidade ou de marketing não podem conter uma palavra-passe. O texto é fixo, "<code> is your verification code.", com duas linhas opcionais, "For your security, do not share this code." e "This code expires in <N> minutes." A escolha que faz é o botão. O WhatsApp desativa o reencaminhamento destas mensagens e, no iOS 26 e posteriores, o código também é sugerido no teclado sem qualquer trabalho da sua parte.

Copy codeTapping copies the code to the clipboard; the user pastes it in your app or site
One-tap autofillAndroid: the button opens your app and hands it the code; needs app changes and a handshake
Zero-tapAndroid only, no button: your app receives the code through a broadcast receiver

Como se cria o template de autenticação?

Escolha-o na Template Library no WhatsApp Manager, ou submeta-o através da API, o que a sua IA pode fazer com create_template e a categoria AUTHENTICATION. Não envia nenhum texto no corpo: a Meta escreve-o a partir das suas definições, no idioma escolhido, e transforma o botão OTP num botão de URL na criação. Um template por idioma. O create_template do conector não transmite message_send_ttl_seconds, por isso aplica-se o tempo de vida predefinido de 10 minutos, a não ser que o altere através da API da Meta.

create_template arguments for a copy-code template
{
  "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 é que o seu backend envia o código?

Um pedido ao endpoint /messages do número por cada código, com o token de acesso obtido em get_api_credentials ou no cartão "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 tem de ser um número de telefone. Antes de enviar, o backend gera o código, guarda um hash dele com um prazo de validade e um contador de tentativas e, depois, compara o que o utilizador escreve com esse hash.

Sending a login code from your backend
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" }] }
    ]
  }
}

Porque é que o código vem do backend e não de uma automação?

Porque o sistema que autentica o utilizador tem de criar o código, memorizá-lo e verificá-lo, e só esse sistema sabe quando é preciso um código. As automações respondem a mensagens que os clientes enviam, e um ecrã de início de sessão nunca escreve para o seu número. O próprio template também as exclui: o botão OTP leva o código como variável do botão, e o passo Send a template preenche apenas variáveis do corpo, por isso não consegue enviar um template de autenticação. A sua IA pode enviar um através de send_template, que passa componentes de botão à Meta, mas isso serve para um teste, não para um fluxo de início de sessão.

O que torna um fluxo de OTP do WhatsApp seguro?

As melhores práticas da Meta e os limites do formato apontam para a mesma lista de verificação. Nada disto exige mais do que o seu backend e a Cloud API:

  • Confirme o número de WhatsApp com o utilizador antes do primeiro código, e diga que o código chegará pelo WhatsApp.
  • Defina o tempo de vida igual ou inferior à validade do código, para que uma entrega tardia nunca mostre um código expirado.
  • Limite as tentativas e os reenvios por número, e expire os códigos na primeira utilização.
  • Não torne o código do WhatsApp o único fator para recuperar a conta: números de telefone reciclados ainda podem chegar a uma conta antiga do WhatsApp.
  • Vigie o webhook de estado e ofereça SMS ou email quando um código não for entregue.

O que muda quando o número também está na aplicação WhatsApp Business?

O envio funciona como em qualquer número da Cloud API, até 20 mensagens por segundo. A Meta replica para as conversas da aplicação as mensagens enviadas pela API, por isso, num número Coexistence, os códigos que envia também aparecem nessas conversas no telemóvel da empresa; mantenha esse telemóvel com pessoas em quem confie, ou envie os códigos a partir de um número separado. As melhores práticas da Meta também pedem que cada empresa envie templates de autenticação a partir do seu próprio número, nunca de um número partilhado entre empresas. A autenticação é uma categoria de template pago, cobrada por mensagem entregue conforme o país do destinatário, com tarifas de autenticação internacional separadas em alguns mercados; o easyCoexistence não aplica qualquer margem.

Como configurar

  1. Connect the numberConnect your WhatsApp Business number to easyCoexistence through Meta's Coexistence flow, or use a separate number reserved for codes.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  • Escrever o código num template de utilidade, como "Your code is {{1}}". A Meta só permite palavras-passe em templates de autenticação e rejeita os de utilidade ou de marketing que as tenham.
  • Enviar o código apenas no corpo. O botão de copiar código precisa do mesmo valor no seu parâmetro; a Meta espera o código duas vezes no pedido.
  • Manter um tempo de vida de 30 dias num template de autenticação antigo. Um telemóvel sem ligação durante uma hora recebe um código expirado; defina-o igual ou inferior à validade do código.
  • Dirigir o código a um ID de utilizador com âmbito de empresa. Os templates de autenticação vão apenas para números de telefone, e a Meta devolve o erro 131062.
Fazer isto com a EasyCoexistence

O número é monitorizado 24 horas por dia, por isso uma desligação que pararia os códigos de início de sessão chega-lhe por email. A partir de US$ 9 por número ligado por mês, descendo até US$ 0.75 à medida que adiciona números, com os primeiros 3 dias grátis.

Perguntas frequentes

É o OTP do WhatsApp mais barato do que um código por SMS?

A cobrança da Meta é por mensagem entregue, à tarifa do país do destinatário, com tarifas especiais em alguns mercados; os preços de SMS variam por operadora e rota. Compare a tabela de tarifas da Meta com a do seu fornecedor de SMS para os seus principais países antes de mudar.

É o mesmo que o PIN de verificação em dois passos do WhatsApp?

Não. A verificação em dois passos é o PIN de seis dígitos que protege o número do WhatsApp Business da própria empresa. Um template de autenticação envia um código aos seus clientes para que a sua aplicação ou site confirme quem eles são.

Os utilizadores têm de dar consentimento para receber códigos?

Sim. A política da Meta exige permissão antes de uma empresa enviar mensagens a alguém, e as suas orientações sobre OTP sugerem oferecer uma escolha de canais, como WhatsApp, SMS ou email. Escolher o WhatsApp no ecrã de início de sessão, junto ao número, é essa permissão.

Uma agência pode enviar códigos de vários clientes a partir de um só número?

Não. As melhores práticas da Meta exigem que cada empresa tenha a sua própria conta WhatsApp Business e o seu próprio número de telefone para os templates de autenticação; partilhar um número entre empresas viola as condições e a política da Meta. Ligue um número por cliente.

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em