Advisor [Prévia para Desenvolvedores]

O recurso “Advisor” analisa e fornece recomendações e avaliações com base nos Insights solicitados e/ou disponíveis em uma solicitação do Identity Insights.

O Advisor baseia-se em quatro modelos estáticos válidos para diferentes casos de uso e setores:

  • Identidade sintética: Modelo desenvolvido para avaliar o risco de identidade sintética ao longo da jornada do cliente.
  • Falsificação de identidade: Modelo desenvolvido para avaliar o risco de falsificação de identidade ao longo da jornada do cliente.
  • Apropriação de conta: Modelo desenvolvido para avaliar o risco de apropriação de conta ao longo da jornada do cliente.
  • Experiência do cliente: Modelo desenvolvido para avaliar indicadores da experiência do cliente ao longo de sua jornada.

Esses modelos apresentam um nível de complexidade e uma variedade de casos de uso que se alinham bem aos sinais atualmente disponíveis no Identity Insights no curto a médio prazo. Cada modelo contém um conjunto de Insights recomendados, definições de sinais com base em valores de atributos e intervalos de atributos.

Se você incluir o insight do Advisor na solicitação, a resposta incluirá, além disso, as seguintes informações para cada modelo:

  • Insights recomendados: Matriz com os insights recomendados para o modelo.
  • Sinais: atributos específicos e seus valores ou intervalos de valores correspondentes, utilizados para avaliar aspectos relevantes da jornada do cliente. Os sinais ajudam a avaliar riscos, a experiência do usuário ou a conformidade, destacando padrões significativos ou anomalias nos dados recuperados pelo Identity Insights.
  • Métricas:
    • completeness_ratio: A proporção entre os Insights disponíveis (sem dados ausentes) e o número total de Insights recomendados, expressa como um valor entre 0 e 1.
    • positive_ratio: Proporção por tipo de recomendação (excluindo MISSED_INSIGHT)
    • warning_ratio: Proporção por tipo de recomendação (excluindo MISSED_INSIGHT)
    • negative_ratio: Proporção por tipo de recomendação (excluindo MISSED_INSIGHT)
    • weighted_ratio: Índice ponderado para cada tipo de recomendação (excluindo MISSED_INSIGHT)
  • Dicas de modelo:
    • completeness: Recomendações com base no completeness_ratio métrico.
    • worst_case: Esse conselho é o pior de todos os conselhos disponíveis
    • weighted: Avalie os sinais relevantes e forneça uma recomendação geral, levando em consideração os sinais positivos, negativos e ausentes.

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 Advisor 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 “Advisor” e “SIM Swap”, com o objetivo de verificar se ocorreu uma troca de SIM nas últimas 240 horas e obter a análise desse insight:

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

A API analisará então a resposta do relatório sobre troca de SIM, fará uma avaliação e fornecerá recomendações com base nela:

{
  "request_id":"c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights":{
    "sim_swap":{
      "latest_sim_swap_at":"2024-07-08T09:30:27.504Z",
      "is_swapped":true,
      "status":{
        "code":"OK",
        "message":"Success"
      }
    },
    "advisor":{
      "synthetic_identity":{
        "recommended_insights":[
          "format",
          "original_carrier"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor synthetic_identity model."
          },
          {
            "attribute":"original_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor synthetic_identity model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "impersonation":{
        "recommended_insights":[
          "format",
          "original_carrier",
          "current_carrier",
          "subscriber_match"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"original_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"current_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          },
          {
            "attribute":"subscriber_match",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor impersonation model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "account_take_over":{
        "recommended_insights":[
          "format",
          "sim_swap"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor account_take_over model."
          },
          {
            "attribute":"sim_swap",
            "advice":"NEGATIVE",
            "assessment":"A SIM swap represents a high risk of account takeover."
          }
        ],
        "metrics":{
          "completeness_ratio":0.5,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":1,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"MEDIUM",
          "worst_case":"NEGATIVE",
          "weighted":"NEGATIVE"
        }
      },
      "customer_experience":{
        "recommended_insights":[
          "format",
          "current_carrier"
        ],
        "signals":[
          {
            "attribute":"format",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor customer_experience model."
          },
          {
            "attribute":"current_carrier",
            "advice":"MISSED_INSIGHT",
            "assessment":"Insight missed - This Insight is recommended to evaluate advisor customer_experience model."
          }
        ],
        "metrics":{
          "completeness_ratio":0,
          "positive_ratio":0,
          "warning_ratio":0,
          "negative_ratio":0,
          "weighted_ratio":0
        },
        "model_advice":{
          "completeness":"LOW",
          "worst_case":"WARNING",
          "weighted":"WARNING"
        }
      },
      "status":{
        "code":"OK",
        "message":"Success."
      }
    }
  }
}

Leitura complementar