Para verificar se o dispositivo de um usuário está ativado para RCS e pode se comunicar com um agente do RBM, solicite os recursos do dispositivo. Identificar quais recursos um dispositivo oferece, se houver, permite que o agente personalize a conversa de acordo com as funcionalidades do dispositivo e evite apresentar interações difíceis ou impossíveis de serem concluídas pelo usuário.
Se o dispositivo de um usuário não for capaz de receber mensagens RCS, você poderá se comunicar com ele por outros serviços, como SMS/MMS.
Verificar as capabilities do dispositivo
O código a seguir envia uma verificação de capacidade e aguarda uma resposta. Para opções de formatação e valores, 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); });
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");
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')
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");
Resposta de capacidade
Depois de executar uma verificação de recursos, a plataforma RBM retorna uma lista formatada em JSON de recursos compatíveis com o dispositivo especificado.
{ "features": [ "RICHCARD_STANDALONE", "RICHCARD_CAROUSEL", "ACTION_CREATE_CALENDAR_EVENT", "ACTION_DIAL", "ACTION_OPEN_URL", "ACTION_SHARE_LOCATION", "ACTION_VIEW_LOCATION", "ACTION_OPEN_URL_IN_WEBVIEW", "PDF_IN_RICH_CARDS" ] }
A solicitação retorna uma resposta ou um erro.
Uma resposta bem-sucedida será retornada somente se o MSISDN (número de telefone) tiver se conectado ao serviço RCS nos últimos 31 dias. Isso significa que o dispositivo do usuário fez check-in com nosso servidor RCS nesse período. Os dispositivos on-line e compatíveis com RCS fazem check-in a cada 1 a 4 horas, em média.
Se um usuário mover o chip para um dispositivo diferente compatível com RCS, a associação anterior será removida, e uma nova será criada, atualizando os recursos do dispositivo no serviço RCS.
Se um chip for colocado em um dispositivo em que o RCS está desativado por uma operadora ou fabricante, ou se o chip permanecer sem uso, o serviço RCS ainda tentará entregar mensagens ao dispositivo associado anteriormente por até 31 dias.
Veja o que causa erros 404:
O usuário não pode ser contatado pelo RBM, por exemplo, se o dispositivo dele não for compatível com RCS.
O usuário tem o RCS, mas seu agente não foi lançado na rede móvel dele.
Enfileiramento off-line
As mensagens ficam na fila por até 31 dias e são entregues quando o dispositivo volta a ficar on-line. Isso significa que, mesmo que um dispositivo fique off-line por um período prolongado (até 31 dias), as mensagens na fila ainda serão entregues após a reconexão, desde que o MSISDN tenha se conectado ao serviço RCS nos últimos 31 dias.
Verificações de recursos 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 está disponível, mas não quais recursos ele aceita.
Para cada verificação em massa, é necessário fornecer de 500 a 10.000 números de telefone exclusivos. Para verificar mais números, faça várias verificações. É possível fazer até 600 chamadas por minuto. Use o script de verificação de capacidade em massa para usar arquivos CSV como formato de entrada. As verificações em massa são lidas do cache de recursos, que é atualizado pelos clientes de forma orgânica usando o RCS. Os agentes não solicitam diretamente os recursos de cada dispositivo. Por isso, os resultados podem não estar atualizados.
As verificações em massa de capacidade retornam uma lista dos números que seu agente pode alcançar em operadoras em que ele é lançado, além de estimativas do número total de usuários alcançáveis em todas as operadoras. Consulte Resposta da verificação de capacidade 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 contatados imediatamente nas 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 alcançáveis em todas as operadoras.
Como funciona
Quando o agente faz uma verificação de capacidade em massa, o RBM seleciona aleatoriamente cerca de 75% desses números para verificar todas as operadoras (informadas em totalRandomSampleUserCount). O RBM também retorna a contagem de números acessíveis por RBM da amostra aleatória, independente do status de lançamento da operadora (reachableRandomSampleUserCount). Ao dividir reachableRandomSampleUserCount por totalRandomSampleUserCount, é possível estimar a porcentagem de números que seu 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 capacidade em massa e o RBM amostrar aleatoriamente cerca de 75% dos números especificados, totalRandomSampleUserCount poderá ser 3750. Se reachableRandomSampleUserCount for 3000, 80% dos números amostrados estavam acessíveis.
Considerar a amostragem aleatória
Testar amostras aleatórias pode levar a variações nos percentuais. Para considerar os efeitos da amostragem aleatória, execute verificações de capacidade 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 calcular a média dos resultados para normalizar o comportamento da amostragem aleatória.
Enviar uma verificação de capacidade 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 valores, consulte users.batchGet.
Os números de telefone precisam estar no formato E.164 (por exemplo, "+12223334444"), e a lista precisa ter de 500 a 10.000 números de telefone exclusivos.
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); });
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"));
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'])
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"}));
Resposta da verificação de capacidade em massa
Depois de executar uma verificação de capacidade 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 pelo 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 alcançados por RBM em todas as operadoras, independente de quais operadoras o agente é lançado. Essa contagem é usada para fornecer uma estimativa aproximada do número total de usuários alcançáveis em todas as operadoras. |
reachableUsersMap
|
Apenas saída. Mapa do ID da operadora para uma lista de usuários acessíveis nessa operadora. Esse campo só é preenchido para números de telefone dos EUA. |
Ferramenta: script de verificação de capacidade em massa
O Script de verificação de recursos em massa (faça login para baixar) realiza 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 do RBM para verificar os recursos de cada dispositivo listado.
Uma máquina virtual de 2 CPUs e 4 GB de RAM executando o script com 500 linhas de execução pode atingir aproximadamente 1.000 QPS, mas o QPS geral depende da máquina usada, do país dos dispositivos, da configuração regional do seu agente e do endpoint da API usado.
Pré-requisitos
Antes de usar a ferramenta para fazer uma verificação em massa de recursos, faça o seguinte:
- O caminho para um arquivo CSV com MSISDNs para realizar verificações de capacidade
- O caminho para a chave da conta de serviço do agente na sua 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 superior
- Java 8
Configurar
Para configurar sua máquina de desenvolvimento para uma verificação de recursos em massa, faça o seguinte:
- Faça o download e extraia o Script de verificação de capacidade em massa (faça login para baixar).
- Siga as etapas no README.
Executar uma verificação de capacidade em massa
Para fazer uma verificação em massa, siga estas etapas:
- Em um terminal, acesse 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 for Business. welcome-botINPUT_FILE O caminho para o arquivo CSV de entrada. input.csvOUTPUT_FILE O caminho para o arquivo CSV de saída. output.csvNUM_OF_THREADS O número de linhas de execução a serem dedicadas às verificações de capacidade. 500START_INDEX Opcional. O valor no arquivo CSV para começar a executar verificações. 5END_INDEX Opcional. O valor no arquivo CSV para encerrar as verificações depois. 500Quando o script for concluído, abra o arquivo CSV de saída para conferir os resultados.