Números de teléfono

Esta guía explica cómo verificar tu número de teléfono y el formato requerido para la API de nube.

Existe un criterio para el tipo de números de teléfono que puedes añadir a la cuenta de WhatsApp Business (WABA). Consulta Números de teléfono para obtener más información.

Algunas de las llamadas a la API enumeradas requieren que conozcas el identificador de tu número de teléfono. Consulta Obtener todos los números de teléfono para saber cómo conseguir los números de teléfono asociados a tu WABA. La respuesta de la llamada a la API incluye identificadores para cada uno de los números de teléfono conectados a tu cuenta de WhatsApp Business. Guarda el identificador del teléfono que quieres utilizar con las llamadas a /PHONE_NUMBER_ID.

Verificar números de teléfono

Tienes que verificar el número de teléfono que quieres utilizar para enviar mensajes a tus clientes. Los números de teléfono deben verificarse con un código enviado mediante SMS/llamada de voz. El proceso de verificación puede llevarse a cabo a través de las llamadas a API Graph especificadas a continuación.

Para verificar un número de teléfono mediante API Graph, haz una solicitud POST a PHONE_NUMBER_ID/request_code. En la llamada, incluye el método y el idioma de verificación 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 el 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'

Las respuestas que se completan correctamente tienen este aspecto:

{
  "success": true
}

Comprobación del cambio de identidad

Es posible que quieras que verifiquemos la identidad de un cliente antes de entregarle un mensaje. Para que podamos hacerlo, activa la opción de configuración de comprobación del cambio de identidad en tu número de teléfono de empresa.

Si un cliente realiza una acción en WhatsApp que consideramos un cambio de identidad, generaremos un nuevo hash de identidad para el usuario. Puedes obtener este hash cuando envías un mensaje al cliente; para ello, activa la opción de configuración de comprobación del cambio de identidad en tu número de teléfono de empresa. Una vez que esté activada, siempre que un cliente te envíe un mensaje o tú le envíes un mensaje sin un hash de identidad, incluiremos su hash en todos los webhooks de mensajes entrantes o los webhooks de estado de la entrega. En ese momento puedes capturar y almacenar dicho hash para futuros usos.

Para usar el hash, inclúyelo en una solicitud de envío de mensaje. Nosotros compararemos el hash de la solicitud con el hash actual del cliente. Si coinciden, el mensaje se entregará. Si no coinciden, significa que el cliente ha cambiado de identidad desde la última vez que le enviaste un mensaje y no entregaremos el mensaje. En su lugar, te notificaremos acerca del fallo y el error de coincidencia mediante un webhook de estado del mensaje con el código de error 137000.

Cuando recibas un webhook de error de coincidencia en el hash, asume que ya no puedes confiar en el número de teléfono del cliente. Para restablecer la confianza, vuelve a verificar la identidad del cliente usando canales distintos de WhatsApp. Una vez que hayas restablecido la confianza, vuelve a enviar el mensaje que no se pudo entregar anteriormente a la nueva identidad (si existe) sin hash. Después, almacena el nuevo hash del cliente incluido en el webhook de estado de entrega del mensaje.

Sintaxis de la solicitud

Envía una solicitud POST al extremo Número de teléfono de WhatsApp Business > Configuración para activar o desactivar la opción de configuración de comprobación del 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>
}

Establece <ENABLE_IDENTITY_KEY_CHECK> en true para activar la comprobación de identidad, o en false para desactivarla.

Ejemplo de solicitud de activació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 activación

{
  "success": true
}

Ejemplo de envío de mensaje con comprobación

Este mensaje de ejemplo solo se entrega si el valor de hash de recipient_identity_key_hash coincide con el hash 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 hash 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 la entrega

En los webhooks de estado de la entrega, el hash 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 con errores

En los webhooks de estado de la entrega, el hash 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 rendimiento

Utiliza el extremo del número de teléfono de WhatsApp Business para obtener el nivel de rendimiento actual de un número de teléfono:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput