CTI API

Referência da API de Yokohama

Release

yokohama

ft:locale

pt-BR

ft:publication_title

Referência da API de Yokohama

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

CTI API

Versão de lançamento: Yokohama

Atualizado 30 de jan. de 2025

9 min. de leitura

. CTI A API fornece endpoints que permitem que os provedores de Integração de Telefonia Computacional (CTI) interajam com a estrutura do call center na nuvem.

Usando esta API, os integradores são capazes de:

Invoque operações de CTI usando manipuladores de operação personalizados na estrutura do call center na nuvem.
Passar eventos de um provedor de CCP para um ServiceNowinstância.
Renderize transcrições e gravações para uma chamada de agente especificada.

Esta API é executada no sn_cti_corenamespace. Para acessar esta API, você deve instalar a aplicação Núcleo do call center na nuvem (sn_cti_core). Para obter informações sobre esta instalação, consulte Instale aplicações de call center na nuvem .

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

CTI_api - OBTER /sn_cti_core/cti_api/call_analysis/

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 do agente associadas. Para acessar este endpoint, as credenciais de usuário que você passa 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 por renderizar os dados da chamada. O sistema base fornece uma implementação para o Amazon Connect. Se a sua implementação for diferente, você deve 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 Usando 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/ci_api/call_analysis/

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. Tipo de dados: Cadeia de caracteres Tabela: Interação [interação]

Tabela 2. Parâmetros de consulta
Nome	Descrição
Nenhum(a)

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

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 da 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/jsonou application/xml. Padrão: application/json

Tabela 5. Cabeçalhos de resposta
Cabeçalho	Descrição
Nenhum(a)

Códigos de status

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

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/provedores//components//Components//versões/ versão

Invoca operações de Integração de Telefonia Computacional (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 transformadores de mensagem associados. Normalmente, isso é feito quando a estrutura do call center na nuvem é implementada inicialmente em sua instância. Para obter informações adicionais, consulte Configuração do provedor no call center na nuvem .

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 associado CTIOperationRequest objeto. 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 mensagens termina de analisar a carga passada, a estrutura do call center na nuvem instancia o manipulador de operação especificado. O manipulador operacional usa o. CTIOperationResponse CTIOperationResponse - escopo, globalAPI OBTER métodos 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 Manipulador de operações [sn_cti_operation_handler]. Para obter informações adicionais sobre como criar manipuladores de operação, consulte Configure um fluxo de contato para uma interação automatizada do chamador .

. ServiceNowO sistema base fornece manipuladores de operação de trabalho 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 um ServiceNowinstância:

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

Você pode encontrar os manipuladores de operação e 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 de usuário que você passa na chamada devem ter a função sn_cti_core.service ou administrador para acessar este endpoint.

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

Formato de URL

URL padrão: /api/sn_cti_core/ci_api/providers//components/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 provedor, como sn_aws_connect_lambda_proxy_component ou sn_aws_connect_lex_intent_processor_component. Tipo de dados: Cadeia de caracteres Tabela: Campo de componente do componente do provedor [sn_cti_provider_component]
provedor	Sys_id do seu registro de provedor de CTI. Tipo de dados: Cadeia de caracteres Tabela: Componente do provedor [sn_cti_provider_component]
versão	Versão do registro do provedor especificado. Tipo de dados: Cadeia de caracteres Tabela: No campo Versão da tabela Componente do provedor [sn_cti_provider_component].

Tabela 8. Parâmetros de consulta
Nome	Descrição
Nenhum(a)

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 sua implementação específica.

Cabeçalhos

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

Tabela 11. Cabeçalhos de resposta
Cabeçalho	Descrição
Nenhum(a)

Códigos de status

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

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 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 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": "+16693504374",
          "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": "+18335441399",
             "Type": "TELEPHONE_NUMBER"
           }
         },
         "References": {},
         "SystemEndpoint": {
           "Address": "+18335441399",
           "Type": "TELEPHONE_NUMBER"
         }
       },
       "Parameters": {
         "sn_component": "sn_aws_connect_lambda_proxy_component",
         "sn_operation": "interactionEvent"
       }
     },
     "Name": "ContactFlowEvent"
   }
 }'

Resposta de exemplo para a chamada do manipulador de 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 - PUBLICAR /sn_cti_core/cti_api/softphone/sources//ator/(ator)/eventos/(evento)

Passa eventos de um provedor de Painel de controle de contato (CCP) para um ServiceNowinstância.

Em geral, você chama esse endpoint na 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 de usuário que você passa 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 base fornece uma implementação para eventos do Amazon Connect. Se a sua implementação for diferente, você deve 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 Usando 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/ci_api/softphone/sources//ator/(ator)/events/(evento)

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 de Integração de Telefonia Computacional (CTI), como Disponível ou Offline. 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_cpc. Tipo de dados: Cadeia de caracteres

Tabela 14. Parâmetros de consulta
Nome	Descrição
Nenhum(a)

Tabela 15. Parâmetros do corpo da solicitação (XML ou JSON)
Nome	Descrição
Implementação específica. Determinado pela implementação do ponto de extensão sn_cti_core.SoftPhoneEventSink.

Cabeçalhos

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

Tabela 17. Cabeçalhos de resposta
Cabeçalho	Descrição
Nenhum(a)

Códigos de status

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

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(a)

Solicitação de curl

O exemplo a seguir passa informações do evento AgentStatusOne para o. ServiceNowinstância. 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": {}
}