Números de teléfono verificados previamente

En este documento se explica cómo ofrecer a los clientes finales números de teléfono de empresa verificados previamente en el nuevo proceso de registro insertado. Los números de teléfono de empresa verificados previamente son números de teléfono de empresa que ya has verificado, de modo que se elimina la necesidad de que los clientes finales se pongan en contacto contigo para obtener una contraseña de un solo uso.

Ten en cuenta que los números de teléfono de empresa verificados previamente se representan mediante objetos de números de teléfono verificados previamente de WhatsApp Business, que son temporales. Cuando un cliente final selecciona uno de estos números y completa el nuevo proceso de registro insertado, el objeto temporal se substituirá por un objeto de número de teléfono de WhatsApp Business y deberás obtener el identificador del nuevo objeto para registrar el número.

Requisitos

• Tu empresa debe ser un proveedor de soluciones aprobado.
• El usuario de la aplicación debe ser un administrador de la empresa en la cuenta empresarial a la que se añadan los números de teléfono de empresa verificados previamente.
• Un identificador de acceso de usuario o de usuario del sistema.
• El permiso business_management.
• Los números de teléfono de empresa deben ser válidos.

Limitaciones

• Solo están disponibles con el nuevo proceso de registro insertado. Consulta el documento Insertar el proceso de registro para obtener información sobre cómo activar el nuevo proceso.
• Eres responsable de hacer un seguimiento del usuario que haya reclamado un número de teléfono de empresa verificado previamente.
• Si ningún cliente final reclama un número de teléfono de empresa verificado previamente en el proceso de registro insertado en los 90 días posteriores a la verificación, el número se revertirá a un estado sin verificar y se deberá volver a verificar para que el estado se restaure durante otros 90 días.
• Los números de teléfono de empresa verificados previamente que no se reclamen no pueden volver a verificarse hasta 45 días antes de que su estado se revierta a sin verificar. Este tiempo se indica en el campo verification_expiry_time.
• Si añades un número de teléfono a tu grupo de números de teléfono de empresa verificados previamente (Paso 1), pero no lo verificas en un plazo de 90 días (Paso 3), se eliminará del grupo y tendrás que volver a añadirlo.

Crear números verificados previamente

Sigue estos pasos para crear un número de teléfono de empresa verificado previamente, mostrarlo en el proceso de registro insertado y registrarlo después de que un cliente final lo haya reclamado.

Paso 1: Crear un número de teléfono de empresa verificado previamente

Usa el extremo Cuenta empresarial > Añadir números de teléfono para crear un número de teléfono de empresa verificado previamente en tu negocio. Esta operación lo añade a tu grupo de números.

Sintaxis de la solicitud

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

Respuesta

Cuando esta operación se realice correctamente, la API devolverá el identificador de un número de teléfono verificado previamente de WhatsApp Business. Captura este valor para utilizarlo en la siguiente solicitud.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

Ejemplo de solicitud

curl -X POST 'https://graph.facebook.com/v20.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "id": "106540352242922"
}

Consulta los formatos de los números de teléfono y los parámetros de consulta admitidos en la referencia del extremo Cuenta empresarial > Añadir números de teléfono.

Paso 2: Solicitar un código de verificación

Usa el extremo Número de teléfono verificado previamente de WhatsApp Business > Solicitar código a fin de solicitar una contraseña de un solo uso por SMS o mensaje de voz para el número de teléfono de empresa verificado previamente que se acaba de crear.

Sintaxis de la solicitud

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

Respuesta

Cuando esta operación se realice correctamente, la API devolverá true.

{
  "success": <SUCCESS>
}

Además, enviaremos un SMS o mensaje de voz con una contraseña de un solo uso al número de teléfono. Captura la contraseña de un solo uso para utilizarla en la siguiente solicitud.

Sintaxis del SMS de la contraseña de un solo uso

WhatsApp code <CODE>

Sintaxis del mensaje de voz de la contraseña de un solo uso

Se repite tres veces.

Verification code is <CODE>

Ejemplo de solicitud

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "success": true
}

Ejemplo del mensaje SMS de la contraseña de un solo uso

WhatsApp code 123-456

Ejemplo del mensaje de voz de la contraseña de un solo uso

Se repite tres veces.

Verification code is 123456

Consulta los métodos de código, lenguajes y parámetros de consulta admitidos en la referencia del extremo Número de teléfono verificado previamente de WhatsApp Business > Solicitar código.

Paso 3: Verificar el número

Usa el extremo Número de teléfono verificado previamente de WhatsApp Business > Verificar código para verificar el número de teléfono de empresa con la contraseña de un solo uso correspondiente.

Sintaxis de la solicitud

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

Respuesta

Cuando esta operación se realice correctamente, la API devolverá true y el valor de code_verification_status del número de teléfono de empresa se establecerá en VERIFIED durante 90 días.

{
  "success": <SUCCESS>
}

Ejemplo de solicitud

curl -X POST 'https://graph.facebook.com/v20.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "success": true
}

Consulta los parámetros de consulta admitidos en la referencia del extremo Número de teléfono verificado previamente de WhatsApp Business > Verificar código.

Cuando tengas un número de teléfono de empresa verificado previamente con un estado verificado (o un conjunto de números de este tipo), debes mostrarlo en el nuevo proceso de registro insertado.

Mostrar números verificados previamente en el registro insertado

Puedes mostrar números de teléfono de empresa verificados previamente en el nuevo proceso de registro insertado mediante datos de formulario rellenados previamente. Para ello, añade un objeto preVerifiedPhone con una propiedad ids al objeto setup y asigna el identificador de los números de teléfono de empresa verificados previamente como una matriz de cadenas a la propiedad ids:

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

Por ejemplo:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

Ten en cuenta que, si un número de teléfono de empresa verificado previamente con un estado VERIFIED no se reclama en los 90 días posteriores a la verificación, el estado se revertirá a UNVERIFIED, pero seguirá apareciendo en el nuevo proceso de registro insertado. Si un cliente final intenta reclamar un número sin verificar, debe completar él mismo la verificación, lo que implica que debe solicitarte una contraseña de un solo uso.

Para evitar esta experiencia de usuario deficiente, te recomendamos que hagas un seguimiento del momento en que verificas un número y que lo vuelvas a verificar antes de que se revierta a un estado sin verificar.

Si no recuerdas cuándo fue la última vez que verificaste un número de teléfono de empresa verificado previamente, consulta el extremo Número de teléfono verificado previamente de WhatsApp Business y lee los campos code_verification_time y verification_expiry_time, que indican la hora de verificación más reciente y la hora de expiración de la verificación.

Determinar si un número se ha reclamado mediante el registro insertado

Consulta Obtener los identificadores de los números de teléfono reclamados.

Obtener los identificadores de los números de teléfono reclamados

Realiza una solicitud GET en el extremo Cuenta de WhatsApp Business > Números de teléfono, que devolverá todos los números de teléfono de WhatsApp Business de una cuenta de WhatsApp Business.

Analiza la propiedad display_phone_number de cada objeto devuelto en el conjunto de resultados. Si un objeto tiene el número de teléfono para mostrar (p. ej., 16505551234) como valor de display_phone_number, significa que se ha reclamado. Copia el valor de la propiedad id del objeto, ya que se trata del identificador del nuevo objeto de número de teléfono de WhatsApp Business que ahora representa este número (el identificador anterior dejará de funcionar).

Como alternativa, puedes usar el mismo extremo con la expansión de field para solicitar el campo display_phone_number y especificar el número de teléfono para mostrar. Por ejemplo:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

Si esta operación devuelve un objeto de número de teléfono de WhatsApp Business con ese número de teléfono para mostrar, significa que el número se ha reclamado y debes copiar el valor de id del objeto.

Obtener los números de teléfono de empresa verificados previamente

Usa el extremo Cuenta empresarial > Números verificados previamente para obtener una lista de todos los objetos de números de teléfono verificados previamente de WhatsApp Business, independientemente de su estado de verificación, del grupo de números de teléfono de empresa verificados previamente de tu cuenta empresarial:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

Los resultados se ordenan automáticamente según la hora de creación. También puedes usar la expansión de campos para solicitar el campo code_verification_status y que la API solo devuelva los números de teléfono de empresa verificados previamente con el estado de verificación indicado:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

Compartir y dejar de compartir números verificados previamente

Envía una solicitud POST al extremo Empresa > Compartir números verificados previamente para compartir números de teléfono de empresa verificados previamente con socios comerciales, o una solicitud DELETE al mismo extremo para dejar de compartirlos.

Los socios comerciales pueden mostrar los números de teléfono de empresa verificados previamente que se comparten en el proceso de registro insertado.

Si compartes números con varios socios comerciales, recomendamos que sugieras a tus socios que obtengan una lista de los números verificados previamente que se comparten antes de mostrarlos en el proceso de registro insertado. Esto reduce la probabilidad de que un socio intente mostrar un número que se haya reclamado (los números reclamados no aparecen en el proceso, pero el socio podría no saberlo y preguntarse por qué no aparece).

Sintaxis de la solicitud para compartir

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Sintaxis de la solicitud para dejar de compartir

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Respuesta

Cuando esta operación se realice correctamente, la API devolverá “true”. Si vas a compartir un número, notifica a tu socio comercial del número verificado previamente que acabas de compartir y proporciónale el identificador del número. Si dejas de compartir un número, el número ya no aparecerá en la implementación del registro insertado del socio.

{
  "success": <SUCCESS>
}

Ejemplo de solicitud para compartir

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Ejemplo de solicitud para dejar de compartir

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Ejemplo de respuesta

{
  "success": true
}

Registrar números verificados previamente mediante programación

Puedes omitir por completo la selección del número de teléfono en el proceso de registro insertado y registrar números de teléfono de empresa verificados previamente en la cuenta de WhatsApp Business de un cliente final incorporado mediante programación. Para ello, sigue los pasos que se describen en el documento Registrar números de teléfono, pero utiliza un identificador de número de teléfono de empresa verificado previamente en el Paso 1 y, a continuación, omite los pasos hasta el Paso 4.

Sintaxis de la solicitud

Usa esta solicitud para crear un número de teléfono de WhatsApp Business en una cuenta de WhatsApp Business utilizando un identificador de número de teléfono verificado previamente. Esto reemplaza el Paso 1.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

Cuerpo de la solicitud POST

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Propiedades

Sintaxis de la respuesta

Cuando esta operación se realice correctamente, la API responderá con el identificador de un número de teléfono de WhatsApp Business. Utiliza este identificador para registrar el número (Paso 4 en el documento Registrar números de teléfono).

{
  "id": "<ID>"
}

Propiedades de la respuesta

Ejemplo de solicitud

curl 'https://graph.facebook.com/v20.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

Ejemplo de respuesta

{
  "id": "108692048990658"
}