CTIOperationResponse - Scoped, Global
-
- UpdatedJan 30, 2025
- 17 minutes to read
- Yokohama
- API reference
The CTIOperationResponse script include provides methods to set and get data on the current CTIOperationResponse object.
You use CTIOperationResponse objects to pass information between an operation handler and a message transformer within the ServiceNow Voice framework.
Typically, an operation handler is responsible for setting values on the CTIOperationResponse object as it processes the associated request. A message transformer is then responsible for getting the values from the CTIOperationRequest object and building the CTI-specific payload that is sent back to the computer telephony integrator (CTI) provider.
- Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
- AWS Lex Bot (Get Customer Input)
The following operation handler script shows how to use various CTIOperationResponse methods to set values on the CTIOperationResponse object.
For additional information on creating operation handlers, see Configure a contact flow for an automated caller interaction.
The following message transformer script gets the values set on the CTIOperationResponse object and stores them in the CTI-specific payload that is then sent back to the CTI provider.
This script include runs in the sn_cti_core
namespace. Before you are able to access the CTIOperationRequest script include, the ServiceNow
Voice Core (sn_cti_core) plugin must be installed. For information on this installation, see Install ServiceNow Voice applications.
For additional information on the ServiceNow Voice, see ServiceNow Voice.
CTIOperationResponse - CTIOperationResponse(String origin)
Instantiates a CTIOperationResponse object.
Name | Type | Description |
---|---|---|
None |
Example
CTIOperationResponse - getAuthToken()
Returns the authentication token that was set on the CTIOperationResponse object.
This token is used by the ServiceNow Voice framework to authenticate the current ServiceNow Voice user before executing the requested operation handler if the handler's auth_required flag is set to true. The auth_required flag is a field in the Operation Handler [sn_cti_operation_handler] table. The life of an authentication token should be for the life of the call session, but is determined by the CTI provider.
You can define whatever authentication/authorization handling required by your implementation by creating your own authentication operation handler. Regardless of how the authentication token is generated, the message translator must pass the token back in the CTI payload. Additionally, the CTI provider must store this authentication token locally and pass it in each operation request that requires authentication.
If using the instance provided authenticate operation handler, the handler initiates the creation of the authentication token based on a four-digit user-entered pin. It then sets the authentication token in the sessionAttributes object of the CTIOperationResponse object. The associated message transformer translates the sessionAttributes object into the CTI-specific payload and then sends it to the CTI provider.
- Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
- AWS Lex Bot (Get Customer Input)
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | The authentication token previously set on the CTIOperationRequest object. If not set, returns null. |
Example
CTIOperationResponse - getError()
Returns the error object associated with the current CTIOperationResponse object.
You might use this information to formulate the payload returned to the computer telephony integration (CTI) provider.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Object | Operation error information. The format of this object is determined by the CTI provider. If an error does not exist, returns null. |
Example
CTIOperationResponse - getInteractionSysId()
Returns the sys_id of the interaction record associated with the call session that was set on the CTIOperationResponse object.
The CTIOperationResponse - setInteractionSysId(String Id) method must have been called prior to calling this method.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | Sys_id of the interaction record set on the CTIOperationResponse object. If the interaction record sys_id is not set, the method returns null. Table: Interaction [interaction] |
Example
CTIOperationResponse - getMajorVersion()
Returns the major version of the computer telephony integrator (CTI) software set on the current CTIOperationResponse object.
Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different payloads. If the payload is only slightly different between the software versions, it may make sense to have only a single message transformer. You can then handle the payload differences by just checking the version of software making the request within your message transformer. If the required payload is significantly different between versions, it may be more effective to use multiple message transformers.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Number | Major version number of the CTI software. If the major version was never set, returns 1. |
Example
CTIOperationResponse - getMessage()
Returns the message string set on the current CTIOperationResponse object.
Typically this is a message that is spoken back to the user once an operation is complete. You can set this value using the CTIOperationResponse - setMessage(String message) method.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | Message text. If no message exists, returns null. |
Example
CTIOperationResponse - getMinorVersion()
Returns the minor version of the computer telephony integrator (CTI) software set on the current CTIOperationResponse object.
Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different payloads. If the payload is only slightly different between the software versions, it may make sense to have only a single message transformer. You can then handle the payload differences by just checking the version of software making the request within your message transformer. If the required payload is significantly different between versions, it may be more effective to use multiple message transformers.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Number | Minor version number of the payload associated with this interaction. If the minor version was never set, returns 0. |
Example
CTIOperationResponse - getParameter(String key)
Returns the value of a specified key previously set on the current CTIOperationResponse object.
Using the get/set parameter methods enables the passing of virtually any string or number value between an operation handler and a message transformer. The parameter object can contain zero or more key/value pairs of data that directly correlate to the current operation response. The operation handler determines what key/value pairs are required as it produces these values. Use the CTIOperationResponse - setParameter(String key, Object value) method to set parameters on the current CTIOperationResponse object.
Name | Type | Description |
---|---|---|
key | String | The name of the key value to return. |
Type | Description |
---|---|
String | The value of the passed in key. If no such key exists, returns null. |
Example
CTIOperationResponse - getParameters()
Returns the key-value pairs for all parameters that were previously set on the current CTIOperationResponse object.
Using the get/set parameter methods enables the passing of virtually any string or number value between an operation handler and a message transformer. The parameter object can contain zero or more key/value pairs of data that directly correlate to the current operation response. The operation handler determines what key/value pairs are required as it produces these values. Use the CTIOperationResponse - setParameter(String key, Object value) method to set parameters on the current CTIOperationResponse object.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Object | A map of key-value pairs that were previously set on the CTIOperationResponse object. This key-value pairs are free-form and defined by the needs of the operation handler. The returned values are either Strings or Numbers. |
Example
CTIOperationResponse - getSessionAttribute(String key)
Returns the value for a specified session attribute key set on the current CTIOperationResponse object.
Using the get/set session attribute methods enables the passing of virtually any string or number value between an operation handler and a message transformer. Session attributes can also be accessed within a contact flow. The sessionAttribute object can contain zero or more key/value pairs of data, such as the contact's phone number, that are valid for the duration of a computer telephony integration provider defined session. The operation handler determines what session attribute key/value pairs are needed as it utilizes these values during processing. Typically the operation handler sets these attributes on the CTIOperationResponse object by calling the CTIOperationResponse - setSessionAttribute(String key, Object value) method and the message transformer consumes the attributes using this method.
Name | Type | Description |
---|---|---|
key | String | The name of the key value to return. |
Type | Description |
---|---|
String | Value of the passed in key. If no such key exists, returns null. |
Example
CTIOperationResponse - getSessionAttributes()
Returns the key-value pairs for all session attributes that were previously set on the current CTIOperationResponse object.
Using the get/set session attribute methods enables the passing of virtually any string or number value between an operation handler and a message transformer. Session attributes can also be accessed within a contact flow. The sessionAttribute object can contain zero or more key/value pairs of data, such as the contact's phone number, that are valid for the duration of a computer telephony integration provider defined session. The operation handler determines what session attribute key/value pairs are needed as it utilizes these values during processing. Typically the operation handler sets these attributes on the CTIOperationResponse object by calling the CTIOperationResponse - setSessionAttribute(String key, Object value) method and the message transformer consumes the attributes using this method.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Object | A map of key-value pairs that were previously set on the CTIOperationResponse object. This key-value pairs are free-form and defined by the needs of the operation handler. The returned values are either Strings or Numbers. |
Example
CTIOperationResponse - getStatusCode()
Returns the status code set on the current CTIOperationResponse object.
These status codes should correspond with standard HTTP status codes, such as 200 for success, 401 for authorization required. Typically, the resultant status codes are determined by the operation handler and are set on the CTIOperationResponse object using the CTIOperationResponse - setStatusCode(String statusCode) method. The message transformer then uses this method to include the status code in the payload returned to the computer telephony integrator provider.
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
Number | Status code of the current operation. If a status code has not been set, returns -1. |
Example
CTIOperationResponse - setAuthToken(String token)
Sets an authentication token on the current CTIOperationResponse object.
This token is used by the ServiceNow Voice framework to authenticate the current ServiceNow Voice user before executing the requested operation handler if the handler's auth_required flag is set to true. The auth_required flag is a field in the Operation Handler [sn_cti_operation_handler] table. The life of an authentication token should be for the life of the call session, but is determined by the CTI provider.
You can define whatever authentication/authorization handling required by your implementation by creating your own authentication operation handler. Regardless of how the authentication token is generated, the message translator must pass the token back in the CTI payload. Additionally, the CTI provider must store this authentication token locally and pass it in each operation request that requires authentication.
If using the instance provided authenticate operation handler, the handler initiates the creation of the authentication token based on a four-digit user-entered pin. It then sets the authentication token in the sessionAttributes object of the CTIOperationResponse object. The associated message transformer translates the sessionAttributes object into the CTI-specific payload and then sends it to the CTI provider.
- Amazon Web Services (AWS) Lambda Proxy (Invoke AWS Lambda function)
- AWS Lex Bot (Get Customer Input)
Name | Type | Description |
---|---|---|
None |
Type | Description |
---|---|
String | The authentication token to use to authenticate operations that have the auth_required flag set. |
Example
CTIOperationResponse - setError(Object error)
Sets the error object in the current CTIOperationResponse object.
You can use the error object in the component to formulate the payload to send to the computer telephony integrator (CTI) provider.
Name | Type | Description |
---|---|---|
error | Object | Information about the error that was detected while processing the requested operation. The format of this object is determined by the CTI provider. |
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setInteractionSysId(String Id)
Sets the sys_id of the interaction record associated with the operation request on the current CTIOperationResponse object.
Name | Type | Description |
---|---|---|
sys_id | String | The sys_id to set for the current interaction. |
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setMajorVersion(Number majorVersion)
Sets the major version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationResponse object.
Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different payloads. If the payload is only slightly different between the software versions, it may make sense to have only a single message transformer. You can then handle the payload differences by just checking the version of software making the request within your message transformer. If the required payload is significantly different between versions, it may be more effective to use multiple message transformers.
Name | Type | Description |
---|---|---|
majorVersion | Number | Major version of the CTI provider software making the operation request. If this value was not previously set, returns 1. |
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setMessage(String message)
Sets a text message on the current CTIOperationResponse object.
Typically this is a message that is spoken back to the user once an operation is complete and is set by the associated operation handler. The message transformer then uses the CTIOperationResponse - getMessage() method to obtain the message and pass it back to the computer telephony integration provider.
Name | Type | Description |
---|---|---|
message | String | Message text |
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setMinorVersion(Number minorVersion)
Sets the minor version of the computer telephony integrator (CTI) provider software making the request on the associated CTIOperationResponse object.
Use this method if the CTI providers connected to your ServiceNow instance are running multiple versions of their software, as different software versions may require different payloads. If the payload is only slightly different between the software versions, it may make sense to have only a single message transformer. You can then handle the payload differences by just checking the version of software making the request within your message transformer. If the required payload is significantly different between versions, it may be more effective to use multiple message transformers.
Name | Type | Description |
---|---|---|
minorVersion | Number | Minor version of the CTI provider software making the operation request. If this value was not previously set, returns 0. |
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setParameter(String key, Object value)
Sets the specified key-value pair on the associated CTIOperationResponse object.
Using the get/set parameter methods enables the passing of virtually any string or number value between an operation handler and a message transformer. The parameter object can contain zero or more key/value pairs of data that directly correlate to the current operation request. The operation handler determines what key/value pairs are required as it consumes these values. Typically the operation handler sets these parameters on the CTIOperationResponse object by calling this method and the message transformer consumes them using the CTIOperationResponse - getParmeter(String key) or CTIOperationResponse - getSParameters() method.
JSON.parse(JSON.stringify(object))
operation. Objects not meeting this
criteria may not propagate correctly through the entire operation processing chain.Name | Type | Description |
---|---|---|
key | String | Name of the key under which to store the associated value. |
value | Object | Value to store for the key. Valid data types:
|
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setSessionAttribute(String key, Object value)
Sets the specified session attribute key-value pair on the associated CTIOperationResponse object.
Using the get/set session attribute methods enables the passing of virtually any string or number value between an operation handler and a message transformer. The sessionAttribute object can contain zero or more key/value pairs of data that are valid for the duration of a computer telephony integration provider defined session. Session attributes can also be accessed within a contact flow. The operation handler determines what session attribute key/value pairs are needed as it consumes these values. Typically the operation handler sets these attributes on the CTIOperationResponse object by calling this method and the message transformer gets the attributes using the CTIOperationResponse - getSessionAttribute(String key) or CTIOperationResponse - getSessionAttribute() method.
JSON.parse(JSON.stringify(object))
operation. Objects not meeting this
criteria may not propagate correctly through the entire operation processing chain.Name | Type | Description |
---|---|---|
key | String | Name of the session attribute key under which to set the associated value. |
value | Object | Value to set. Valid data types:
|
Type | Description |
---|---|
void |
Example
CTIOperationResponse - setStatusCode(Number statusCode)
Sets the status code of the current operation request on the CTIOperationResponse object.
You can use any integer values to define the status, but it is recommended that you emulate the HTTP status codes, such as 200 = Ok/Success, 400 = Bad Request, 401 = Unauthorized.
Name | Type | Description |
---|---|---|
statusCode | Number | Integer that uniquely identifies the status of the requested operation. |
Type | Description |
---|---|
void |
Example
On this page
- CTIOperationResponse - CTIOperationResponse(String origin)
- CTIOperationResponse - getAuthToken()
- CTIOperationResponse - getError()
- CTIOperationResponse - getInteractionSysId()
- CTIOperationResponse - getMajorVersion()
- CTIOperationResponse - getMessage()
- CTIOperationResponse - getMinorVersion()
- CTIOperationResponse - getParameter(String key)
- CTIOperationResponse - getParameters()
- CTIOperationResponse - getSessionAttribute(String key)
- CTIOperationResponse - getSessionAttributes()
- CTIOperationResponse - getStatusCode()
- CTIOperationResponse - setAuthToken(String token)
- CTIOperationResponse - setError(Object error)
- CTIOperationResponse - setInteractionSysId(String Id)
- CTIOperationResponse - setMajorVersion(Number majorVersion)
- CTIOperationResponse - setMessage(String message)
- CTIOperationResponse - setMinorVersion(Number minorVersion)
- CTIOperationResponse - setParameter(String key, Object value)
- CTIOperationResponse - setSessionAttribute(String key, Object value)
- CTIOperationResponse - setStatusCode(Number statusCode)