Números de teléfono verificados previamente

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

Ten en cuenta que los números de teléfono del negocio verificados previamente están representados por objetos de números de teléfono verificados previamente de WhatsApp Business, que son temporales. Cuando un cliente final selecciona alguno de estos números y completa el nuevo proceso de registro insertado, el objeto temporal se reemplaza por un objeto de número de teléfono de WhatsApp Business, y debes obtener el identificador del nuevo objeto para registrar el número.

Requisitos

• Tu negocio debe ser un Socio de soluciones aprobado.
• El usuario de la app debe ser administrador del negocio en la cuenta de empresa a la que se agregaron los números de teléfono del negocio verificados previamente.
• Un usuario o un token de acceso de usuario del sistema.
• El permiso business_management.
• Los números de teléfono del negocio deben ser válidos.

Limitaciones

• Solo está disponible con el nuevo proceso de registro insertado. Consulta el documento Inserta el proceso de registro para aprender a habilitar en nuevo proceso.
• Eres responsable de realizar un seguimiento de quién solicitó un número de teléfono del negocio verificado previamente.
• Si un cliente final no reclama un número de teléfono del negocio verificado previamente en el proceso de registro insertado dentro de los 90 días desde la verificación, el número volverá a tener estado de no verificado, y se deberá volver a verificar para que su estado se restaure por otros 90 días.
• Los números de teléfono del negocio verificados previamente no reclamados no se pueden volver a verificar hasta 45 días antes de volver al estado no verificado. Este tiempo se indica en el campo verification_expiry_time.
• Si agregas un número de teléfono al conjunto de números de teléfono del negocio verificados previamente (paso 1), pero no lo verificas en un plazo de 90 días (paso 3), el número se eliminará del conjunto y tendrás que volver a agregarlo.

Creación de números verificados previamente

Sigue estos pasos para crear un número de teléfono del negocio verificado previamente, buscarlo en el registro insertado y registrarlo después de que lo haya solicitado un cliente final.

Paso 1: crea un número de teléfono del negocio verificado previamente

Usa el punto de conexión Cuenta comercial > Agregar números de teléfono para crear un número de teléfono del negocio verificado previamente. Así quedará agregado a tu conjunto de números.

Sintaxis de la solicitud

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

Respuesta

Si la solicitud se realiza con éxito, la API devolverá un identificador del número de teléfono verificado previamente de WhatsApp Business. Guarda este valor para usarlo en la siguiente solicitud.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "id": "106540352242922"
}

Consulta la referencia del punto de conexión Cuenta comercial > Agregar números de teléfono para conocer los parámetros de consulta y los formatos de números de teléfono admitidos.

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

Usa el punto de conexión Número de teléfono verificado previamente de WhatsApp Business > Solicitar código para solicitar una contraseña de un solo uso por SMS o mensaje de voz relacionada con el nuevo número de teléfono del negocio verificado previamente.

Sintaxis de la solicitud

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

Respuesta

Si la solicitud se realiza correctamente, la API devolverá true.

{
  "success": <SUCCESS>
}

Además, enviaremos un SMS o mensaje de voz con una contraseña de un solo uso para el número de teléfono. Guarda la contraseña de un solo uso para usarla en la próxima 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/v19.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Ejemplo de respuesta

{
  "success": true
}

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

WhatsApp code 123-456

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

Se repite tres veces.

Verification code is 123456

Consulta la referencia del punto de conexión Número de teléfono verificado previamente de WhatsApp Business > Solicitar código para conocer los métodos, idiomas y parámetros de consulta admitidos.

Paso 3: Verifica el número

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

Sintaxis de la solicitud

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

Respuesta

Si la solicitud es correcta, la API devolverá true, y el número de teléfono del negocio tendrá su code_verification_status configurado en VERIFIED por 90 días.

{
  "success": <SUCCESS>
}

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "success": true
}

Consulta la referencia del punto de conexión Número de teléfono verificado previamente de WhatsApp Business > Verificar código para conocer los parámetros de consulta admitidos.

Una vez que tengas un número de teléfono del negocio verificado previamente con un estado verificado (o un conjunto de números con esa característica), muéstralos en el nuevo proceso de registro insertado.

Mostrar números verificados previamente en el registro insertado

Puedes mostrar números de teléfono del negocio verificados previamente en el nuevo proceso de registro insertado mediante los datos del formulario predeterminados. Para ello, agrega un objeto preVerifiedPhone con una propiedad ids al objeto setup y asigna los identificadores de tus números de teléfono del negocio verificados previamente como 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 no se reclama un número de teléfono del negocio verificado previamente con el estado VERIFIED en el transcurso de los 90 días desde la verificación, su estado cambiará a UNVERIFIED, pero seguirá apareciendo en el proceso de registro insertado. Si un cliente final intenta reclamar un número no verificado, debe completar la verificación por su cuenta, lo que significa que tiene que solicitarte una contraseña de un solo uso.

Para evitar esta mala experiencia de usuario, te recomendamos realizar un seguimiento del momento en que verificas los números y volver a verificarlos antes de que vuelvan a un estado no verificado.

Si no recuerdas con precisión cuándo verificaste por última vez un número de teléfono del negocio verificado previamente, consulta el punto de conexión Número de teléfono de WhatsApp Business previamente verificado y lee los campos code_verification_time y verification_expiry_time, que indican el momento de verificación más reciente y el momento de caducidad de la verificación.

Determinar si un número se reclamó durante el registro insertado

Consulta Reclamar identificadores de números de teléfono.

Reclamar identificadores de números de teléfono

Realiza una solicitud GET en el punto de conexión Cuenta WhatsApp Business > Números de teléfono, que muestra 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 de visualización (por ejemplo, 16505551234) como valor de display_phone_number, quiere decir que ya se solicitó. Copia el valor de la propiedad id del objeto, ya que es el identificador del nuevo objeto de número de teléfono de WhatsApp Business, que ahora representa este número (el identificador anterior ya no funciona).

De manera alternativa, puedes usar el mismo punto de conexión con la expansión de campos para solicitar el campo (field) display_phone_number y especificar el número de teléfono de visualización. Por ejemplo:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

Si esto devuelve un objeto de número de teléfono de WhatsApp Business con ese número de teléfono de visualización, quiere decir que el número ya se solicitó y deberías copiar el id del objeto.

Obtener números de teléfono del negocio verificados previamente

Usa el punto de conexión Cuenta comercial > Números de teléfono verificados previamente para obtener una lista de todos los objetos de número de teléfono verificado previamente de WhatsApp Business, independientemente del estado de verificación, en tu conjunto de números de teléfono del negocio verificados previamente de tu cuenta comercial:

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 y restringir el campo code_verification_status para solicitar que la API solo devuelva números de teléfono del negocio 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 punto de conexión Negocio > Compartir números verificados previamente para compartir números de teléfono del negocio verificados previamente con socios comerciales, o una solicitud DELETE al mismo punto de conexión para dejar de compartirlos.

Los números de teléfono del negocio verificados previamente que se han compartido pueden mostrarse a socios comerciales en el proceso de registro insertado.

Si compartes números con varios socios comerciales, recomendamos que les aconsejes que obtengan una lista de números verificados previamente que compartiste con ellos antes de mostrarlos en el registro insertado. Esto reduce la probabilidad de que un socio intente buscar un número ya solicitado (los números reclamados no aparecen en el proceso, pero el socio puede no saberlo y preguntarse por qué no lo ve).

Sintaxis de la solicitud de compartir

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

Sintaxis de la solicitud de no compartir

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

Respuesta

Si la solicitud se realiza correctamente, la API devolverá true. Si compartes un número verificado previamente con tu socio comercial, avísale cuál es y bríndale la identificación. Si dejas de compartirlo, el número ya no aparecerá en la implementación de registro insertado del socio.

{
  "success": <SUCCESS>
}

Ejemplo de solicitud de 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 de no 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 la selección de número de teléfono del registro insertado y registrar números de teléfono del negocio verificados previamente en la cuenta de WhatsApp Business de un cliente final mediante programación. Sigue los pasos que se encuentran en el documento de Registro de números de teléfono, pero utiliza un ID de número de teléfono del negocio verificado previamente del Paso 1. Luego, dirígete al Paso 4.

Sintaxis de la solicitud

Utiliza esta solicitud para crear un número de teléfono del negocio de WhatsApp en una cuenta de WhatsApp Business utilizando un ID 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

Si la operación se completa con éxito, la API responderá con la identificación de un número de teléfono de WhatsApp Business. Utiliza esta identificación para registrar el número (paso 4 del documento de Registro de números de teléfono).

{
  "id": "<ID>"
}

Propiedades de la respuesta

Ejemplo de solicitud

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