Reachability [Prévia para desenvolvedores]

Ao fornecer informações em tempo real diretamente das operadoras de celular, o Reachability Insight pode ser usado para verificar o status de conectividade de um determinado dispositivo, incluindo se ele está conectado à rede para dados, SMS ou ambos.

Os principais benefícios incluem:

  • Melhoria da experiência do usuário por meio do envio de comunicações relevantes: Determine se é possível entrar em contato com um cliente e envie a ele a comunicação pertinente, por SMS ou dados.
  • Gerenciamento do banco de dados de registros de clientes: Determine quais clientes precisam ser contatados para atualizar seu número de telefone, por exemplo, se um determinado usuário não tiver tido conectividade de dados ou SMS nos últimos 60 dias.
  • Diagnóstico e monitoramento remotos rápidos de dispositivos IoT: Identifique quais dispositivos estão offline e, nesse caso, quando estiveram online pela última vez, além de obter remotamente informações sobre quais dispositivos precisam de manutenção.

Observação: o uso dessa informação em ambiente de produção requer a aprovação das operadoras de telefonia móvel, que é gerenciada por meio do “Registro de Rede”. Para saber como solicitar acesso, siga este guia.

Pré-requisitos

Para usar o Identity Insights, você deve verificar se sua conta está configurada corretamente; consulte o Introdução guia para obter mais informações sobre:

  • Criando seu account,
  • Criação de uma aplicação da Vonage para uso com a API do Identity Insights,
  • Os diferentes ambientes disponíveis e como configurar sua Account para utilizá-los,
  • E como usar a interface de usuário “Introdução” do Painel de Controle para utilizar a API sem precisar escrever nenhum código.

Este guia explicará como utilizar o Reachability Insight programaticamente por meio do cURL.

A API do Identity Insights está disponível por meio de vários endpoints regionais. Os exemplos deste guia utilizam o endpoint da UE, mas você pode encontrar a lista completa em Detalhes técnicos.

Fazendo uma chamada de API

A autenticação na API do Identity Insights é feita por meio de JWTs, um token JSON compacto e autônomo. Para gerar um JWT, você pode usar nosso gerador online, ou, se preferir, use o CLI da Vonage. Você precisará do ID do seu aplicativo e da chave privada para gerar o JWT. Assim que tiver o JWT, poderá enviar uma solicitação à API.

Este exemplo mostra uma solicitação cURL para o insight de acessibilidade, a fim de verificar se, e de que forma, um determinado dispositivo está conectado à rede móvel:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+990123400",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "reachability": {}
        }
    }'

A API retornará, então, informações sobre a acessibilidade desse dispositivo, incluindo uma confirmação da acessibilidade atual e os tipos de tráfego disponíveis (atualmente, SMS e dados são suportados):

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "reachability": {
        "latest_status_at":"2024-02-20T10:41:38.657Z",
        "is_reachable": true,
        "connectivity": ["DATA", "SMS"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
  }
}

Aqui, o status O objeto indica o status das informações retornadas para o número de telefone especificado:

Campo Descrição
status.code Código que indica o status da solicitação. Deve ser um dos seguintes:

NO_COVERAGE: O país ou a rede de celular não é compatível com os fornecedores disponíveis.
INVALID_PURPOSE: A finalidade indicada não é válida nem permitida para este Insight.
UNAUTHORIZED: Não foi possível autorizar a solicitação para essa combinação de aplicativo, fornecedor e número de telefone.
INTERNAL_ERROR: Ocorreu um erro interno durante o processamento da solicitação.
SUPPLIER_ERROR: O fornecedor apresentou um erro durante o processamento da solicitação.
NOT_FOUND: Não foi possível encontrar o número de telefone para este Insight.
UNSUPPORTED_NETWORK_TYPE: Esse tipo de rede não é compatível com este Insight.
INVALID_NUMBER_FORMAT: O formato do número de telefone não é válido para atribuição pelas operadoras aos usuários.
OK: A informação foi processada com sucesso.
status.message Descrição mais detalhada do status.

Se status.code na resposta está OK, você também poderá ver os campos descritos na tabela abaixo. Se um campo estiver marcado como “Sim” na coluna “Obrigatório”, ele sempre será retornado quando o status for OK. Se um campo estiver marcado como “Não”, ele poderá ou não ser retornado.

Campo Descrição Obrigatório
latest_status_at A última vez em que o status de conectividade do dispositivo associado foi atualizado. Sim
is_reachable Indica a acessibilidade geral do dispositivo — será true se o dispositivo estiver conectado à rede. Sim
connectivity Indica se o dispositivo está conectado à rede para DATA ou SMS uso. Só será devolvido se is_reachable é true. Sim

Leitura complementar