API de CTI

A API de CTI fornece endpoints que permitem que os provedores de Integração de Telefonia e Computadores (CTI) interajam com a estrutura do Cloud Call Center.

Usando esta API, os integradores podem:

• Invoque operações de CTI usando manipuladores de operação personalizados na estrutura do Cloud Call Center.
• Passe eventos de um provedor CCP para uma instância ServiceNow.
• Renderizar transcrições e gravações para uma chamada de agente especificada.

Esta API é executada no namespace sn_cti_core. Antes de acessar essa API, você deve instalar a aplicação Cloud Call Center Core (sn_cti_core). Para obter informações sobre esta instalação, consulte Instalar aplicações Call center na nuvem.

Para obter informações adicionais sobre o Call center na nuvem, consulte Call centerna nuvem.

CTI_API - GET /sn_cti_core/cti_api/call_analysis/{interaction_sys_id}

Renderiza transcrições e gravações para uma chamada de agente especificada.

Os componentes usam este endpoint nos Espaços do agente e do gerente para renderizar transcrições e gravações de chamadas de agente associadas. Para acessar esse endpoint, as credenciais do usuário passadas na chamada devem ter a função workspace_user, interaction_agent ou admin.

Este endpoint tem um ponto de extensão correspondente, sn_cti_core.CTICAllAnalysisExtractor, que é responsável pela renderização dos dados da chamada. O sistema de base fornece uma implementação para o Amazon Connect. Se sua implementação for diferente, você deverá personalizar este ponto de extensão antes de utilizar este endpoint. Além disso, os parâmetros de resposta retornados por este endpoint correspondem à implementação deste ponto de extensão. Para obter informações adicionais sobre como implementar pontos de extensão, consulte Como usar pontos de extensão para estender a funcionalidade da aplicação e Pontos de extensão no Call center na nuvem.

Formato de URL

URL padrão: /api/sn_cti_core/cti_api/call_analysis/{interaction_sys_id}

Parâmetros de solicitação compatíveis

Tabela 1. Parâmetros de caminho

Nome	Descrição
interaction_sys_id	Sys_id da chamada do agente para a qual renderizar para transcrição e gravação. Localizado na tabela Interação [interação]. Tipo de dados: cadeia de caracteres

Tabela 2. Parâmetros de consulta

Nome	Descrição
Nenhum

Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)

Nome	Descrição
Nenhum

Cabeçalhos

Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

Tabela 4. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml. Padrão: application/json

Tabela 5. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.

Tabela 6. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
Vários	Depende da implementação no ponto de extensão sn_cti_core.CTICAllAnalysisExtractor.

Parâmetros do corpo da resposta (JSON ou XML)

Nome	Descrição
Depende da implementação no ponto de extensão sn_cti_core.CTICAllAnalysisExtractor.

Solicitação de cURL

O exemplo a seguir solicita a renderização de uma chamada de agente específica.

curl -X POST \
  https://instance.servicenow.com/api/sn_cti_core/cti_api/call_analysis/88f2d9b7dbd7101058f05214dc96192a \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'

Dados de chamada renderizados com base no processamento especificado no ponto de extensão sn_cti_core.CTICAllAnalysisExtractor.

{
  "result":{
    "status":"success",
    "recordingData":{
      "recordingUrls":[
        "https://instance.awsapps.com/connect/get-recording?format=wav&callLegId=7626da7f-e083-4085-b77a-85bfea18fe24",
        "https://s3.console.aws.amazon.com/s3/object/connect-60f8665899b6/connect/instance/CallRecordings/2020/09/23/7626da7f-e083-4085-b77a-85bfea18fe24_20200923T18%3A24_UTC.wav"
      ],
      "status":"success"
    },
    "transcriptData":{
      "transcript":[
        {
          "content":"Okay. Hello? Mhm. Okay, okay.",
          "beginOffsetMillis":3940,
          "participantId":"CUSTOMER",
          "additionalInfo":[
            {
              "value":"Neutral",
              "highlightColor":"info"
            }
          ]
        },
        {
          "content":"bye.",
          "beginOffsetMillis":26040,
          "participantId":"AGENT",
          "additionalInfo":[
            {
              "value":"Neutral",
              "highlightColor":"info"
            }
          ]
        }
      ],
      "sentimentTrend":[
        {
          "x":0,
          "y":0
        },
        {
          "x":3939,
          "y":0
        },
        {
          "x":3940,
          "y":0
        },
        {
          "x":26450,
          "y":0
        }
      ],
      "sentimentPercents":{
        "positive":0,
        "neutral":100,
        "negative":0
      },
      "talkTimePercents":{
        "agent_talk_time":2.515491747959998,
        "customer_talk_time":28.82998956991226,
        "non_talk_time":68.65451868212774
      },
      "metadata":{
        "ctiVendor":"amazon_connect",
        "customerId":"Alice Smith",
        "agentId":"Piper Epps"
      },
      "status":"success"
    },
    "metadata":{
      "callMonitorURL":"https://instance.awsapps.com/connect/real-time-metrics?tableType=user",
      "recordingState":"success",
      "transcriptState":"success",
      "emptyStateImages":{
        "in_progress":"call_in_progress.png",
        "processing":"processing_post_call.png",
        "unavailable":"transcript_failed.png"
      }
    }
  }
}

CTI_API - POST /sn_cti_core/cti_api/providers/{provider}/components/{component}/versions/{version}

Invoca operações de integração de telefonia e computador (CTI) usando manipuladores de operação especificados na estrutura do Call center na nuvem.

Antes de chamar este endpoint, você deve criar um registro de configuração do provedor e os transformadores de mensagem associados. Isso normalmente é feito quando a estrutura do Cloud Call Center é implementada pela primeira vez em sua instância. Para obter informações adicionais, consulte Configuração do provedor no Cloud Call Center.

Um transformador de mensagem é responsável por analisar a carga especificada no corpo da solicitação deste endpoint e definir os dados da carga em um objeto CTIOperationRequest associado. Um manipulador de operação é responsável por obter as informações do objeto CTIOperationRequest e usar os dados para processar a operação solicitada.

Depois que o transformador de mensagem termina de analisar a carga passada, a estrutura do Call center na nuvem instancia o manipulador de operação especificado. O manipulador operacional usa os métodos GET da API CTIOperationResponse CTIOperationResponse - com escopo, global para obter as informações necessárias do objeto CTIOperationRequest associado para processar a operação solicitada.

Você define o manipulador de operação a ser invocado e seus parâmetros associados no corpo da solicitação desta chamada de endpoint. O manipulador de operação especificado deve ser definido em sua instância na tabela Operation Handler [sn_cti_operation_handler]. Para obter informações adicionais sobre como criar manipuladores de operação, consulte Configurar um fluxo de contato para uma interação automatizada com o solicitante.

O sistema base ServiceNow fornece manipuladores de operação e transformadores de mensagem que permitem a conexão com o Amazon Connect. Ao criar fluxos de contato no Amazon Connect, há dois pontos de integração entre os serviços da Amazon e uma instância ServiceNow :

• Proxy do Amazon Web Services (AWS) Lambda (invocar a função do AWS Lambda)
• Bot do AWS Lex (obter entrada do cliente)

Você pode encontrar os manipuladores de operação e os transformadores de mensagem disponíveis para esses pontos de integração nas tabelas Manipuladores de operação [sn_cti_operation_handler] e Transformador de mensagem do provedor [sn_cti_provider_msg_transormer].

Além disso, as credenciais do usuário que você passa na chamada devem ter a função de administrador ou sn_cti_core.service para acessar este endpoint.

Para obter informações adicionais sobre o Call center na nuvem, consulte Call centerna nuvem.

Formato de URL

URL padrão: /api/sn_cti_core/cti_api/providers/{provider}/components/{component}/versions/{version}

Parâmetros de solicitação compatíveis

Tabela 7. Parâmetros de caminho

Nome	Descrição
componente	Rótulo do componente do seu provedor, como sn_aws_connect_lambda_proxy_component ou sn_aws_connect_lex_intent_processor_component. Localizado no campo Componente da tabela Componente do provedor [sn_cti_provider_component]. Tipo de dados: cadeia de caracteres
provedor	Sys_id do registro do seu provedor de CTI. Localizado na tabela Componente do provedor [sn_cti_provider_component]. Tipo de dados: cadeia de caracteres
versão	Versão do registro do provedor especificado. Localizado no campo Versão da tabela Componente do provedor [sn_cti_provider_component]. Tipo de dados: cadeia de caracteres

Tabela 8. Parâmetros de consulta

Nome	Descrição
Nenhum

Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)

Nome	Descrição
Depende do manipulador de operação que está sendo chamado e de sua implementação específica.

Cabeçalhos

Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

Tabela 10. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml. Padrão: application/json

Tabela 11. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.

Tabela 12. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
Vários	Depende da operação que está sendo chamada e de sua implementação específica.

Parâmetros do corpo da resposta (JSON ou XML)

Nome	Descrição
Depende da operação que está sendo chamada e de sua implementação específica.

Solicitação de cURL

O exemplo a seguir invoca o manipulador de operação interactionEvent por meio do componente sn_aws_connect_lambda_proxy_component.

curl -X POST \
  https://instance.servicenow.com/api/sn_cti_core/cti_api/providers/c4b12aa6e700001034b36584c2f6a9bc/components/sn_aws_connect_lambda_proxy_component/versions/v1.0 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'
  -d '{
  "context": {
    "callbackWaitsForEmptyEventLoop": true,
    "functionVersion": "$LATEST",
    "functionName": "snRALJNLambda",
    "memoryLimitInMB": "128",
    "logGroupName": "/aws/lambda/snRALJNLambda",
    "logStreamName": "2020/09/24/[$LATEST]b604a9579ef548a1b3f6b6739d19e1d9",
    "invokedFunctionArn": "arn:aws:lambda:us-west-2:028738656045:function:snRALJNLambda",
    "awsRequestId": "b528a5a8-bb0b-4ec8-8e76-aa568f68fdc8"
  },
  "event": {
    "Details": {
      "ContactData": {
        "Attributes": {
          "$accepted_terms": "true"
        },
        "Channel": "VOICE",
        "ContactId": "8fe7c107-78df-4eec-85b3-91c6dcb8e912",
        "CustomerEndpoint": {
          "Address": "[phone]",
          "Type": "TELEPHONE_NUMBER"
        },
        "Description": null,
        "InitialContactId": "8fe7c107-78df-4eec-85b3-91c6dcb8e912",
        "InitiationMethod": "INBOUND",
        "InstanceARN": "arn:aws:connect:us-west-2:028738656045:instance/d276bd83-6305-4f63-abee-e66fd5bdf503",
        "LanguageCode": "en-US",
        "MediaStreams": {
          "Customer": {
            "Audio": null
           }
         },
         "Name": null,
         "PreviousContactId": "8fe7c107-78df-4eec-85b3-91c6dcb8e912",
         "Queue": {
           "ARN": "arn:aws:connect:us-west-2:028738656045:instance/d276bd83-6305-4f63-abee-e66fd5bdf503/queue/0f17b62d-d493-439a-88c6-42db0d0e652f",
           "Name": "BasicQueue",
           "OutboundCallerId": {
             "Address": "[phone]",
             "Type": "TELEPHONE_NUMBER"
           }
         },
         "References": {},
         "SystemEndpoint": {
           "Address": "[phone]",
           "Type": "TELEPHONE_NUMBER"
         }
       },
       "Parameters": {
         "sn_component": "sn_aws_connect_lambda_proxy_component",
         "sn_operation": "interactionEvent"
       }
     },
     "Name": "ContactFlowEvent"
   }
 }'

Exemplo de resposta à chamada do manipulador da operação interactionEvent.

{
  "result": {
    "snc_user_first_name": "Jane",
    "snc_user_last_name": "Doe",
    "snc_user_sys_id": "bbe591bfdb5710100231dbdb5e9619e3",
    "snc_user_vip": "false",
    "interactionTable": "interaction",
    "interactionId": "973b07c8dbe710100231dbdb5e961908",
    "statusCode": 200,
    "message": "success"
  }
}

CTI_API - POST /sn_cti_core/cti_api/softphone/sources/{source}/actor/{actor}/events/{event}

Passa eventos de um provedor de Painel de controle de contato (CCP) para uma instância ServiceNow.

Normalmente, você chama este endpoint da página de IU do CCP para executar várias tarefas (eventos), como mudar o estado de presença de um agente ou mudar o estado de um registro na conclusão da chamada. Para acessar este endpoint, as credenciais do usuário passadas na chamada devem ter a função sn_openframe_user ou admin.

Este endpoint tem um ponto de extensão correspondente, sn_cti_core.SoftPhoneEventSink, que é responsável por determinar a ação que é realmente realizada por esta chamada de endpoint para cada evento. O sistema de base fornece uma implementação para eventos do Amazon Connect. Se sua implementação for diferente, você deverá personalizar este ponto de extensão antes de utilizar este endpoint. O corpo da solicitação e os formatos de resposta deste endpoint correspondem à implementação deste ponto de extensão. Para obter informações adicionais sobre como implementar pontos de extensão, consulte Como usar pontos de extensão para estender a funcionalidade da aplicação e Pontos de extensão no Call center na nuvem.

Formato de URL

URL padrão: /api/sn_cti_core/cti_api/softphone/sources/{source}/actor/{actor}/events/{event}

Parâmetros de solicitação compatíveis

Tabela 13. Parâmetros de caminho

Nome	Descrição
ator	Emissor do evento, como agent ou external_system. Os valores específicos são determinados pelo implementador. Tipo de dados: cadeia de caracteres
evento	Nome do evento no sistema do fornecedor da Integração de telefonia e computação (CTI), como Disponível ou Off-line. Os valores específicos são determinados pelo implementador, mas devem ser uma única palavra/frase sem espaços ou caracteres especiais. Tipo de dados: cadeia de caracteres
origens	Identificador da página de IU do Softphone do fornecedor, como aws_ccp. Tipo de dados: cadeia de caracteres

Tabela 14. Parâmetros de consulta

Nome	Descrição
Nenhum

Tabela 15. Parâmetros do corpo da solicitação (XML ou JSON)

Nome	Descrição
Específico da implementação. Determinado pela implementação do ponto de extensão sn_cti_core.SoftPhoneEventSink.

Cabeçalhos

Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

Tabela 16. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml. Padrão: application/json

Tabela 17. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.

Tabela 18. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.

Parâmetros do corpo da resposta (JSON ou XML)

Nome	Descrição
Nenhum

Solicitação de cURL

O exemplo a seguir passa informações de evento AgentStatusOne para a instância ServiceNow. Os parâmetros do corpo da solicitação são determinados pela implementação do ponto de extensão sn_cti_core.SoftPhoneEventSink.

curl -X POST \
  https://instance.servicenow.com/api/sn_cti_core/cti_api/softphone/sources/aws_ccp/actor/agent/events/AgentStatusOne \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'
  -d '{
   "agent":{
      "sys_id":"doe.john@snc",
      "status":{
         "agentStateARN":null,
         "type":"not_routable",
         "name":"AgentStatusOne",
         "startTimestamp":"2020-09-24T21:43:20.957Z"
      }
   },
   "window":{
      "location":{
         "href":"https://instance.servicenow.com/sn_cti_amzn_cct_aws_ccp.do?id=44106eabdb5710100231dbdb5e96191d",
         "search":"?id=44106eabdb5710100231dbdb5e96191d"
      }
   },
   "aws":{
      "connect":{
         "config":{
            "ccpHost":"instance.awsapps.com",
            "ccpUrl":"https://instance.awsapps.com/connect/ccp-v2/",
            "loginPopup":true,
            "audioRecordingUrlPrefix":"https://instance.awsapps.com/connect/get-recording?format=wav&callLegId=",
            "softphone":{
               "allowFramedSoftphone":true
            },
            "region":"us-west-2"
         }
      }
   }
}'

Nenhum parâmetro de resposta é retornado.

{
  "result": {}
}