{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":523,"path":"api-reference/rest-apis/openframe-api.md","title":"openframe API","bundle":null,"doc_type":null,"release":"australia","body":"\n# openframe API\n\nThe openframe API provides endpoints that provide Contact Center as a Service \\(CCaaS\\) the ability to create and update interaction records without using the Operation Handler.\n\nUse this API to create interaction records to track agent phone calls. Once an interaction record is created, the interaction can automatically display in the CRM Workspace when an agent receives a phone call.\n\nTo access this API, the com.sn\\_openframe\\_store plugin must be installed on the instance and the calling user must have either the sn\\_openframe\\_api\\_user or sn\\_openframe\\_user role. The openframe API runs in the `sn_openframe` namespace.\n\nFor additional information on CSM voice interaction records, see [CSM voice interaction record page](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/customer-service-management/csm-native-voice-record-page.md).\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## openframe - PATCH /openframe/voice-interaction/\\{interactionSysId\\}\n\nUpdates the specified interaction record in the Interaction \\[interaction\\] table. Contact Center as a Service \\(CCaaS\\) providers can then use these records to track phone calls.\n\n### URL format\n\nVersioned URL: `/api/now/openframe/{api_version}/voice-interaction/{interactionSysId}`\n\nDefault URL: `/api/now/openframe/voice-interaction/{interactionSysId}`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n</td></tr><tr><td>\n\ninteractionSysId\n\n</td><td>\n\nSys\\_id of the interaction record to update. This value is returned by the [Create Voice Interaction/POST](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/openframe-api.md) endpoint.Data type: String\n\nTable: Interaction \\[interaction\\]\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ninteraction\n\n</td><td id=\"openframe-interaction-entry\">\n\nRequired. Details of the voice interaction. At least one parameter must be passed.Data type: Object\n\n```\n\"interaction\": {\n  \"additionalParams\": {Object},\n  \"callbackPhoneNumber\": \"String\",\n  \"clientSessionId\": \"String\",\n  \"inboundId\": \"String\",\n  \"userPhoneNumber\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\ninteraction.additionalParams\n\n</td><td id=\"openframe-interaction_additionalParams-entry\">\n\nName-value pairs of the associated interaction record fields and their respective values.For example:\n\n```\n\"additionalParams\": {\n  \"direction\": \"inbound\",\n  \"short_description\": \"New outbound call\",\n  \"assigned_to\": \"a8f98bb0eb32010045e1a5115206fe3a\"\n}\n```\n\nData type: Object\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.callbackPhoneNumber\n\n</td><td id=\"openframe-interaction_callbackPhoneNumber-entry\">\n\nCaller's callback phone number. This is the number the agent uses to reach the caller in case the call drops.This value maps to the caller\\_phone\\_number field in the Interaction \\[interaction\\] table.\n\nSee also the **callerPhoneNumber** property description for [Create Voice Interaction/POST](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/openframe-api.md).\n\nData type: String\n\nFormat: E.164\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.clientSessionId\n\n</td><td id=\"openframe-interaction_clientSessionId-entry\">\n\nUnique identifier of the record in an external system used to track this phone call. This information links the records between the two systems.Data type: String\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.inboundId\n\n</td><td id=\"openframe-interaction_inboundId-entry\">\n\nUnique identifier of the application provider for the voice service.Table: Inbound ID field in the Provider Channel Application \\[sys\\_cs\\_provider\\_application\\] table.\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.userPhoneNumber\n\n</td><td>\n\nPhone number of the user that made the call associated with the voice interaction.Data type: String\n\nFormat: E.164\n\n</td></tr><tr><td>\n\ninteractionContext\n\n</td><td id=\"openframe-interactionContext-entry\">\n\nInteraction context variables to set. Name-value pairs of the interaction context variables to save in the interaction record. These values are determined by CCaaS.For example:\n\n```\n\"interactionContext\":{\n  \"devicetype\": \"genesys\",\n  \"requester_session_language\": \"en-US\"\n}\n```\n\nData type: Object\n\nDefault: None\n\n</td></tr><tr><td>\n\nphoneLogs\n\n</td><td id=\"openframe-phoneLogs-entry\">\n\nName-value pairs of the phone logs to create and associate with a call. You can specify any field in the Phone Log \\[sn\\_open\\_frame\\_phone\\_log\\] table.For example:\n\n```\n\"phoneLogs\":[\n  {\n    \"agent\": \"String\",\n    \"call_id\": \"String\",\n    \"start_time\": \"String\"\n  }\n]\n```\n\nData type: Array of Objects\n\nDefault: None\n\n</td></tr><tr><td>\n\nrelatedRecords\n\n</td><td id=\"openframe-relatedRecords-entry\">\n\nRecords related to the call.Data type: Array of Objects\n\n```\n\"relatedRecords\":[\n  {\n    \"documentId\": \"String\",\n    \"documentTable\": \"String\"\n  }\n]\n```\n\nDefault: None\n\n</td></tr><tr><td>\n\nrelatedRecords.documentId\n\n</td><td id=\"openframe-relatedRecords_documentId-entry\">\n\nSys\\_id of the related record. Data type: String\n\nTable: Specified in the **relatedRecords.documentTable** parameter.\n\n</td></tr><tr><td>\n\nrelatedRecords.documentTable\n\n</td><td id=\"openframe-relatedRecords_documentTable-entry\">\n\nName of the table that contains the related record.Data type: String\n\n</td></tr></tbody>\n</table>### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nstatus\n\n</td><td>\n\nStatus of the record update.Possible values:\n\n-   SUCCESS: The interaction record was successfully updated.\n-   FAILURE: The interaction record was not updated.\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following code example shows how to update the interaction record with the sys\\_id 12961fff7fb2d2102d0cd3cf8c86652b.\n\n```\ncurl \"http://instance.service-now.com/api/now/openframe/voice-interaction/12961fff7fb2d2102d0cd3cf8c86652b\" \\\n--request PATCH \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n   \\\"interaction\\\":{\n      \\\"additionalParams\\\":{\n         \\\"direction\\\":\\\"inbound\\\",\n         \\\"short_description\\\":\\\"New Poonam outbound call\\\",\n         \\\"assigned_to\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\"\n      }\n   },\n   \\\"interactionContext\\\":{\n      \\\"devicetype\\\":\\\"genesys\\\",\n      \\\"requester_session_language\\\":\\\"en-US\\\"\n   },\n   \\\"phoneLogs\\\":[\n      {\n         \\\"call_id\\\":\\\"2323223\\\",\n         \\\"agent\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\",\n         \\\"start_time\\\":\\\"2024-11-04 21:45:00\\\"\n      },\n      {\n         \\\"call_id\\\":\\\"33535353\\\",\n         \\\"agent\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\",\n         \\\"start_time\\\":\\\"2024-11-04 21:45:00\\\"\n      },\n      {\n         \\\"call_id\\\":\\\"1997654\\\",\n         \\\"agent\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\",\n         \\\"start_time\\\":\\\"2024-11-04 21:45:00\\\"\n      }\n   ],\n   \\\"relatedRecords\\\":[\n      {\n         \\\"documentTable\\\":\\\"csm_consumer\\\",\n         \\\"documentId\\\":\\\"59e788fbdb1b1200b6075200cf9619d2\\\"\n      },\n      {\n         \\\"documentTable\\\":\\\"sys_user\\\",\n         \\\"documentId\\\":\\\"62826bf03710200044e0bfc8bcbe5df1\\\"\n      }\n   ]\n}\" \\\n--user 'username':'pasword'\n\n```\n\nResponse:\n\n```\n{\n  \"result\": {\n    \"status\": \"SUCCESS\"\n  }\n}\n\n```\n\n## openframe - POST /openframe/voice-interaction\n\nCreates an interaction record in the Interaction \\[interaction\\] table when an agent accepts a call. Contact Center as a Service \\(CCaaS\\) providers can then use these records to track phone calls.\n\nUse this endpoint to provide a consistent experience for agents, similar to other native channels such as chat and case, when accepting phone calls.\n\n### URL format\n\nVersioned URL: `/api/now/openframe/{api_version}/voice-interaction`\n\nDefault URL: `/api/now/openframe/voice-interaction`\n\n**Note:** Available versions are specified in the [REST API Explorer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_CustomWebServices.md).\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td id=\"version-entry-RESTAPI\">\n\nOptional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ninteraction\n\n</td><td>\n\nRequired. Details of the voice interaction. At least one parameter must be passed.Data type: Object\n\n```\n\"interaction\": {\n  \"additionalParams\": {Object},\n  \"callbackPhoneNumber\": \"String\",\n  \"clientSessionId\": \"String\",\n  \"inboundId\": \"String\",\n  \"userPhoneNumber\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\ninteraction.additionalParams\n\n</td><td id=\"openframe-interaction_additionalParams-entry\">\n\nName-value pairs of the associated interaction record fields and their respective values.For example:\n\n```\n\"additionalParams\": {\n  \"direction\": \"inbound\",\n  \"short_description\": \"New outbound call\",\n  \"assigned_to\": \"a8f98bb0eb32010045e1a5115206fe3a\"\n}\n```\n\nData type: Object\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.callbackPhoneNumber\n\n</td><td id=\"openframe-interaction_callbackPhoneNumber-entry\">\n\nCaller's callback phone number. This is the number the agent uses to reach the caller in case the call drops.This value maps to the caller\\_phone\\_number field in the Interaction \\[interaction\\] table.\n\nSee also the **callerPhoneNumber** property description for [Create Voice Interaction/POST](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/openframe-api.md).\n\nData type: String\n\nFormat: E.164\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.clientSessionId\n\n</td><td id=\"openframe-interaction_clientSessionId-entry\">\n\nUnique identifier of the record in an external system used to track this phone call. This information links the records between the two systems.Data type: String\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.inboundId\n\n</td><td id=\"openframe-interaction_inboundId-entry\">\n\nUnique identifier of the application provider for the voice service.Table: Inbound ID field in the Provider Channel Application \\[sys\\_cs\\_provider\\_application\\] table.\n\nDefault: None\n\n</td></tr><tr><td>\n\ninteraction.userPhoneNumber\n\n</td><td id=\"openframe-interaction_userPhoneNumber-entry\">\n\nRequired. Phone number of the user that made the call associated with the voice interaction.Data type: String\n\nFormat: E.164\n\n</td></tr><tr><td>\n\ninteractionContext\n\n</td><td id=\"openframe-interactionContext-entry\">\n\nInteraction context variables to set. Name-value pairs of the interaction context variables to save in the interaction record. These values are determined by CCaaS.For example:\n\n```\n\"interactionContext\":{\n  \"devicetype\": \"genesys\",\n  \"requester_session_language\": \"en-US\"\n}\n```\n\nData type: Object\n\nDefault: None\n\n</td></tr><tr><td>\n\nphoneLogs\n\n</td><td id=\"openframe-phoneLogs-entry\">\n\nName-value pairs of the phone logs to create and associate with a call. You can specify any field in the Phone Log \\[sn\\_open\\_frame\\_phone\\_log\\] table.For example:\n\n```\n\"phoneLogs\":[\n  {\n    \"agent\": \"String\",\n    \"call_id\": \"String\",\n    \"start_time\": \"String\"\n  }\n]\n```\n\nData type: Array of Objects\n\nDefault: None\n\n</td></tr><tr><td>\n\nrelatedRecords\n\n</td><td id=\"openframe-relatedRecords-entry\">\n\nRecords related to the call.Data type: Array of Objects\n\n```\n\"relatedRecords\":[\n  {\n    \"documentId\": \"String\",\n    \"documentTable\": \"String\"\n  }\n]\n```\n\nDefault: None\n\n</td></tr><tr><td>\n\nrelatedRecords.documentId\n\n</td><td id=\"openframe-relatedRecords_documentId-entry\">\n\nSys\\_id of the related record. Data type: String\n\nTable: Specified in the **relatedRecords.documentTable** parameter.\n\n</td></tr><tr><td>\n\nrelatedRecords.documentTable\n\n</td><td id=\"openframe-relatedRecords_documentTable-entry\">\n\nName of the table that contains the related record.Data type: String\n\n</td></tr></tbody>\n</table>### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nnumber\n\n</td><td>\n\nOnly returned on success. Interaction number of the newly created voice interaction. Data type: String\n\n</td></tr><tr><td>\n\nstatus\n\n</td><td>\n\nStatus of the record creation.Possible values:\n\n-   SUCCESS: The interaction record was successfully created.\n-   FAILURE: The interaction record was not created.\n\n</td></tr><tr><td>\n\nsysId\n\n</td><td>\n\nOnly returned on success. Sys\\_id of the newly created voice interaction record. Table: Interaction \\[interaction\\]\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe following code example shows how to create a new interaction record.\n\n```\ncurl \"http://instance.service-now.com/api/now/openframe/voice-interaction\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n   \\\"interaction\\\":{\n      \\\"userPhoneNumber\\\":\\\"+1303506536\\\",\n      \\\"clientSessionId\\\":\\\"a545t65678\\\",\n      \\\"callbackPhoneNumber\\\":\\\"+14089965744\\\",\n      \\\"additionalParams\\\":{\n         \\\"direction\\\":\\\"inbound\\\",\n         \\\"short_description\\\":\\\"New outbound call\\\",\n         \\\"assigned_to\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\"\n      }\n   },\n   \\\"interactionContext\\\":{\n      \\\"devicetype\\\":\\\"genesys\\\",\n      \\\"requester_session_language\\\":\\\"en-US\\\"\n   },\n   \\\"phoneLogs\\\":[\n      {\n         \\\"call_id\\\":\\\"2323223\\\",\n         \\\"agent\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\",\n         \\\"start_time\\\":\\\"2024-11-04 21:45:00\\\"\n      },\n      {\n         \\\"call_id\\\":\\\"33535353\\\",\n         \\\"agent\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\",\n         \\\"start_time\\\":\\\"2024-11-04 21:45:00\\\"\n      },\n      {\n         \\\"call_id\\\":\\\"1997654\\\",\n         \\\"agent\\\":\\\"a8f98bb0eb32010045e1a5115206fe3a\\\",\n         \\\"start_time\\\":\\\"2024-11-04 21:45:00\\\"\n      }\n   ],\n   \\\"relatedRecords\\\":[\n      {\n         \\\"documentTable\\\":\\\"csm_consumer\\\",\n         \\\"documentId\\\":\\\"59e788fbdb1b1200b6075200cf9619d2\\\"\n      },\n      {\n         \\\"documentTable\\\":\\\"sys_user\\\",\n         \\\"documentId\\\":\\\"62826bf03710200044e0bfc8bcbe5df1\\\"\n      }\n   ]\n}\" \\\n--user 'username':'password'\n\n```\n\nResponse:\n\n```\n{\n  \"result\": {\n    \"status\": \"SUCCESS\",\n    \"sysId\": \"12961fff7fb2d2102d0cd3cf8c86652b\",\n    \"number\": \"IMS0000052\"\n  }\n}\n```\n\n"}}