{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":717,"path":"api-reference/server-api-reference/CTIOperationRequestAPI.md","title":"CTIOperationRequest - Scoped, Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# CTIOperationRequest - Scoped, Global\n\nThe CTIOperationRequest script include provides methods to set and get data on the current CTIOperationRequest object.\n\nYou use CTIOperationRequest objects to pass information between a message transformer and an operation handler within the ServiceNow Voice framework.\n\nTypically, a message transformer is responsible for parsing an incoming CTI-specific payload 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.\n\nThe 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:\n\n-   Amazon Web Services \\(AWS\\) Lambda Proxy \\(Invoke AWS Lambda function\\)\n-   AWS Lex Bot \\(Get Customer Input\\)\n\nYou 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.\n\nA payload is passed into a ServiceNow instance from an external source, such as from a computer telephony integration \\(CTI\\) provider that is making an operation request. When a request is received, a message transformer parses the payload and uses the CTIOperationRequest set methods to set payload values, such as the operation handler name, onto an operation and contact-specific CTIOperationRequest object.\n\nFor example, the following message transformer script parses the passed in JSON payload and sets the values required by the associated operation handler on the CTIOperationRequest object.\n\n```\n{\t\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n\tvar event = jsonPayload.event;\n\tif (event) {\n\t  var details = event.Details;\n\t  if (details) {\t\t\t\t\t\n\t    operationRequest.setOperationName(details.Parameters['sn_operation']);\n\t    var contactData = details.ContactData;\n\t    if(contactData) {\n\t\t// Call id should be surfaced in openframe call log so it can be tied to transcription later\n\t\toperationRequest.setParameter('contact.call_id', contactData.ContactId);\n\t\tfor(var ck in contactData.CustomerEndpoint) {\n\t\t  operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]);\n\t       }\n\t       operationRequest.setParameter('contact.id', contactData.ContactId);\n\t       operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address);\n\t    }\n\t    var parameters = details.Parameters;\n\t    if (parameters) {\n\t\tfor (var pk in parameters) {\n\t\t  switch(pk) {\n\t\t    case 'interactionId':\n\t\t\toperationRequest.setInteractionSysId(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'authToken':\n\t\t\toperationRequest.setAuthToken(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'language':\n\t\t\toperationRequest.setLanguage(parameters[pk]);\n\t\t\tbreak;\n\t\t\t\t\t\t\t\t\n\t\t    default:\n\t\t\toperationRequest.setParameter(pk, parameters[pk]);\n\t\t }\t\t\t\t\t\t\n            }\n          }\t\t\t\t\t\n        }\n      }\n    }\n  } catch(e) {\n\t\tctx.setError(e);\n  }\n})(httpRequest, operationRequest, ctx);\n```\n\nAfter the message transformer finishes parsing the passed in payload, the ServiceNow Voice framework instantiates the specified operation handler. The operating handler uses the CTIOperationResponse script include get methods to obtain the information that it needs from the associated CTIOperationRequest object to process the requested operation.\n\nFor example, the following operation handler script stores values that were set on the CTIOperationRequest object in the interaction record associated with the call.\n\n```\n(function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, ctx) {\n  // Returns the sys_id of the interaction record.\n  var interactionSysId = request.getInteractionSysId();\n  var number = request.getParameter('number');\n  var addComment = request.getParameter('add_comment');\n  addComment = addComment ? addComment.toLowerCase() : addComment;\n  addComment = 'yes' === addComment || 'true' === addComment || '1' === addComment;\n  var workNotes = request.getParameter('work_notes');\n  var message = gs.getMessage('Thankyou');\n  var interactionGr = request.getInteractionRecord();\n  var openedFor = interactionGr ? interactionGr.getValue('opened_for') : null;\n  if (openedFor && number && addComment && workNotes) {\n    var now_GR = new GlideRecordSecure('incident');\n    now_GR.addQuery('caller_id', openedFor);\n    now_GR.addQuery('number', number);\n    now_GR.query();\n    if (now_GR.next()) {\n      now_GR.work_notes += workNotes;\n      now_GR.update();\n      message = now_GR.getMessage('Your comment was added');\n    }\n  }\n  response.setStatusCode(200);\n  response.setMessage(message);\n})(request, response, ctx);\n```\n\nFor additional information on creating operation handlers, see [Configure a contact flow for an automated caller interaction](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/establish-automated-bot-interactions.md).\n\nThis script include runs in the `sn_cti_core` namespace. Before you are able to access the CTIOperationRequest script include, the ServiceNow Voice \\(sn\\_cti\\_core\\) plugin must be activated. For information on activating ServiceNow Voice, see [Install ServiceNow Voice applications](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/install-ccc-apps.md).\n\nFor additional information on the ServiceNow Voice, see [ServiceNow Voice](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/cloud-call-center-overview.md).\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## CTIOperationRequest - CTIOperationRequest\\(String origin\\)\n\nInstantiates a CTIOperationRequest object.\n\n<table id=\"table_mvz_lgy_glb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\norigin\n\n</td><td>\n\nString\n\n</td><td>\n\nOptional. Origin of the request. Usually the name of the computer telephony integrator provider. Default: null\n\n</td></tr></tbody>\n</table>```\nvar request = new sn_cti_core.CTIOperationRequest('AWS Connect');\nrequest.setSessionAttribute('contact.phone', '+15552222345');\nrequest.setSessionAttribute('contact.okToCall', true);\nrequest.setSessionAttribute('contact.address', {\n    street: '1234 Main St'\n    city: 'API City',\n    zip: 91335\n});\n```\n\n## CTIOperationRequest - getAuthToken\\(\\)\n\nReturns the authentication token set on the associated CTIOperationRequest object.\n\nThis 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.\n\nYou 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.\n\nIf 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.\n\n**Note:** If the authentication token is not passed, all requests to execute operation handlers with the **auth\\_required** flag set will fail. If you do not use authentication, you do not need to maintain authentication tokens.\n\nThe 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:\n\n-   Amazon Web Services \\(AWS\\) Lambda Proxy \\(Invoke AWS Lambda function\\)\n-   AWS Lex Bot \\(Get Customer Input\\)\n\nYou 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.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|The authentication token associated with the current ServiceNow Voice user.|\n\n```\n(function( /*CTIProviderResponseExecutionContext*/ ctx, /*CTIOperationRequest*/ operationRequest, /*CTIOperationResponse*/ operationResponse, /*HTTPResponse*/ httpResponse) {\n  var sessionAttributes = {},\n      intentResponse;\n  var statusCode = -1;\n  var message = 'Unprocessed';\n  if (operationResponse) {\n    statusCode = operationResponse.getStatusCode();\n    sessionAttributes = operationResponse.getSessionAttributes();\n    message = operationResponse.getMessage();\n    var error = operationResponse.getError();\n    if (error) {\n      sessionAttributes.error = error;\n    }\n  }\n  if (sn_cti_core.CTIRequestDispatcher.Constants.HTTP.Status.AUTH_REQUIRED.code === statusCode) {\n    //first call for a secure action without authentication token\n    sessionAttributes.statusCode = 401;\n    sessionAttributes.message = message;\n    intentResponse = {\n      sessionAttributes: sessionAttributes,\n      dialogAction: {\n        type: 'Close',\n        fulfillmentState: 'Fulfilled',\n        message: {\n          contentType: 'PlainText',\n          content: 'This operation requires authentication. Say authenticate for authentication.'\n        }\n      }\n    };\n  } else if ('DialogCodeHook' === operationRequest.getParameter('$$invocationSource')) {\n      //pass back authToken and interactionId\n      sessionAttributes.authToken = operationRequest.getAuthToken();\n      sessionAttributes.interactionId = operationRequest.getInteractionSysId();\n      var originalSlots = operationRequest.getParameter('$$slots');\n      var responseParameters = operationResponse ? operationResponse.getParameters() : {};\n      responseParameters = responseParameters ? responseParameters : {};\n      // See if processing happened and we got a dialogAction\n      var responseDialogAction = responseParameters['dialogAction'];\n      // Default dialog action\n      var dialogAction = {\n        type: 'Delegate',\n        slots: originalSlots\n      };\n      // If the response doesn't contain an override replay the inputs\n      if (responseDialogAction) {\n        // We bypassed dialoghook so delegate and pass through inputs\n        dialogAction = responseDialogAction;\n      }\n      intentResponse = {\n        sessionAttributes: sessionAttributes,\n        dialogAction: dialogAction\n      };\n  } else {\n    // Override required session attributes\n    sessionAttributes.statusCode = statusCode;\n    sessionAttributes.message = message;\n    // Build response template\n    intentResponse = {\n      sessionAttributes: sessionAttributes,\n      dialogAction: {\n        type: 'Close',\n        fulfillmentState: 'Fulfilled',\n        message: {\n          contentType: 'PlainText',\n          content: message\n        }\n      }\n    };\n  }\n  httpResponse.setBody(intentResponse);\n})(ctx, operationRequest, operationResponse, httpResponse);\n```\n\n## CTIOperationRequest - getInteractionRecord\\(\\)\n\nReturns the interaction GlideRecord associated with the operation request.\n\nAn interaction represents a customer request for assistance made through a chat, phone call, or in-person. Interactions can be routed to queues for assignment or assigned to agents directly. Interaction records are stored in the Interaction \\[interaction\\] table and can contain any type of data that describes service account interactions with a customer for a specific session.\n\nInteraction records are associated with a CTIOperationRequest object through the [CTIOperationRequest - setInteractionSysId\\(String Id\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method. This method is typically called by the message transformer and must be called prior to calling the getInteractionRecord\\(\\) method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|GlideRecord|Interaction GlideRecord object associated with the current CTIOperationRequest object. If the interaction record sys\\_id has not been set on the CTIOperationRequest object, returns null.|\n\n```\n(function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, /*Context*/ ctx) {\t\n  var notes = '', lang = request.getLanguage();\n  try { \n    // Returns the interaction record (GlideRecord) set on the passed in CTIOperationRequest object\t\t\n    var interactionGr = request.getInteractionRecord();\n\n    var now_GR = new GlideRecord('sys_user');\n    if(interactionGr && now_GR.get(interactionGr.opened_for.toString())) {\t\n    if(now_GR.locked_out == true) {\n        notes += gs.getMessageLang(\"User record found locked. Unlocking the account.\\n\", lang);\n        now_GR.locked_out=false;\n        now_GR.update();\n        response.setStatusCode(200);\n        response.setMessage(gs.getMessageLang(\"Your account has been unlocked.\", lang));\n      } else {\n        notes += gs.getMessageLang(\"User record not locked.\\n\", lang);\n        response.setStatusCode(200);\n        response.setMessage(gs.getMessageLang(\"Your account doesn't seem to be locked.\", lang));\n      }\t\n    } else {\n      notes += gs.getMessageLang(\"User record not found. Transfer to agent\\n\", lang);\n      response.setStatusCode(302);\n      response.setMessage(gs.getMessageLang(\"I am unable to find your record. Let me transfer to someone who can help.\", lang));\n    }\n    if(interactionGr) {\n      interactionGr.work_notes = notes;\n      interactionGr.update();\n    }\n  } catch(e) {\n    ctx.setError(e);\n  }\n})(request, response, ctx);\n```\n\n## CTIOperationRequest - getInteractionSysId\\(\\)\n\nReturns the sys\\_id of the interaction record associated with the current CTIOperationRequest object.\n\nThe [CTIOperationRequest - setInteractionSysId\\(String Id\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method must have been called prior to calling this method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n<table id=\"table_djp_gpg_ykb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nString\n\n</td><td>\n\nThe sys\\_id of the interaction record set on the current CTIOperationRequest object.If the sys\\_id was not set on the associated CTIOperationRequest object, the method returns null.\n\n</td></tr></tbody>\n</table>```\n(function( /*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, ctx) {\n  // Returns the sys_id of the interaction record associated with the CTIOperationRequest object.\n  var interactionSysId = request.getInteractionSysId();\n  var number = request.getParameter('number');\n  var addComment = request.getParameter('add_comment');\n  addComment = addComment ? addComment.toLowerCase() : addComment;\n  addComment = 'yes' === addComment || 'true' === addComment || '1' === addComment;\n  var workNotes = request.getParameter('work_notes');\n  var message = gs.getMessage('Thankyou');\n  var interactionGr = request.getInteractionRecord();\n  var openedFor = interactionGr ? interactionGr.getValue('opened_for') : null;\n  if (openedFor && number && addComment && workNotes) {\n    var now_GR = new GlideRecordSecure('incident');\n    now_GR.addQuery('caller_id', openedFor);\n    now_GR.addQuery('number', number);\n    now_GR.query();\n    if (now_GR.next()) {\n    now_GR.work_notes += workNotes;\n    now_GR.update();\n      message = gs.getMessage('Your comment was added');\n    }\n  }\n  response.setStatusCode(200);\n  response.setMessage(message);\n})(request, response, ctx);\n```\n\n## CTIOperationRequest - getLanguage\\(\\)\n\nReturns the ISO 639.1 language code that was set on the current CTIOperationRequest object.\n\nUsing the customer preferred language enables you to use platform-provided internationalization and localization capabilities to customize messages and other communications with the associated caller.\n\nTypically an operation handler calls the getLanguage\\(\\) method and the message transformer sets the language on the CTIOperationRequest object by calling the [CTIOperationRequest - setLanguage\\(String languageCode\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|The ISO 639.1 language code set on the current CTIOperationRequest object. If the language code is not set, returns `en`.|\n\nThe following example shows an operation handler calling getLanguage\\(\\) to obtain the caller's preferred language.\n\n```\n(function(/*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response) {\n  // Obtain the contact's preferred language\n  var notes = \"\", announcement, lang = request.getLanguage();\n  try {\n\t\t\n    var interactionGr = request.getInteractionRecord();\n\t\t\n    announcement = gs.getMessageLang(\"We are currently experiencing issues with VPN. If you are calling about VPN issues, you may hang up the call.\", lang);\n    // Use the contact's language to customize the response messages and notes\t\n    if(announcement) {\t\n      notes = gs.getMessageLang(\"Listened to announcement: {0}\", lang, [announcement]);\n      response.setStatusCode(200);\n    } else {\n      announcement = gs.getMessageLang(\"There are currently no known outage announcements\", lang);\n      //use the status case as the flag to check for announcements in contact flow\n      response.setStatusCode(404);\n    }\t\t\t\n    response.setMessage(announcement);\t\n\t\t\t\n    if(interactionGr && notes) {\t\t\t\n      interactionGr.work_notes = notes;\t\t\n      interactionGr.update();\n    }\n\t\t\n  } catch(e) {\n    ctx.setError(e);\n  }\n\n})(request, response);\n```\n\n## CTIOperationRequest - getMajorVersion\\(\\)\n\nReturns the major version of the computer telephony integrator \\(CTI\\) software set on the current CTIOperationRequest object.\n\nUse 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 processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers.\n\nTypically the message transformer sets the software version on the CTIOperationRequest object by calling the [CTIOperationRequest - setMajorVersion\\(Number majorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method and an operation handler then consumes the set value using this method. You can also get/set the minor version value of a provider's software using the [CTIOperationRequest - getMinorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) and [CTIOperationRequest - setMinorVersion\\(Number minorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) methods.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n<table id=\"table_plp_qvg_ykb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nNumber\n\n</td><td>\n\nMajor version number of the CTI software.If the major version was never set, returns `1`.\n\n</td></tr></tbody>\n</table>```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar majorVersion = request.getMajorVersion();\n```\n\n## CTIOperationRequest - getMinorVersion\\(\\)\n\nReturns the minor version of the computer telephony integrator \\(CTI\\) software associated with a CTIOperationRequest object.\n\nUse 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 processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers.\n\nTypically the message transformer sets the software version on the CTIOperationRequest object by calling the [CTIOperationRequest - setMinorVersion\\(Number minorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) [CTIOperationRequest - setMinorVersion\\(Number minorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method and an operation handler then consumes the set value using this method. You can also get/set the major version value of a provider's software using the [CTIOperationRequest - getMajorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) [CTIOperationRequest - getMajorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) and [CTIOperationRequest - setMajorVersion\\(Number majorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) [CTIOperationRequest - setMajorVersion\\(Number majorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) methods.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n<table id=\"table_dhp_z41_zkb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nNumber\n\n</td><td>\n\nMinor version number of the CTI software. If the minor version was never set, returns `0`.\n\n</td></tr></tbody>\n</table>```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar minorVersion = request.getMinorVersion();\n```\n\n## CTIOperationRequest - getOperationName\\(\\)\n\nReturns the name of the operation that the computer telephony integration \\(CTI\\) provider is requesting to execute.\n\nThe operation name determines the operation handler that is used to process a request. Typically the message transformer sets the operation name on the CTIOperationRequest object using the [CTIOperationRequest - setOperationName\\(String name\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method.\n\n**Note:** The getOperationName\\(\\) method does not instantiate the associated operation handler. This is done by the ServiceNow Voiceframework. This method simply returns the associated operation handler name.\n\n**Note:** For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix \\(myOperation\\_SUFFX\\), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request \\(myOperation\\).\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|The name of the operation that the CTI provider is requesting to execute. If the operation name is not set, returns null.|\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar name = request.getOperationName();\n\n```\n\n## CTIOperationRequest - getOperationSubStepName\\(\\)\n\nReturns the substep operation handler name set on the current CTIOperationRequest object.\n\nUse substeps to perform actions such as initialization and validation before processing an operation. Unlike operation handlers that are meant to be generic and used by all CTI providers, substeps are CTI provider specific and use terminology and naming conventions that are specific to the CTI provider.\n\nThe ServiceNow Voice framework performs the following steps to locate the required operation handler and any associated substep operation handlers.\n\n**Note:** For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix \\(myOperation\\_SUFFX\\), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request \\(myOperation\\).\n\n1.  Tries to locate the operation handler associated with the request.\n    -   First checks for an operation handler called `myOperation_SUFFX`.\n    -   If not found, checks for the operation handler `myOperation`. If not found, errors out.\n2.  If the handler is found, checks the **auth\\_required** flag on the operation handler. If set, it checks that a valid authentication token \\(obtained through the getAuthToken\\(\\) method\\) is present on the request. If present and valid, continue processing, else throw an error.\n3.  Looks up the operation handler for the passed in substep. For this example let's assume `subStepName=SubStep`.\n    -   First checks for an operation handler named `myOperation_SUFFX.SubStep`. If found, executes the handler.\n    -   If not found, checks for the handler `myOperation.SubStep`. If found executes the handler.\n    -   If not found, checks if a `subStepNotFoundBehavior` was set on the request object.\n    -   If set, executes the behavior, otherwise, errors out.\n4.  Executes the primary operation handler \\(`myOpersation_SUFFX` or `myOperation`.\\)\n\nTypically the message transformer sets the substep name on the CTIOperationRequest object using the [CTIOperationRequest - setOperationSubStepName\\(String name\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method. You can override this behavior if you are creating your own transformer by calling the [CTIOperationRequest - setSubStepNotFoundBehaviour\\(Object behaviour\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|String|The name of the substep operation handler set on the CTIOperationRequest object. If it does not exist, returns null.|\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar name = request.getOperationSubStepName();\n```\n\n## CTIOperationRequest - getParameter\\(String key\\)\n\nReturns the value of a specified key previously set on the current CTIOperationRequest object.\n\nUsing the get/set parameter methods enables the passing of virtually any string or number value between a message transformer and an operation handler. 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 message transformer sets these parameters on the CTIOperationRequest object by calling the [CTIOperationRequest - setParameter\\(String key, Object value\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method and the operation handler consumes them using this method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|key|String|The name of the key value to return.|\n\n|Type|Description|\n|----|-----------|\n|String or Number|Value of the specified key. If no such key exists, returns null.|\n\n```\n(function( /*CTIOperationRequest*/ request, /*CTIOperationResponse*/ response, ctx) {\n  var interactionSysId = request.getInteractionSysId();\n  // Returns the number and add_comment parameters from the CTIOperationRequest object\n  var number = request.getParameter('number');\n  var addComment = request.getParameter('add_comment');\n  addComment = addComment ? addComment.toLowerCase() : addComment;\n  addComment = 'yes' === addComment || 'true' === addComment || '1' === addComment;\n  var workNotes = request.getParameter('work_notes');\n  var message = gs.getMessage('Thankyou');\n  var interactionGr = request.getInteractionRecord();\n  var openedFor = interactionGr ? interactionGr.getValue('opened_for') : null;\n  if (openedFor && number && addComment && workNotes) {\n    var now_GR = new GlideRecordSecure('incident');\n    now_GR.addQuery('caller_id', openedFor);\n    now_GR.addQuery('number', number);\n    now_GR.query();\n    if (now_GR.next()) {\n    now_GR.work_notes += workNotes;\n    now_GR.update();\n      message = gs.getMessage('Your comment was added');\n    }\n  }\n  response.setStatusCode(200);\n  response.setMessage(message);\n})(request, response, ctx);\n```\n\n## CTIOperationRequest - getParameters\\(\\)\n\nReturns the key-value pairs for all parameters that were previously set on the current CTIOperationRequest object.\n\nUsing the get/set parameter methods enables the passing of virtually any string or number value between a message transformer and an operation handler. 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 message transformer sets these parameters on the CTIOperationRequest object by calling the [CTIOperationRequest - setParameter\\(String key, Object value\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method and the operation handler consumes them using this method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Object|A map of key-value pairs that were previously set on the CTIOperationRequest 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.|\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar parms = request.getParameters();\nfor(var key in parms) {\n    gs.info(key + '=' + parms[key]);\n}\n```\n\n## CTIOperationRequest - getSessionAttribute\\(String key\\)\n\nReturns the value of a specified session attribute key set on the current CTIOperationRequest object.\n\nUsing the get/set session attribute methods enables the passing of virtually any string or number value between a message transformer and an operation handler. 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, such as the contact's phone number. 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 message transformer sets these attributes on the CTIOperationRequest object by calling the [CTIOperationRequest - setSessionAttribute\\(String key, Object value\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method. Session attributes are different than parameters in that they persist for the life of the session \\(such as the entire call\\) and should be passed back by the CTI provider with each operation request within that call session.\n\n|Name|Type|Description|\n|----|----|-----------|\n|key|String|The name of the key value to return.|\n\n|Type|Description|\n|----|-----------|\n|String or Number|Value of the specified key. If no such key exists, returns null.|\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar phoneAttribute = request.getSessionAttribute('contact.phone');\n```\n\n## CTIOperationRequest - getSessionAttributes\\(\\)\n\nReturns a key-value pair map of all session attributes set on the current CTIOperationRequest object.\n\nUsing the get/set session attribute methods enables the passing of virtually any string or number value between a message transformer and an operation handler. 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, such as the contact's phone number. 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 message transformer sets these attributes on the CTIOperationRequest object by calling the [CTIOperationRequest - setSessionAttribute\\(String key, Object value\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method. Session attributes are different than parameters in that they persist for the life of the session \\(such as the entire call\\) and should be passed back by the CTI provider with each operation request within that call session.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Object|A map of session attribute key-value pairs that were set on the associated CTIOperationResponse object. This map is free-form and defined by the needs of the operation handler.|\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar parms = request.getSessionAttributes();\nfor(var key in parms) {\n    gs.info(key + '=' + parms[key]);\n}\n```\n\n## CTIOperationRequest - getSubStepNotFoundBehaviour\n\nReturns the handling behavior for a subsep when a substep's operation handler is not found.\n\nUse substeps to perform actions such as initialization and validation before processing an operation. Unlike operation handlers that are meant to be generic and used by all CTI providers, substeps are CTI provider specific and use terminology and naming conventions that are specific to the CTI provider.\n\nIf the requested substep operation handler cannot be found by the ServiceNow Voice framework, it attempts to use the \"step not found behavior\". This behavior is typically set by the message transformer when an operation is initially requested.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n<table id=\"table_hxb_rg2_1lb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nOperationNotFoundBehaviours\n\n</td><td>\n\nThe behavior/handling to perform when an operation handler cannot be found for the operation/substep combination \\(**&lt;operation\\_name&gt;**.SubStep&gt;\\). If not defined, returns null.Possible values:\n\n-   OperationNotFoundBehaviours.ThrowError: Throw an error.\n-   OperationNotFoundBehaviours.PassThrough: Do not perform any further processing on the request, just return.\n-   OperationNotFoundBehaviours.RouteToOperation: Use the parent operation handler **&lt;operation\\_name&gt;**.\n\n</td></tr></tbody>\n</table>```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nvar behavior = request.getSubStepNotFoundBehaviour();\n```\n\n## CTIOperationRequest - setAuthToken\\(String id\\)\n\nSets an authentication token on the current CTIOperationRequest object.\n\nThis 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.\n\nYou 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.\n\nIf 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.\n\n**Note:** If the authentication token is not passed, all requests to execute operation handlers with the **auth\\_required** flag set will fail. If you do not use authentication, you do not need to maintain authentication tokens.\n\nThe 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:\n\n-   Amazon Web Services \\(AWS\\) Lambda Proxy \\(Invoke AWS Lambda function\\)\n-   AWS Lex Bot \\(Get Customer Input\\)\n\nYou 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.\n\n|Name|Type|Description|\n|----|----|-----------|\n|id|String|The authentication token for the associated ServiceNow Voice user.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\nExample of message transformer script that saves the passed in authentication token.\n\n```\n{\t\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n\tvar event = jsonPayload.event;\n\tif (event) {\n\t  var details = event.Details;\n\t  if (details) {\t\t\t\t\t\n\t    operationRequest.setOperationName(details.Parameters['sn_operation']);\n\t    var contactData = details.ContactData;\n\t    if(contactData) {\n\t\t// Call id should be surfaced in openframe call log so it can be tied to transcription later\n\t\toperationRequest.setParameter('contact.call_id', contactData.ContactId);\n\t\tfor(var ck in contactData.CustomerEndpoint) {\n\t\t  operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]);\n\t       }\n\t       operationRequest.setParameter('contact.id', contactData.ContactId);\n\t       operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address);\n\t    }\n\t    var parameters = details.Parameters;\n\t    if (parameters) {\n\t\tfor (var pk in parameters) {\n\t\t  switch(pk) {\n\t\t    case 'interactionId':\n\t\t\toperationRequest.setInteractionSysId(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'authToken':\n\t\t\toperationRequest.setAuthToken(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'language':\n\t\t\toperationRequest.setLanguage(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'statusCode':\n\t\t    case 'message':\n\t\t\tbreak;\n\t\t\t\t\t\t\t\t\n\t\t    default:\n\t\t\toperationRequest.setParameter(pk, parameters[pk]);\n\t\t }\t\t\t\t\t\t\n            }\n          }\t\t\t\t\t\n        }\n      }\n    }\n  } catch(e) {\n\t\tctx.setError(e);\n  }\n})(httpRequest, operationRequest, ctx);\n```\n\n## CTIOperationRequest - setInteractionSysId\\(String Id\\)\n\nSets the sys\\_id of the interaction record associated with the operation request on the current CTIOperationRequest object.\n\nIf you want to maintain contact interaction information within a contact-specific interaction record, the interaction record sys\\_id must be maintained for the entire ServiceNow Voice call session.\n\nTypically, an operation handler creates an interaction record when a new contact call is initiated. It then sets the interaction record sys\\_id and table name on the associated CTIOperationResponse object as session attributes using the [CTIOperationRequest - setSessionAttribute\\(String key, Object value\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationResponseAPI.md) method. The associated method transformer then translates this information into the computer telephony integration \\(CTI\\) provider payload and sends it back to the CTI provider.\n\nThe CTI provider must store the interaction record sys\\_id for the contact session locally. Each time the CTI provider interacts with the ServiceNow Voice for this contact session, it must pass back the corresponding interaction record sys\\_id in its payload. The receiving message transformer then parses the payload and uses the CTIOperationRequest - setInteractionSysId\\(\\) method to set the interaction record sys\\_id on the associated CTIOperationtRequest object.\n\nThe [CTIOperationRequest - getInteractionRecord\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method uses this sys\\_id to obtain the correct interaction record for the contact session.\n\n<table id=\"table_usk_lrg_ykb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nsys\\_id\n\n</td><td>\n\nString\n\n</td><td>\n\nSys\\_id of the interaction record to associate with the request.Table: Interaction \\[interaction\\]\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\nExample of a message transformer script that extracts the interaction record sys\\_id from the incoming payload \\(passed as a parameter\\) and sets it on the associated CTIOperationRequest object.\n\n```\n{\t\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n\tvar event = jsonPayload.event;\n\tif (event) {\n\t  var details = event.Details;\n\t  if (details) {\t\t\t\t\t\n\t    operationRequest.setOperationName(details.Parameters['sn_operation']);\n\t    var contactData = details.ContactData;\n\t    if(contactData) {\n\t\t// Call id should be surfaced in openframe call log so it can be tied to transcription later\n\t\toperationRequest.setParameter('contact.call_id', contactData.ContactId);\n\t\tfor(var ck in contactData.CustomerEndpoint) {\n\t\t  operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]);\n\t       }\n\t       operationRequest.setParameter('contact.id', contactData.ContactId);\n\t       operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address);\n\t    }\n\t    var parameters = details.Parameters;\n\t    if (parameters) {\n\t\tfor (var pk in parameters) {\n\t\t  switch(pk) {\n                 // Associate the existing customer interaction record with the request\n\t\t    case 'interactionId':\n\t\t\toperationRequest.setInteractionSysId(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'authToken':\n\t\t\toperationRequest.setAuthToken(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'language':\n\t\t\toperationRequest.setLanguage(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'statusCode':\n\t\t    case 'message':\n\t\t\tbreak;\n\t\t\t\t\t\t\t\t\n\t\t    default:\n\t\t\toperationRequest.setParameter(pk, parameters[pk]);\n\t\t }\t\t\t\t\t\t\n            }\n          }\t\t\t\t\t\n        }\n      }\n    }\n  } catch(e) {\n\t\tctx.setError(e);\n  }\n})(httpRequest, operationRequest, ctx);\n```\n\n## CTIOperationRequest - setLanguage\\(String languageCode\\)\n\nSets the ISO 639.1 language code to use when processing the associated operation on a CTIOperationRequest object.\n\nUsing the customer preferred language enables you to use platform-provided internationalization and localization capabilities to customize messages and other communications with the associated caller. Typically the message transformer sets the language on the CTIOperationRequest object.\n\n|Name|Type|Description|\n|----|----|-----------|\n|languageCode|String|The ISO 639.1 language code to use when processing the associated operation.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\n{\t\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n\tvar event = jsonPayload.event;\n\tif (event) {\n\t  var details = event.Details;\n\t  if (details) {\t\t\t\t\t\n\t    operationRequest.setOperationName(details.Parameters['sn_operation']);\n\t    var contactData = details.ContactData;\n\t    if(contactData) {\n\t\t// Call id should be surfaced in openframe call log so it can be tied to transcription later\n\t\toperationRequest.setParameter('contact.call_id', contactData.ContactId);\n\t\tfor(var ck in contactData.CustomerEndpoint) {\n\t\t  operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]);\n\t       }\n\t       operationRequest.setParameter('contact.id', contactData.ContactId);\n\t       operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address);\n\t    }\n\t    var parameters = details.Parameters;\n\t    if (parameters) {\n\t\tfor (var pk in parameters) {\n\t\t  switch(pk) {\n\t\t    case 'interactionId':\n\t\t\toperationRequest.setInteractionSysId(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'authToken':\n\t\t\toperationRequest.setAuthToken(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'language':\n\t\t\toperationRequest.setLanguage(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'statusCode':\n\t\t    case 'message':\n\t\t\tbreak;\n\t\t\t\t\t\t\t\t\n\t\t    default:\n\t\t\toperationRequest.setParameter(pk, parameters[pk]);\n\t\t }\t\t\t\t\t\t\n            }\n          }\t\t\t\t\t\n        }\n      }\n    }\n  } catch(e) {\n\t\tctx.setError(e);\n  }\n})(httpRequest, operationRequest, ctx);\n```\n\n## CTIOperationRequest - setMajorVersion\\(Number majorVersion\\)\n\nSets the major version of the computer telephony integrator \\(CTI\\) provider software making the request on the associated CTIOperationRequest object.\n\nUse 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 processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers.\n\nTypically the message transformer sets the software version on the CTIOperationRequest object by calling this method and an operation handler then consumes the set value using the [CTIOperationRequest - getMajorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method. You can also get/set the minor version value of a provider's software using the [CTIOperationRequest - getMinorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) and [CTIOperationRequest - setMinorVersion\\(Number minorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) methods.\n\n<table id=\"table_jlt_pz1_zkb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nmajorVersion\n\n</td><td>\n\nNumber\n\n</td><td>\n\nMajor version of the CTI provider software making the operation request.If this value was not previously set, returns `1`.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nrequest.setMajorVersion(2);\n```\n\n## CTIOperationRequest - setMinorVersion\\(Number minorVersion\\)\n\nSets the minor version of the computer telephony integrator \\(CTI\\) provider software making the request on the associated CTIOperationRequest object.\n\nUse 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 processing behavior. If the processing behavior is only slightly different between the software versions, it may make sense to have only a single operation handler. You can then handle the processing differences by just checking the version of software making the request and process the request/data within your operation handler. If the required processing is significantly different between versions, it may be more effective to use multiple operation handlers.\n\nTypically the message transformer sets the software version on the CTIOperationRequest object by calling this method and an operation handler then consumes the set value using the [CTIOperationRequest - getMinorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method. You can also get/set the major version value of a provider's software using the [CTIOperationRequest - getMajorVersion\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) and [CTIOperationRequest - setMajorVersion\\(Number majorVersion\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) methods.\n\n<table id=\"table_zqj_52b_zkb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nminorVersion\n\n</td><td>\n\nNumber\n\n</td><td>\n\nMinor version of the CTI provider software making the operation request.If this value was not previously set, returns `0`.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\n...\nrequest.setMinorVersion(3);\n```\n\n## CTIOperationRequest - setOperationName\\(String name\\)\n\nSets the name of the operation that the computer telephony integration \\(CTI\\) provider is attempting to execute on the current CTIOperationRequest object.\n\nThe operation name determines the operation handler that is used to process the request. Call this method from the associated message transformer.\n\n**Note:** For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix \\(myOperation\\_SUFFX\\), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request \\(myOperation\\).\n\n<table id=\"table_msx_jpw_zkb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nname\n\n</td><td>\n\nString\n\n</td><td>\n\nThe name of the operation that the CTI provider is currently attempting to execute. This name must be the same as the name of the operation handler to use to process the request. If it is not, an error is thrown. You can locate the available operation handlers in the Operation Handler \\[sn\\_cti\\_operation\\_handler\\] table.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\n{\t\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n\tvar event = jsonPayload.event;\n\tif (event) {\n\t  var details = event.Details;\n\t  if (details) {\t\n           // Set the operation handler to use to process the request\t\t\t\t\n\t    operationRequest.setOperationName(details.Parameters['sn_operation']);\n\t    var contactData = details.ContactData;\n\t    if(contactData) {\n\t\t// Call id should be surfaced in openframe call log so it can be tied to transcription later\n\t\toperationRequest.setParameter('contact.call_id', contactData.ContactId);\n\t\tfor(var ck in contactData.CustomerEndpoint) {\n\t\t  operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]);\n\t       }\n\t       operationRequest.setParameter('contact.id', contactData.ContactId);\n\t       operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address);\n\t    }\n\t    var parameters = details.Parameters;\n\t    if (parameters) {\n\t\tfor (var pk in parameters) {\n\t\t  switch(pk) {\n\t\t    case 'interactionId':\n\t\t\toperationRequest.setInteractionSysId(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'authToken':\n\t\t\toperationRequest.setAuthToken(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'language':\n\t\t\toperationRequest.setLanguage(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'statusCode':\n\t\t    case 'message':\n\t\t\tbreak;\n\t\t\t\t\t\t\t\t\n\t\t    default:\n\t\t\toperationRequest.setParameter(pk, parameters[pk]);\n\t\t }\t\t\t\t\t\t\n            }\n          }\t\t\t\t\t\n        }\n      }\n    }\n  } catch(e) {\n\t\tctx.setError(e);\n  }\n})(httpRequest, operationRequest, ctx);\n```\n\n## CTIOperationRequest - setOperationSubStepName\\(String name\\)\n\nSets the operation substep name on the current CTIOperationRequest object.\n\nUse substeps to perform actions such as initialization and validation before processing an operation. Unlike operation handlers that are meant to be generic and used by all CTI providers, substeps are CTI provider specific and use terminology and naming conventions that are specific to the CTI provider.\n\nThe ServiceNow Voice framework performs the following steps to locate the required operation handler and any associated substep operation handlers.\n\n**Note:** For Amazon Connect Lex Bot implementations, intent names are appended with a five letter suffix as different Amazon intents cannot have the same intent name. In the ServiceNow Voice framework, the intent name equals the operation handler name. An operation handler can either be specific for an intent, having an operation handler name that includes this suffix \\(myOperation\\_SUFFX\\), or it can be generic and used by multiple CTI providers or different use cases, such as using the same handler for processing an HR request and a helpdesk request \\(myOperation\\).\n\n1.  Tries to locate the operation handler associated with the request.\n    -   First checks for an operation handler called `myOperation_SUFFX`.\n    -   If not found, checks for the operation handler `myOperation`. If not found, errors out.\n2.  If the handler is found, checks the **auth\\_required** flag on the operation handler. If set, it checks that a valid authentication token \\(obtained through the getAuthToken\\(\\) method\\) is present on the request. If present and valid, continue processing, else throw an error.\n3.  Looks up the operation handler for the passed in substep. For this example let's assume `subStepName=SubStep`.\n    -   First checks for an operation handler named `myOperation_SUFFX.SubStep`. If found, executes the handler.\n    -   If not found, checks for the handler `myOperation.SubStep`. If found executes the handler.\n    -   If not found, checks if a `subStepNotFoundBehavior` was set on the request object.\n    -   If set, executes the behavior, otherwise, errors out.\n4.  Executes the primary operation handler \\(`myOpersation_SUFFX` or `myOperation`.\\)\n\nYou can set the default behavior of a substep by calling the [CTIOperationRequest - setSubStepNotFoundBehaviour\\(Object behaviour\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|name|String|The name of the substep that the CTI provider is trying to execute.|\n\n|Type|Description|\n|----|-----------|\n|void| |\n\n```\n(function( /*HTTPRequest*/ httpRequest, /*CTIOperationRequest*/ operationRequest, /*Context*/ ctx) {\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n      var event = jsonPayload.event;\n      if (event) {\n        var intent = event.currentIntent;\n\t var inputTranscript = event.inputTranscript;\n\t if(inputTranscript) {\n\t   operationRequest.setParameter('$utterance', inputTranscript);\n\t }\n        if (intent) {\n          operationRequest.setOperationName(intent.name);\n\t   // Add this because intent name gets changed through the pipeline\n\t   operationRequest.setParameter('$original_intent', intent.name);\n          var sessionAttributes = event.sessionAttributes;\n          if (sessionAttributes) {\n            for (var sk in sessionAttributes) {\n              switch (sk) {\n                case 'interactionId':\n                  operationRequest.setInteractionSysId(sessionAttributes[sk]);\n                  break;\n                case 'authToken':\n                  operationRequest.setAuthToken(sessionAttributes[sk]);\n                  break;\n\t\t  case 'language':\n\t\t    operationRequest.setLanguage(sessionAttributes[sk]);\n\t\t    break;\n                case 'statusCode':\n                case 'message':\n                  break;\n                default:\n                  operationRequest.setSessionAttribute(sk, sessionAttributes[sk]);\n              }\n            }\n          }\n          var slots = intent.slots;\n\t   // Always copy in slots they are the parameters for the operation\n          if (slots) {\n            for (var pk in slots) {\n              operationRequest.setParameter(pk, slots[pk]);\n            }\n          }\n          var invocationSource = event.invocationSource;\n\t   operationRequest.setParameter('$$invocationSource', invocationSource);\n          // Specific handling for dialog hooks with a way to override for Amazon specific provider\n          if (invocationSource === 'DialogCodeHook') {\n\t     // Set substep to trigger forwarding to another handler IF it s present\n\t     operationRequest.setOperationSubStepName(invocationSource);\n\t     // Allow pass through behavior\n\t     var behaviourToUse = sn_cti_core.CTIOperationRequest.OperationNotFoundBehaviours.PassThrough;\n\t     operationRequest.setSubStepNotFoundBehaviour(behaviourToUse);\n\t     // Reserved - copy slots in so we can just use delegate as default if the call isn't handled\n\t     operationRequest.setParameter('$$slots', slots);\n          }\n        }\n      }\n    }\n  } catch (e) {\n      ctx.setError(e);\n  }\n  return operationRequest;\n})(httpRequest, operationRequest, ctx);\n```\n\n## CTIOperationRequest - setParameter\\(String key, Object value\\)\n\nSets the specified key-value pair on the parameter object of the current CTIOperationRequest object.\n\nUsing the get/set parameter methods enables the passing of virtually any string or number value between a message transformer and an operation handler. 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 message transformer sets these parameters on the CTIOperationRequest object by calling this method and the operation handler consumes them using the [CTIOperationRequest - getParameter\\(String key\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) or [CTIOperationRequest - getParameters\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method.\n\n**Note:** You should only store objects that can survive a `JSON.parse(JSON.stringify(object))` operation. Objects not meeting this criteria may not propagate correctly through the entire operation processing chain.\n\nFor example:\n\n```\nvar x = {\n  \"string\": 'abc',\n  \"int\": 123,\n  \"float\": 1.234,\n  \"number\": new Number(3),\n  \"boolean\": true,\n  \"date\": new Date(2006, 0, 2, 15, 4, 5),\n  \"object\": {\n    \"string\": 'abc',\n    \"int\": 123,\n    \"float\": 1.234,\n    \"number\": new Number(3),\n    \"boolean\": true,\n    \"date\": new Date(2006, 0, 2, 15, 4, 5)\n  },\n  \"function\": function(abc) {\n\n  }\n}\nvar stringify = JSON.stringify(x);\ngs.info(stringify);\nvar hydrate = JSON.parse(stringify);\nvar stringify2 = JSON.stringify(hydrate);\ngs.info(stringify2);\n\n```\n\nProduces:\n\n```\n{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\",\"object\":{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\"}}\n{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\",\"object\":{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\"}}\n\n```\n\n<table id=\"table_ab4_k3r_zkb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nkey\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the key under which to store the associated value.\n\n</td></tr><tr><td>\n\nvalue\n\n</td><td>\n\nObject\n\n</td><td>\n\nValue to store.Valid data types:\n\n-   string\n-   int\n-   float\n-   number\n-   boolean\n-   date\n-   object\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\n{\t\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n\tvar event = jsonPayload.event;\n\tif (event) {\n\t  var details = event.Details;\n\t  if (details) {\t\t\t\t\t\n\t    operationRequest.setOperationName(details.Parameters['sn_operation']);\n\t    var contactData = details.ContactData;\n\t    if(contactData) {\n\t\t// Call id should be surfaced in openframe call log so it can be tied to transcription later\n\t\toperationRequest.setParameter('contact.call_id', contactData.ContactId);\n\t\tfor(var ck in contactData.CustomerEndpoint) {\n\t\t  operationRequest.setParameter('contact.' + ck, contactData.CustomerEndpoint[ck]);\n\t       }\n\t       operationRequest.setParameter('contact.id', contactData.ContactId);\n\t       operationRequest.setParameter('contact.phone', contactData.CustomerEndpoint.Address);\n\t    }\n\t    var parameters = details.Parameters;\n\t    if (parameters) {\n\t\tfor (var pk in parameters) {\n\t\t  switch(pk) {\n\t\t    case 'interactionId':\n\t\t\toperationRequest.setInteractionSysId(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'authToken':\n\t\t\toperationRequest.setAuthToken(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'language':\n\t\t\toperationRequest.setLanguage(parameters[pk]);\n\t\t\tbreak;\n\t\t    case 'statusCode':\n\t\t    case 'message':\n\t\t\tbreak;\n\t\t\t\t\t\t\t\t\n\t\t    default:\n\t\t\toperationRequest.setParameter(pk, parameters[pk]);\n\t\t }\t\t\t\t\t\t\n            }\n          }\t\t\t\t\t\n        }\n      }\n    }\n  } catch(e) {\n\t\tctx.setError(e);\n  }\n})(httpRequest, operationRequest, ctx);\n```\n\n## CTIOperationRequest - setSessionAttribute\\(String key, Object value\\)\n\nSets the specified session attribute key-value pair on the current CTIOperationRequest object.\n\nUsing the get/set session attribute methods enables the passing of virtually any string or number value between a message transformer and an operation handler. 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 message transformer sets these attributes on the CTIOperationRequest object by calling this method and the operation handler gets the attributes using the [CTIOperationRequest - getSessionAttribute\\(String key\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) or [CTIOperationRequest - getSessionAttribute\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/CTIOperationRequestAPI.md) method.\n\n**Note:** You should only store objects that can survive a `JSON.parse(JSON.stringify(object))` operation. Objects not meeting this criteria may not propagate correctly through the entire operation processing chain.\n\nFor example:\n\n```\nvar x = {\n  \"string\": 'abc',\n  \"int\": 123,\n  \"float\": 1.234,\n  \"number\": new Number(3),\n  \"boolean\": true,\n  \"date\": new Date(2006, 0, 2, 15, 4, 5),\n  \"object\": {\n    \"string\": 'abc',\n    \"int\": 123,\n    \"float\": 1.234,\n    \"number\": new Number(3),\n    \"boolean\": true,\n    \"date\": new Date(2006, 0, 2, 15, 4, 5)\n  },\n  \"function\": function(abc) {\n\n  }\n}\nvar stringify = JSON.stringify(x);\ngs.info(stringify);\nvar hydrate = JSON.parse(stringify);\nvar stringify2 = JSON.stringify(hydrate);\ngs.info(stringify2);\n\n```\n\nProduces:\n\n```\n{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\",\"object\":{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\"}}\n{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\",\"object\":{\"string\":\"abc\",\"int\":123,\"float\":1.234,\"number\":3,\"boolean\":true,\"date\":\"2006-01-02T23:04:05.000Z\"}}\n\n```\n\n<table id=\"table_ihm_rxr_zkb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nkey\n\n</td><td>\n\nString\n\n</td><td>\n\nName of the key under which to store the associated value.\n\n</td></tr><tr><td>\n\nvalue\n\n</td><td>\n\nObject\n\n</td><td>\n\nValue to store.Valid data types:\n\n-   string\n-   int\n-   float\n-   number\n-   boolean\n-   date\n-   object\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\nvar request = new sn_cti_core.CTIOperationRequest('origin');\nrequest.setSessionAttribute('contact.phone', '+15552222345');\nrequest.setSessionAttribute('contact.okToCall', true);\nrequest.setSessionAttribute('contact.address', {\n    street: '1234 Main St'\n    city: 'API City',\n    zip: 91335\n});\n```\n\n## CTIOperationRequest - setSubStepNotFoundBehaviour\\(Object behaviour\\)\n\nSets the behavior to perform if the current substep's operation handler is not found.\n\nThis method should be called by the input message transformer.\n\n<table id=\"table_k4q_dmf_1lb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nbehaviour\n\n</td><td>\n\nOperationNotFoundBehaviours\n\n</td><td>\n\nBehavior to use if a handling behavior is not specified for the substep. This must be a behavior defined on the CTIOperationRequest.OperationNotFoundBehaviours object.Possible values:\n\n-   ThrowError: Throw an error.\n-   PassThrough: Do not perform any further processing on the request, just return.\n-   RouteToOperation: Use the parent operation handler **&lt;operation\\_name&gt;**.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|void| |\n\n```\n(function( /*HTTPRequest*/ httpRequest, /*CTIOperationRequest*/ operationRequest, /*Context*/ ctx) {\n  try {\n    var jsonPayload = httpRequest.body.data;\n    if (jsonPayload) {\n      var event = jsonPayload.event;\n      if (event) {\n        var intent = event.currentIntent;\n\t var inputTranscript = event.inputTranscript;\n\t if(inputTranscript) {\n\t   operationRequest.setParameter('$utterance', inputTranscript);\n\t }\n        if (intent) {\n          operationRequest.setOperationName(intent.name);\n\t   // Add this because intent name gets changed through the pipeline\n\t   operationRequest.setParameter('$original_intent', intent.name);\n          var sessionAttributes = event.sessionAttributes;\n          if (sessionAttributes) {\n            for (var sk in sessionAttributes) {\n              switch (sk) {\n                case 'interactionId':\n                  operationRequest.setInteractionSysId(sessionAttributes[sk]);\n                  break;\n                case 'authToken':\n                  operationRequest.setAuthToken(sessionAttributes[sk]);\n                  break;\n\t\t  case 'language':\n\t\t    operationRequest.setLanguage(sessionAttributes[sk]);\n\t\t    break;\n                case 'statusCode':\n                case 'message':\n                  break;\n                default:\n                  operationRequest.setSessionAttribute(sk, sessionAttributes[sk]);\n              }\n            }\n          }\n          var slots = intent.slots;\n\t   // Always copy in slots they are the parameters for the operation\n          if (slots) {\n            for (var pk in slots) {\n              operationRequest.setParameter(pk, slots[pk]);\n            }\n          }\n          var invocationSource = event.invocationSource;\n\t   operationRequest.setParameter('$$invocationSource', invocationSource);\n          // Specific handling for dialog hooks with a way to overide for Amazon specific provider\n          if (invocationSource === 'DialogCodeHook') {\n\t     // Set substep to trigger forwarding to another handler IF it s present\n\t     operationRequest.setOperationSubStepName(invocationSource);\n\t     // Allow pass through behavior\n\t     var behaviourToUse = sn_cti_core.CTIOperationRequest.OperationNotFoundBehaviours.PassThrough;\n\t     operationRequest.setSubStepNotFoundBehaviour(behaviourToUse);\n\t     // Reserved - copy slots in so we can just use delegate as default if the call isn't handled\n\t     operationRequest.setParameter('$$slots', slots);\n          }\n        }\n      }\n    }\n  } catch (e) {\n      ctx.setError(e);\n  }\n  return operationRequest;\n})(httpRequest, operationRequest, ctx);\n```\n\n"}}