--- sourceDocument: Xanadu API Reference sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference Release : - xanadu ft:locale : - en-US ft:publication_title : - Xanadu API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # CTI API # CTI API {#ariaid-title1} * Release version: Xanadu * * Updated August 1, 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 8 minutes to read 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. {#cti-api__ul_wrs_spc_2nb} 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](https://www.servicenow.com/docs/access?context=install-ccc-apps&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). For additional information on the Cloud Call Center, see [Cloud Call Center](https://www.servicenow.com/docs/access?context=cloud-call-center-overview&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). ## CTI_API - GET /sn_cti_core/cti_api/call_analysis/{interaction_sys_id} {#ariaid-title2} 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](https://servicenow-prod.fluidtopics.net/agUCalbZ4ypHMncaJXRaoQ "Use extension points to extend the functionality of an application without altering the original application code. You can use pre-existing extension points available in selected ServiceNow AI Platform applications, or you can add extension points when you develop custom applications in your own instance.") and [Extension points in Cloud Call Center](https://www.servicenow.com/docs/access?context=extension-point-ccc&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). ### URL format Default URL: /api/sn_cti_core/cti_api/call_analysis/{interaction_sys_id} ### Supported request parameters {#cti_api-GET-call_analysis__entry__2} | Name | Description | |-|-| | interaction_sys_id | Sys_id of the agent call for which to render to transcript and recording. Located in the Interaction \[interaction\] table. Data type: String | [Table 1. Path parameters] {#cti_api-GET-call_analysis__entry__6} | Name | Description | |-|-| | None | | [Table 2. Query parameters] {#cti_api-GET-call_analysis__entry__10} | Name | Description | |-|-| | None | | [Table 3. Request body parameters (XML or JSON)] ### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#cti_api-GET-call_analysis__entry__14}{#cti_api-GET-call_analysis__accept-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json | [Table 4. Request headers] {#cti_api-GET-call_analysis__entry__18} | Header | Description | |-|-| | None | | [Table 5. Response headers] ### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#cti_api-GET-call_analysis__entry__22}{#cti_api-GET-call_analysis__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | Various | Depends on the implementation in the sn_cti_core.CTICallAnalysisExtractor extension point. | [Table 6. Status codes] ### Response body parameters (JSON or XML) {#cti_api-GET-call_analysis__entry__28} | Name | Description | |-|-| | Depends on the implementation in the sn_cti_core.CTICallAnalysisExtractor extension point. | | [ ] ### cURL request {#cti_api-GET-call_analysis__example_h2g_cs1_2nb} 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} {#ariaid-title3} 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](https://www.servicenow.com/docs/access?context=provider-configuration-ccc&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). 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](https://servicenow-prod.fluidtopics.net/F5PYyUBzJcPNBpkPugBQeQ#CTIOperationRequestAPI "The CTIOperationRequest script include provides methods to set and get data on the current CTIOperationRequest object.") 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](https://servicenow-prod.fluidtopics.net/5ijvP7RkHP~~EiAqN4XyIA#CTIOperationResponseAPI "The CTIOperationResponse script include provides methods to set and get data on the current CTIOperationResponse object.") [CTIOperationResponse - Scoped, Global](https://servicenow-prod.fluidtopics.net/5ijvP7RkHP~~EiAqN4XyIA#CTIOperationResponseAPI "The CTIOperationResponse script include provides methods to set and get data on the current CTIOperationResponse object.") 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](https://www.servicenow.com/docs/access?context=establish-automated-bot-interactions&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). 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) {#cti_api-POST-prov-comp-ver__ul_pqp_3hl_hlb}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](https://www.servicenow.com/docs/access?context=cloud-call-center-overview&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). ### URL format Default URL: /api/sn_cti_core/cti_api/providers/{provider}/components/{component}/versions/{version} ### Supported request parameters {#cti_api-POST-prov-comp-ver__entry__2} | Name | Description | |-|-| | component | Label of your provider component, such as sn_aws_connect_lambda_proxy_component or sn_aws_connect_lex_intent_processor_component. Located in the Component field of the Provider Component \[sn_cti_provider_component\] table. Data type: String | | provider | Sys_id of your CTI provider record. Located in the Provider Component \[sn_cti_provider_component\] table. Data type: String | | version | Version of the specified provider record. Located in the Version field of the Provider Component \[sn_cti_provider_component\] table. Data type: String | [Table 7. Path parameters] {#cti_api-POST-prov-comp-ver__entry__10} | Name | Description | |-|-| | None | | [Table 8. Query parameters] {#cti_api-POST-prov-comp-ver__entry__14} | Name | Description | |-|-| | Depends on the operation handler being called and its specific implementation. | | [Table 9. Request body parameters (XML or JSON)] ### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#cti_api-POST-prov-comp-ver__entry__18}{#cti_api-POST-prov-comp-ver__accept-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json | [Table 10. Request headers] {#cti_api-POST-prov-comp-ver__entry__22} | Header | Description | |-|-| | None | | [Table 11. Response headers] ### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#cti_api-POST-prov-comp-ver__entry__26}{#cti_api-POST-prov-comp-ver__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | | Various | Depends on the operation being called and its specific implementation. | [Table 12. Status codes] ### Response body parameters (JSON or XML) {#cti_api-POST-prov-comp-ver__entry__32} | Name | Description | |-|-| | Depends on the operation being called and its specific implementation. | | [ ] ### 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} {#ariaid-title4} 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](https://servicenow-prod.fluidtopics.net/agUCalbZ4ypHMncaJXRaoQ "Use extension points to extend the functionality of an application without altering the original application code. You can use pre-existing extension points available in selected ServiceNow AI Platform applications, or you can add extension points when you develop custom applications in your own instance.") and [Extension points in Cloud Call Center](https://www.servicenow.com/docs/access?context=extension-point-ccc&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US). ### URL format Default URL: /api/sn_cti_core/cti_api/softphone/sources/{source}/actor/{actor}/events/{event} ### Supported request parameters {#cti_api-POST-softphone__entry__2} | 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 13. Path parameters] {#cti_api-POST-softphone__entry__10} | Name | Description | |-|-| | None | | [Table 14. Query parameters] {#cti_api-POST-softphone__entry__14} | Name | Description | |-|-| | Implementation specific. Determined by the implementation of the sn_cti_core.SoftPhoneEventSink extension point. | | [Table 15. Request body parameters (XML or JSON)] ### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#cti_api-POST-softphone__entry__18}{#cti_api-POST-softphone__accept-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json | [Table 16. Request headers] {#cti_api-POST-softphone__entry__22} | Header | Description | |-|-| | None | | [Table 17. Response headers] ### 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](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other."). {#cti_api-POST-softphone__entry__26}{#cti_api-POST-softphone__entry-200-status-code} | Status code | Description | |-|-| | 200 | Successful. The request was successfully processed. | [Table 18. Status codes] ### Response body parameters (JSON or XML) {#cti_api-POST-softphone__entry__30} | Name | Description | |-|-| | None | | [ ] ### cURL request {#cti_api-POST-softphone__example_h2g_cs1_2nb} 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": {} }