Atualizações: consulte as notas da versão para ver os novos recursos e atualizações do produto.

Esta página foi traduzida pela API Cloud Translation.

Verificações de capacidade

Para verificar se o dispositivo de um usuário está ativado para RCS e é capaz de se comunicar com um agente do RBM, solicite os recursos do dispositivo. A identificação de quais recursos um dispositivo oferece suporte, se houver, permite que o agente adapte a conversa aos recursos do dispositivo e evite apresentar interações que são difíceis ou impossíveis para o usuário realizar.

Se o dispositivo de um usuário não for capaz de receber mensagens RCS, você poderá se comunicar com o usuário por outros serviços, como SMS.

Enviar uma verificação de capacidade

O código a seguir envia uma verificação de recursos e aguarda uma resposta. Para opções de formatação e valor, consulte 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 é um trecho de um agente de amostra do 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 é um trecho de um agente de exemplo do 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 é um trecho de um agente de amostra do 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 é um trecho de um agente de exemplo do RBM.

Resposta da capacidade

Depois de executar uma verificação de recursos, a plataforma RBM retorna uma lista formatada em JSON dos recursos compatíveis com o dispositivo especificado.

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

Se você enviar uma verificação de recursos para um usuário que não pode ser alcançado pelo RBM, por exemplo, se o dispositivo não for compatível com RCS, a plataforma RBM vai retornar um erro 404.

Se você enviar uma verificação de recursos para um usuário do RCS em uma rede em que seu agente ainda não foi lançado, a plataforma RBM vai retornar um erro 403.

Verificações de capabilities em massa

Para estimar o número de usuários que podem ser alcançados pelo RBM, faça uma verificação de recursos em massa. As verificações em massa indicam se um número de telefone é acessível, mas não quais recursos são compatíveis.

É possível especificar até 10.000 números de telefone por verificação de recursos em massa. Para verificar mais números, faça várias verificações. Use o script de verificação de recursos em massa para usar arquivos CSV como formato de entrada.

As verificações de recursos em massa têm um máximo de 600 consultas por minuto (QPM).

As verificações de capacidade em massa retornam uma lista dos números que o agente pode alcançar nas operadoras em que é lançado, bem como estimativas do número total de usuários acessíveis em todas as operadoras. Consulte Resposta da verificação de recursos em massa.

Estimar o total de usuários alcançáveis

Embora as respostas da verificação em massa incluam uma lista de números de telefone que podem ser acessados imediatamente pelas operadoras lançadas do seu agente (reachableUsers), as respostas também incluem dois valores que podem ajudar você a estimar o número total de usuários acessíveis em todas as operadoras.

Quando o agente realiza uma verificação de recursos em massa de mais de 500 números de telefone, o RBM seleciona aleatoriamente cerca de 75% desses números para verificar todas as operadoras (informados em totalRandomSampleUserCount). O RBM também retorna a contagem de números alcançáveis pelo RBM da amostra aleatória, independentemente do status de lançamento da operadora (reachableRandomSampleUserCount). Ao dividir reachableRandomSampleUserCount por totalRandomSampleUserCount, é possível estimar a porcentagem de números que o agente poderia alcançar se fosse lançado em todas as operadoras.

Por exemplo, se você especificar 5.000 números de telefone na verificação de recursos em massa e a RBM amostrar aleatoriamente cerca de 75% dos números especificados, totalRandomSampleUserCount poderá ser 3750. Se reachableRandomSampleUserCount for 3000, 80% dos números amostrados foram alcançáveis.

O teste de amostras aleatórias pode gerar variações nos percentuais. Para considerar os efeitos da amostragem aleatória, execute verificações de recursos em massa com quantidades maiores de números de telefone. Você também pode realizar verificações com os mesmos lotes de números várias vezes e, em seguida, calcular a média dos resultados para normalizar o comportamento de amostragem aleatória.

Enviar uma verificação de recursos em massa

O código a seguir envia uma verificação de capacidade em massa e aguarda uma resposta. Para opções de formatação e valor, consulte users.batchGet.

Os números de telefone precisam estar no formato E.164. Por exemplo, "+12223334444".

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);
});

Este código usa o agente de exemplo 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"));

Este código usa o agente de exemplo 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'])

Este código usa o agente de exemplo do 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"}));

Este código usa o agente de exemplo RBM.

Resposta da verificação de capacidade em massa

Depois de executar uma verificação de recursos em massa, o RBM retorna uma resposta formatada em JSON.

{
  "reachableUsers": [
    "PHONE_NUMBER"
  ],
  "totalRandomSampleUserCount": "COUNT_OF_SAMPLE",
  "reachableRandomSampleUserCount": "REACHABLE_FROM_SAMPLE"
}

Campo	Descrição
`reachableUsers`	Uma lista de usuários alcançáveis nas operadoras lançadas do agente.
`totalRandomSampleUserCount`	A contagem de uma amostra aleatória de números especificados. Normalmente, cerca de 75% dos números especificados.
`reachableRandomSampleUserCount`	A contagem de números da amostra aleatória que podem ser acessados pelo RBM em todas as operadoras, independentemente de em quais operadoras o agente é iniciado.

Ferramenta: script de verificação de recursos em massa

O do script de verificação de recursos (faça login para fazer o download) executa verificações de recursos em massa usando arquivos CSV como formatos de entrada e saída. O script analisa o arquivo CSV de MSISDNs e usa o SDK RBM para verificar os recursos de cada dispositivo listado.

Uma máquina virtual de 2 CPUs e 4 GB de RAM que executa o script com 500 linhas de execução pode alcançar aproximadamente mil QPS, mas o QPS geral depende da máquina usada, do país dos dispositivos, da configuração regional do agente e do endpoint da API usado.

Pré-requisitos

Antes de usar a ferramenta para realizar uma verificação de recursos em massa, faça o seguinte:

O caminho para um arquivo CSV com MSISDNs para realizar verificações de capacidade em
O caminho para a chave da conta de serviço do agente na máquina de desenvolvimento

Além disso, você precisa ter o seguinte software instalado na sua máquina de desenvolvimento:

Apache Maven 3.3.9 ou mais recente
Java 8

Configurar

Na máquina de desenvolvimento, faça o download e extraia o Script de verificação de capacidade em massa (faça login para fazer o download).
Siga as etapas no README.

Executar uma verificação em massa

Em um terminal, navegue até o diretório raiz do script.

Execute os comandos a seguir:

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"

Substitua as variáveis pelos valores que você identificou.

Substituir	Com	Exemplo
`AGENT_ID`	ID do agente do RCS Business Messaging	`welcome-bot`
`INPUT_FILE`	O caminho para o arquivo CSV de entrada.	`input.csv`
`OUTPUT_FILE`	O caminho para o arquivo CSV de saída.	`output.csv`
`NUM_OF_THREADS`	O número de linhas de execução a serem dedicadas às verificações de capacidade.	`500`
`START_INDEX`	Opcional. O valor no arquivo CSV para iniciar a execução de verificações.	`5`
`END_INDEX`	Opcional. O valor no arquivo CSV para finalizar as verificações.	`500`

Quando o script for concluído, abra o arquivo CSV de saída para conferir os resultados.

Eventos