openframe API

Yokohama API Reference

Release

yokohama

ft:locale

en-US

ft:publication_title

Yokohama API Reference

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

openframe API

Release version: Yokohama

Updated January 30, 2025

7 minutes to read

The 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.

Use this API to create interaction records to track agent phone calls. Once an interaction record is created, the interaction can automatically display in the CSM Configurable Workspace when an agent receives a phone call.

To 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.

For additional information on CSM voice interaction records, see CSM voice interaction record page.

openframe - PATCH /openframe/voice-interaction/{interactionSysId}

Updates 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.

URL format

Versioned URL: /api/now/openframe/{api_version}/voice-interaction/{interactionSysId}

Default URL: /api/now/openframe/voice-interaction/{interactionSysId}

Note:

Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 1. Path parameters
Name	Description
api_version	Optional. 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
interactionSysId	Sys_id of the interaction record to update. This value is returned by the Create Voice Interaction/POST endpoint. Data type: String Table: Interaction [interaction]

Table 2. Query parameters
Name	Description
None

Table 3. Request body parameters (XML or JSON)
Name	Description
interaction	Required. Details of the voice interaction. At least one parameter must be passed. Data type: Object `"interaction": { "additionalParams": {Object}, "callbackPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userPhoneNumber": "String" }`
interaction.additionalParams	Name-value pairs of the associated interaction record fields and their respective values. For example: `"additionalParams": { "direction": "inbound", "short_description": "New outbound call", "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a" }` Data type: Object Default: None
interaction.callbackPhoneNumber	Caller'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. See also the callerPhoneNumber property description for Create Voice Interaction/POST. Data type: String Format: E.164 Default: None
interaction.clientSessionId	Unique 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 Default: None
interaction.inboundId	Unique identifier of the application provider for the voice service. Table: Inbound ID field in the Provider Channel Application [sys_cs_provider_application] table. Default: None
interaction.userPhoneNumber	Phone number of the user that made the call associated with the voice interaction. Data type: String Format: E.164
interactionContext	Interaction 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: `"interactionContext":{ "devicetype": "genesys", "requester_session_language": "en-US" }` Data type: Object Default: None
phoneLogs	Name-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: `"phoneLogs":[ { "agent": "String", "call_id": "String", "start_time": "String" } ]` Data type: Array of Objects Default: None
relatedRecords	Records related to the call. Data type: Array of Objects `"relatedRecords":[ { "documentId": "String", "documentTable": "String" } ]` Default: None
relatedRecords.documentId	Sys_id of the related record. Data type: String Table: Specified in the relatedRecords.documentTable parameter.
relatedRecords.documentTable	Name of the table that contains the related record. Data type: String

Headers

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

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

Table 5. Response headers
Header	Description
None

Status codes

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

Table 6. Status codes
Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)


Name	Description
status	Status of the record update. Possible values: SUCCESS: The interaction record was successfully updated. FAILURE: The interaction record was not updated.

cURL request

The following code example shows how to update the interaction record with the sys_id 12961fff7fb2d2102d0cd3cf8c86652b.

curl "http://instance.service-now.com/api/now/openframe/voice-interaction/12961fff7fb2d2102d0cd3cf8c86652b" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New Poonam outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'pasword'

Response:

{
  "result": {
    "status": "SUCCESS"
  }
}

openframe - POST /openframe/voice-interaction

Creates 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.

Use this endpoint to provide a consistent experience for agents, similar to other native channels such as chat and case, when accepting phone calls.