Verificaciones de capacidades

Para verificar si el dispositivo de un usuario está habilitado para RCS y puede comunicarse con un agente de RBM, puedes solicitar las capacidades del dispositivo. Identificar las funciones que admite un dispositivo, si las hay, permite que tu agente adapte la conversación a las capacidades del dispositivo y evite presentar interacciones que sean difíciles o imposibles de completar para el usuario.

Si el dispositivo de un usuario no puede recibir mensajes RCS, puedes comunicarte con él a través de otros servicios, como SMS o MMS.

Cómo verificar las funciones del dispositivo

El siguiente código envía una verificación de capacidades y espera una respuesta. Para ver las opciones de formato y valor, consulta getCapabilities.

cURL

curl -X GET "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/capabilities?requestId=REQUEST_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send a capability check to the device
rbmApiHelper.checkCapability('+12223334444', function(response) {
   // Print capabilities of the device
   console.log(response);
});
 Este código es un extracto de un agente de ejemplo de RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Check the capabilities of the device
boolean capability = rbmApiHelper.getCapability("+12223334444");
 Este código es un extracto de un agente de ejemplo de RBM.

Python

# Reference to RBM Python client helper
from rcs_business_messaging import rbm_service

# Send the tester invite to a device
response = rbm_service.make_cap_request('+12223334444')
 Este código es un extracto de un agente de ejemplo de RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

// Register the device as a tester
Capabilities capabilities = rbmApiHelper.GetCapability("+12223334444");
 Este código es un extracto de un agente de ejemplo de RBM.

Respuesta de capacidad

Después de ejecutar una verificación de funciones, la plataforma de RBM muestra una lista con formato JSON de las funciones que admite el dispositivo especificado.

{
  "features": [
    "REVOCATION",
    "RICHCARD_STANDALONE",
    "RICHCARD_CAROUSEL",
    "ACTION_CREATE_CALENDAR_EVENT",
    "ACTION_DIAL",
    "ACTION_OPEN_URL",
    "ACTION_SHARE_LOCATION",
    "ACTION_VIEW_LOCATION",
    "ACTION_OPEN_URL_IN_WEBVIEW",
    "ACTION_COMPOSE",
  ]
}

La solicitud muestra una respuesta o un error.

Se muestra una respuesta correcta solo si el MSISDN (número de teléfono) se conectó al servicio de RCS en las últimas 24 horas.

A continuación, se indican las causas de los errores 404:

  • El RBM no puede comunicarse con el usuario (por ejemplo, si su dispositivo no admite RCS).

  • El usuario tiene RCS, pero tu agente no se inició en su red móvil.

Creación de filas sin conexión

Los mensajes se ponen en cola hasta por 30 días y se entregan cuando el dispositivo vuelve a estar en línea. Para garantizar la entrega, el dispositivo debe haber mostrado signos de actividad de RCS dentro de las 24 horas posteriores al envío del mensaje. Esto significa que, incluso si un dispositivo se desconecta durante un período prolongado (hasta 30 días), los mensajes en cola se seguirán entregando cuando se vuelva a conectar, siempre y cuando se haya cumplido el período de actividad de 24 horas en el momento del envío.

Verificaciones masivas de capacidades

Para estimar la cantidad de usuarios a los que se puede llegar con la RBM, realiza una verificación masiva de capacidades. Las verificaciones masivas indican si se puede comunicar con un número de teléfono, pero no qué funciones admite.

Para cada verificación masiva de capacidades, debes proporcionar entre 500 y 10,000 números de teléfono únicos. Para verificar más números, realiza varias verificaciones. Puedes realizar hasta 600 llamadas por minuto. Usa la secuencia de comandos de verificación de capacidades masivas para usar archivos CSV como formato de entrada. Las verificaciones masivas se leen de la caché de capacidades, que los clientes actualizan de forma orgánica con RCS. Los agentes no solicitan directamente las capacidades de cada dispositivo. Por este motivo, es posible que los resultados no sean actuales.

Las verificaciones masivas de capacidades muestran una lista de los números a los que puede llamar tu agente en los operadores en los que se lanzó, así como estimaciones de la cantidad total de usuarios a los que se puede llamar en todos los operadores. Consulta Respuesta de la verificación masiva de capacidades.

Estimación del total de usuarios alcanzables

Si bien las respuestas de la verificación masiva incluyen una lista de números de teléfono que se pueden alcanzar de inmediato en los operadores lanzados de tu agente (reachableUsers), las respuestas también incluyen dos valores que pueden ayudarte a estimar la cantidad total de usuarios que se pueden alcanzar en todos los operadores.

Cómo funciona

Cuando tu agente realiza una verificación masiva de capacidades, RBM toma muestras de forma aleatoria de aproximadamente el 75% de esos números para verificar todos los operadores (se informa en totalRandomSampleUserCount). RBM también muestra el recuento de números a los que se puede acceder desde RBM a partir de la muestra aleatoria, independientemente del estado de lanzamiento del operador (reachableRandomSampleUserCount). Si divides reachableRandomSampleUserCount por totalRandomSampleUserCount, puedes estimar el porcentaje de números a los que podría llegar tu agente si se lanzara en todos los operadores.

Por ejemplo, si especificas 5,000 números de teléfono en la verificación de capacidades masivas y la RBM toma muestras de forma aleatoria de alrededor del 75% de los números especificados, totalRandomSampleUserCount puede ser 3750. Si reachableRandomSampleUserCount es 3000, se pudo establecer conexión con el 80% de los números muestreados.

Ten en cuenta el muestreo aleatorio

Probar muestras aleatorias puede generar variaciones en los porcentajes. Para tener en cuenta los efectos del muestreo aleatorio, ejecuta verificaciones de capacidad masivas con cantidades mayores de números de teléfono. También puedes realizar verificaciones con los mismos lotes de números variadas veces y, luego, promediar los resultados para normalizar el comportamiento del muestreo aleatorio.

Cómo enviar una verificación masiva de capacidades

El siguiente código envía una verificación masiva de capacidades y espera una respuesta. Para ver las opciones de formato y valor, consulta users.batchGet.

Los números de teléfono deben tener el formato E.164 (por ejemplo, "+12223334444") y la lista debe contener entre 500 y 10,000 números de teléfono únicos.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/users:batchGet?agentId=AGENT_ID \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "users": [
    "PHONE_NUMBER",
  ]
}'

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Specify phone numbers
let phoneNumbers = ['+12223334444', '+12223334444'];

// Perform a bulk capability check
rbmApiHelper.getUsers(phone_numbers, function(response) {
   // Print the bulk capability check response
   console.log(response);
});
 En este código, se usa el agente de muestra de RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Perform a bulk capability check
BatchGetUsersResponse batchGetUsersResponse = rbmApiHelper.getUsers(Arrays.asList("+12223334444", "+12223334444"));
 En este código, se usa el agente de muestra de RBM.

Python

# Reference to RBM Python client helper
from rcs_business_messaging import rbm_service

# Perform a bulk capability check
response = rbm_service.make_batch_cap_request(['+12223334444', '+12223334444'])
 En este código, se usa el agente de muestra de RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

// Perform a bulk capability check
BatchGetUsersResponse batchGetUsersResponse = rbmApiHelper.GetUsers(new List({"+12223334444", "+12223334444"}));
 En este código, se usa el agente de muestra de RBM.

Respuesta de la verificación masiva de capacidades

Después de ejecutar una verificación masiva de capacidades, RBM muestra una respuesta en formato JSON.

{
  "reachableUsers": [
    "PHONE_NUMBER"
  ],
  "totalRandomSampleUserCount": "COUNT_OF_SAMPLE",
  "reachableRandomSampleUserCount": "REACHABLE_FROM_SAMPLE"
}
Campo Descripción
reachableUsers Es una lista de usuarios accesibles en los operadores lanzados del agente.
totalRandomSampleUserCount Es el recuento de una muestra aleatoria de números especificados. Por lo general, alrededor del 75% de los números especificados.
reachableRandomSampleUserCount Es el recuento de números de la muestra aleatoria que son accesibles para la RBM en todos los operadores, independientemente de los operadores en los que se inicia el agente. Este recuento se usa para proporcionar una estimación aproximada de la cantidad total de usuarios alcanzables en todos los operadores.

Herramienta: Secuencia de comandos de verificación masiva de capacidades

La secuencia de comandos de verificación de capacidades de Buck (Accede para descargar) realiza verificaciones de capacidades masivas con archivos CSV como formatos de entrada y salida. La secuencia de comandos analiza el archivo CSV de MSISDN y usa el SDK de RBM para verificar las capacidades de cada dispositivo de la lista.

Una máquina virtual de 2 CPUs y 4 GB de RAM que ejecuta la secuencia de comandos con 500 subprocesos puede alcanzar aproximadamente 1, 000 QPS, pero la QPS general depende de la máquina que se usa, el país de los dispositivos, la configuración regional de tu agente y el extremo de la API que se usa.

Requisitos previos

Antes de usar la herramienta para realizar una verificación masiva de capacidades, obtén lo siguiente:

  • Es la ruta de acceso a un archivo CSV con MSISDN para realizar verificaciones de capacidades.
  • La ruta de acceso a la clave de la cuenta de servicio de tu agente en tu máquina de desarrollo

Además, debes tener instalado el siguiente software en tu máquina de desarrollo:

Configurar

Para configurar tu máquina de desarrollo para una verificación masiva de capacidades, haz lo siguiente:

  1. Descarga y extrae la Secuencia de comandos de verificación de capacidades masivas (Accede para descargarla).
  2. Sigue los pasos que se indican en el archivo readme.

Ejecuta una verificación masiva de capacidades

Para ejecutar una verificación masiva, sigue estos pasos:

  1. En una terminal, navega al directorio raíz de la secuencia de comandos.

  2. Ejecuta los siguientes comandos:

    export MAVEN_OPTS="-Xms1024m -Xmx3000m"
mvn compile && mvn exec:java -Dexec.args="AGENT_ID INPUT_FILE OUTPUT_FILE NUM_OF_THREADS START_INDEX END_INDEX"

    Reemplaza las variables por los valores que identificaste.

    Reemplazar Con Ejemplo
    AGENT_ID Es el ID del agente de RCS Business Messaging. welcome-bot
    INPUT_FILE Es la ruta de acceso al archivo CSV de entrada. input.csv
    OUTPUT_FILE Es la ruta de acceso al archivo CSV de salida. output.csv
    NUM_OF_THREADS Es la cantidad de subprocesos que se dedicarán a las verificaciones de capacidades. 500
    START_INDEX Opcional. Es el valor del archivo CSV con el que se deben comenzar a ejecutar las verificaciones. 5
    END_INDEX Opcional. Es el valor del archivo CSV que se debe verificar después. 500

  3. Cuando se complete la secuencia de comandos, abre el archivo CSV de salida para ver los resultados.

Anterior
Eventos