CTI API

Referência de API Zurich

Release

zurich

ft:locale

pt-BR

ft:publication_title

Referência de API Zurich

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

CTI API

Versão de lançamento: Zurich

Atualizado 31 de jul. de 2025

9 min. de leitura

. CTI A API fornece endpoints que permitem que os provedores de Integração de telefonia por computador (CTI) interajam com a estrutura do call center em nuvem.

Usando esta API, os integradores podem:

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 ServiceNow instâ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 Cloud Call Center Core (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 - OBTÉM /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 do 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 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 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/cti_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 [interaction]

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

Tabela 3. Solicitar parâmetros do corpo (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 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/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 Códigos de resposta HTTP da REST API .

Tabela 6. Códigos de status
Código do 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/

Invoca operações de Integração de telefonia por computador (CTI) usando manipuladores de operação especificados na estrutura do call center em 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 mensagem conclui a análise da carga passada, a estrutura do call center na nuvem instancia o manipulador de operação especificado. O manipulador operacional usa o. CTIOperationResponse CTIOperationResponse - Com escopo, global API 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 .

. ServiceNow O sistema de 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 ServiceNow instância:

Proxy Lambda da Amazon Web Services (AWS) (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 de 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/cti_api/providers/

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 registro do 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. Solicitar parâmetros do corpo (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 Códigos de resposta HTTP da REST API .

Tabela 12. Códigos de status
Código do 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 - POST /sn_cti_core/cti_api/softphone/sources/

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

Normalmente, 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 do 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 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 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/cti_api/softphone/sources/

Parâmetros de solicitação compatíveis

Tabela 13. Parâmetros de caminho
Nome	Descrição
ator	Emissor do evento, como agente 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 por computador (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. Solicitar parâmetros do corpo (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 Códigos de resposta HTTP da REST API .

Tabela 18. Códigos de status
Código do 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 de evento do AgentStatusOne para ServiceNow instâ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": {}
}