openFrameAPI - Client

  • Release version: Zurich
  • Updated July 31, 2025
  • 37 minutes to read

    • The openFrameAPI provides methods that interact with OpenFrame. OpenFrame is an omni-present frame that communication partners can use to integrate their systems into the ServiceNow platform.

    One of the core requirements is the ability to connect and serve code from different domains that can connect seamlessly with partner subsystems. This cross domain connection is required to keep connections and callbacks registered into communication systems without any cross domain issues.

    OpenFrame has two significant parts. One lives in the ServiceNow application (referred to as TopFrame) and this API that is sourced from the partner application. This API has the necessary methods to communicate with TopFrame and control the visual features of the OpenFrame.
    Note:
    To stay current with reference to the OpenFrame library, use the following resource URI: https://[servicenow instance]/scripts/openframe/latest/openFrameAPI.min.js.

    openFrameAPI - getAWAAgentPresence(String success, String failure)

    Returns the logged in agent’s current presence state.

    Table 1. Parameters
    Name Type Description
    success String If the method is successful, name of the callback function to invoke.
    failure String If the method fails, name of the callback function to invoke.
    Table 2. Returns
    Type Description
    presence Results passed to the success callback function by the openFrame infrastructure.

    Data type: Object

    "presence": {  
  "available": Boolean, 
  "channels": [Array],
  "name": "String", 
  "sys_id": "String"
}
    presence.available Flag that indicates whether the associated agent is available.
    Valid values:
    • true: Agent is available.
    • false: Agent isn't available.

    Data type: Boolean
    presence.channels List of available channels of communication with the agent.

    Data type: Array of Objects

    "channels": [
  { 
    "available": Boolean,
    "name": "String",
    "restrict_update": Boolean,
    "service_channel_type": "String",
    "sys_id": "String"
  }
]
    presence.channels.available Flag that indicates whether the channel is available.
    Valid values:
    • true: Channel is available.
    • false: Channel isn't available.

    Data type Boolean
    presence.channels.name Name of the channel, such as Chat or Phone.

    Data type: String
    presence.channels.restrict_update Flag that indicates whether the user can restrict updates to the channel.
    Valid values:
    • true: User can restrict updates to the channel.
    • false: User can't restrict updates to the channel.

    Data type Boolean
    presence.channels.service_channel_type Type of the service channel.

    Data type: String
    presence.channels.sys_id Sys_id of the channel record.

    Data type: String

    Table: Service Channels [awa_service_channel]
    presence.name Name of the agent's presence state.

    Data type: String
    presence.sys_id Sys_id of the presence state record.

    Data type: String

    Table: Presence States [awa_presence_state]

    The following code example shows how to call this method.

    function failure(data)
{
  console.log("failure: " + JSON.stringify(data));
}
 
function success(data)
{
  console.log("success: " + JSON.stringify(data));
}
 
openFrameAPI.getAWAAgentPresence(success, failure)

    Response to success callback function:

    success: { 
  "presence": { 
    "name": "Available", 
    "sys_id": "0b10223c57a313005baaaa65ef94f970", 
    "available": true, 
    "channels": [ 
      { 
        "name": "Chat", 
        "available": true, 
        "sys_id": "27f675e3739713004a905ee515f6a7c3", 
        "restrict_update": false, 
        "service_channel_type": "chat" 
      } 
    ] 
  } 
}

    openFrameAPI - hide()

    Hides the OpenFrame in the TopFrame.

    Table 3. Parameters
    Name Type Description
    None
    Table 4. Returns
    Type Description
    void 
    openFrameAPI.hide()

    openFrameAPI - init(Object config, function successCallback, function failureCallback)

    Initializes OpenFrame. This must be the first method that you call.

    This method initializes communication to TopFrame and initializes any visual elements passed in the config parameter.

    Table 5. Parameters
    Name Type Description
    config Object Name-value pairs to use during the initialization process.
    Possible keys:
    • height
    • subTitle
    • title
    • titleIcon
    • width
    All keys are optional. Pass an empty object if you don't want to set these key-value pairs.
    successCallback function Name of the callback function to use if the init method succeeds. The OpenFrame configuration stored in the system is passed as a parameter to the callback function.
    failureCallback function Name of the callback function to use if the init method fails.
    Table 6. Returns
    Type Description
    void 
    var config = {
height: 300,
width: 200
}
function handleCommunicationEvent(context) {
console.log("Communication from Topframe", context);
}
function initSuccess(snConfig) {
console.log("openframe configuration", snConfig);
//register for communication event from TopFrame
openFrameAPI.subscribe(openFrameAPI.EVENTS.COMMUNICATION_EVENT,
handleCommunicationEvent);
}
function initFailure(error) {
console.log("OpenFrame init failed...", error);
}
openFrameAPI.init(config, initSuccess, initFailure);

    openFrameAPI - isVisible(function callback)

    Checks to see if the OpenFrame is visible in the TopFrame.

    Table 7. Parameters
    Name Type Description
    callback function The callback function receives a parameter with a value of true or false. True if OpenFrame is visible and false if not visible.
    Table 8. Returns
    Type Description
    void 
    function callback(isVisible) {
console.log(isVisible)
}
openFrameAPI.isVisible(callback)

    openFrameAPI - openCustomURL(String details)

    Opens a custom URL in the UI16 interface.

    Table 9. Parameters
    Name Type Description
    Url String Text of the custom URL.

    Maximum size: 2083 characters
    Table 10. Returns
    Type Description
    void 
    openFrameAPI.openCustomURL('10_cool_things.do');

    openFrameAPI - openServiceNowForm(Object details)

    Opens a form URL.

    When an agent receives an incoming call, the OpenFrame window displays information such as the account, contact, or consumer. Clicking a link in the OpenFrame window displays the corresponding record.
    • In the platform interface, this API opens a form URL in TopFrame.
    • For Agent Workspace, this API supports interaction tab management. In Agent Workspace, an interaction record opens in a parent tab and the specified entity record opens in a child tab under the interaction tab.
    Table 11. Parameters
    Name Type Description
    details Object Key-value pairs that identify the form URL to open. 
    "details": {
  "entity": "String";
  "interaction_sys_id": "String";
  "query": "String"
}
    details.entity String Table or entity name.
    details.interaction_sys_id String Optional. Sys_id of the interaction record to open as parent tab in Agent Workspace.
    Note:
    In the platform interface the interaction_sys_id is ignored.
    details.query String Query to identify the record to open, such as: query:'sys_id=<record_sys_id>'.
    Table 12. Returns
    Type Description
    void

    The following example shows basic usage in platform:

    openFrameAPI.openServiceNowForm({entity:'customer_account', 
query:'sys_id=447832786f0331003b3c498f5d3ee452', 'interaction_sys_id':'3be092313b711300758ce9b534efc4dd'});

    The following example shows how to use the query parameter to create a new record with data provided in the form by using sysparm_query and an encoded query to populate the first and last name fields in Workspace:

    openFrameAPI.openServiceNowForm({ entity: 'sys_user',
query: 'sys_id=-1&sysparm_query=first_name=Ivan^last_name=Greggor' });

    openFrameAPI - openServiceNowFormwithChildTab()

    Opens a ServiceNow form with a child tab if invoked in a workspace or opens an entity if invoked in the UI16 interface.

    Table 13. Parameters
    Name Type Description
    openServiceNowFormwithChildTab Object Defines if the API opens a ServiceNow form with a child tab if invoked in a workspace or opens an entity if invoked in the UI16 interface.
    openFrameAPI.openServiceNowFormwithChildTab({
  entity: "String",
  sys_id: String", 	
  parent_entity: "String",	
  parent_entity_sys_id: "String"
})
    openServiceNowFormwithChildTab.entity String Name of the table that contains the record to open.
    openServiceNowFormwithChildTab.sys_id String Sys_id of the record to open.
    openServiceNowFormwithChildTab.parent_entity String Name of the table to open as a parent tab.
    openServiceNowFormwithChildTab.parent_entity_sys_id String Sys_id of the parent record to open.
    Table 14. Returns
    Type Description
    None

    The following example opens the parent entity as a parent tab on a configured workspace, or opens just the entity if invoked in UI16.

    openFrameAPI.openServiceNowFormwithChildTab({
  entity: "customer_account", 
  sys_id: "447832786f0331003b3c498f5d3ee452", 	
  parent_entity: "interaction", 
  parent_entity_sys_id: "3be092313b711300758ce9b534efc4dd"
});

    openFrameAPI - openServiceNowList(Object details)

    Opens a list URL in the UI16 interface.

    Table 15. Parameters
    Name Type Description
    details Object Key value pairs that describe the content to use when opening the list URL.

    Valid values:
    Table 16. Returns
    Type Description
    void 
    openFrameAPI.openServiceNowList({entity:'case', query:'active=true'});

    openFrameAPI - setFrameMode(mode)

    Sets the OpenFrame mode.

    The mode passed in this API:
    • Sets the appropriate icon in the header: collapse or expand
    • Raises the relevant event for CTI:
      • openFrameAPI.EVENTS.COLLAPSE
      • openFrameAPI.EVENTS.EXPAND
    Table 17. Parameters
    Name Type Description
    Mode String Set OpenFrame Mode. Enumerated options:
    1. openFrameAPI.FRAME_MODE.COLLAPSE
    2. openFrameAPI.FRAME_MODE.EXPAND
    Table 18. Returns
    Type Description
    void 
    openFrameAPI.setFrameMode(openFrameAPI.FRAME_MODE.COLLAPSE);

    openFrameAPI - setHeight(height)

    Sets the OpenFrame height.

    Table 19. Parameters
    Name Type Description
    Height Number Height in pixels
    Table 20. Returns
    Type Description
    void 
    openFrameAPI.setHeight(100);

    openFrameAPI - setICContext(String Type, Object <Context>)

    Sets the context data related to the interaction controls on the client. Use this context data to determine the client UI to display in OpenFrame.

    For additional information on interactive controls, see Interaction Controls Component.

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

    Table 21. Parameters
    Name Type Description
    Type String Type of context data to set.
    Valid values:
    • activeCall: Sets the context for the ongoing Active call component. When you pass this context type, you must also pass the activeCall[]Context parameter.
    • idleState: Sets the idle state capabilities for the current user. When this type is set, the idle state UI (dial pad) appears in OpenFrame. When you pass this context type, you must also pass the <idleState>{} JSON as the Context parameter.
    • offerContext: Sets the current participant's offer context for resiliency. When you pass this context type, you must also pass the offerContext{} JSON as the Context parameter.
    • searchTargetList: Sets the telephone directory context. When this type is set, it enables Transfer call on the Active call component. When you pass this context type, you must also pass the searchTargetList[] JSON as the Context parameter.
    <Context> Object Context data to set. Each context data type is a unique set of input data.
    Valid Context data objects:
    • activeCall
    • idleState
    • offerContext
    • searchTargetList
    activeCall Array of Objects Context details about an active call. Each object represents an ongoing active call.
    "activeCall": [
  { 
    "callbackContext": {Object},
    "currentParticipant": {Object},
    "customPayload: {Object},
    "direction": "String",
    "externalId": "String",
    "nowRecordId": "String",
    "nowRecordTable": "String",
    "participants": [Array],
    "type": "String"
  }
]
    activeCall.callbackContext Object Only used if the activeCall.type property is callback. Callback context information for the ongoing callback component.
    "callbackContext": {
  "callAttemptedByAgent": Boolean,
  "callbackNumbers": [Array],
  "closeInEndTime": "String",
  "customerName": "String",
  "dialInEndTime": "String"
}
    activeCall. callbackContext. callAttemptedByAgent Boolean Flag that indicates whether callback was attempted by a customer service agent.
    Valid values:
    • true: The callback was attempted by a customer service agent. If true, set closeInEndTime.
    • false: The callback wasn’t attempted by a customer service agent. If false, set dialInEndTime.

    Default: False
    activeCall. callbackContext. callbackNumbers Array List of phone numbers provided as strings.
    activeCall. callbackContext. closeInEndTime String Set only if callAttemptedByAgent is true. End time for callback in UTC format.
    activeCall. callbackContext. customerName String Name of the customer.
    activeCall. callbackContext. dialInEndTime String Set only if callAttemptedByAgent is false and the type of callback is auto-dial. Dial-in end time for callback in UTC format.
    activeCall.currentParticipant Object Required. Details about the current participant's call capabilities and call status.
    "currentParticipant": {
  "actor": "String",
  "callStartTime": "String",
  "capabilities": {Object},
  "connectedTime": "String",
  "custom-capability-state-1": Boolean,
  "flagged": Boolean,
  "held": Boolean,
  "id": "String",
  "muted": Boolean,
  "name": "String",
  "paused": Boolean,
  "recording": "String",
  "state": "String",
  "wrapUP": {Object}
}
    activeCall.currentParticipant.​actor String Type of participant on the call.
    Valid values:
    • agent
    Note:
    Other participant types to be added in the future.
    activeCall.currentParticipant.​callStartTime String Date and time that the call started.

    Time standard: UTC

    Format: RSS - "<day of week>, dd mmm yyyy hh:MM:ss GMT". For example: "Wed, 17 Dec 2024 05:23:41 GMT"
    activeCall.currentParticipant.​capabilities Object Details about the capabilities that the current (agent) participant can perform during a call. The associated icons appear in the Active call component for the capabilities that are enabled.

    Screen shot of Active call component with capabilities icons
    "capabilities": {
  "callbackTransferStatus": "String",
  "cancelCallbackTransferEligible": Boolean,
  "closeCallback": Boolean,
  "dtmf": Boolean,
  "endCall": Boolean,
  "flag": Boolean,
  "hold": Boolean,
  "initiateCall": Boolean,
  "leaveAndTransfer": Boolean,
  "mergeCall": Boolean,
  "mute": Boolean,
  "resumeRecording": Boolean,
  "pauseRecording": Boolean,
  "startRecording": Boolean,
  "stopRecording": Boolean,
  "transfer": Boolean
}
    activeCall.currentParticipant.​capabilities.callbackTransferStatus String CCaaS (Contact Center as a Service) callback transfer status.

    Possible values:

    • Failed
    • Empty string (default)
    activeCall.currentParticipant.​capabilities.cancelCallbackTransferEligible Boolean Flag that indicates if the cancel callback transfer option is enabled.
    Valid values:
    • true: Cancel callback transfer option is enabled.
    • false: Cancel callback transfer option is disabled.

    Default: false
    activeCall.currentParticipant.​capabilities.closeCallback Boolean Flag that indicates whether the close callback button is enabled.
    Valid values:
    • true: Close callback button is enabled.
    • false: Close callback button is disabled.

    Default: false
    activeCall.currentParticipant.​capabilities.​dtmf Boolean Flag that indicates whether the agent has dual tone multi-frequency (DTMF) capability for the current call.
    Valid values:
    • true: Participant has DTMF capability.
    • false: Participant doesn't have DTMF capability.

    Default: false
    activeCall.currentParticipant.​capabilities.​endCall Boolean Flag that indicates whether the associated participant can end the call.
    Valid values:
    • true: Participant can end the call. The end call button is enabled in the UI.
    • false: Participant can't end the call. The end call button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​flag Boolean Flag that indicates whether the participant can flag the call for quality issues, such as voice quality problems.
    Valid values:
    • true: Participant can flag problem calls.
    • false: Participant can't flag problem calls.

    Default: false
    activeCall.currentParticipant.​capabilities.​hold Boolean Flag that indicates whether the participant can put the call on hold.
    Valid values:
    • true: Participant can put the call on hold. The hold button is enabled in the UI.
    • false: Participant can't put the call on hold. The hold button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​initiateCall Boolean Flag that indicates whether the associated participant can start the call.
    Valid values:
    • true: Participant can start the call. The initiate call button is enabled in the UI.
    • false: Participant can't start the call. The initiate call button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​leaveAndTransfer Boolean Flag that indicates whether the participant can transfer the call to another agent and then drop off the call. Enable this capability for actions such as consult transfers, where the user who is consulted is not the owner of the call.
    Valid values:
    • true: Participant can transfer and drop off the call.
    • false: Participant can't transfer and drop off the call.

    Default: false
    activeCall.currentParticipant.​capabilities.​mergeCall Boolean Flag that indicates whether the participant can merge the call. Use this capability when the participant's call legs are capable of merging.
    Valid values:
    • true: Participant can merge the call. The merge button is enabled in the UI.
    • false: Participant can't merge the call. The merge button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​mute Boolean Flag that indicates whether the participant can mute the call.
    Valid values:
    • true: Participant can mute the call. The mute button is enabled in the UI.
    • false: Participant can't mute the call. The mute button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​resumeRecording Boolean Flag that indicates whether the participant can resume recording the call.
    Valid values:
    • true: Participant can resume recording the call. The pause recording button is enabled in the UI.
    • false: Participant can't resume recording the call. The pause recording button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​pauseRecording Boolean Flag that indicates whether the participant can pause recording the call.
    Valid values:
    • true: Participant can pause recording the call. The pause recording button is enabled in the UI.
    • false: Participant can't pause recording the call. The pause recording button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​startRecording Boolean Flag that indicates whether the participant can start recording the call.
    Valid values:
    • true: Participant can start recording the call. The recording button is enabled in the UI.
    • false: Participant can't start recording the call. The recording button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​stopRecording Boolean Flag that indicates whether the participant can stop recording the call.
    Valid values:
    • true: Participant can stop recording the call. The stop recording button is enabled in the UI.
    • false: Participant can't stop recording the call. The stop recording button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​capabilities.​transfer Boolean Flag that indicates whether the participant can transfer the call.
    Valid values:
    • true: Participant can transfer the call. The transfer button is enabled in the UI.
    • false: Participant can't transfer the call. The transfer button is disabled in the UI.

    Default: false
    activeCall.currentParticipant.​connectedTime String Date and time that the call initially connected.

    Time base: UTC

    Format: RSS - "<day of week>, dd mmm yyyy hh:MM:ss GMT". For example: "Wed, 17 Dec 2024 05:23:41 GMT"
    activeCall.currentParticipant.​custom-capability-state-1 Boolean Flag that indicates whether there are any current participants on the call.
    Valid values:
    • true: Current participants on the call.
    • false: No current participants on the call.

    Default: false
    activeCall.currentParticipant.​flagged Boolean Flag that indicates whether the call is flagged for an issue, such as a voice quality issue.
    Valid values:
    • true: Call has been flagged for an issue.
    • false: Call hasn't been flagged for an issue.

    Default: false
    activeCall.currentParticipant.​held Boolean Flag that indicates the participant’s held state.
    Valid values:
    • true: Participant is on-hold.
    • false: Participant isn't on-hold.

    Default: false
    activeCall.currentParticipant.​id String Required. Sys_id of the associated participant record, such as the sys_id of the agent.

    Table: User [sys_user]
    activeCall.currentParticipant.​muted Boolean Flag that indicates the participant’s muted state.
    Valid values:
    • true: Participant is muted.
    • false: Participant isn't muted.

    Default: false
    activeCall.currentParticipant.​name String Participant's name.
    activeCall.currentParticipant.​paused Boolean Flag that indicates the participant’s paused state.
    Valid values:
    • true: Participant is paused.
    • false: Participant isn't paused.

    Default: false
    activeCall.currentParticipant.​recording String Current recording state of the call.
    Valid values:
    • in_progress
    • none
    activeCall.currentParticipant.​wrapUP Object Future use.
    activeCall.customPayload Object Custom payload to pass to OpenFrame as part of OpenFrame events. This is a free-form object and can contain any data needed to customize the active call component, such as adding buttons or text.
    activeCall.direction String Direction of the call for the associated participant.
    Valid values:
    • inbound
    • outbound
    activeCall.externalId Required. Unique value that identifies the current active call on the associated external system.
    activeCall.​nowRecordId String Required. Sys_id of the active call record.

    Table: Interaction [interaction] Only supported option for base system.
    activeCall.​nowRecordTable String Required. Table to which the active call belongs.

    Table: Interaction [interaction] Only supported option for base system.
    activeCall.​participants Array of Objects Required. List of the additional participants on the call. A participant can be an agent, a customer, an external person who is not an agent or a customer, or a queue.
    "participants": [
  {
    "actor": "String",
    "ani": "String",
    "address": "String",
    "capabilities": {Object},
    "callStartTime" "String",
    "connectedTime": "String",
    "customPayload": {Object},
    "dnis": "String",
    "held": Boolean,
    "heldAtTime": "String",
    "id": "String",
    "muted": Boolean,
    "name": "String",
    "requestACW": Boolean,
    "requireWrapup": Boolean,
    "state": "String"
  }
]
    activeCall.​participants.​actor String Type of actor for the associated participant.
    For example:
    • agent
    • customer
    • external
    • queue
    activeCall.​participants.​ani Automatic number identification. Telephone number to display to the receiver of the phone call.
    activeCall.​participants.​address String Participant's telephone number.
    activeCall.​participants.​capabilities Object Details about the type of capabilities that the participant has for the associated call.
    "capabilities": {
  "endCall": Boolean,
  "hold": Boolean,
  "mute": Boolean
}
    activeCall.​participants.​capabilities.​endCall Boolean Flag that indicates whether the associated participant can end the call.
    Valid values:
    • true: Participant can end the call. The end call button is enabled in the UI.
    • false: Participant can't end the call. The end call button is disabled in the UI.

    Default: false
    activeCall.​participants.​capabilities.​hold Boolean Flag that indicates whether the participant can put the call on hold.
    Valid values:
    • true: Participant can put the call on hold. The hold button is enabled in the UI.
    • false: Participant can't put the call on hold. The hold button is disabled in the UI.

    Default: false
    activeCall.​participants.​capabilities.​mute Boolean Flag that indicates whether the participant can mute the call.
    Valid values:
    • true: Participant can mute the call. The mute button is enabled in the UI.
    • false: Participant can't mute the call. The mute button is disabled in the UI.

    Default: false
    activeCall.​participants.​connectedTime String Required. Date and time that the participant initially connected to the call.

    Time standard: UTC

    Format: RSS - "<day of week>, dd mmm yyyy hh:MM:ss GMT". For example: "Wed, 17 Dec 2024 05:23:41 GMT"
    activeCall.​participants.​customPayload Object Custom payload to pass to OpenFrame as part of Open Frame custom events. This is a free-form object and can contain any data needed to customize the Active call component, such as adding buttons or text.
    activeCall.​participants.​dnis String Dialed Number Identification Service. Telephone number the participant dialed.
    activeCall.​participants.​held Boolean Flag that indicates the participant’s held state.
    Valid values:
    • true: Participant is on-hold.
    • false: Participant isn't on-hold.

    Default: false
    activeCall.​participants.​heldAtTime String Date and time that the participant's connection to the call was put on hold.

    Time base: UTC

    Format: RSS - "<day of week>, dd mmm yyyy hh:MM:ss GMT". For example: "Wed, 17 Dec 2024 05:23:41 GMT"
    activeCall.​participants.​id String Required. Participant's unique ID from the Contact Center as a Service (CCaaS) system.
    activeCall.​participants.​muted Boolean Flag that indicates the participant’s mute state.
    Valid values:
    • true: Participant is muted.
    • false: Participant isn't muted.

    Default: false
    activeCall.​participants.​name String Name of the participant.
    activeCall.​participants.​requestACW Boolean For agent use case only - only valid when the activeCall.currentParticipant.actor is "agent".

    Flag that indicates whether the participant is to follow up with the customer.

    Valid values:
    • true: Follow-up required.
    • false: No follow-up required.

    Default: false
    activeCall.​participants.​requireWrapup Boolean For agent use case only - only valid when the activeCall.currentParticipant.actor is "agent".

    Flag that indicates whether to display the Wrap up component once the call is complete.


    Screen shot of Wrap up component
    Valid values:
    • true: Display the Wrap up component at call completion.
    • false: Don't display the Wrap up component at call completion.

    Default: false
    activeCall.​participants.​state String State of the participant's call leg. Appears beneath the phone number in the Active call component.
    Active call window showing state
    This can be any meaningful text, such as:
    • Alerting
    • Connected
    • Ringing
    activeCall.type String Type of call.
    Valid values:
    • call
    • callback
      Note:
      If set, you must include the activeCall.callbackContext object details.
    • voicemail
    idleState Object Describes the idle state context of the agent. This context data determines the information that appears on the dial pad when an agent is waiting for a call and the capabilities they have through this dial pad.
    idleState {
 "capability": {Object},
 "currentInboundId": "String",
 "dialpadInfoMessage": {Object},
 "enableState": {Object}
}
    idleState.capability Object Description of the current user's idle state capabilities.
    "capability": {
  "globalContactSearch": Boolean,
  "logOut": Boolean,
  "outBoundCall": Boolean
}
    idleState.capability.​globalContactSerarch Boolean Flag that indicates whether to display the global contact list while in the idle state.
    Valid values:
    • true: Display the global contact list.
    • false: Don't display the global contact list.

    Default: false
    idleState.capability.​logOut Boolean Flag that indicates whether the user can logout while in the idle state.
    Valid values:
    • true: User can log out when the call is idle. The log out button appears on the dial pad.
    • false: User can't log out when the call is idle.

    Default: false
    idleState.capability.​outBoundCall Boolean Flag that indicates whether the user can make an outbound call while in the idle state.
    Valid values:
    • true: User can make an outbound call when the call is idle.
    • false: User can't make an outbound call when the call is idle.

    Default: false
    idleState.​currentInboundId String Inbound identifier of the provider application used to create the outbound call interaction.

    Table: Located in the id field of the Provider Channel Identities [sys_cs_provider_application] table.

    Default: Base system provider application
    idleState.​dialpadInfoMessage Object Details about the information message to display on the user's dial pad, such as the currently selected queue.
    "dialpadInfoMessage": {
   "label": "String",
   "value": "String"
 }

    In the following example, the label is Selected queue: and the value is Customer Inquiries. You can also just use either the label or the value parameter with Selected queue: Customer Inquiries.


    Screen shot of dial pad with information message
    idleState.​dialpadInfoMessage.​label String Free-form label to display on the dial pad.
    idleState.​dialpadInfoMessage.​value String Free-form message text to display after the label on the dial pad.
    idleState.​enableState Object Details about the enable state of the buttons on the dial pad.
    "enableState": {
   "logOut": Boolean,
   "outBoundCall": Boolean
 }
    idleState.​enableState.​logOut Boolean Flag that indicates whether to enable the logout button in the UI while in the idle state.
    Valid values:
    • true: Display the logout button while in the idle state.
    • false: Don't display the logout button while in the idle state.

    Default: false
    idleState.​enableState.​outBoundCall Boolean Flag that indicates whether to enable the outbound call button in the UI while in the idle state.
    Valid values:
    • true: Display the outbound call button while in the idle state.
    • false: Don't display the outbound call button while in the idle state.

    Default: false
    offerContext Object Details about the current participant's offer context for resiliency.
    {
  "assignment": {Object},
  "creationTime": "String",
  "description": "String",
  "displayContent": {Object},
  "externalId": "String",
  "externalSegmentId": "String",
  "isResilient": Boolean,
  "metadata": {Object},
  "nowRecordId": "String",
  "nowRecordTable": "String",
  "providerAppInboundId": "String",
  "queueId": "String",
  "requesterId": "String",
  "transferContent": {Object},
  "type": "String"
}
    offerContext.assignment Object Details about the agent assignment.
    "assignment": {
  "allowedToDecline": Boolean,
  "enableAutoAssign": Boolean,
  "offeredOn": "String",
  "timeout": "String"
}
    offerContext.assignment. allowedToDecline Boolean Required. Flag that indicates whether the agent is allowed to decline the assignment.
    Valid values:
    • true: The agent is allowed to decline the assignment.
    • false: The agent is not allowed to decline the assignment.

    Default: false
    offerContext.assignment. enableAutoAssign Boolean Required. Flag that indicates whether an agent receive the assignment automatically.
    Valid values:
    • true: An agent can receive the assignment automatically.
    • false: An agent can not receive the assignment automatically.

    Default: false
    offerContext.assignment. offeredOn String Date at which the offer was made in UTC format (Www, dd Mmm yyyy HH:mm:ss GMT).
    offerContext.assignment. timeout String Time in milliseconds to assign to an agent before timeout.
    offerContext.creationTime String Optional. Call creation date and time in UTC format (YYYY-MM-DDTHH:MM:SS).
    offerContext.description String Optional. Description of the offer.
    offerContext.displayContent Object Optional. Unique JSON payload values representing values displayed on screen.
    offerContext.externalId String Unique value that identifies the current active call on the associated external system.
    offerContext.isResilient Boolean Optional. Flag that indicates whether the offer context is resilient.
    Valid values:
    • true: The offer context is resilient.
    • false: The offer context is not resilient.

    Default: true
    offerContext.metadata Object Optional. Free-form custom JSON payload values.
    offerContext.​nowRecordId String Required. Sys_id of the active call record.

    Table: Interaction [interaction] Only supported option for base system.
    offerContext.​nowRecordTable String Optional. Use this property to set the work item and segment for transfers.
    offerContext. providerAppInboundId String Optional. Unique ID from the inbound third-party provider.
    offerContext.​queueId String Required for regular (non-transfer) assignments. Unique ID representing the assignment queue. Use the transferContent.targetId property for transfer assignments.
    offerContext.​requesterId String Required. Unique ID of the offer requester. For voice, this value can be the phone number of the user.
    offerContext.transferContent Object Details required for transfer assignments.
    "transferContent": {
  "sourceQueueId": "String",
  "targetId": "String",
  "targetType": "String",
  "transferType": "String"
}
    offerContext.transferContent. sourceQueueId String The sys_id or external ID of the assignment queue.
    offerContext.transferContent. targetId String The sys_id or external ID of the queue transfer.
    offerContext.transferContent. targetType String Type of transfer target.
    Valid values:
    • agent
    • queue
    offerContext.transferContent. transferType String Type of transfer.
    Valid values:
    • blind
    • consult
    offerContext.type String Type of call.
    Valid values:
    • call
    • callback request
    • voicemail
    searchTargetList Array of Objects Context details of the transfer related data for a ServiceNow table.
    "searchTargetList": [
  {
    "externalId": "String",
    "nowRecordId": "String",
    "nowRecordTable": "String",
    "participantID": "String",
    "targets": [Array]
  }
]
    searchTargetList.​externalId String Unique identifier of the associated call on the CCaaS system.
    searchTargetList.​nowRecordId String Required. Sys_id of the record to which the searchTargetList belongs.
    Note:
    Only records in the Interaction [interaction] table are currently supported.
    searchTargetList.​nowRecordTable String Required. ServiceNow table to which the searchTargetList belongs.

    Table: Only valid value - "interaction"
    searchTargetList.​participantID String Unique identifier for the participant from the CCaaS system.
    searchTargetList.​targets Array of Objects Details about the agents, external users, and/or queues to whom the call can be transferred.
    "targets": [
  {
    "payload": {Object},
    "transferSubtypes": [Array],
    "type": "String"
  }
]
    searchTargetList.​targets.​payload Object Details about the information to display in the transfer call control.

    The following is an example of a Transfer call control that contains a list of agents that the call can be transferred to. The screen shot shows what elements of the UI that each parameter in the list.payload controls.


    Screen shot of Transfer call window showing parameter association
    "payload": {
  "list": [Array]
}

    This example shows an agent payload ("searchTargetList.targets.type" : "agent").

    "payload": {
  "list": [
    {
      "name": "Alice Anderson",
      "id": "agent1Id",
      "hasStats": "true",
      "presence": "available",
      "moreInfo": [
        {
          "label": "Skill",
          "value": "CRM certified"
        }
      ]
    }
  ]
}

    The following shows an example of a queue payload ("searchTargetList.targets.type" : "queue").

    "payload": {
  "list": [
    {
      "name": "Product Support Queue",
      "id": "queue1Id",
      "hasStats": "true",
      "moreInfo": [
        {
          "label": "Skill",
          "value": "10sec"
        },
        {
          "label": "Queue Skill",
          "value": "German"
        }
      ]
    },
    {
      "name": "Billing Queue",
      "id": "queue2Id",
      "hasStats": "true",
      "moreInfo": [
        {
           "label": "Skill",
           "value": "10sec"
        }
      ]
    }
  ]
}
    searchTargetList.​targets.​payload.​list Array of Objects Details about the payload for each type of target.
    "list": [
  {
    "hasStats": Boolean,
    "id": "String",
    "moreInfo": [Array],
    "name": "String",
    "presence": "String"
  }
]
    searchTargetList.​targets.​payload.​list.​hasStats Boolean Flag that indicates whether the associated target has additional statistics such as a wait-time for a queue.
    Valid values:
    • true: Target has additional statistics. An information icon appears next to the agent name or queue.
    • false: Target doesn't have additional statistics.

    Default: false
    searchTargetList.​targets.​payload.​list.​id String Unique identifier of the agent or queue in the CCaaS system.
    searchTargetList.​targets.​payload.​list.​moreInfo Array of Objects Required if searchTargetList.targets.payload.list.hasStats is set to "true". List of skills that the agent or queue has. This information appears in a pop-up window when the user selects the information icon at the end of the entities name.
    "moreInfo": [
  {
    "label": "String",
    "value": "String"
  }
]
    searchTargetList.​targets.​payload.​list.​moreInfo.​label String Free-form label for the information to display in the pop-up window, such as a Skill or Language.
    searchTargetList.​targets.​payload.​list.​moreInfo.​value String Text to display in the pop-up window after the label, such as CRM certified or German.
    searchTargetList.​targets.​payload.​list.​name String Name of the agent, external user, or queue. Located in the CCaaS system.
    searchTargetList.​targets.​payload.​list.​presence String Presence state of the associated agent. This parameter is only valid for a searchTargetList.targets.type of "agent".
    Valid values:
    • available
    • away
    • busy
    • offline
    searchTargetList.​targets.​transferSubtypes Array of Objects Details about the type of transfer supported for the specified searchTargetList.targets.type.

    This information appears when the user clicks the ellipse next to the target's name in the UI.


    Transfer call component showing transfer types

    For example, if only a consult type is supported for the current target type, say queue, this array will contain one object to denote the consult type of transfer.

    "transferSubtypes": [
  {
    "id": "String",
    "label": "String"
  }
]
    searchTargetList.​targets.​transferSubtypes.​id String Identifier of the transfer subtype.
    Valid values:
    • blind: Agent directly transfers the customer call to another agent or queue without first speaking to the agent.
    • consult: Agent contacts the agent to whom they want to consult, then merges the customer into the call with the consulting agent.

    This must correspond to the value in searchTargetList.targets.transferSubtypes.label.
    searchTargetList.​targets.​transferSubtypes.​label String Label of the transfer subtype. If you don't pass a label, nothing appears in the UI for transfer subtype.
    Valid values:
    • Blind
    • Consult

    This must correspond to the value in searchTargetList.targets.transferSubtypes.id.
    searchTargetList.​targets.​type String Type of target.
    Valid values:
    • agent
    • external
    • queue
    Table 22. Returns
    Type Description
    None
    Error (offerContext) Error messages associated with the offerContext object used for resiliency. To view these messages, use the subscribe() method to subscribe to openframe_awa_client_offer event.
    Context values are represented as follows:
    1. success
    2. error
    3. partialSuccess
    AWA_EXTUSER_ROLE_CHECK_FAILED
    Message: User does not have the awa_external_user role.
    This event indicates that the required role 'awa_external_user' or 'admin' is not present for the agent.
    AWA_AGENT_NOT_AVAILABLE
    Message: Agent is not available to receive work.
    This event indicates that the agent selected is unavailable.
    AWA_OFFER_ASSIGNMENT_PAYLOAD_MISSING
    Message: Assignment payload is empty or undefined in the offerContext.
    This event indicates that the payload is empty or undefined in the offerContext object.
    AWA_OFFER_QUEUEID_MISSING
    Message: Transfer Source queue ID is missing in the offerContext.
    This event indicates that the required transfer queue ID (transferContent.targetId) is missing from the offerContext object.
    AWA_ASSIGNMENT_OFFEREDON_FUTURE
    Message: OfferedOn time is in future.
    This event indicates that the value of the assignment.offeredOn property is a future date and invalid. The date must be present or earlier.
    AWA_ASSIGNMENT_OFFEREDON_INVALID_FORMAT
    Message: OfferedOn date format is invalid, Please send it in "Www, dd Mmm yyyy HH:mm:ss GMT" UTC format.
    This event indicates that the value provided for the offerContext.assignment.offeredOn property is not in the proper time date format.
    AWA_OFFER_EXTERNALID_MISSING
    Message: ExternalId is missing in the offerContext.
    This event indicates that the required externalId property has not been provided for the offer. This value identifies the current active call on the associated external system.

    The following code example shows how to set the active state context.

    openFrameAPI.setICContext("activeCall", {
  "activeCall": [
    { 
      "nowRecordTable": "interaction",
      "nowRecordId": "12345675678903456",
      "externalId": "1234567890",
      "type": "call",
      "direction": "inbound",
      "currentParticipant": {
        "id": "participant1",
        "name": "John 1",
        "actor": "agent",
        "state": "connected",
        "connectedTime": "Fri, 12 Jul 2024 05:23:41 GMT",
        "callStartTime": "Fri, 12 Jul 2024 04:20:22 GMT",
        "muted": false,
        "held": true,
        "paused": true,
        "flagged": true,
        "recording": "in_progress",
        "capabilities": {
          "hold": false,
          "mute": true,
          "endCall": true,
          "startRecording": true,
          "pauseRecording": true,
          "stopRecording": true,
          "resumeRecording": true,
          "transfer": true,
          "mergeCall": true,
          "leaveAndTransfer": true,
          "dtmf": true,
          "flag": true
        }
      },
      "participants": [
        {
          "id": "customer1",
          "name": "Gilly 1",
          "actor": "customer",
          "address": "+18582359874",
          "ani": "+16193287356", 
          "dnis": "+18004346258",
          "state": "connected",
          "connectedTime": "Fri, 12 Jul 2024 00:23:41 GMT",
          "callStartTime": "Fri, 12 Jul 2024 20:55:04 GMT",
          "muted": false,
          "held": false,
          "heldAtTime": "Fri, 12 Jul 2024 20:55:04 GMT", 
          "capabilities": {
            "mute": true,
            "hold": true,
            "endCall": true
          }
        },
        {
          "id": "agent2",
          "name": "Ned",
          "actor": "agent",
          "address": "+3134787324",
          "ani": "+13134787324", 
          "dnis": "+14773286943",
          "state": "Ringing...",
          "requireWrapup": true,
          "requestACW": true,
          "connectedTime": "Fri, 12 Jul 2024 20:24:41 GMT",
          "callStartTime": "Fri, 12 Jul 2024 20:56:34 GMT",
          "muted": true,
          "held": true,
          "heldAtTime": "Fri, 12 Jul 2024 20:55:41 GMT",
          "capabilities": {
            "mute": true,
            "endCall": true,
            "hold": true 
          }
        }
      ]
    },
    {
      "nowRecordTable": "interaction",
      "nowRecordId": "12345yhedfh534576u5",
      "externalId": "1234567890",
      "type": "call",
      "direction": "inbound",
      "currentParticipant": {
        "id": "participant1",
        "name": "John 1",
        "actor": "agent",
        "state": "connected",
        "muted": true,
        "held": false,
        "recording": "in_progress",
        "paused": true,
        "flagged": true,
        "capabilities": {
          "hold": false,
          "mute": true,
          "endCall": true,
          "record": true,
          "startRecording": true,
          "stopRecording": true,
          "transfer": true,
          },
          "mergeCall": false,
          "dtmf": true,
          "flag": true
        }
      },
      "participants": [
        {
          "id": "customer1",
          "name": "Gilly 2",
          "actor": "customer",
          "address": "+123456789",
          "state": "connected",
          "connectedTime": "Wed, 04 Dec 2024 00:23:41 GMT",
          "muted": true,
          "held": false,
          "heldAtTime": "Fri, 12 Jul 2024 20:24:41 GMT”,
          "capabilities": {
            "mute": true,
            "hold": true,
            "endCall": true
          }
        },
        {
          "id": "agent2",
          "name": "Ned 2",
          "actor": "agent",
          "address": "+123456789",
          "state": "Ringing...",
          "connectedTime": "Fri, 12 Jul 2024 20:24:41 GMT",
          "muted": true,
          "held": true,
          "heldaAtTime": "Fri, 12 Jul 2024 20:24:41 GMT”,
          "capabilities": {
            "mute": true,
            "endCall": true,
            "hold": true
          }
        }
      ]
     }
    ]
  }
);

    The following example shows how to set the idle state context.

    openFrameAPI.setICContext("idleState", {
  "capability": {
    "outBoundCall": true,
    "logOut": true 
  },
  "enableState": {
    "outBoundCall": true,
    "logOut": true
  },
  "dialpadInfoMessage": {
    "label": "Info Message Label",
    "value": "Info Message Value"
  },
  "currentInboundId": "1234"
});

    The following example shows how to set the search target list context.

    openFrameAPI.setICContext("searchTargetList",
  {
    "searchTargetList": [
      {
        "nowRecordTable": "interaction",
        "nowRecordId": "1234",
        "externalId": "5678",
        "participantID": "participant1",
        "targets": [
          {
            "type": "agent",
            "transferSubtypes": [
              {
                "id": "consult",
                "label": "Consult"
              },
              {
                "id": "blind",
                "label": "Blind"
              }
            ],
            "payload": {
              "list": [
                {
                  "name": "John Jason",
                  "id": "agent1Id",
                  "hasStats": "true",
                  "presence": "away",
                  "moreInfo": [
                    {
                      "label": "Skill",
                      "value": "10sec"
                    }
                  ]
                }
              ]
            }
          },
          {
            "type": "queue",
            "transferSubtypes": [
              {
                "id": "consult",
                "label": "Consult"
              },
              {
                "id": "blind",
                "label": "Blind"
              }
            ],
            "payload": {
              "list": [
                {
                  "name": "Product Support Queue",
                  "id": "queue1Id",
                  "hasStats": "true",
                  "moreInfo": [
                    {
                      "label": "Skill",
                      "value": "10sec"
                    },
                    {
                      "label": "Queue Skill",
                      "value": "German"
                    }
                  ]
                },
                {
                  "name": "Billing Queue",
                  "id": "queue2Id",
                  "hasStats": "true",
                  "moreInfo": [
                    {
                      "label": "Skill",
                      "value": "10sec"
                    }
                  ]
                }
              ]
            }
          }
        ],
        "customPayload": {}
      }
    ],
    "customPayload": {}
  });
    The following example suggests how to set callback context and related capabilities settings.
    openFrameAPI.setICContext('activeCall', callbackContext);

var callbackContext = {
  "activeCall": [
    {
      "nowRecordTable": "Customer interaction",
      "nowRecordId": "12345yhedfh534576u5",
      "externalId": "1234567890",
      "type": "callback",
      "currentParticipant": {
        "id": "agent1",
        "capabilities": {
          "initiateCall": "true",
          "closeCallback": "true",
          "transfer": "true",
          "cancelCallbackTransferEligible": "false",
          "callbackTransferStatus": ""
        }
      },
      "callbackContext": {
        "customerName": "Fred Luddy",
        "callbackNumbers": [
          "8665551234"
        ],
        "callAttemptedByAgent": "true",
        "closeInEndTime": "Mon, 05 Dec 2024 09:25:08 GMT",
        "dialInEndTime": ""
      }
    }
  ]
}

    The following example shows how to set resiliency call response details using the offerContext property.

    // Set offerContext
openFrameAPI.setICContext('offerContext', offerContext);

var offerContext = {
  "offerContext": [
    {
      "nowRecordTable": "interaction",
      "type": "phone",
      "externalId": "1234567890",
      "externalSegmentId": "12345yhedfh534576u5",
      "queueId": "10111ad087063250df52fe66cebb3520",
      "creationTime": "19-12-2025 11:23:45",
      "requesterId": "4085018550",
      "assignment": {
        "offeredOn": "Fri, 19-12-2025  13:07:59",
        "timeout": "4000",
        "allowedToDecline": true,
        "enableAutoAssign": true
      },
      "displayContent": {
        "title": "Phone",
        "displayContent1": "Abel Tuter",
        "displayContent2": "Priority - 4-Low",
        "displayContent3": "category - Product Issue"
      }
    }
  ]
};

    openFrameAPI - setIcons(Array icons)

    Defines icons in the OpenFrame header that are placed next to the close icon.

    Table 23. Parameters
    Name Type Description
    icons Array of objects A list of icon configurations, where each icon configuration is an object with key values imageURL, imageTitle, and any other needed context.

    Maximum size: Icons can be a maximum of 16x16 pixels. Larger images are automatically adjusted to this maximum.
    Table 24. Returns
    Type Description
    void 
    openFrameAPI.setIcons([{imageURL:'https://mydomian.com/image/mute.png',
imageTitle:'mute', id:101}, {imageURL:'https://mydomian.com/image/hold.png',
imageTitle:'hold', id:102}]);

    openFrameAPI - setPresenceIndicator(presence)

    Sets the presence indicator to display agent availability in a workspace.

    For more information on configuring OpenFrame, refer to Create an OpenFrame configuration

    Table 25. Parameters
    Name Type Description
    state String Presence state of the agent.

    Default states:

    • Available
    • Away
    • Offline

    You can also specify custom states.
    color String Presence indicator color on workspace.

    Supported colors:

    • red
    • orange
    • grey
    • green
    Table 26. Returns
    Type Description
    void 
    openframeAPI.setPresenceIndicator('Available', 'green');

    openFrameAPI - setSize(Number width, Number height)

    Sets the OpenFrame size.

    Table 27. Parameters
    Name Type Description
    width Number Should be greater than zero.
    height Number Should be greater than zero.
    Table 28. Returns
    Type Description
    void 
    openFrameAPI.setSize(300, 370);

    openFrameAPI - setSubtitle(String subTitle)

    Sets the OpenFrame subtitle.

    Table 29. Parameters
    Name Type Description
    subTitle String A string of 256 or fewer characters.
    Table 30. Returns
    Type Description
    void 
    openFrameAPI.setSubtitle('+18888888888');

    openFrameAPI - setTitle(String title)

    Sets the OpenFrame title.

    Table 31. Parameters
    Name Type Description
    title String A string of 256 or fewer characters.
    Table 32. Returns
    Type Description
    void 
    openFrameAPI.setTitle('Incoming Call');

    openFrameAPI - setTitleIcon(Object icon)

    Sets the OpenFrame's title icon.

    Table 33. Parameters
    Name Type Description
    icon Object Object of key value pairs. Keys include imageURL, imageTitle, and any other context needed.

    Maximum size: Icons can be a maximum of 16x16 pixels. Larger images are automatically adjusted to this maximum.
    Table 34. Returns
    Type Description
    void 
    openFrameAPI.setTitleIcon({imageURL:'/my/image/path.png', imageTitle:'mute', id:101});
    openFrameAPI.setTitleIcon({imageURL:'https://mydomian.com/image/path.png',
imageTitle:'mute', id:101});

    openFrameAPI - setWidth(width)

    Sets the OpenFrame width.

    Table 35. Parameters
    Name Type Description
    Width Number Width in pixels
    Table 36. Returns
    Type Description
    void 
    openFrameAPI.setWidth(100);

    openFrameAPI - show()

    Makes the OpenFrame visible in the TopFrame.

    Table 37. Parameters
    Name Type Description
    None
    Table 38. Returns
    Type Description
    void 
    openFrameAPI.show()

    openFrameAPI - subscribe(openFrameAPIEVENT event, function eventCallback)

    Subscribes to a specified event.

    Table 39. Parameters
    Name Type Description
    event openFrameAPIEVENT The event to subscribe to:
    • interaction_control_action: Receives the interaction lifecycle event or calls control updates from OpenFrame and updates the UI accordingly. Call control update examples include call initiated, muted, held, ended, and transfer requests.
    • openframe_agent_off_interaction: Indicates the presence of an agent on chat as off or available.
    • openframe_awa_agent_presence: In Advanced Work Assignment (AWA), this event occurs when there's any change in the agent presence state. Computer Telephony Integration (CTI) developers can subscribe to this event to receive presence state changes.
    • openframe_awa_client_offer: Occurs when an offer or transfer is made on a resiliency-related offer.
    • openframe_awa_workitem_accepted: Occurs when a work item is accepted by an agent.
    • openframe_awa_workitem_offered: Occurs when a work item is offered to an agent.
    • openframe_awa_workitem_rejected: Occurs when a work item is rejected by an agent.
    • openframe_before_destroy: Occurs before the TopFrame is unloaded.
    • openframe_collapse: Occurs when the collapse icon is selected on the OpenFrame header.
    • openframe_communication: Application-specific and can be customized.
    • openframe_communication_failure: Occurs when communication to TopFrame fails.
    • openframe_expand: Occurs when the expand icon is selected on the OpenFrame header.
    • openframe_heart_beat: Occurs when the user session is extended or logged out.
    • openframe_header_icon_clicked: Deprecated. Use openframe_icon_clicked or openframe_title_icon_clicked instead.
    • openframe_hidden: Occurs when the OpenFrame is hidden.
    • openframe_icon_clicked: Occurs when any icon other than the close icon is selected on the OpenFrame footer. The callback receives the icon object as a parameter.
    • openframe_shown: Occurs when the OpenFrame is shown.
    • openframe_title_icon_clicked: Occurs when the title icon is selected on the OpenFrame. The callback receives the titleIcon object as a parameter.
    • openframe_wrap_up_submitted: Occurs when the wrap up periods ends on the wrap-up modeless dialog. The event is triggered only when the wrap up is external.
    eventCallback function Function to call when the specified event occurs.
    Table 40. Returns
    Type Description
    results Most event subscriptions have no return values. The event subscriptions that do return values are described in the following table entries.
    openframe_awa_agent_presence In AWA, the openframe_awa_agent_presence event returns the presence object:
    "presence":{
  "available": Boolean,
  "channels":[
    {
      "available": Boolean,
      "name": "String",
      "restrict_update": Boolean,
      "sys_id": "String"
    }
  ],
  "name": "String",
  "sys_id": "String"
}
    presence: Information about an agent's current presence state and channel.
    • presence.available: Flag that indicates whether the agent is available.
    • presence.channels: List of objects that describe the available channels of communication with the agent.
      • presence.channels.available: Flag that indicates whether the channel is available.
      • presence.channels.name: Channel name, such as Chat or Phone.
      • presence.channels.restrict_update: Flag that indicates whether the user can restrict updates.
      • presence.channels.sys_id: Channel sys_id.
    • presence.name: Name of the agent's presence state.
    • presence.sys_id: Presence state sys_id.
    openframe_awa_workitem_accepted and openframe_awa_workitem_offered In AWA, the openframe_awa_workitem_accepted and openframe_awa_workitem_offered events return the workItem object:
    "workItem": {
  "document": {
    "sys_id": "String",
    "table": "String"
  },
  "isAutoAccepted": Boolean,
  "isQueueTransferred": Boolean,
  "previousWorkItem": "String",
  "serviceChannel": {
    "name": "String",
    "sys_id": "String"
  },
  "size": Number,
  "sys_id": "String"
}

    workItem: Information about the work item that is associated with the event.

    • workItem.document: List of documents associated with the work item task.
      • workItem.document.sys_id: Sys_id of the document assigned to the work item task.
      • workItem.document.table: Name of the document table assigned to the task.
    • workItem.isAutoAccepted: Flag that indicates whether the work item was automatically accepted by the system. Set to true if the work item was auto-accepted.
    • workItem.isQueueTransferred: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't. For more information on queue transfers, see Transfer a chat to another queue.
    • workItem.previousWorkItem: Sys_id of the previous work item for the same document ID. For the non-transfer work items this value is empty.
    • workItem.serviceChannel: List of service channels associated with the work item task.
      • workItem.serviceChannel.name: Name of the service channel, such as Chat or Phone.
      • workItem.serviceChannel.sys_id: Sys_id of the service channel.
    • workItem.size: Agent's capacity used when this work item is assigned to the agent.
    • workItem.sys_id: Sys_id of the work item that was accepted or offered.
    openframe_awa_workitem_rejected In AWA, the openframe_awa_workitem_rejected event returns the workItem object:
    "workItem": {
  "document": {
    "sys_id": "String",
    "table": "String"
  },
  "isQueueTransferred": Boolean,
  "previousWorkItem": "String",
  "rejection": {
    "reason": "String",
    "sys_id": "String"
  },
  "serviceChannel": {
    "name": "String",
    "sys_id": "String"
  },
  "size": Number,
  "sys_id": "String"
}

    workItem: Information about the work item that is associated with the event.

    • workItem.document: List of documents associated with the work item task.
      • workItem.document.sys_id: Sys_id of the document assigned to the work item task.
      • workItem.document.table: Name of the document table assigned to the task.
    • workItem.isQueueTransferred: Flag that indicates whether the work item is queue transferred. Set to true if the work item is queue transferred, false if it isn't. For more information on queue transfers, see Transfer a chat to another queue.
    • workItem.previousWorkItem: Sys_id of the previous work item for the same document ID. For the non-transfer work items this value is empty.
    • workItem.rejection: List of reasons for the rejection of the work item.
      • workItem.rejection.reason: Name of the reason for rejecting the work items.
      • workItem.rejection.sys_id: Sys_id of the rejection reason.

        Table: Reject Reasons [awa_reject_reason]

    • workItem.serviceChannel: List of service channels associated with the work item task.
      • workItem.serviceChannel.name: Name of the service channel, such as Chat or Phone.
      • workItem.serviceChannel.sys_id: Sys_id of the service channel.
    • workItem.size: Agent's capacity used when this work item is assigned to the agent.
    • workItem.sys_id: Sys_id of the work item that was accepted or offered.
    openframe_heart_beat The openframe_heart_beat event returns the following object:
    {
  "lastUiActivity": "String",
  "sessionLoggedIn": Boolean
}
    • lastUiActivity: Optional. Time stamp of last UI activity that extended the user session.
    • sessionLoggedIn Flag that indicates whether the user is logged in.
      • true: User is logged in.
      • false: User isn't logged in.
    openframe_wrap_up_submitted The openframe_wrap_up_submitted event returns the following object:
    { 
  "wrapUp": {
    "external": Boolean,
    "externalSegmentId": "String", 
    "recordId": "String",
    "recordTable": "String",
    "wrapUpCode": "String",
    "wrapUpNotes": "String",
    "wrapUpSegmentId": "String"
  }
}
    • external: Flag that indicates whether the wrap up is handled internally by the ServiceNow instance or managed outside of the ServiceNow instance by some other call system.
      • true: Wrap up is handled by an external call system.
      • false: Wrap up is handled by the ServiceNow instance.
    • externalSegmentId: Unique identifier of the external data object that triggered the external wrap up.
    • recordId: Sys_id of the interaction record that is undergoing wrap up.
    • recordTable: Name of the table containing the record. Always set as “interaction".
    • wrapUpCode: Code selected by the user during the wrap up that indicates how the interaction was resolved.
    • wrapUpNotes: Free-form text entered by the user during wrap up that describes how the interaction was resolved.
    • wrapUpSegmentId: Sys_id of the interaction wrap up segment record associated with the interaction. Located in the Wrap Up Segment [interaction_wrap_up_segment] table. Contains the wrap up data.

    The following code example shows how to call this method for an openframe_awa_agent_presence event.

    function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_agent_presence, handleIconClick);

    Output:

    // Sample presence object output
// openframe_awa_agent_presence event only

{
  "result":{
    "presence":{
      "name":"Available",
      "sys_id":"27f675e3739713004a905ee515f6a7c3",
      "available":true,
      "channels":[
        {
          "name":"Chat",
          "available":true,
          "sys_id":"36f675e4239713124a905fe515f6a832",
          "restrict_update":false
        },
        {
          "name":"Phone",
          "available":true,
          "sys_id":"9378a530a1820610f809018efd9bc01e",
          "restrict_update":false
        }
      ]
    }
  }
}

    The following code example shows how to call this method for an openframe_awa_workitem_accepted event.

    function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_workitem_accepted, handleIconClick);

    Output:

    // Sample workItem object output
// openframe_awa_workitem_accepted event only
{
  "result": {
    "workItem": {
      "sys_id": "14c86c40a1650610f87701807d9bc0be",
      "size": 1,
      "serviceChannel": {
        "name": "Chat",
        "sys_id": "27f675e3739713004a905ee515f6a7c3"
      },
      "document": {
        "sys_id": "aa582040a1650610f87701807d9bc076",
        "table": "interaction"
      },
      "previousWorkItem": "7c78a440a1650610f87701807d9bc02b",
      "isQueueTransferred": true,
      "isAutoAccepted": true
    }
  }
}

    The following code example shows how to call this method for an openframe_awa_workitem_rejected event.

    function handleIconClick(context) {
console.log("Icon was clicked", context);
}
openFrameAPI.subscribe(openFrameAPI.events.openframe_awa_workitem_rejected, handleIconClick);

    Output:

    // Sample workItem object output
// openframe_awa_workitem_rejected event only
{
  "payload": {
    "workItem": {
      "sys_id": "2c3bdc4824250610f8775e73b116f8de",
      "size": "1",
      "serviceChannel": {
        "name": "Chat",
        "sysID": "27f675e3739713004a905ee515f6a7c3"
      },
      "document": {
        "sys_id": "cf0a180824250610f8775e73b116f80c",
        "table": "interaction"
      },
      "rejection": {
        "reason": "Busy",
        "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
      },
      "previousWorkItem": "831b9c4824250610f8775e73b116f841",
      "isQueueTransferred": true
    }
  }
}

    The following example shows how to subscribe to the interaction_control_action event.

    openFrameAPI.subscribe("interaction_control_action", function(action) {
    // Can perform the action based on the name
    if (action.name == "mute") {
        mute();
        openFrameAPI.setICContext("activeCall", context); // Update context representing the change
    } else if (action.name == "getSearchTarget") {
        action.payload.searchType == "queue" ? fetchQueueTransferList(action.payload.searchTerm) : fetchAgentTransferList(action.payload.searchTerm);
        openFrameAPI.setICContext("searchTargetList", context); // Call context will have the transfer list
    } else if (action.name == "logout") {
        logout();
        openFrameAPI.showIframe(); // Show iframe api
    }
});

    openFrameAPI - toastMessage(String message, String type, Number duration)

    Displays an alert message.

    Table 41. Parameters
    Name Type Description
    message String Message to display in the alert.
    type String Type of message.
    Possible values:
    • info
    • warning
    • error
    duration Number Optional. Duration to display the message before it is auto-dismissed.

    Units: Milliseconds

    Default: The message is displayed until it is manually closed.
    Table 42. Returns
    Type Description
    None

    This example displays info, warning, and error messages.

    openFrameAPI.toastMessage("Testing info message", "info", 10000); //display for 10 seconds
openFrameAPI.toastMessage("Testing warning message", "warning"); //display until manually closed
openFrameAPI.toastMessage("Testing error message", "error");

    openFrameAPI - version()

    Returns the OpenFrame API version.

    Table 43. Parameters
    Name Type Description
    None
    Table 44. Returns
    Type Description
    String The OpenFrame API version 
    var version = openFrameAPI.version();

console.log("API version " + version);