The CTI API provides endpoints that enable Computer Telephony Integration (CTI) providers to interact with the Cloud Call Center framework.

Using this API, integrators are able to:
  • Invoke CTI operations using custom operation handlers within the Cloud Call Center framework.
  • Pass events from a CCP provider to a ServiceNow instance.
  • Render transcripts and recordings for a specified agent call.

This API runs in the sn_cti_core namespace. Before you are able to access this API, you must install the Cloud Call Center Core (sn_cti_core) application. For information on this installation, see Install Cloud Call Center applications.

For additional information on the Cloud Call Center, see Cloud Call Center.

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

Renders transcripts and recordings for a specified agent call.

Components use this endpoint in Agent and Manager workspaces to render associated agent call transcripts and recordings. To access this endpoint, the user credentials that you pass in the call must have the workspace_user, interaction_agent, or admin role.

This endpoint has a corresponding extension point, sn_cti_core.CTICallAnalysisExtractor, that is responsible for rendering the call data. The base system provides an implementation for Amazon Connect. If your implementation is different, you should customize this extension point before utilizing this endpoint. Also, the response parameters returned by this endpoint correspond to the implementation of this extension point. For additional information on implementing extension points, see Using extension points to extend application functionality and Extension points in Cloud Call Center.

URL format

Default URL: /api/sn_cti_core/cti_api/call_analysis/{interaction_sys_id}

Supported request parameters

Table 1. Path parameters
Name Description
interaction_sys_id Sys_id of the agent call for which to render to transcript and recording.

Data type: String

Table: Interaction [interaction]
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes
Status code Description
200 Successful. The request was successfully processed.
Various Depends on the implementation in the sn_cti_core.CTICallAnalysisExtractor extension point.

Response body parameters (JSON or XML)

Name Description
Depends on the implementation in the sn_cti_core.CTICallAnalysisExtractor extension point.

Example: cURL request

The following example requests the rendering of a specific agent call.

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'

Rendered call data based on the processing specified in the sn_cti_core.CTICallAnalysisExtractor extension point.

{
  "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}

Invokes Computer Telephony Integration (CTI) operations using a specified operation handlers within the Cloud Call Center framework.

Before calling this endpoint, you must create a provider configuration record and associated message transformers. This is typically done when the Cloud Call Center framework is initially implemented in your instance. For additional information, see Provider configuration in Cloud Call Center.

A message transformer is responsible for parsing the payload specified in the request body of this endpoint and setting the payload data on an associated CTIOperationRequest object. An operation handler is then responsible for getting the information from the CTIOperationRequest object and using the data to process the requested operation.

After the message transformer finishes parsing the passed in payload, the Cloud Call Center framework instantiates the specified operation handler. The operating handler uses the CTIOperationResponse CTIOperationResponse - Scoped, Global API GET methods to obtain the information that it needs from the associated CTIOperationRequest object to process the requested operation.

You define the operation handler to invoke, and its associated parameters, in the request body of this endpoint call. The specified operation handler must be defined in your instance within the Operation Handler [sn_cti_operation_handler] table. For additional information on creating operation handlers, see Configure a contact flow for an automated caller interaction.

The ServiceNow base system provides working operation handlers and message transformers that enable connection to Amazon Connect. When building contact flows within Amazon Connect, there are two integration points between Amazon services and a ServiceNow instance:
  • Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
  • AWS Lex Bot (Get Customer Input)
You can find the available operation handlers and message transformers for these integration points in the Operation Handlers [sn_cti_operation_handler] and Provider Message Transformer [sn_cti_provider_msg_transormer] tables.

In addition, the user credentials that you pass in the call must have the sn_cti_core.service or admin role to access this endpoint.

For additional information on the Cloud Call Center, see Cloud Call Center.

URL format

Default URL: /api/sn_cti_core/cti_api/providers/{provider}/components/{component}/versions/{version}

Supported request parameters

Table 7. Path parameters
Name Description
component Label of your provider component, such as sn_aws_connect_lambda_proxy_component or sn_aws_connect_lex_intent_processor_component.

Data type: String

Table: Component field of the Provider Component [sn_cti_provider_component]
provider Sys_id of your CTI provider record.

Data type: String

Table: Provider Component [sn_cti_provider_component]
version Version of the specified provider record.

Data type: String

Table: In the Version field of the Provider Component [sn_cti_provider_component] table.
Table 8. Query parameters
Name Description
None
Table 9. Request body parameters (XML or JSON)
Name Description
Depends on the operation handler being called and its specific implementation.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 11. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 12. Status codes
Status code Description
200 Successful. The request was successfully processed.
Various Depends on the operation being called and its specific implementation.

Response body parameters (JSON or XML)

Name Description
Depends on the operation being called and its specific implementation.

Example: cURL request

The following example invokes the interactionEvent operation handler through the sn_aws_connect_lambda_proxy_component 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"
   }
 }'

Example response to the interactionEvent operation handler call.

{
  "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}

Passes events from a Contact Control Panel (CCP) provider to a ServiceNow instance.

Typically you call this endpoint from your CCP UI page to perform various tasks (events), such as changing the presence state of an agent or changing the state of a record on call completion. To access this endpoint, the user credentials that you pass in the call must have the sn_openframe_user or admin role.

This endpoint has a corresponding extension point, sn_cti_core.SoftPhoneEventSink, that is responsible for determining the action that is actually performed by this endpoint call for each event. The base system provides an implementation for Amazon Connect events. If your implementation is different, you should customize this extension point before utilizing this endpoint. The request body and response formats of this endpoint correspond to the implementation of this extension point. For additional information on implementing extension points, see Using extension points to extend application functionality and Extension points in Cloud Call Center.

URL format

Default URL: /api/sn_cti_core/cti_api/softphone/sources/{source}/actor/{actor}/events/{event}

Supported request parameters

Table 13. Path parameters
Name Description
actor Emitter of the event, such as agent or external_system. The specific values are determined by the implementer.

Data type: String
event Name of the event in the Computer Telephony Integration (CTI) vendor’s system, such as Available or Offline. The specific values are determined by the implementer but must be a single word/phrase without spaces or special characters.

Data type: String
sources Identifier of the vendor's Softphone UI page, such as aws_ccp.

Data type: String
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
Name Description
Implementation specific. Determined by the implementation of the sn_cti_core.SoftPhoneEventSink extension point.

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 16. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 17. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 18. Status codes
Status code Description
200 Successful. The request was successfully processed.

Response body parameters (JSON or XML)

Name Description
None

Example: cURL request

The following example passes AgentStatusOne event information to the ServiceNow instance. The request body parameters are determined by the implementation of the sn_cti_core.SoftPhoneEventSink extension point.

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"
         }
      }
   }
}'

No response parameters are returned.

{
  "result": {}
}