Recuperar números de teléfono

Recupera los números de teléfono que una empresa haya registrado para su cuenta de WhatsApp Business mediante la API de administración de WhatsApp Business.

Antes de empezar

Necesitarás lo siguiente:

• El identificador de la cuenta de WhatsApp Business de los números de teléfono de la empresa que quieras recuperar.
• Un identificador de acceso de usuario del sistema vinculado a la cuenta de WhatsApp Business.
• El permiso whatsapp_business_management.

Limitaciones

• Esta API solo puede recuperar números de teléfono registrados. Con esta API no se pueden añadir, actualizar ni eliminar números de teléfono.

Obtener todos los números de teléfono

Para obtener una lista de todos los números de teléfono asociados a una cuenta de WhatsApp Business, envía una solicitud GET al extremo Cuenta de WhatsApp Business > Números de teléfono.

Además, los números de teléfono se pueden ordenar de forma ascendente o descendente según el valor de last_onboarded_time, que se basa en el momento en que el usuario completó la incorporación para el registro insertado. Si no se especifica, el orden predeterminado es el descendente.

Ejemplo de solicitud

curl -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-id}/phone_numbers
      ?access_token={system-user-access-token}"

Cuando esta operación se completa correctamente, se devuelve un objeto JSON con una lista de todos los nombres de empresa, números de teléfono, identificadores de números de teléfono y calificaciones de calidad asociados con la empresa. Los resultados se ordenan según la fecha de finalización del registro insertado en orden descendente y se muestran primero los incorporados más recientemente.

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
      
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Ejemplo de solicitud

curl -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-id}/phone_numbers
      ?access_token={system-user-access-token}]&sort=['last_onboarded_time_ascending']"

Cuando esta operación se completa correctamente, se devuelve un objeto JSON con una lista de todos los nombres de empresa, números de teléfono, identificadores de números de teléfono y calificaciones de calidad asociados con la empresa. Se ordena según la fecha de finalización del registro insertado en orden ascendente y se muestran en último lugar los incorporados más recientemente.

{
  "data": [
   {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    },
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"     
    }   
  ]
}

Filtrar números de teléfono

Puedes consultar números de teléfono y filtrarlos por la opción account_mode. La opción de filtración se está probando actualmente en modo beta. No todos los desarrolladores tienen acceso a esta opción.

Parámetros

Ejemplo de solicitud

curl -i -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}/phone_numbers?filtering=[{"field":"account_mode","operator":"EQUAL","value":"SANDBOX"}]&access_token=access-token"

Ejemplo de respuesta

{
  "data": [
    {
      "id": "1972385232742141",    
      "display_phone_number": "+1 631-555-1111",
      "verified_name": "John’s Cake Shop",
      "quality_rating": "UNKNOWN",
    }
  ],
  "paging": {
	"cursors": {
		"before": "abcdefghij",
		"after": "klmnopqr"
	}
   }
}

Obtener un único número de teléfono

Para obtener información sobre un número de teléfono, envía una solicitud GET al extremo de números de teléfono de WhatsApp Business:

Sintaxis de la solicitud

GET https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>

Ejemplo de solicitud

curl \
'https://graph.facebook.com/v15.0/105954558954427/' \
-H 'Authorization: Bearer EAAFl...'

Cuando esta operación se completa correctamente, se devuelve un objeto JSON con el nombre de empresa, el número de teléfono, el identificador de número de teléfono y la calificación de calidad del número de teléfono consultado.

{
  "code_verification_status" : "VERIFIED",
  "display_phone_number" : "15555555555",
  "id" : "105954558954427",
  "quality_rating" : "GREEN",
  "verified_name" : "Support Number"
}

Obtener el estado del nombre para mostrar (beta)

Incluye fields=name_status como parámetro de la cadena de consulta para obtener el estado de un nombre para mostrar asociado con un número de teléfono específico. Actualmente, este campo se encuentra en versión beta y no está disponible para todos los desarrolladores.

Ejemplo de solicitud

curl \
'https://graph.facebook.com/v15.0/105954558954427?fields=name_status' \
-H 'Authorization: Bearer EAAFl...'

Ejemplo de respuesta

{
  "id" : "105954558954427",
  "name_status" : "AVAILABLE_WITHOUT_REVIEW"
}

El valor de name_status puede ser uno de los siguientes:

• APPROVED: el nombre se ha aprobado. Ya puedes descargar el certificado.
• AVAILABLE_WITHOUT_REVIEW: el certificado para el teléfono está disponible y el nombre para mostrar está listo para usarse sin revisión.
• DECLINED: el nombre no se ha aprobado. No puedes descargar el certificado.
• EXPIRED: el certificado ha caducado y ya no se puede descargar.
• PENDING_REVIEW: la solicitud de nombre está en proceso de revisión. No puedes descargar el certificado.
• NONE: no hay ningún certificado disponible.

Ten en cuenta que los certificados son válidos durante siete días.

Más información

Para obtener una lista de todos los valores posibles para cada campo, consulta la referencia de la API Graph del campo Número de teléfono.