Verificação de compatibilidade do dispositivo RCS

É possível realizar uma verificação de compatibilidade para determinar se o dispositivo de destino suporta os recursos de mensagens RCS. Atualmente, existem duas maneiras de realizar essa verificação:

• Verificação individual do dispositivo
• Verificação em massa

Verificação das capacidades de cada dispositivo

A verificação é realizada por meio de um GET enviar uma solicitação para a seguinte URL:

https://api.nexmo.com/v1/channel-manager/rcs/agents/{vonage_id}/google/phones/{phone_number}/capabilities

Existem dois parâmetros de caminho obrigatórios:

• vonage_id. Este é o ID do remetente do agente RCS e será fornecido a você como parte do Processo de configuração e integração do RCS.
• phone_number. O número do dispositivo ao qual se refere a verificação de capacidade.

A Authorization O cabeçalho é obrigatório como parte da solicitação. O valor do cabeçalho deve conter um JWT (JSON Web Token) válido no formato Bearer ${JWT}. O JWT pode ser criado usando o ID do aplicativo e a chave privada do seu aplicativo Vonage ao qual o RCS Sender ID está associado. Consulte Autenticação para obter mais informações sobre a criação de JWTs.

Veja o Especificação da API do Channel Manager para obter todos os detalhes técnicos deste endpoint.

Exemplo de solicitação

A seguir, apresentamos um exemplo de solicitação cURL para o endpoint de verificação de recursos:

curl --location 'https://api.nexmo.com/v1/channel-manager/rcs/agents/VonageBasic/google/phones/447900000000/capabilities' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...'

Respostas

200 OK

Se o dispositivo for acessível via RCS, um 200 OK Será recebida uma resposta HTTP. O corpo da resposta conterá uma matriz com os recursos RCS suportados pelo dispositivo, por exemplo:

{ 
  "features": 
   [ 
     "RICHCARD", 
     "RICHCARD_CAROUSEL", 
     "CREATE_CALENDAR_EVENT", 
     "DIAL_PHONE_NUMBER", 
     "OPEN_URL", 
     "SHARE_LOCATION", 
     "VIEW_LOCATION" 
   ] 
}

400 Solicitação inválida

Existem várias situações em que um 400 Bad Request Será recebida uma resposta HTTP, por exemplo, indicando que o ID do remetente do agente não é válido ou que o número de telefone verificado possui um formato inválido.

403 Acesso proibido

Se estiver usando um agente de teste e o número não estiver na lista de números permitidos para esse agente, ou se estiver usando um agente ativo e o número não estiver conectado a uma rede compatível no país em que o agente foi iniciado, um 403 Forbidden Será recebida uma resposta HTTP.

404 Não encontrado

Se o dispositivo não estiver acessível via RCS, um 404 Not Found Será recebida uma resposta HTTP.

Verificação de compatibilidade de dispositivos em massa

A verificação é realizada por meio de um POST enviar uma solicitação para a seguinte URL:

https://api.nexmo.com/v1/channel-manager/rcs/agents/{vonage_id}/google/{operation}

Existem dois parâmetros de caminho obrigatórios:

• vonage_id. Este é o ID do remetente do agente RCS e será fornecido a você como parte do Processo de configuração e integração do RCS.
• operation. A operação a ser executada pelo agente RBM. Neste caso, trata-se de users:batchGet.

A Authorization O cabeçalho é obrigatório como parte da solicitação. O valor do cabeçalho deve conter um JWT (JSON Web Token) válido no formato Bearer ${JWT}. O JWT pode ser criado usando o ID do aplicativo e a chave privada do seu aplicativo Vonage ao qual o RCS Sender ID está associado. Consulte Autenticação para obter mais informações sobre a criação de JWTs.

A Content-Type O cabeçalho é obrigatório como parte da solicitação. O valor do cabeçalho deve ser application/json.

A solicitação deve conter um corpo em JSON, que possui uma propriedade: users. Trata-se de um matriz de strings que representam os números de telefone a serem verificados durante a verificação em massa.

Ao contrário da verificação individual de recursos, a verificação em massa não retorna uma lista dos recursos suportados. Para estimar o número de usuários acessíveis pelo RBM, realize uma verificação em massa de recursos. As verificações em massa indicam se um número de telefone é acessível, mas não quais recursos ele suporta.

• Cada verificação em massa deve incluir entre 500 e 10.000 números de telefone únicos. Para verificar mais números, realize várias verificações.
• Observe também que as solicitações com menos de 500, mais de 10.000 ou números duplicados gerarão um erro.
• As verificações em massa retornam uma lista de números que seu agente pode contatar nas operadoras ativas e estimativas do número total de usuários contatáveis em todas as operadoras.

Estimativa do número total de usuários alcançáveis

Embora as respostas de verificação em massa incluam uma lista de números de telefone que podem ser contatados imediatamente nas operadoras ativas do seu agente (reachableUsers), as respostas também incluem dois valores que ajudam a estimar o número total de usuários acessíveis em todas as operadoras.

Como funciona:

1. O RBM seleciona aleatoriamente cerca de 75% dos números de uma verificação de capacidade em massa (totalRandomSampleUserCount).
2. O RBM também retorna a contagem de números acessíveis pelo RBM na amostra (reachableRandomSampleUserCount).
3. Ao dividir reachableRandomSampleUserCount por totalRandomSampleUserCount, você pode estimar a porcentagem de números que seu aplicativo poderia alcançar se fosse lançado em todas as operadoras.

Exemplo:

Se você enviar 5.000 números de telefone, a RBM poderá selecionar aleatoriamente 3.750 deles. Se 3.000 desses números forem acessíveis, isso significa que 80% dos números selecionados estavam acessíveis.

Veja o Especificação da API do Channel Manager para obter todos os detalhes técnicos deste endpoint.

Exemplo de solicitação

A seguir, está um exemplo de solicitação cURL para o endpoint de verificação em massa de recursos:

curl -X POST https://api.nexmo.com/v1/channel-manager/rcs/agents/VonageBasic/google/users:batchGet \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-d '{
  "users": [
    "34613994828",
    "34613994829"
  ]
}'

Respostas

200 OK

{ 
  "reachableUsers": [ 
    "34613994828",
    "34613994829"
    // rest of reachableUsers list
  ],
  "totalRandomSampleUserCount": 632,
  "reachableRandomSampleUserCount": 324
}

400 Solicitação inválida

Existem várias situações em que um 400 Bad Request Será recebida uma resposta HTTP, indicando, por exemplo, que o ID do remetente do agente não é válido ou que um ou mais dos números de telefone verificados apresentam um formato inválido.