API de Gerenciamento do WhatsApp Business

Modelos de autenticação

Os modelos de autenticação ficarão disponíveis na Índia em 1º de julho de 2024.

Caso seu app para celular ofereça aos usuários a opção de receber senhas descartáveis ou códigos de verificação via WhatsApp, você precisará usar um modelo de autenticação.

Os modelos de autenticação são compostos pelo seguinte:

Texto predefinido fixo: <VERIFICATION_CODE> é seu código de verificação.
Um aviso legal opcional: Para sua segurança, não compartilhe este código.
Um aviso sobre validade opcional: Este código expirará em <NUM_MINUTES> minutos.
Um botão de preencher automaticamente com um toque, um botão de copiar código ou nenhum botão, caso o método usado seja sem toque.

Recomendamos o uso de botões de preencher automaticamente com um toque porque eles oferecem a melhor experiência ao usuário. No entanto, atualmente, esse tipo de botão só é compatível com Android e exige alterações no código do app.

Consulte as diretrizes adicionais sobre os contextos de uso apropriados.

Modelos de autenticação de preenchimento automático com um toque

Os modelos de autenticação incluem um botão de preencher automaticamente com um toque.

Quando um usuário do WhatsApp toca no botão de preenchimento automático, o cliente do WhatsApp dispara uma atividade que abre seu app e fornece a senha ou o código.

Consulte One-Tap Autofill Authentication Template para saber como usar esses modelos.

Modelos de autenticação de copiar código

Os modelos de autenticação de cópia de código permitem que você envie aos usuários uma senha ou um código descartável junto com um botão de copiar código.

Quando um usuário do WhatsApp toca no botão de copiar código, o cliente do WhatsApp copia a senha ou o código para a área de transferência do dispositivo. Depois disso, o usuário pode abrir o app e colar a senha ou o código na interface do software.

Consulte Copy Code Authentication Templates para saber como usar esses modelos.

Modelos de autenticação sem toque

Os modelos de autenticação sem toque permitem que seus usuários recebam senhas ou códigos descartáveis via WhatsApp sem precisar sair do app.

Quando um usuário solicita uma senha ou um código e você entrega essa chave usando um modelo de autenticação sem toque, o cliente do WhatsApp transmite a senha ou o código incluído, que pode ser capturado pelo seu app usando um receptor de transmissão.

Consulte Zero-Tap Authentication Templates para saber como usar esses modelos.

Boas práticas

Antes de enviar a senha ou o código descartável, verifique o número de telefone do WhatsApp do usuário.
Deixe claro para os usuários que a senha ou o código será enviado ao número de telefone do WhatsApp, especialmente se você oferecer diferentes métodos de recebimento. Consulte Obter aceitação para o WhatsApp para mais dicas.
Quando a senha ou o código for colado pelo usuário ou recebido como parte do fluxo de preenchimento automático no app, informe ao usuário que a captura foi bem-sucedida.

Veja também Best Practices for Authenticating Users via WhatsAppp.

Tempo de vida

Se não conseguirmos entregar uma mensagem a um usuário do WhatsApp, continuaremos tentando entregá-la por um período conhecido como tempo de vida.

Por padrão, as mensagens têm um tempo de vida de 30 dias, mas modelos de autenticação recém-criados têm um tempo de vida padrão de 10 minutos.

Se não conseguirmos entregar um modelo de autenticação após o período definido como tempo de vida, interromperemos as tentativas de envio e descartaremos a mensagem. Caso a solicitação de envio exceda o tempo de vida do modelo de autenticação e você não receba nenhum webhook, será possível presumir que a mensagem foi descartada.

Para substituir o tempo de vida padrão ao criar um modelo de autenticação, inclua a propriedade message_send_ttl_seconds com um valor entre 60 e 600 segundos.

Os modelos existentes criados antes da disponibilização dessa funcionalidade têm um tempo de vida de 30 dias. É possível editar um modelo existente e substituir o tempo de vida dele definindo a propriedade message_send_ttl_seconds.

Você também pode definir a propriedade message_send_ttl_seconds do modelo de autenticação como -1. Isso definirá o tempo de vida como 30 dias.

Recomendamos que você defina um tempo de vida para todos os modelos de autenticação, de preferência igual a ou menor que o tempo de expiração do código. Isso garantirá que seus clientes recebam a mensagem enquanto for possível usar o código.

Observação: pode haver um atraso na entrega do webhook de mensagem com falha. Por isso, talvez seja importante criar um pequeno buffer ao inferir o descarte da mensagem.

Enviar mensagens de modelo de autenticação

Use a API de Nuvem ou a API Local para enviar modelos de autenticação aprovados em uma mensagem.

Enviar modelos de autenticação (API de Nuvem)
Sending Authentication Message Templates with One-Time Password Buttons (API Local)

Prévias do modelo

É possível gerar prévias do texto do modelo de autenticação em vários idiomas que incluam ou excluam as strings de recomendação de segurança e de expiração do código usando o ponto de extremidade WhatsApp Business Account > Message Template Previews.

Sintaxe da solicitação

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

Parâmetros da string de consulta

Espaço reservado Descrição Valor de exemplo

Espaço reservado	Descrição	Valor de exemplo
`<LANGUAGE>` Lista separada por vírgulas	Opcional. Lista separada por vírgulas dos códigos de localidade e idioma das versões que você quer retornar. Em caso de omissão, as versões em todos os idiomas aceitos serão retornadas.	`en_US,es_ES`
`<ADD_SECURITY_RECOMMENDATION>` Booliano	Opcional. Defina como `true` se quiser que a string do corpo da recomendação de segurança seja incluída na resposta. Em caso de omissão, a string não será incluída.	`true`
`<CODE_EXPIRATION_MINUTES>` Int64	Opcional. Defina como um número inteiro se quiser que a string de rodapé da expiração do código seja incluída na resposta. Em caso de omissão, a string não será incluída. O valor indica o número de minutos até a expiração do código. Mínimo `1`, máximo `90`.	`10`
`<BUTTON_TYPES>` Lista de strings separadas por vírgulas	Obrigatório. Lista separada por vírgulas de strings que indicam o tipo de botão. Em caso de inclusão, a resposta exibirá o texto de cada botão. Nos modelos de autenticação, esse valor deve ser `OTP`.	`OTP`

<LANGUAGE>

Lista separada por vírgulas

Opcional.

Lista separada por vírgulas dos códigos de localidade e idioma das versões que você quer retornar.

Em caso de omissão, as versões em todos os idiomas aceitos serão retornadas.

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

Booliano

Opcional.

Defina como true se quiser que a string do corpo da recomendação de segurança seja incluída na resposta.

Em caso de omissão, a string não será incluída.

true

<CODE_EXPIRATION_MINUTES>

Int64

Opcional.

Defina como um número inteiro se quiser que a string de rodapé da expiração do código seja incluída na resposta.

Em caso de omissão, a string não será incluída.

O valor indica o número de minutos até a expiração do código.

Mínimo 1, máximo 90.

10

<BUTTON_TYPES>

Lista de strings separadas por vírgulas

Obrigatório.

Lista separada por vírgulas de strings que indicam o tipo de botão.

Em caso de inclusão, a resposta exibirá o texto de cada botão.

Nos modelos de autenticação, esse valor deve ser OTP.

OTP

Exemplo de solicitação

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

Gerenciamento em massa

Use o ponto de extremidade WhatsApp Business Account > Upsert Message Templates para atualizar ou criar modelos de autenticação em massa e em vários idiomas que incluam ou excluam os avisos opcionais de segurança e expiração.

Se já houver um modelo com o nome e o idioma correspondentes, ele será atualizado com o conteúdo da solicitação. Caso contrário, um novo modelo será criado.

Sintaxe da solicitação

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Corpo da publicação

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-tap buttons only
        }
      ]
    }
  ]
}

Propriedades

Todas as propriedades de criação de modelos são compatíveis, exceto estas:

A propriedade language é incompatível. Como alternativa, use languages e defina o valor como uma matriz de strings de código de localidade e idioma. Por exemplo: ["en_US","es_ES","fr"].
A propriedade text é incompatível.
A propriedade autofill_text é incompatível.

Exemplo de solicitação para copiar código

Este exemplo cria três modelos de autenticação (em inglês, espanhol e francês) com botões de copiar código. Cada modelo recebe o nome de "authentication_code_copy_code_button" e inclui a recomendação de segurança e o tempo de expiração.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

Exemplo de solicitação para preencher automaticamente com um toque

Este exemplo (1) atualiza um modelo existente com o nome "authentication_code_autofill_button" e o idioma "en_US" e (2) cria dois novos modelos de autenticação (em espanhol e francês) com botões de preencher automaticamente com um toque. Os dois modelos recém-criados recebem o nome de "authentication_code_autofill_button" e incluem a recomendação de segurança e o tempo de expiração.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

Exemplo de resposta

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

Exemplo de app

Consulte o exemplo de app de senha descartável do WhatsApp para Android no GitHub. O exemplo de app demonstra como enviar e receber códigos e senhas descartáveis por meio da API, como integrar botões de preenchimento automático com um toque e de copiar código, como criar modelos e como rotacionar um exemplo de servidor.

Veja também

Conta comercial oficial: você pode querer solicitar o status de conta comercial oficial para gerar confiança nos usuários, o que reduzirá a probabilidade de eles dispensarem ou ignorarem suas mensagens.
Configuração de Webhooks: recomendamos que você assine o campo de mensagens do webhook para receber notificações quando seu modelo de autenticação com um botão de senha descartável for entregue e lido. Consulte Configuração de Webhooks (API de Nuvem) ou Webhooks para a API Local.