Números de teléfono

En esta guía, se especifica cómo puedes verificar tu número de teléfono y el formato que debe tener para la API de la nube.

Existe un criterio que determina qué tipo de números de teléfono puedes agregar a tu cuenta de WhatsApp Business (WABA). Para obtener más información, consulta Números de teléfono.

Algunas llamadas a la API mencionadas requieren que conozcas el identificador de tu número de teléfono. Consulta Obtener todos los números de teléfono para conocer cómo lograr asociar los números de teléfono a tu WABA. La respuesta de la llamada a la API incluye los identificadores de los números de teléfono conectados a tu cuenta de WhatsApp Business. Guarda el identificador del teléfono que quieres usar con cualquiera de las llamadas a /PHONE_NUMBER_ID.

Verificar números de teléfono

Es necesario que verifiques el número de teléfono que quieres usar para enviar mensajes a tus clientes. La verificación de los números de teléfono debe realizarse mediante un código que se envía por SMS o llamada de voz. El proceso de verificación puede completarse mediante las llamadas a la API Graph que se especifican a continuación.

Para verificar un número de teléfono con la API Graph, realiza una solicitud POST a PHONE_NUMBER_ID/request_code. En la llamada, incluye el método de verificación y el idioma elegidos.

Parámetros

Ejemplo:

Ejemplo de solicitud:

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'

Después de la llamada a la API, recibirás tu código de verificación mediante el método que hayas seleccionado. Para finalizar el proceso de verificación, incluye el código en una solicitud POST a PHONE_NUMBER_ID/verify_code.

Parámetros

Ejemplo:

Ejemplo de solicitud:

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

Una respuesta correcta tiene este aspecto:

{
  "success": true
}

Comprobación de cambio de identidad

Puede que quieras que verifiquemos la identidad de un cliente antes de que le entreguemos tu mensaje. Para ello, tienes que habilitar la opción de comprobación de cambio de identidad en tu número de teléfono del negocio.

Si un cliente realiza una acción en WhatsApp que consideramos un cambio de identidad, generamos un nuevo cifrado de identidad para ese usuario. Puedes obtener ese cifrado cuando envías un mensaje al cliente mediante la habilitación de la opción de comprobación de cambio de identidad en tu número de teléfono del negocio. Una vez habilitada la opción, cada vez que el cliente te envíe un mensaje o que tú le envíes un mensaje al cliente sin un cifrado de identidad, nosotros incluiremos su cifrado en cualquier webhook de mensaje entrante o de estado de entrega. Puedes capturar y almacenar el cifrado para usarlo en el futuro.

Para usar el cifrado, debes incluirlo en una solicitud de envío de mensaje. Compararemos el cifrado de la solicitud con el cifrado actual del cliente. Si los cifrados coinciden, se entregará el mensaje. Si, por el contrario, no coinciden, quiere decir que el cliente cambió su identidad desde la última vez que le enviaste un mensaje y no entregaremos el mensaje. En cambio, te enviaremos un webhook de estado de mensaje con el código de error 137000, que te notificará sobre el error y la falta de coincidencia.

Cuando recibes un webhook de este tipo, debes asumir que el número de teléfono del cliente ya no es de confianza. Para restablecer la confianza, verifica nuevamente la identidad del cliente usando otros canales que no sean de Whatsapp. Una vez que hayas restablecido la confianza, vuelve a enviar el mensaje fallido a la nueva identidad (si la hay), sin un cifrado. Luego, almacena el nuevo cifrado del cliente incluido en el webhook de entrega de estado del mensaje.

Sintaxis de la solicitud

Envía una solicitud POST al punto de conexión Número de teléfono del negocio de WhatsApp Business > Configuración para habilitar o inhabilitar la opción de comprobación de cambio de identidad.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Cuerpo de la solicitud POST

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

Configura <ENABLE_IDENTITY_KEY_CHECK> en true para habilitar la comprobación de identidad o false para inhabilitarla.

Ejemplo de solicitud de habilitación

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

Ejemplo de respuesta de habilitación

{
  "success": true
}

Ejemplo de envío de mensaje con comprobación

Este mensaje de ejemplo solo se enviaría si el valor de cifrado de recipient_identity_key_hash coincide con el cifrado actual del cliente.

curl 'https://graph.facebook.com/v19.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... "
    }
}'

Ejemplo de webhook de mensaje entrante

En los webhooks de mensajes entrantes, el cifrado del cliente se asigna a la propiedad 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"
        }
      ]
    }
  ]
}

Ejemplo de webhook de estado de entrega

En los webhooks de estado de entrega, el cifrado del cliente se asigna a la propiedad 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"
        }
      ]
    }
  ]
}

Ejemplo de webhook de estado de entrega fallido

En los webhooks de estado de entrega, el cifrado del cliente se asigna a la propiedad 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"
        }
      ]
    }
  ]
}

Obtener el nivel de volumen

Utiliza el punto de conexión número de teléfono de WhatsApp Business para obtener el nivel actual de volumen de un número de teléfono:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput