Números de telefone

Este guia descreve o processo de verificação do número de telefone e sua formatação necessária para a API de Nuvem.

Existem critérios em relação aos tipos de número de telefone que podem ser adicionados à conta do WhatsApp Business (WABA, pelas iniciais em inglês). Para ver mais informações, consulte Números de telefone.

Para algumas chamadas de API listadas, é preciso que você saiba o ID do número de telefone. Se você quiser receber uma lista dos números de telefone associados à WABA, consulte Obter todos os números de telefone. A resposta à chamada de API inclui o ID de cada um dos números de telefone conectados à sua conta do WhatsApp Business. Salve o ID correspondente ao número de telefone que você quer usar nas chamadas /PHONE_NUMBER_ID.

Verificar números de telefone

É preciso verificar o número de telefone que você quer usar para enviar mensagens aos clientes. Os números de telefone devem ser verificados por meio de um código enviado por SMS ou ligação de voz. O processo de verificação pode ser feito a partir das chamadas da Graph API especificadas a seguir.

Para verificar um número de telefone usando a Graph API, faça uma solicitação POST a PHONE_NUMBER_ID/request_code. Na chamada, inclua o idioma e o método de verificação escolhido.

Parâmetros

Exemplo

Exemplo de solicitação:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

Depois da chamada de API, você receberá o código de verificação por meio do método selecionado. Para concluir o processo de verificação, inclua o código em uma solicitação POST a PHONE_NUMBER_ID/verify_code.

Parâmetros

Exemplo

Exemplo de solicitação:

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

A resposta bem-sucedida é semelhante a esta:

{
  "success": true
}

Verificação de alteração de identidade

Podemos verificar a identidade de um cliente antes de enviarmos sua mensagem para ele. Para isso, habilite a verificação de alteração de identidade no seu número de telefone comercial.

Se o cliente realizar uma ação no WhatsApp que considerarmos uma alteração de identidade, geraremos um novo hash de identidade para ele. Com essa configuração habilitada, você poderá obter esse hash sempre que enviar uma mensagem ao cliente. Nesse caso, sempre que você receber ou enviar uma mensagem para um cliente sem um hash de identidade, incluiremos o hash dele nos webhooks de mensagem recebida ou status de entrega. Assim, você pode capturar e armazenar esse hash para uso futuro.

Quando quiser usar o hash, inclua-o na solicitação de envio de mensagem. Compararemos o hash da solicitação com o atual do cliente. Se eles forem iguais, a mensagem será entregue. Caso haja incompatibilidade, isso significa que a identidade do cliente foi alterada depois do seu último contato com ele. Por isso, não entregaremos a mensagem. Em vez disso, enviaremos um webhook de status de mensagem com o código de erro 137000, notificando sobre a falha e a discrepância dos hashes.

Ao receber esse tipo de webhook, considere que o número de telefone do cliente deixou de ser confiável. Para reestabelecer a confiança, verifique a identidade do cliente por meio de outro canal que não seja o WhatsApp. Depois, reenvie a mensagem com falha para a nova identidade (se houver), sem um hash. Armazene, então, o novo hash do cliente incluído no webhook de status de entrega.

Sintaxe da solicitação

Envie uma solicitação POST ao ponto de extremidade WhatsApp Business Phone Number > Settings para habilitar ou desabilitar a verificação de alteração de identidade.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Corpo da publicação

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

Defina <ENABLE_IDENTITY_KEY_CHECK> como true para habilitar a verificação de identidade ou como false para desabilitá-la.

Exemplo de solicitação para habilitar a configuração

curl 'https://graph.facebook.com/v21.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

Exemplo de resposta a essa solicitação

{
  "success": true
}

Exemplo de envio de mensagem com verificação

Esta mensagem só seria entregue se o valor recipient_identity_key_hash correspondesse ao hash atual do cliente.

curl 'https://graph.facebook.com/v21.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

Exemplo de webhook de mensagem recebida

Em webhooks de mensagem recebida, o hash do cliente é atribuído à propriedade identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Exemplo de webhook de status de entrega

Em webhooks de status de entrega, o hash do cliente é atribuído à propriedade recipient_identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Exemplo de webhook de status de falha na entrega

Em webhooks de status de entrega, o hash do cliente é atribuído à propriedade recipient_identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Como obter o nível da taxa de transferência de dados

Use o ponto de extremidade WhatsApp Business Phone Number para obter o nível da taxa de transferência de dados atual de um número de telefone:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput