Api Console
Api Console
Guide
Version 42.0, Spring ’18
@salesforcedocs
Last updated: April 18, 2018
© Copyright 2000–2018 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
getEnclosingPrimaryTabId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
getEnclosingPrimaryTabObjectId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
getEnclosingTabId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
getFocusedPrimaryTabId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
getFocusedPrimaryTabObjectId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
getFocusedSubtabId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
getFocusedSubtabObjectId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
getPageInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
getPrimaryTabIds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
getSubtabIds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
getTabLink() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
isInConsole() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
onEnclosingTabRefresh() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
onFocusedSubtab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
onTabSave() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
openConsoleUrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
openPrimaryTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
openSubtab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
openSubtabByPrimaryTabName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
refreshPrimaryTabById() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
refreshPrimaryTabByName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
refreshSubtabById() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
refreshSubtabByNameAndPrimaryTabId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
refreshSubtabByNameAndPrimaryTabName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
reopenLastClosedTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
resetSessionTimeOut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
setTabUnsavedChanges() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
setTabIcon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
setTabLink() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
setTabStyle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
setTabTextStyle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
setTabTitle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Methods for Navigation Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
focusNavigationTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
getNavigationTabs() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
getSelectedNavigationTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
refreshNavigationTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
setSelectedNavigationTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Methods for Computer-Telephony Integration (CTI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
fireOnCallBegin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
fireOnCallEnd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
fireOnCallLogSaved() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
getCallAttachedData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
getCallObjectIds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Contents
onCallBegin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
onCallEnd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
onCallLogSaved() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
onSendCTIMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
sendCTIMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
setCallAttachedData() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
setCallObjectIds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Methods for Application-Level Custom Console Components . . . . . . . . . . . . . . . . . . . . . . . 100
addToBrowserTitleQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
blinkCustomConsoleComponentButtonText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
isCustomConsoleComponentPoppedOut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
isCustomConsoleComponentWindowHidden() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
isCustomConsoleComponentHidden() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
isInCustomConsoleComponent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
onCustomConsoleComponentButtonClicked() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
onFocusedPrimaryTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
removeFromBrowserTitleQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
runSelectedMacro() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
scrollCustomConsoleComponentButtonText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
selectMacro() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
setCustomConsoleComponentButtonIconUrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
setCustomConsoleComponentButtonStyle() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
setCustomConsoleComponentButtonText() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
setCustomConsoleComponentHeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
setCustomConsoleComponentVisible() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
setCustomConsoleComponentWidth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
setCustomConsoleComponentPopoutable() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
setCustomConsoleComponentWindowVisible() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
setSidebarVisible() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Methods for Push Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
addPushNotificationListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
removePushNotificationListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Methods for Console Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
addEventListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
fireEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
removeEventListener() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Methods for Live Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
acceptChat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
cancelFileTransferByAgent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
declineChat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
endChat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
getAgentInput() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
getAgentState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
getChatLog() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Contents
getChatRequests() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
getDetailsByChatKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
getDetailsByPrimaryTabId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
getEngagedChats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
getMaxCapacity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
initFileTransfer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
onAgentSend() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
onAgentStateChanged() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
onChatCanceled() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
onChatCriticalWaitState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
onChatDeclined() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
onChatEnded() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
onChatRequested() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
onChatStarted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
onChatTransferredOut() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
onCurrentCapacityChanged() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
onCustomEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
onFileTransferCompleted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
onNewMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
onTypingUpdate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
sendCustomEvent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
sendMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
setAgentInput() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
setAgentState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Methods for Live Agent Chat Visitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Methods for Omni-Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
acceptAgentWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
closeAgentWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
declineAgentWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
getAgentWorks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
getAgentWorkload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
getServicePresenceStatusChannels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
getServicePresenceStatusId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
setServicePresenceStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Methods for Omni-Channel Console Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
getFocusedTabInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
getTabInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
getTabURL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
isConsoleNavigation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
isSubtab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
openSubtab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
openTab() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
setTabHighlighted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
setTabIcon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
setTabLabel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Methods for the Utility Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
getAllUtilityInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
getEnclosingUtilityId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
getUtilityInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
minimizeUtility() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
openUtility() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
setPanelHeaderIcon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
setPanelHeaderLabel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
setPanelHeight() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
setPanelWidth() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
setUtilityHighlighted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
setUtilityIcon() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
setUtilityLabel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
toggleModalMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Methods for Omni-Channel (Beta) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
acceptAgentWork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
closeAgentWork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
declineAgentWork() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
getAgentWorks() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
getAgentWorkload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
getServicePresenceStatusChannels() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
getServicePresenceStatusId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
login() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
logout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
setServicePresenceStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
lightning:omniChannelLoginSuccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
lightning:omniChannelStatusChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
lightning:omniChannelLogout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
lightning:omniChannelWorkAssigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
lightning:omniChannelWorkAccepted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
lightning:omniChannelWorkDeclined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
lightning:omniChannelWorkClosed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
lightning:omniChannelWorkloadChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
CHAPTER 1 What Is the Console Developer Guide?
The Lightning Console JavaScript API and the Salesforce Console Integration Toolkit both interact with Salesforce console apps. This
guide provides reference material for both.
Starting with API version 42.0 of the Salesforce Console Integration Toolkit, many of the methods used in existing Visualforce pages and
third-party web tabs now work in Lightning Experience. Just point to the latest version of the toolkit script in your Visualforce pages or
third-party web tabs. Third-party content must be whitelisted in the CSP Trusted Sites list to be used in Lightning Experience. See
Salesforce Console Integration Toolkit Methods Supported in Lightning Console JavaScript API for a list of supported methods.
To use this guide, it helps if you have a basic familiarity with:
• JavaScript
• Visualforce
• Web services
• Software development
• Salesforce console
• Lightning
• Lightning console apps
SEE ALSO:
Why Your UI Matters
Lightning Console JavaScript API for Lightning Experience
Salesforce Console Integration Toolkit for Salesforce Classic
1
CHAPTER 2 Why Your UI Matters
The user interface of your org dictates which development tools you can use with the Salesforce console.
2
Why Your UI Matters Console API Method Parity—What’s Different Between
Lightning Experience and Salesforce Classic?
IN THIS SECTION:
Console API Method Parity—What’s Different Between Lightning Experience and Salesforce Classic?
The Lightning Console JavaScript API provides methods similar to those methods in the Salesforce Console Integration Toolkit.
SEE ALSO:
Lightning Console JavaScript API for Lightning Experience
Salesforce Console Integration Toolkit for Salesforce Classic
Important: Only Salesforce Console Integration Toolkit methods with a Lightning Console JavaScript API or workaround appear
in this table. Methods without alternatives or workarounds are not listed.
focusPrimaryTabById() focusTab()
focusSubtabById() focusTab()
getEnclosingPrimaryTabObjectId() Use getEnclosingTabId() to get the tab ID. Then, use the tab ID to call
getTabInfo(tabId), which includes the object ID in the response payload (if
applicable).
getFocusedPrimaryTabId() getFocusedTabInfo()
getFocusedPrimaryTabObjectId() getFocusedTabInfo()
getFocusedSubtabId() getFocusedTabInfo()
3
Why Your UI Matters Console API Method Parity—What’s Different Between
Lightning Experience and Salesforce Classic?
Salesforce Console Integration Toolkit Lightning Console JavaScript API Method (Lightning Experience)
(Salesforce Classic)
getPageInfo() getTabInfo()
getTabLink() getTabURL()
onFocusedSubtab() lightning:tabFocused
openPrimaryTab() openTab()
openSubtab() openSubtab()
setTabIcon() setTabIcon()
setTabTitle() setTabLabel()
Salesforce Console Integration Toolkit Lightning Console JavaScript API Method (Lightning Experience)
(Salesforce Classic)
focusNavigationTab() force:navigateToObjectHome
refreshNavigationTab() force:navigateToObjectHome
setSelectedNavigationTab() force:navigateToObjectHome
4
Why Your UI Matters Console API Method Parity—What’s Different Between
Lightning Experience and Salesforce Classic?
isCustomConsoleComponentWindowHidden() getUtilityInfo()
onFocusedPrimaryTab() lightning:tabFocused
setCustomConsoleComponentButtonIconUrl() setUtilityIcon()
setPanelHeaderIcon()
setCustomConsoleComponentButtonStyle() setUtilityHighlighted
setCustomConsoleComponentButtonText() setUtilityLabel
setCustomConsoleComponentHeight() setPanelHeight()
setCustomConsoleComponentVisible() openUtility()
minimizeUtility()
setCustomConsoleComponentWidth() setPanelWidth()
5
CHAPTER 3 Lightning Console JavaScript API for Lightning
Experience
Lightning console apps allow users to quickly find the information they need, and make edits while
EDITIONS
viewing multiple records on one screen. The Lightning Console JavaScript API gives you
programmatic access to Lightning console apps, so you can fully integrate Lightning console apps Available in: Lightning
with the Lightning framework and extend them to meet your business needs. Experience
The Lightning Console JavaScript API includes two libraries, the utility bar API and the workspace
Available in: Essentials,
API. The utility bar API provides methods that can be used from Lightning components in the utility
Professional, Enterprise,
bar to open, resize, or minimize a utility. The workspace API provides methods for opening, closing, Performance, Unlimited,
and getting information about workspace tabs and subtabs. The utility bar API can be used in and Developer Editions
Lightning apps with standard or console navigation, while the workspace API can be used in
Lightning console apps are
Lightning console apps only.
available for an extra cost to
For a full list of methods in each API, see the reference section of this guide. users with Salesforce
Platform user licenses for
IN THIS SECTION: certain products. Some
restrictions apply. For pricing
Get to Know the Lightning Console details, contact your
Lightning console apps are similar to the console in Salesforce Classic. Salesforce account
Get to Know the Utility Bar executive.
The utility bar API includes a set of methods for working with utilities and the utility bar.
Lightning Console JavaScript API Syntax
Use Lightning Console JavaScript API methods in the JavaScript controller of a Lightning component.
Salesforce Console Integration Toolkit Methods Supported in Lightning Console JavaScript API
This table lists the Salesforce Console Integration Toolkit methods that you can use in Lightning Console JavaScript API starting with
API version 42.0.
Using Events in Lightning Console Apps
The Lightning framework uses event-driven programming, which allows you to create handlers to respond to interface events as
they occur. The Lightning Console JavaScript API provides several events specific to Lightning console apps.
Using Page Context in the Utility Bar API
In both Lightning console apps and standard navigation apps, utilities can respond to the context of the current page. Set
implements="force:hasRecordId" on a Lightning component used in the utility bar to access the recordId of the
record a user is viewing.
6
Lightning Console JavaScript API for Lightning Experience Get to Know the Lightning Console
Debugging
Use your browser’s console and JavaScript error messages generated within Salesforce to debug Lightning pages built with the
Lightning Console JavaScript API. The methods in the Lightning Console JavaScript APIs are asynchronous and return their results
using promises.
SEE ALSO:
Methods for Lightning Experience
To select objects, use the item menu in the navigation bar (1). Records selected from the table list view or split view open as workspace
tabs (2). When you click related records from the workspace tab, those records open as subtabs (3). To keep you efficient and productive,
split view lets you work with a list view while still working on other records (4). You can close and open split view whenever you
want—click the arrow on the split view pane (5). You can also click anywhere in the vertical divider between split view and record page.
You can view and update a record using the details area (6) and the feed (7). Keep in mind that page layouts can be different for each
type of record. Finally, utilities let you access common processes and tools, like History and Notes (8).
In this example, there are two workspace tabs open—Acme and Global Media. Under the Global Media workspace tab, there are three
subtabs open—the contact record for Jon Amos, a related case, and a related opportunity. In the History utility, you can easily access
your recently opened records.
7
Lightning Console JavaScript API for Lightning Experience Get to Know the Utility Bar
8
Lightning Console JavaScript API for Lightning Experience Lightning Console JavaScript API Syntax
SEE ALSO:
Salesforce Help: Customize Your Lightning Console App with Utilities
This component implements flexipage:availableForAllPageTypes so that it can be accessed in the Lightning App
Builder.
This is the component’s JavaScript controller:
({
openUtilityBar : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.openUtility();
}
9
Lightning Console JavaScript API for Lightning Experience JavaScript Promises
The controller has two functions, each of which uses an API method. To use a method in a controller, use component.find with
the aura:id you gave to the lightning:workspaceAPI or lightning:utilityBarAPI.
Methods in the Workspace API and the Utility Bar API take a JSON object as an argument. The values included in the object depend on
the method. openTab, for example, takes an object that includes the url and focus (whether the new tab has focus). Check the
reference section of this guide before using a method so that you know which arguments to pass to it.
IN THIS SECTION:
JavaScript Promises
Methods in the Lightning Console JavaScript API return results using promises.
Error Handling with Promises
Promises can simplify code that handles the success or failure of asynchronous calls. To use error handling with promises, use the
catch() method on the promise that is returned from calling an API method.
JavaScript Promises
Methods in the Lightning Console JavaScript API return results using promises.
This example uses the Workspace API’s openTab() function to get the tab ID of the focused tab. Then the function calls focusTab()
with the tabId returned by the openTab() method.
({
focusNewTab : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.openTab({
url: '#/sObject/001R0000003HgssIAC/view',
label: 'Global Media'
}).then(function(response) {
workspaceAPI.focusTab({tabId : response});
})
.catch(function(error) {
console.log(error);
});
}
})
10
Lightning Console JavaScript API for Lightning Experience Salesforce Console Integration Toolkit Methods Supported
in Lightning Console JavaScript API
Important: Only API versions 42.0 and above of the Salesforce Console Integration Toolkit are supported in the Lightning Console
JavaScript API.
Salesforce Console Integration Toolkit methods that aren’t supported in Lightning Experience result in a failure error message.
disableTabClose()
focusPrimaryTabById()
focusPrimaryTabByName()
focusSidebarComponent()
focusSubtabById()
focusSubtabByNameAndPrimaryTabId()
focusSubtabByNameAndPrimaryTabName()
generateConsoleUrl()
getEnclosingPrimaryTabId()
getEnclosingTabId()
getFocusedPrimaryTabId()
getFocusedPrimaryTabObjectId()
getFocusedSubtabId()
getFocusedSubtabObjectId()
11
Lightning Console JavaScript API for Lightning Experience Salesforce Console Integration Toolkit Methods Supported
in Lightning Console JavaScript API
getPrimaryTabIds()
getSubtabIds()
isInConsole()
onEnclosingTabRefresh()
onFocusedPrimaryTab()
onFocusedSubtab()
onTabSave()
openConsoleUrl()
openSubtabByPrimaryTabName()
refreshPrimaryTabById()
refreshPrimaryTabByName()
refreshSubtabById()
12
Lightning Console JavaScript API for Lightning Experience Salesforce Console Integration Toolkit Methods Supported
in Lightning Console JavaScript API
refreshSubtabByNameAndPrimaryTabName()
reopenLastClosedTab()
resetSessionTimeOut()
setTabUnsavedChanges()
setTabIcon() See notes Only Salesforce Lightning Design System icons are
supported for iconUrl. URLs and custom icons aren’t
supported.
Sample supported values:
• sforce.console.setTabIcon(“standard:email”)
• sforce.console.setTabIcon(“action:new”)
• sforce.console.setTabIcon(“custom:custom1”)
setTabLink()
setTabStyle()
setTabTextStyle()
setTabTitle()
blinkCustomConsoleComponentButtonText()
isCustomConsoleComponentPoppedOut()
isCustomConsoleComponentHidden()
isInCustomConsoleComponent()
onCustomConsoleComponentButtonClicked()
onFocusedPrimaryTab()
removeFromBrowserTitleQueue()
runSelectedMacro()
13
Lightning Console JavaScript API for Lightning Experience Salesforce Console Integration Toolkit Methods Supported
in Lightning Console JavaScript API
selectMacro()
setCustomConsoleComponentButtonIconUrl() See notes In Lightning Console, URL values for icons aren’t supported
in utility bar utilities. Only Salesforce Lightning Design
System are supported.
Sample supported iconUrl values:
• setCustomConsoleComponentButtonIconUrl("clock");
• setCustomConsoleComponentButtonIconUrl("utility:clock");
setCustomConsoleComponentButtonStyle()
setCustomConsoleComponentButtonText()
setCustomConsoleComponentHeight()
setCustomConsoleComponentVisible()
setCustomConsoleComponentWidth()
setCustomConsoleComponentPopoutable()
setCustomConsoleComponentWindowVisible()
setSidebarVisible()
getNavigationTabs()
getSelectedNavigationTab()
refreshNavigationTab()
setSelectedNavigationTab()
14
Lightning Console JavaScript API for Lightning Experience Using Events in Lightning Console Apps
removeEventListener()
Let’s look at a more fleshed out example. The following component uses the lightning:tabClosed event.
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<aura:handler event="lightning:tabClosed" action="{! c.onTabClosed }"/>
</aura:component>
When a tab is closed, the event handler calls onTabClosed in the component’s controller, which logs the tabId of the closed tab.
({
onTabClosed : function(component, event, helper) {
var tabId = event.getParam("tabId");
alert(“Tab with tabId of “ + tabId + “ was just closed.”);
}
})
15
Lightning Console JavaScript API for Lightning Experience Using Page Context in the Utility Bar API
You can use Lightning console events with the Workspace API and Utility Bar API to customize your users’ experience. You can, for
example, give a tab focus when it’s refreshed, or notify the user with a modal dialogue when a tab is replaced.
SEE ALSO:
Events for Lightning Experience
Trailhead: Connect Components with Events
Lightning Components Developer Guide : Communicating with Events
The component’s controller listens for changes to the recordId, and prints the new recordId to the developer console upon a
change.
({
onRecordIdChange : function(component, event, helper) {
var newRecordId = component.get("v.recordId");
console.log(newRecordId);
}
})
This image shows what the component looks like in the utility bar of a Lightning console app.
16
Lightning Console JavaScript API for Lightning Experience Debugging
Debugging
Use your browser’s console and JavaScript error messages generated within Salesforce to debug Lightning pages built with the Lightning
Console JavaScript API. The methods in the Lightning Console JavaScript APIs are asynchronous and return their results using promises.
To print messages to your browser’s console, use console.log() in your component controller code.
Salesforce also displays JavaScript errors at runtime, which provide the stack trace when there’s a bug.
17
CHAPTER 4 Salesforce Console Integration Toolkit for Salesforce
Classic
The Salesforce Console Integration Toolkit is a browser-based JavaScript API that provides you with
EDITIONS
programmatic access to the console in Salesforce Classic. The Salesforce Console Integration Toolkit
uses browsers as clients to display pages as tabs in the console. For example, the toolkit lets you Available in: Salesforce
integrate third-party systems with the console, opening up an external application in the same Classic
window, in a tab.
Available in: Professional,
This guide explains how to use the Salesforce Console Integration Toolkit in JavaScript to embed
Enterprise, Performance,
API calls and processes. The toolkit is available for use with third-party domains, such as Unlimited, and Developer
www.yourdomain.com; however, the examples in this guide are in Visualforce. The functionality Editions
it describes is available to your organization if you have:
• Enterprise, Unlimited, Performance, or Developer Edition with the Service Cloud
• Salesforce console
The Salesforce Console Integration Toolkit supports any browser that the Salesforce console supports.
Note: To enable the toolkit for third-party domains, add the domains to the whitelist of the Salesforce console.
IN THIS SECTION:
When to Use the Salesforce Console Integration Toolkit
The Salesforce Console Integration Toolkit helps advanced administrators and developers implement custom functionality for the
Salesforce console. For example, you can use the Salesforce Console Integration Toolkit to display Visualforce pages or third-party
content as tabs in the Salesforce console. The Salesforce Console Integration Toolkit is an API that uses browsers as clients to display
pages in the console.
Salesforce Console Integration Toolkit Support Policy
The current release of the Salesforce Console Integration Toolkit is the only version that receives enhancements.
Sample Visualforce Page Using the Salesforce Console Integration Toolkit
Each implementation of Salesforce Console Integration Toolkit can look different. This example shows how to change the Salesforce
console user interface using the Salesforce Console Integration Toolkit.
Working with the Salesforce Console Integration Toolkit
You can use Salesforce Console Integration Toolkit to streamline a business process.
SEE ALSO:
Salesforce Help: Whitelist Domains for a Salesforce Console in Salesforce Classic
Salesforce Help: Supported Browsers
Methods for Salesforce Classic
18
Salesforce Console Integration Toolkit for Salesforce Classic When to Use the Salesforce Console Integration Toolkit
Feature Description
SOAP API Use standard SOAP API calls if you want to add functionality to a composite application that processes
only one type of record at a time and does not require any transactional control (such as setting a
Savepoint or rolling back changes).
For more information, see the SOAP API Developer Guide.
Visualforce Visualforce consists of a tag-based markup language that gives developers a more powerful way of
building applications and customizing the Salesforce user interface. With Visualforce you can:
• Build wizards and other multistep processes.
• Create your own custom flow control through an application.
• Define navigation patterns and data-specific rules for optimal, efficient application interaction.
For more information, see the Visualforce Developer's Guide.
19
Salesforce Console Integration Toolkit for Salesforce Classic Backward Compatibility
IN THIS SECTION:
Backward Compatibility
Salesforce strives to make backward compatibility easy when using the Salesforce Console Integration Toolkit.
End-of-Life
Salesforce is committed to supporting each Salesforce Console Integration Toolkit version for a minimum of three years from the
date of its first release. To improve the quality and performance of the Salesforce Console Integration Toolkit, versions that are more
than three years old may not be supported.
Backward Compatibility
Salesforce strives to make backward compatibility easy when using the Salesforce Console Integration Toolkit.
Each new Salesforce release consists of two components:
• A new release of platform software that resides on Salesforce systems
• A new version of the API
The Salesforce Console Integration Toolkit matches the API version for any given release. For example, if the current version of SOAP API
is 42.0, then there’s also a version 42.0 of Salesforce Console Integration Toolkit.
We maintain support for each Salesforce Console Integration Toolkit version across releases of the platform. The Salesforce Console
Integration Toolkit is backward compatible in that an application created to work with a given Salesforce Console Integration Toolkit
version will continue to work with that same Salesforce Console Integration Toolkit version in future platform releases.
Salesforce doesn't guarantee that an application written against one Salesforce Console Integration Toolkit version will work with future
Salesforce Console Integration Toolkit versions: Changes in method signatures and data representations are often required as we continue
to enhance the Salesforce Console Integration Toolkit. However, we strive to keep the Salesforce Console Integration Toolkit consistent
from version to version with minimal changes required to port applications to newer Salesforce Console Integration Toolkit versions.
For example, an application written using Salesforce Console Integration Toolkit version 37.0, which shipped with the Summer ’16 release,
will continue to work with Salesforce Console Integration Toolkit version 37.0 on the Winter ’17 release and on future releases. However,
that same application may not work with Salesforce Console Integration Toolkit version 38.0 without modifications to the application.
End-of-Life
Salesforce is committed to supporting each Salesforce Console Integration Toolkit version for a minimum of three years from the date
of its first release. To improve the quality and performance of the Salesforce Console Integration Toolkit, versions that are more than
three years old may not be supported.
When a Salesforce Console Integration Toolkit version is scheduled to be unsupported, an advance end-of-life notice will be given at
least one year before support for the version ends. Salesforce will directly notify customers using Salesforce Console Integration Toolkit
versions scheduled for end of life.
20
Salesforce Console Integration Toolkit for Salesforce Classic Sample Visualforce Page Using the Salesforce Console
Integration Toolkit
This code demonstrates various functions of the Salesforce Console Integration Toolkit:
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function openPrimaryTab() {
sforce.console.openPrimaryTab(undefined,
'http://www.example.com', true, 'example');
}
//The callback function that openSubtab will call once it has the ID for its
primary tab
var callOpenSubtab=function callOpenSubtab(result) {
sforce.console.openSubtab(result.id,
'http://www.example.com', true, 'example');
};
function openSubtab() {
sforce.console.getEnclosingPrimaryTabId(callOpenSubtab);
}
//The callback function that closeTab will call once it has the ID for its tab
var callCloseTab= function callCloseTab(result) {
sforce.console.closeTab(result.id);
}
function closeTab() {
sforce.console.getEnclosingTabId(callCloseTab);
}
</script>
</apex:page>
3. Create a custom link for cases that uses your Visualforce page.
4. Edit the page layout for cases and add your custom link.
5. Add any domains to the console’s whitelist.
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Here’s what your sample Visualforce page looks like in the console:
21
Salesforce Console Integration Toolkit for Salesforce Classic Working with the Salesforce Console Integration Toolkit
SEE ALSO:
Visualforce Developer Guide
Salesforce Help: Edit Page Layouts for Standard Objects
Salesforce Help: Whitelist Domains for a Salesforce Console in Salesforce Classic
IN THIS SECTION:
Connecting to the Toolkit
The first portion of any JavaScript code that uses the Salesforce Console Integration Toolkit must make the toolkit available to the
JavaScript code. The syntax for this is different depending on whether you are embedding JavaScript in a Visualforce page, or a
third-party domain.
Asynchronous Calls with the Salesforce Console Integration Toolkit
The Salesforce Console Integration Toolkit lets you issue asynchronous calls. Asynchronous calls allow the client-side process to
continue instead of waiting for a callback from the server. To issue an asynchronous call, you must include an additional parameter
with the API call, which is referred to as a callback function. Once the result is ready, the server invokes the callback method with
the result.
Working with Lightning Platform Canvas
To integrate the Salesforce Console with external applications that require authentication methods, such as signed requests or OAuth
2.0 protocols, Salesforce recommends you use Lightning Platform Canvas.
22
Salesforce Console Integration Toolkit for Salesforce Classic Connecting to the Toolkit
Best Practices
Salesforce recommends that you adhere to a few best practices as you use the Salesforce Console Integration Toolkit.
For third-party domains, it’s necessary to specify an absolute URL to integration.js to use the toolkit. If you can't determine
the org's instance, you can access the toolkit library at the default instance. Contact Salesforce for the default instance’s URL.
For example:
//Open a new primary tab with the Salesforce home page in it
sforce.console.openPrimaryTab(null, 'http://www.salesforce.com',
false, 'Salesforce', callback);
23
Salesforce Console Integration Toolkit for Salesforce Classic Best Practices
Lightning Platform Canvas and the Salesforce Console Integration Toolkit are similar—they’re a set of tools and JavaScript APIs that
developers can use to add third-party systems to Salesforce. However, one of the benefits of Lightning Platform Canvas, is the ability to
choose authentication methods. For more information, see the Lightning Platform Canvas Developer’s Guide.
Note: For a canvas app to appear in a console, you must add it to the console as a custom console component.
When developing a canvas app, and you want to include functionality from the Salesforce Console Integration Toolkit, do the following:
1. Include the console integration toolkit API in index.jsp.
2. If your console has a whitelist for domains, add the domain of your canvas app to the whitelist.
3. Call Sfdc.canvas.client.signedrequest() to store the signed request needed by the console integration toolkit
API. For example, if the Lightning Platform Canvas method of authentication is a signed request, do the following:
Sfdc.canvas.client.signedrequest('<%=signedRequest%>')
If the Lightning Platform Canvas method of authentication is OAuth, do the following in the callback function used to get the context
as shown in “Getting Context in Your Canvas App” in the Lightning Platform Canvas Developer’s Guide:
Sfdc.canvas.client.signedrequest(msg)
Consider the following when working with the Salesforce Console Integration Toolkit and canvas apps:
• The console integration toolkit API script depends on the signed request and should be added after the call to
Sfdc.canvas.client.signedrequest() has executed. We recommend that you load the scripts dynamically.
• To retrieve the entity ID of the record that is associated with the canvas sidebar component, do the following:
// Get signedRequest
var signedRequest = Sfdc.canvas.client.signedrequest();
var parsedRequest = JSON.parse(signedRequest);
// get the entity Id that is associated with this canvas sidebar component.
var entityId = parsedRequest.context.environment.parameters.entityId;
To see an example on how to retrieve msg.payload, see the Lightning Platform Canvas Developer’s Guide.
SEE ALSO:
Salesforce Canvas Developer Guide : Getting Context in Your Canvas App
Salesforce Help: Add Console Components to Apps in Salesforce Classic
Salesforce Help: Whitelist Domains for a Salesforce Console in Salesforce Classic
Best Practices
Salesforce recommends that you adhere to a few best practices as you use the Salesforce Console Integration Toolkit.
• Many of the methods in the Salesforce Console Integration Toolkit are asynchronous and return their results using a callback method.
We recommend that you refer to the documentation for each method to understand the information for each response.
• Errors generated by the Salesforce Console Integration Toolkit are typically emitted in a way that doesn't halt JavaScript processing.
Therefore, we recommend that you use a tool such as Firebug for Firefox to monitor the JavaScript console and to help you debug
your code.
24
Salesforce Console Integration Toolkit for Salesforce Classic Best Practices
• When using Firefox, we recommend that you don't call closeTab() on a tab with an active alert box because the browser may
not load properly.
• Duplicate tabs might open when users initiate methods with invalid URLs. We recommend that you check URLs for validity before
you include them in methods.
• To prevent External Page from displaying as a tab name, we recommend that you specify the tabLabel argument on
methods such as openPrimaryTab() and openSubtab().
• For information on how you can customize, extend, or integrate the sidebars of the Salesforce console using Visualforce, see “Customize
a Console with Custom Components in Salesforce Classic” in the Salesforce online help.
• To enable the toolkit for third-party domains, add the domains to the whitelist of the Salesforce console.
• The Salesforce Console Integration Toolkit methods don't work in nested iFrames. For example, when you embed a Visualforce page
into a page layout or use a custom quick action in a feed, the API method works as expected. However, if Development Mode is
enabled in your org, the API method doesn't work because an iFrame is automatically added.
25
CHAPTER 5 Methods for Salesforce Classic
If your org is using Salesforce Classic, use Salesforce Console Integration Toolkit methods.
IN THIS SECTION:
Methods for Primary Tabs and Subtabs
Methods for Navigation Tabs
Methods for Computer-Telephony Integration (CTI)
Methods for Application-Level Custom Console Components
Methods for Push Notifications
Methods for Console Events
Methods for Live Agent
Methods for Omni-Channel
IN THIS SECTION:
closeTab()
Closes a specified primary tab or subtab. Note that closing the first tab in a primary tab closes the primary tab itself. This method is
only available in API version 20.0 or later.
disableTabClose()
Prevents a user from closing a tab or a subtab. If the ID parameter doesn’t specify a tab, the enclosing tab is used. You can also use
this method to re-enable a tab that has been disabled. Available in API version 42.0 or later.
focusPrimaryTabById()
Focuses the browser on a primary tab that is already open with the specified ID. This method is only available in API version 22.0 or
later.
focusPrimaryTabByName()
Focuses the browser on a primary tab that is already open with the specified name. This method is only available in API version 22.0
or later.
26
Methods for Salesforce Classic Methods for Primary Tabs and Subtabs
focusSidebarComponent()
Focuses the browser on a sidebar component. Use this method to focus on a component with the tab or accordion sidebar style.
For more information, see “Sidebar Styles for Console Components in Salesforce Classic” in the Salesforce Help. This method is only
available in API version 34.0 or later.
focusSubtabById()
Focuses the browser on a subtab that is already open with the specified ID. This method is only available in API version 22.0 or later.
focusSubtabByNameAndPrimaryTabId()
Focuses the browser on a subtab that is already open with the specified name and primary tab ID. This method is only available in
API version 22.0 or later.
focusSubtabByNameAndPrimaryTabName()
Focuses the browser on a subtab that is already open with the specified name and primary tab name. This method is only available
in API version 22.0 or later.
generateConsoleUrl()
Generates a URL to a tab, or group of related tabs, in the Salesforce console. If any tabs include external URLs, then add the external
URLs to the console’s whitelist so that they can display correctly. For more information, see “Whitelist Domains for a Salesforce
Console in Salesforce Classic” in the online help. This method is only available in API version 28.0 or later.
getEnclosingPrimaryTabId()
Returns the ID of the current primary tab. This method works within a primary tab or subtab, not within the navigation tab or custom
console components. This method is only available in API version 20.0 or later.
getEnclosingPrimaryTabObjectId()
Returns the object ID of the current primary tab, which contains a subtab. For example, a case ID or account ID. This method works
within a primary tab or subtab. This method is only available in API version 24.0 or later.
getEnclosingTabId()
Returns the ID of the tab that contains the current Visualforce page, which may be a primary tab or subtab. This method will work
if the call is made within a component enclosed within a subtab. This method is only available in API version 20.0 or later.
getFocusedPrimaryTabId()
Returns the ID of the primary tab on which the browser is focused. This method is only available in API version 25.0 or later.
getFocusedPrimaryTabObjectId()
Returns the object ID of the primary tab on which the browser is focused. This method is only available in API version 25.0 or later.
getFocusedSubtabId()
Returns the ID of the subtab on which the browser is focused. For example, a case ID or account ID. This method is only available in
API version 25.0 or later.
getFocusedSubtabObjectId()
Returns the object ID of the subtab on which the browser is focused. For example, a case ID or account ID. This method is only
available in API version 24.0 or later.
getPageInfo()
Returns page information for the specified tab after its content has loaded. If the tab ID is null, it returns page information for the
enclosing primary tab or subtab. Note that to get the page information from a custom console component, a tabId must be
passed as the first parameter to this method.This method is only available in API version 26.0 or later.
getPrimaryTabIds()
Returns all of the IDs of open primary tabs. This method is only available in API version 26.0 or later.
27
Methods for Salesforce Classic Methods for Primary Tabs and Subtabs
getSubtabIds()
Returns all of the IDs of the subtabs on the primary tab specified by a primary tab ID. If the primary tab ID is null, it returns the IDs of
the subtabs on the current primary tab. This method can only be called from a custom console component or a detail page overwritten
by a Visualforce page. This method is only available in API version 26.0 or later.
getTabLink()
Retrieves the URL to a tab, or group of related tabs, from the Salesforce console. This method is only available in API version 28.0 or
later.
isInConsole()
Determines if the page is in the Salesforce console. This method is only available in API version 22.0 or later.
onEnclosingTabRefresh()
Registers a function to call when the enclosing tab refreshes. This method is only available in API version 24.0 or later.
onFocusedSubtab()
Registers a function to call when the focus of the browser changes to a different subtab. This method is only available in API version
24.0 or later.
onTabSave()
Registers and calls a callback method when a user clicks Save in a subtab’s Unsaved Changes dialog box. When using this method,
call setTabUnsavedChanges() in the callback method. This notifies the console that the custom save operation completed.
In the call to setTabUnsavedChanges(), pass the first parameter as false to indicate a successful save or true to indicate
an unsuccessful save. This method is only available in API version 28.0 or later.
openConsoleUrl()
Opens a URL created by the generateConsoleUrl() method (a URL to a tab, or group of related tabs, in the Salesforce
console). This method is only available in API version 28.0 or later.
openPrimaryTab()
Opens a new primary tab to display the content of the specified URL, which can be relative or absolute. You can also override an
existing tab. This method is only available in API version 20.0 or later.
openSubtab()
Opens a new subtab (within a primary tab) that displays the content of a specified URL, which can be relative or absolute. You can
also override an existing subtab. Use to open a new subtab on a primary tab via the primary tab's ID. This method is only available
in API version 20.0 or later.
openSubtabByPrimaryTabName()
Opens a new subtab (within a primary tab) that displays the content of a specified URL, which can be relative or absolute. You can
also override an existing subtab. Use to open a new subtab on a primary tab via the primary tab's name. This method is only available
in API version 22.0 or later.
refreshPrimaryTabById()
Refreshes a primary tab specified by ID, including its subtabs. This method can't refresh subtabs with URLs to external pages or
Visualforce pages. This method is only available in API version 22.0 or later.
refreshPrimaryTabByName()
Refreshes a primary tab specified by name, including its subtabs. This method can't refresh subtabs with URLs to external pages or
Visualforce pages. This method is only available in API version 22.0 or later.
refreshSubtabById()
Refreshes a subtab with the last known URL with a specified ID. This method can't refresh a subtab if the last known URL is an external
page or a Visualforce page. This method is only available in API version 22.0 or later.
28
Methods for Salesforce Classic closeTab()
refreshSubtabByNameAndPrimaryTabId()
Refreshes a subtab with the last known URL with the specified name and primary tab ID. This method can't refresh a subtab if the
last known URL is an external page or a Visualforce page. This method is only available in API version 22.0 or later.
refreshSubtabByNameAndPrimaryTabName()
Refreshes a subtab with the last known URL with the specified name and primary tab name. This method can't refresh a subtab if
the last known URL is an external page or a Visualforce page. This method is only available in API version 22.0 or later.
reopenLastClosedTab()
Reopens the last closed primary tab, and any of its subtabs that were open, the moment it was closed. This method is only available
in API version 35.0 or later.
resetSessionTimeOut()
Resets a session timeout for a console app. This method ensures that users can continue working on Visualforce pages without being
prompted to log back in to the console when they return to a console tab or console component. This method is only available in
API version 24.0 or later.
setTabUnsavedChanges()
Sets the unsaved changes icon ( ) on subtabs to indicate unsaved data. This method is only available in API version 23.0 or later.
setTabIcon()
Sets an icon on the specified tab. If a tab is not specified, the icon is set on the enclosing tab. Use this method to customize a tab’s
icon. This method is only available in API version 28.0 or later.
setTabLink()
Sets a console tab’s URL attribute to the location of the tab’s content. Use this method to generate secure console URLs when users
navigate to tabs displaying content outside of the Salesforce domain.This method is only available in API version 28.0 or later.
setTabStyle()
Sets a cascading style sheet (CSS) on the specified tab. If a tab is not specified, the CSS is set on the enclosing tab. Use this method
to customize a tab’s look and feel. This method is only available in API version 28.0 or later.
setTabTextStyle()
Sets a cascading style sheet (CSS) on a specified tab’s text. If a tab is not specified, the CSS is set on the enclosing tab’s text. Use this
method to customize a tab’s text style. This method is only available in API version 28.0 or later.
setTabTitle()
Sets the title of a primary tab or subtab. This method is only available in API version 20.0 or later.
closeTab()
Closes a specified primary tab or subtab. Note that closing the first tab in a primary tab closes the primary tab itself. This method is only
available in API version 20.0 or later.
Syntax
sforce.console.closeTab(id:String, (optional) callback:Function)
29
Methods for Salesforce Classic closeTab()
Arguments
Name Type Description
id string ID of the primary tab or subtab to close.
callback function For API version 35.0 or later, the JavaScript method that’s called upon completion
of the method.
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testCloseTab() {
//First find the ID of the current tab to close it
sforce.console.getEnclosingTabId(closeSubtab);
}
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
None
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var callback = function () {
if (result.error) {
alert("Error message is " + result.error);
}
};
function testCloseTab() {
30
Methods for Salesforce Classic disableTabClose()
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
fields:
Tip: When using Firefox, we recommend that you don't call closeTab() on a tab with an active alert box because the browser
may not load properly.
disableTabClose()
Prevents a user from closing a tab or a subtab. If the ID parameter doesn’t specify a tab, the enclosing tab is used. You can also use this
method to re-enable a tab that has been disabled. Available in API version 42.0 or later.
Note:
• If you disable subtabs from closing, the primary tab is also disabled from closing.
• If a record is deleted whose primary tab is disabled, the tab is forcibly closed.
• If a record is deleted whose subtab is disabled, the subtab is not closed.
Syntax
sforce.console.disableTabClose(disable:boolean, (optional) tabId:String, (optional)
callback:Function)
31
Methods for Salesforce Classic disableTabClose()
Arguments
Name Type Description
disable boolean Specifies whether to disable the tab. If true, the user can’t close the tab. If false,
the user can close the tab.
tabId string The tabId for the tab to enable or disable. Use false to automatically select the
enclosing tab or subtab without needing to specify a tabId. The enclosing tabId can’t
be inferred when this call is made from outside a sidebar component. For example,
if you call this method from a footer widget, specify the tabId. If the tabId is for a
“Details” subtab of a primary tab, the primary tabId is used instead.
callback function JavaScript method that’s called upon completion of the method. The callback is
passed a response object. See response information below.
Sample Code–Visualforce
<apex:page >
<html>
<head>
<title>Disable close Tab on Load</title>
function displayResultsCallback(result){
var resDiv = document.getElementById("eventResults");
resDiv.innerHTML = JSON.stringify(result);
}
// For use within a tab's sidebar (you don't need tab ID)
function testDisableTabCloseTrueWithoutId() {
sforce.console.disableTabClose(true, false, displayResultsCallback);
}
function testDisableTabCloseFalseWithoutId() {
sforce.console.disableTabClose(false, false, displayResultsCallback);
}
// Note: Your tab ID might be different than the one used here.
// You can get the tab ID many different ways,
// including sforce.console.getEnclosingTabId().
// See the documentation for details.
function testDisableTabCloseTrueWithId() {
var tabId = window.prompt("Enter the tab ID","scc-pt-0");
32
Methods for Salesforce Classic disableTabClose()
function testDisableTabCloseFalseWithId() {
var tabId = window.prompt("Enter the tab ID","scc-pt-0");
sforce.console.disableTabClose(false, tabId, displayResultsCallback);
}
</script>
</head>
<body>
<h1>Disable Tab Close Examples</h1>
<br/><br/>
<ul>
<li><a href="#" onClick="testDisableTabCloseTrueWithoutId();return false;">
Disable closing for the enclosing tab</a></li>
<ul>
<li><a href="#" onClick="testDisableTabCloseTrueWithId();return false;">
Disable closing for a specific tab (via tab ID)</a></li>
</body>
</html>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
33
Methods for Salesforce Classic focusPrimaryTabById()
message string If the action completed successfully, message contains the affected tabId. If the
action failed, message contains the error message.
focusPrimaryTabById()
Focuses the browser on a primary tab that is already open with the specified ID. This method is only available in API version 22.0 or later.
Syntax
sforce.console.focusPrimaryTabById(id:String, (optional)callback:Function)
Arguments
Name Type Description
id string ID of the primary tab to go to.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFocusPrimaryTabById() {
//Get the value for 'scc-pt-0' from the openPrimaryTab method
//This value is for example purposes only
var primaryTabId = 'scc-pt-0';
sforce.console.focusPrimaryTabById(primaryTabId, focusSuccess);
}
</script>
34
Methods for Salesforce Classic focusPrimaryTabByName()
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
focusPrimaryTabByName()
Focuses the browser on a primary tab that is already open with the specified name. This method is only available in API version 22.0 or
later.
Syntax
sforce.console.focusPrimaryTabByName(name:String, (optional)callback:Function)
Arguments
Name Type Description
name string Name of the primary tab to go to.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFocusPrimaryTabByName() {
//Get the value for 'myPrimaryTab' from the openPrimaryTab method
//This value is for example purposes only
var primaryTabName = 'myPrimaryTab';
sforce.console.focusPrimaryTabByName(primaryTabName, focusSuccess);
}
35
Methods for Salesforce Classic focusSidebarComponent()
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
focusSidebarComponent()
Focuses the browser on a sidebar component. Use this method to focus on a component with the tab or accordion sidebar style. For
more information, see “Sidebar Styles for Console Components in Salesforce Classic” in the Salesforce Help. This method is only available
in API version 34.0 or later.
Syntax
sforce.console.focusSidebarComponent(componentInfo:string (optional)tabId:string,
callback:Function)
Arguments
Name Type Description
componentInfo string The JSON object that represents the component to focus on. This argument must
include one of the following forms:
Unambiguous types:
• {componentType: 'CASE_EXPERT_WIDGET' }
• {componentType: 'FILES_WIDGET' }
36
Methods for Salesforce Classic focusSidebarComponent()
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
37
Methods for Salesforce Classic focusSubtabById()
focusSubtabById()
Focuses the browser on a subtab that is already open with the specified ID. This method is only available in API version 22.0 or later.
Syntax
sforce.console.focusSubtabById(id:String, (optional)callback:Function)
Arguments
Name Type Description
id string ID of the subtab to go to.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFocusSubtabById() {
//Get the value for 'scc-st-0' from the openSubtab method
//This value is for example purposes only
var subtabId = 'scc-st-0';
sforce.console.focusSubtabById(subtabId, focusSuccess);
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
38
Methods for Salesforce Classic focusSubtabByNameAndPrimaryTabId()
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
focusSubtabByNameAndPrimaryTabId()
Focuses the browser on a subtab that is already open with the specified name and primary tab ID. This method is only available in API
version 22.0 or later.
Syntax
sforce.console.focusSubtabByNameAndPrimaryTabId(name:String,
primaryTabId:String,(optional)callback:Function)
Arguments
Name Type Description
name string Name of the subtab to go to.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFocusSubtabByNameAndPrimaryTabId() {
//Get the values for 'mySubtab' and 'scc-pt-0' from the openSubtab method
//These values are for example purposes only
var subtabName = 'mySubtab';
var primaryTabId = 'scc-pt-0';
sforce.console.focusSubtabByNameAndPrimaryTabId(subtabName, primaryTabId,
focusSuccess);
}
39
Methods for Salesforce Classic focusSubtabByNameAndPrimaryTabName()
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
focusSubtabByNameAndPrimaryTabName()
Focuses the browser on a subtab that is already open with the specified name and primary tab name. This method is only available in
API version 22.0 or later.
Syntax
sforce.console.focusSubtabByNameAndPrimaryTabName(name:String,
primaryTabName:String,(optional)callback:Function)
Arguments
Name Type Description
name string Name of the subtab to go to.
primaryTabName string Name of the primary tab in which the subtab opened.
callback function JavaScript method that’s called upon completion of the method.
40
Methods for Salesforce Classic generateConsoleUrl()
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFocusSubtabByNameAndPrimaryTabName() {
//Get the value for 'mySubtab' and 'myPrimaryTab' from the openSubtab method
//These values are for example purposes only
var subtabName = 'mySubtab';
var primaryTabName = 'myPrimaryTab';
sforce.console.focusSubtabByNameAndPrimaryTabName(subtabName, primaryTabName,
focusSuccess);
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
generateConsoleUrl()
Generates a URL to a tab, or group of related tabs, in the Salesforce console. If any tabs include external URLs, then add the external URLs
to the console’s whitelist so that they can display correctly. For more information, see “Whitelist Domains for a Salesforce Console in
Salesforce Classic” in the online help. This method is only available in API version 28.0 or later.
41
Methods for Salesforce Classic getEnclosingPrimaryTabId()
Syntax
sforce.console.generateConsoleUrl(urls:String, (optional)callback:Function)
Arguments
Name Type Description
urls string An array of URLs. The first URL is a primary tab and subsequent URLs are subtabs.
Note that the last URL is the subtab on which the console is focused. These URLs
can be standard Salesforce URLs or relative URLs.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<A HREF="#" onClick="testGenerateConsoleURL();return false">
Click here to generate a console URL</A>
<script type="text/javascript">
function showConsoleUrl(result) {
alert(result.consoleUrl);
}
function testGenerateConsoleURL() {
sforce.console.generateConsoleUrl([/apex/pagename, /entityId,
www.externalUrl.com, Standard Salesforce Url/entityId], showConsoleUrl); }
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if the URL was generated successfully, false if otherwise.
callback function JavaScript method that’s called upon completion of the method.
getEnclosingPrimaryTabId()
Returns the ID of the current primary tab. This method works within a primary tab or subtab, not within the navigation tab or custom
console components. This method is only available in API version 20.0 or later.
42
Methods for Salesforce Classic getEnclosingPrimaryTabObjectId()
Syntax
sforce.console.getEnclosingPrimaryTabId((optional)callback:function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<A HREF="#" onClick="testCloseTab();return false">
Click here to close this primary tab</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testCloseTab() {
//First find the ID of the current primary tab to close it
sforce.console.getEnclosingPrimaryTabId(closeSubtab);
}
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
getEnclosingPrimaryTabObjectId()
Returns the object ID of the current primary tab, which contains a subtab. For example, a case ID or account ID. This method works within
a primary tab or subtab. This method is only available in API version 24.0 or later.
43
Methods for Salesforce Classic getEnclosingTabId()
Syntax
sforce.console.getEnclosingPrimaryTabObjectId((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<A HREF="#" onClick="testGetEnclosingPrimaryTabObjectId();">
Click here to get enclosing primary tab object ID</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetEnclosingPrimaryTabObjectId() {
sforce.console.getEnclosingPrimaryTabObjectId(showObjectId);
}
var showObjectId = function showObjectId(result) {
// Display the object ID
alert ('Object ID: ' + result.id);
};
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the enclosing primary tab was successful; false if returning
the enclosing primary tab wasn't successful.
getEnclosingTabId()
Returns the ID of the tab that contains the current Visualforce page, which may be a primary tab or subtab. This method will work if the
call is made within a component enclosed within a subtab. This method is only available in API version 20.0 or later.
44
Methods for Salesforce Classic getFocusedPrimaryTabId()
Syntax
sforce.console.getEnclosingTabId()
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<A HREF="#" onClick="testCloseTab();return false">
Click here to close this tab</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testCloseTab() {
//First find the ID of the current tab to close it
sforce.console.getEnclosingTabId(closeSubtab);
}
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
getFocusedPrimaryTabId()
Returns the ID of the primary tab on which the browser is focused. This method is only available in API version 25.0 or later.
45
Methods for Salesforce Classic getFocusedPrimaryTabObjectId()
Syntax
sforce.console.getFocusedPrimaryTabId((optional) callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetFocusedPrimaryTabId() {
sforce.console.getFocusedPrimaryTabId(showTabId);
}
var showTabId = function showTabId(result) {
//Display the tab ID
alert('Tab ID: ' + result.id);
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the primary tab ID on which the browser is focused was successful;
false if returning the primary tab ID on which the browser is focused wasn't
successful.
getFocusedPrimaryTabObjectId()
Returns the object ID of the primary tab on which the browser is focused. This method is only available in API version 25.0 or later.
46
Methods for Salesforce Classic getFocusedSubtabId()
Syntax
sforce.console.getFocusedPrimaryTabObjectId((optional) callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetFocusedPrimaryTabObjectId() {
sforce.console.getFocusedPrimaryTabObjectId(showObjectId);
}
var showObjectId = function showObjectId(result) {
//Display the object ID
alert('Object ID: ' + result.id);
};
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
success boolean true if returning the primary tab object ID on which the browser is focused was
successful; false if returning the primary tab object ID on which the browser is
focused wasn't successful.
getFocusedSubtabId()
Returns the ID of the subtab on which the browser is focused. For example, a case ID or account ID. This method is only available in API
version 25.0 or later.
47
Methods for Salesforce Classic getFocusedSubtabObjectId()
Syntax
sforce.console.getFocusedSubtabId((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testGetFocusedSubtabId();">
Click here to get the ID of the focused subtab</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetFocusedSubtabId() {
sforce.console.getFocusedSubtabId(showTabId);
}
var showTabId = function showTabId(result) {
// Display the tab ID
alert ('Tab ID: ' + result.id);
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the ID of the focused subtab was successful; false if returning
the ID of the focused subtab wasn't successful.
getFocusedSubtabObjectId()
Returns the object ID of the subtab on which the browser is focused. For example, a case ID or account ID. This method is only available
in API version 24.0 or later.
48
Methods for Salesforce Classic getPageInfo()
Syntax
sforce.console.getFocusedSubtabObjectId((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<A HREF="#" onClick="testGetFocusedSubtabObjectId();">
Click here to get the object ID of the focused subtab</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetFocusedSubtabObjectId() {
sforce.console.getFocusedSubtabObjectId(showObjectId);
}
var showObjectId = function showObjectId(result) {
// Display the object ID
alert ('Object ID: ' + result.id);
};
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the object ID of the focused subtab was successful; false if
returning the object ID of the focused subtab wasn't successful.
getPageInfo()
Returns page information for the specified tab after its content has loaded. If the tab ID is null, it returns page information for the enclosing
primary tab or subtab. Note that to get the page information from a custom console component, a tabId must be passed as the first
parameter to this method.This method is only available in API version 26.0 or later.
49
Methods for Salesforce Classic getPageInfo()
Syntax
sforce.console.getPageInfo(tabId:String, (optional)callback:Function)
Arguments
Name Type Description
tabId string ID of the tab from which page information is returned.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testGetPageInfo();return false">
Click here to get page information</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetPageInfo() {
//Get the page information of 'scc-pt-1'
//This value is for example purposes only
var tabId = 'scc-pt-1';
sforce.console.getPageInfo(tabId , showPageInfo);
}
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
{"url":"https://yourInstance.salesforce.com/001x0000003DGQR",
"objectId":"001x0000003DGQR","objectName":"Acme","object":"Account","displayName":"Company"
For API version 31.0 and later, invoking this API method on a PersonAccount object returns the following
additional information.
• accountId or contactId, the associated account or contact ID
• personAccount, which is true if the object is a PersonAccount and false otherwise
50
Methods for Salesforce Classic getPrimaryTabIds()
{"url":"https://yourInstance.salesforce.com/001x0000003DGQR",
"objectId":"001x0000003DGQR","objectName":"Acme Person Account",
"object":"Account", "contactId":"003D000000QOMqg",
"personAccount":true}
callback function JavaScript method that’s called upon completion of the method.
getPrimaryTabIds()
Returns all of the IDs of open primary tabs. This method is only available in API version 26.0 or later.
Syntax
sforce.console.getPrimaryTabIds((optional) callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testGetPrimaryTabIds();return false">
Click here to get the primary tab IDs</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetPrimaryTabIds() {
sforce.console.getPrimaryTabIds(showTabId);
}
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
51
Methods for Salesforce Classic getSubtabIds()
success boolean true if returning the IDs of open primary tabs was successful; false if returning
the IDs of open primary tabs wasn't successful.
getSubtabIds()
Returns all of the IDs of the subtabs on the primary tab specified by a primary tab ID. If the primary tab ID is null, it returns the IDs of the
subtabs on the current primary tab. This method can only be called from a custom console component or a detail page overwritten by
a Visualforce page. This method is only available in API version 26.0 or later.
Syntax
sforce.console.getSubtabIds( (optional) primaryTabId:String, (optional) callback:Function)
Arguments
Name Type Description
primaryTabId string ID of the primary tab from which the subtab IDs are returned.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testGetSubtabIds();return false">
Click here to get the subtab IDs</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testGetSubtabIds() {
//Get the subtabs of the primary tab 'scc-pt-0'
//This value is for example purposes only
var primaryTabId = 'scc-pt-0';
sforce.console.getSubtabIds(primaryTabId , showTabId);
}
52
Methods for Salesforce Classic getTabLink()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if firing the event was successful; false if firing the event wasn't successful.
getTabLink()
Retrieves the URL to a tab, or group of related tabs, from the Salesforce console. This method is only available in API version 28.0 or later.
Syntax
sforce.console.getTabLink(level:String, (optional)tabId:String,
(optional)callback:Function)
Arguments
Name Type Description
level string Level that matches one of the Link to Share options in the Salesforce console user
interface. The options are:
• All primary tabs and subtabs —
sforce.console.TabLink.PARENT_AND_CHILDREN.
• Only the specified tab — sforce.console.TabLink.TAB_ONLY
• A standard Salesforce URL —
sforce.console.TabLink.SALESFORCE_URL
For more information, see “Tabs and Navigation in the Salesforce Classic Console”
in the online help.
tabId string Optional tab ID of the tab from which you’re retrieving the URL. If you do not pass
a tab ID, the URL to the current tab is returned.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<A HREF="#" onClick="getEnclosingPrimaryTabId();return false">
Click here to get tab link</A>
<script type="text/javascript">
53
Methods for Salesforce Classic isInConsole()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if the link was retrieved successfully, false if retrieving was unsuccessful.
callback function JavaScript method that’s called upon completion of the method.
isInConsole()
Determines if the page is in the Salesforce console. This method is only available in API version 22.0 or later.
Syntax
sforce.console.isInConsole()
Arguments
None
Sample Code–Visualforce
<apex:page standardController="Case">
<A HREF="#" onClick="testIsInConsole();return false">
Click here to check if the page is in the Service Cloud console</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testIsInConsole() {
if (sforce.console.isInConsole()) {
alert('in console');
} else {
54
Methods for Salesforce Classic onEnclosingTabRefresh()
alert('not in console');
}
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
Returns true if the page is in the Salesforce console; false if the page is not in the Salesforce console.
onEnclosingTabRefresh()
Registers a function to call when the enclosing tab refreshes. This method is only available in API version 24.0 or later.
Syntax
sforce.console.onEnclosingTabRefresh(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when the enclosing tab refreshes.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function eventHandler(result) {
alert('Enclosing tab has refreshed:' + result.id
+ 'and the object Id is:' + result.objectId);
};
sforce.console.onEnclosingTabRefresh(eventHandler);
</script>
</apex:page>
55
Methods for Salesforce Classic onFocusedSubtab()
objectId string The object ID of the refreshed tab or null if no object exists.
onFocusedSubtab()
Registers a function to call when the focus of the browser changes to a different subtab. This method is only available in API version 24.0
or later.
Syntax
sforce.console.onFocusedSubtab(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when the focus of the browser changes to a different
subtab.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('Focus changed to a different subtab. The subtab Id is:'
+ result.id + 'and the object Id is:' + result.objectId);
};
sforce.console.onFocusedSubtab(eventHandler);
</script>
</apex:page>
objectId string The object ID of the subtab on which the browser is focused or null if no object exists.
56
Methods for Salesforce Classic onTabSave()
onTabSave()
Registers and calls a callback method when a user clicks Save in a subtab’s Unsaved Changes dialog box. When using this method, call
setTabUnsavedChanges() in the callback method. This notifies the console that the custom save operation completed. In the
call to setTabUnsavedChanges(), pass the first parameter as false to indicate a successful save or true to indicate an
unsuccessful save. This method is only available in API version 28.0 or later.
Registering a callback method affects the user interface. When no save handler is registered, the user is presented with two options
when closing a subtab with unsaved changes: Continue or Cancel. When a save handler is registered, the user is presented with three
options when closing the subtab: Save, Don’t Save, or Cancel. In this scenario, the callback method registered is called when the user
chooses Save.
Note: Calling onTabSave() from a custom console component prevents that component from refreshing when saving the
subtab. For more information on custom console components, see “Customize a Console with Custom Components in Salesforce
Classic” in the Salesforce online help.
Syntax
sforce.console.onTabSave(callback:Function)
Arguments
Name Type Description
callback function JavaScript method called to handle the save operation.
Sample Code–Visualforce
<apex:page>
<a href="#" onClick="testOnTabSave();return false">
Click here to register save handler</a>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testOnTabSave() {
sforce.console.onTabSave(handleSave);
}
57
Methods for Salesforce Classic openConsoleUrl()
Response
Name Type Description
id string ID of the subtab being saved.
objectId string Object ID of the subtab being saved, if applicable; null otherwise.
openConsoleUrl()
Opens a URL created by the generateConsoleUrl() method (a URL to a tab, or group of related tabs, in the Salesforce console).
This method is only available in API version 28.0 or later.
Syntax
sforce.console.openConsoleUrl(id:String, consoleUrl:URL, active:Boolean,
(optional)tabLabels:String, (optional)tabNames:String, (optional)callback:Function)
Arguments
Name Type Description
id string ID of the console tab to override. If the ID corresponds to an existing primary tab,
then the existing primary tab is redirected to the given URL because the console
prevents duplicate tabs. Use null to create a new primary tab.
consoleUrl string Console URL that represents the array of URLs passed into Salesforce.
active boolean If true, the opened primary tab displays immediately. If false, the opened
primary tab displays in the background and the current tab maintains focus.
tabLabels string Optional array of labels of the opened primary tab or subtabs. The order in which
the tabs appear in the console URL should match the order of the labels that appear
in the array. If you do not want to set the labels of tabs, use an empty string ('').
tabNames string Optional array of names of the opened primary and subtabs. The order in which the
tabs appear in the console URL should match the order of the names that appear in
the array. If you do not want to set the names of tabs, use an empty string ('').
58
Methods for Salesforce Classic openPrimaryTab()
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<A HREF="#" onClick="testGenerateConsoleURL();return false">
Click here to open a console URL</A>
<script type="text/javascript">
var generateConsoleUrl = function testGenerateConsoleURL() {
sforce.console.generateConsoleUrl([/apex/pagename, /entityId,
www.externalUrl.com, Standard Salesforce Url/entityId], showConsoleUrl);
}
var openConsoleUrl = function showConsoleUrl(result) {
sforce.console.openConsoleUrl(null, result.consoleUrl, true, ['Apex', '',
'Salesforce', ''], ['', '', 'externalUrl', ''])
}
</script>
</apex:page>
Note: This example shows that if you want to set a label or name, you must set the other values to empty string (‘’).
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
openPrimaryTab()
Opens a new primary tab to display the content of the specified URL, which can be relative or absolute. You can also override an existing
tab. This method is only available in API version 20.0 or later.
• If the ID corresponds to an existing primary tab, the existing tab is redirected to the given URL because the Salesforce console prevents
duplicate tabs.
• If the URL is to a Salesforce object, that object displays as specified in the Salesforce console app settings. For example, if cases are
set to open as a subtab of their parent accounts, and openPrimaryTab() is called on a case, the case opens as subtab on its
parent account's primary tab.
If there's an error opening the tab, the error code is reported in the JavaScript console.
59
Methods for Salesforce Classic openPrimaryTab()
Syntax
sforce.console.openPrimaryTab(id:String, url:URL, active:Boolean,
(optional)tabLabel:String, (optional)callback:Function, (optional)name)
Arguments
Name Type Description
id string ID of the primary tab to override.
Use null to create a new primary tab.
If the ID corresponds to an existing primary tab, the existing tab is redirected to the
given URL because the Salesforce console prevents duplicate tabs.
Note: When using a relative URL, make sure that you include "/" at the
beginning of your URL. When pointing to a Visualforce page, use "/apex/"
at the beginning of your URL. Otherwise, your URL might not work as expected.
active boolean If true, the opened primary tab displays immediately. If false, the opened
primary tab displays in the background and the current tab maintains focus.
tabLabel string Optional label of the opened primary tab. If a label isn't specified, External
Page displays.
Add labels as text; HTML isn't supported.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
60
Methods for Salesforce Classic openSubtab()
<script type="text/javascript">
function testOpenPrimaryTab() {
//Open a new primary tab with the salesforce.com home page in it
sforce.console.openPrimaryTab(null, 'http://www.salesforce.com', false,
'salesforce', openSuccess, 'salesforceTab');
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
id string ID of the primary tab. IDs are only valid during a user session; IDs become invalid
when a user leaves the Salesforce console.
openSubtab()
Opens a new subtab (within a primary tab) that displays the content of a specified URL, which can be relative or absolute. You can also
override an existing subtab. Use to open a new subtab on a primary tab via the primary tab's ID. This method is only available in API
version 20.0 or later.
If there's an error opening the tab, the error code is reported in the JavaScript console.
Syntax
sforce.console.openSubtab(primaryTabId:String, url:URL, active:Boolean, tabLabel:String,
id:String, (optional)callback:Function, (optional)name:String)
61
Methods for Salesforce Classic openSubtab()
Arguments
Name Type Description
primaryTabId string ID of the primary tab in which the subtab opened.
Note: When using a relative URL, make sure that you include "/" at the
beginning of your URL. When pointing to a Visualforce page, use "/apex/"
at the beginning of your URL. Otherwise, your URL might not work as expected.
active boolean If true, the opened subtab displays immediately. If false, the opened subtab
displays in the background and the current tab maintains focus.
tabLabel string Optional label of the opened subtab. If a label isn't specified, External Page
displays.
Add labels as text; HTML isn't supported.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testOpenSubtab() {
//First find the ID of the primary tab to put the new subtab in
sforce.console.getEnclosingPrimaryTabId(openSubtab);
}
62
Methods for Salesforce Classic openSubtabByPrimaryTabName()
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
id string ID of the subtab. IDs are only valid during a user session; IDs become invalid when
the user leaves the Salesforce console.
openSubtabByPrimaryTabName()
Opens a new subtab (within a primary tab) that displays the content of a specified URL, which can be relative or absolute. You can also
override an existing subtab. Use to open a new subtab on a primary tab via the primary tab's name. This method is only available in API
version 22.0 or later.
If there's an error opening the tab, the error code is reported in the JavaScript console.
Syntax
sforce.console.openSubtabByPrimaryTabName(primaryTabName:String, url:URL, active:Boolean,
tabLabel:String, id:String, (optional)callback:Function, (optional)name:String)
Arguments
Name Type Description
primaryTabName string Name of the primary tab in which the subtab opened.
63
Methods for Salesforce Classic openSubtabByPrimaryTabName()
active boolean If true, the opened subtab displays immediately. If false, the opened subtab
displays in the background and the current tab maintains focus.
tabLabel string Optional label of the opened subtab. If a label isn't specified, External Page
displays.
Add labels as text; HTML isn't supported.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testOpenSubtabByPrimaryTabName() {
//First open a primary tab by name
sforce.console.openPrimaryTab(null, 'http://www.yahoo.com', true, 'Yahoo',
openSubtab, 'yahoo');
}
64
Methods for Salesforce Classic refreshPrimaryTabById()
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
id string ID of the subtab. IDs are only valid during a user session; IDs become invalid when
the user leaves the Salesforce console.
refreshPrimaryTabById()
Refreshes a primary tab specified by ID, including its subtabs. This method can't refresh subtabs with URLs to external pages or Visualforce
pages. This method is only available in API version 22.0 or later.
Syntax
sforce.console.refreshPrimaryTabById(id:String, active:Boolean, (optional)callback:Function,
(optional)fullRefresh:Boolean)
Arguments
Name Type Description
id string ID of the primary tab to refresh.
active boolean If true, the refreshed primary tab displays immediately. If false, the refreshed
primary tab displays in the background.
callback function JavaScript method that’s called upon completion of the method.
65
Methods for Salesforce Classic refreshPrimaryTabByName()
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testRefreshPrimaryTabById() {
//Get the value for 'scc-pt-0' from the openPrimaryTab method
//This value is for example purposes only
var primaryTabId = 'scc-pt-0';
sforce.console.refreshPrimaryTabById(primaryTabId, true, refreshSuccess);
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
refreshPrimaryTabByName()
Refreshes a primary tab specified by name, including its subtabs. This method can't refresh subtabs with URLs to external pages or
Visualforce pages. This method is only available in API version 22.0 or later.
Syntax
sforce.console.refreshPrimaryTabByName(name:String, active:Boolean,
(optional)callback:Function), (optional)fullRefresh:Boolean)
66
Methods for Salesforce Classic refreshPrimaryTabByName()
Arguments
Name Type Description
name string Name of the primary tab to refresh.
active boolean If true, the refreshed primary tab displays immediately. If false, the refreshed
primary tab displays in the background.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testRefreshPrimaryTabByName() {
//Set the name of the tab by using the openPrimaryTab method
//This value is for example purposes only
var primaryTabName = 'myPrimaryTab';
sforce.console.refreshPrimaryTabByName(primaryTabName, true, refreshSuccess);
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
67
Methods for Salesforce Classic refreshSubtabById()
refreshSubtabById()
Refreshes a subtab with the last known URL with a specified ID. This method can't refresh a subtab if the last known URL is an external
page or a Visualforce page. This method is only available in API version 22.0 or later.
Syntax
sforce.console.refreshSubtabById(id:String, active:Boolean, (optional)callback:Function,
(optional)fullRefresh:Boolean)
Arguments
Name Type Description
id string ID of the subtab to refresh.
active boolean If true, the refreshed subtab displays immediately. If false, the refreshed subtab
displays in the background.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testRefreshSubtabById() {
//Set the name of the tab by using the openSubtab method
//This value is for example purposes only
var subtabId = 'scc-st-0';
sforce.console.refreshSubtabById(subtabId, true, refreshSuccess);
}
68
Methods for Salesforce Classic refreshSubtabByNameAndPrimaryTabId()
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
refreshSubtabByNameAndPrimaryTabId()
Refreshes a subtab with the last known URL with the specified name and primary tab ID. This method can't refresh a subtab if the last
known URL is an external page or a Visualforce page. This method is only available in API version 22.0 or later.
Syntax
sforce.console.refreshSubtabByNameAndPrimaryTabId(name:String, primaryTabId:String,
active:Boolean, (optional)callback:Function, (optional)fullRefresh:Boolean)
Arguments
Name Type Description
name string Name of the subtab to refresh.
active boolean If true, the refreshed subtab displays immediately. If false, the refreshed subtab
displays in the background.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
69
Methods for Salesforce Classic refreshSubtabByNameAndPrimaryTabName()
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testRefreshSubtabByNameAndPrimaryTabId() {
//Get the value for 'mySubtab' and 'scc-pt-0' from the openSubtab method
//These values are for example purposes only
var subtabName = 'mySubtab';
var primaryTabId = 'scc-pt-0';
sforce.console.refreshSubtabByNameAndPrimaryTabId(subtabName, primaryTabId,
true, refreshSuccess);
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
refreshSubtabByNameAndPrimaryTabName()
Refreshes a subtab with the last known URL with the specified name and primary tab name. This method can't refresh a subtab if the
last known URL is an external page or a Visualforce page. This method is only available in API version 22.0 or later.
Syntax
sforce.console.refreshSubtabByNameAndPrimaryTabName(name:String, primaryTabName:String,
active:Boolean, (optional)callback:Function, (optional)fullRefresh:Boolean)
70
Methods for Salesforce Classic refreshSubtabByNameAndPrimaryTabName()
Arguments
Name Type Description
name string Name of the subtab to refresh.
primaryTabName string Name of the primary tab in which the subtab opened.
active boolean If true, the refreshed subtab displays immediately. If false, the refreshed subtab
displays in the background.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testRefreshSubtabByNameAndPrimaryTabName() {
//Get the value for 'mySubtab' and 'myPrimaryTab' from the openSubtab method
//These values are for example purposes only
var subtabName = 'mySubtab';
var primaryTabName = 'myPrimaryTab';
sforce.console.refreshSubtabByNameAndPrimaryTabName(subtabName, primaryTabName,
true, refreshSuccess);
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
71
Methods for Salesforce Classic reopenLastClosedTab()
reopenLastClosedTab()
Reopens the last closed primary tab, and any of its subtabs that were open, the moment it was closed. This method is only available in
API version 35.0 or later.
Syntax
sforce.console.reopenLastClosedTab()
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function reopenLastClosedTabTest() {
sforce.console.reopenLastClosedTab(callback);
}
</script>
<A HREF="#" onClick="reopenLastClosedTabTest(); return false">Re-open Last Closed Tab</A>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
field:
72
Methods for Salesforce Classic resetSessionTimeOut()
resetSessionTimeOut()
Resets a session timeout for a console app. This method ensures that users can continue working on Visualforce pages without being
prompted to log back in to the console when they return to a console tab or console component. This method is only available in API
version 24.0 or later.
For more information, see Modify Session Security Settings.
Syntax
sforce.console.resetSessionTimeOut()
Arguments
None
Sample Code–Visualforce
<apex:page standardController="Case">
<A HREF="#" onClick="testResetSessionTimeOut();">
Click here to reset session timeout</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testResetSessionTimeOut() {
sforce.console.resetSessionTimeOut();
};
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
None
setTabUnsavedChanges()
Sets the unsaved changes icon ( ) on subtabs to indicate unsaved data. This method is only available in API version 23.0 or later.
73
Methods for Salesforce Classic setTabUnsavedChanges()
Syntax
sforce.console.setTabUnsavedChanges(unsaved:Boolean, callback:Function,
(optional)subtabId:String)
Arguments
Name Type Description
unsaved boolean If true, the tab is marked as having unsaved changes.
callback function JavaScript method that’s called upon completion of the method.
subtabId string The ID of the subtab that is marked as having unsaved changes.
This argument is only available in API version 25.0 or later.
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetTabUnsavedChanges() {
sforce.console.setTabUnsavedChanges(true, displayResult);
};
function displayResult(result) {
if (result.success) {
alert('Tab status has been successfully updated');
} else {
alert('Tab status couldn’t be updated');
}
}
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
This method returns its response in an object in a callback method. The response object contains the following field:
74
Methods for Salesforce Classic setTabIcon()
<apex:includeScript value="/support/console/25.0/integration.js"/>
<script type="text/javascript">
function testSetTabUnsavedChanges() {
sforce.console.getFocusedSubtabId(setTabDirty);
};
function setTabDirty(result) {
sforce.console.setTabUnsavedChanges(true, displayResult, result.id);
};
function displayResult(result) {
if (result.success) {
alert('Tab status has been successfully updated');
} else {
alert('Tab status couldn’t be updated');
}
};
</script>
</apex:page>
Note: This example is only set to run if the Visualforce page is inside an application-level custom component. For more information,
see Methods for Application-Level Custom Console Components on page 100.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
setTabIcon()
Sets an icon on the specified tab. If a tab is not specified, the icon is set on the enclosing tab. Use this method to customize a tab’s icon.
This method is only available in API version 28.0 or later.
Syntax
sforce.console.setTabIcon(iconUrl:String, tabID:String, (optional)callback:Function)
75
Methods for Salesforce Classic setTabIcon()
Arguments
Name Type Description
iconUrl string A URL pointing to an image, which is used as the tab’s icon. If null or undefined, the
tab’s default icon is used.
tabId string The ID of the tab on which to set the icon. If null or undefined, the enclosing tab’s
ID is used.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testSetTabIcon();return false">
Click here to change the enclosing tab’s icon</A> <BR/>
<A HREF="#" onClick="testResetTabIcon(); return false;">
Click here to reset the enclosing tab’s icon</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function checkResult(result) {
if (result.success) {
alert('Tab icon set successfully!');
} else {
alert('Tab icon cannot be set!');
}
}
function testSetTabIcon() {
sforce.console.setTabIcon('http://host/path/to/your/icon.png', null,
checkResult);
}
function testResetTabIcon() {
sforce.console.setTabIcon(null, null, checkResult);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
76
Methods for Salesforce Classic setTabLink()
Note: If this method is called without passing in a tab ID, the tab in which the Visualforce page is enclosed is used. If there isn’t
an enclosing tab, the error message Cannot get a workspace or view tab from the given ID displays
in the browser’s developer console.
setTabLink()
Sets a console tab’s URL attribute to the location of the tab’s content. Use this method to generate secure console URLs when users
navigate to tabs displaying content outside of the Salesforce domain.This method is only available in API version 28.0 or later.
Syntax
sforce.console.setTabLink((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page standardController="Account">
<apex: detail />
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
window.onload = function() {
sforce.console.setTabLink();
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
callback function JavaScript method that’s called upon completion of the method.
setTabStyle()
Sets a cascading style sheet (CSS) on the specified tab. If a tab is not specified, the CSS is set on the enclosing tab. Use this method to
customize a tab’s look and feel. This method is only available in API version 28.0 or later.
77
Methods for Salesforce Classic setTabStyle()
Syntax
sforce.console.setTabStyle(style:String, tabId:String, (optional)callback:Function)
Arguments
Name Type Description
style string A CSS specification string used to style the tab. If null or undefined, the tab’s default
style is used.
tabId string The ID of the tab on which to set the style. If null or undefined, the enclosing tab’s
ID is used.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testSetTabStyle();return false">
Click here to change the enclosing tab’s background color to red</A> <BR/>
<A HREF="#" onClick="testResetTabStyle(); return false;">
Click here to reset the enclosing tab’s style</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function checkResult(result) {
if (result.success) {
alert('Tab style set successfully!');
} else {
alert('Tab style cannot be set!');
}
}
function testSetTabStyle() {
sforce.console.setTabStyle('background:red;', null, checkResult);
}
function testResetTabStyle() {
sforce.console.setTabStyle(null, null, checkResult);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
78
Methods for Salesforce Classic setTabTextStyle()
Note: If this method is called without passing in a tab ID, the tab in which the Visualforce page is enclosed is used. If there isn’t
an enclosing tab, the error message Cannot get a workspace or view tab from the given ID displays
in the browser’s developer console.
setTabTextStyle()
Sets a cascading style sheet (CSS) on a specified tab’s text. If a tab is not specified, the CSS is set on the enclosing tab’s text. Use this
method to customize a tab’s text style. This method is only available in API version 28.0 or later.
Syntax
sforce.console. setTabTextStyle(style:String, tabID:String, (optional)callback:Function))
Arguments
Name Type Description
style string A CSS specification string used to set a tab’s text style. If null or undefined, the tab’s
default text style is used.
tabId string The ID of the tab on which to set the text style. If null or undefined, the enclosing
tab’s ID is used.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testSetTabTextStyle();return false">
Click here to change the enclosing tab’s text style</A> <BR/>
<A HREF="#" onClick="testResetTabTextStyle(); return false;">
Click here to reset the enclosing tab’s text style</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function checkResult(result) {
if (result.success) {
alert('Tab text style set successfully!');
} else {
alert('Tab text style cannot be set!');
}
}
function testSetTabTextStyle() {
sforce.console.setTabTextStyle('color:blue;font-style:italic;', null,
checkResult);
}
function testResetTabTextStyle() {
sforce.console.setTabTextStyle(null, null, checkResult);
}
79
Methods for Salesforce Classic setTabTitle()
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
Note: If this method is called without passing in a tab ID, the tab in which the Visualforce page is enclosed is used. If there isn’t
an enclosing tab, the error message Cannot get a workspace or view tab from the given ID displays
in the browser’s developer console.
setTabTitle()
Sets the title of a primary tab or subtab. This method is only available in API version 20.0 or later.
Syntax
sforce.console.setTabTitle(tabTitle:String, (optional)tabID:String)
Arguments
Name Type Description
tabTitle string Title of a primary tab or subtab.
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetTabTitle() {
//Set the current tab's title
sforce.console.setTabTitle('My New Title');
}
80
Methods for Salesforce Classic Methods for Navigation Tabs
</script>
</apex:page>
Note: To see this example in action, click the custom link on a case. For more information, see Define Custom Buttons and Links
in the Salesforce help.
Response
None
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetTabTitle() {
sforce.console.getFocusedPrimaryTabId(function(result) {
sforce.console.setTabTitle('My New Title', result.id);
});
}
</script>
</apex:page>
Note: This example is only set to run if the Visualforce page is inside an application-level custom component. For more information,
see Methods for Application-Level Custom Console Components on page 100.
Response
None
IN THIS SECTION:
focusNavigationTab()
Focuses the browser on the navigation tab. This method is only available in API version 31.0 or later.
getNavigationTabs()
Returns all of the objects in the navigation tab. This method is only available in API version 31.0 or later.
getSelectedNavigationTab()
Returns the selected object in the navigation tab. This method is only available in API version 31.0 or later.
81
Methods for Salesforce Classic focusNavigationTab()
refreshNavigationTab()
Refreshes the selected navigation tab. This method is only available in API version 31.0 or later.
setSelectedNavigationTab()
Sets the navigation tab with a specific ID or URL. This method is only available in API version 31.0 or later.
focusNavigationTab()
Focuses the browser on the navigation tab. This method is only available in API version 31.0 or later.
Syntax
sforce.console.focusNavigationTab((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
82
Methods for Salesforce Classic getNavigationTabs()
getNavigationTabs()
Returns all of the objects in the navigation tab. This method is only available in API version 31.0 or later.
Syntax
sforce.console.getNavigationTabs((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
alert('Label:'+tempItem[i].label+'listViewURl:'+tempItem[i].listViewUrl+'navTabid:'
+tempItem[i].navigationTabId+'Selected ' +tempItem[i].selected);
}
} else {
alert('something is wrong!');
}
};
sforce.console.getNavigationTabs(callback);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the IDs of objects in the navigation tab was successful, false
otherwise.
83
Methods for Salesforce Classic getSelectedNavigationTab()
getSelectedNavigationTab()
Returns the selected object in the navigation tab. This method is only available in API version 31.0 or later.
Syntax
sforce.console.getSelectedNavigationTab((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
selected boolean true if returning the selected field of the object was successful, false otherwise.
success boolean true if returning the object IDs was successful, false otherwise.
84
Methods for Salesforce Classic refreshNavigationTab()
refreshNavigationTab()
Refreshes the selected navigation tab. This method is only available in API version 31.0 or later.
Syntax
sforce.console.refreshNavigationTab((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
setSelectedNavigationTab()
Sets the navigation tab with a specific ID or URL. This method is only available in API version 31.0 or later.
85
Methods for Salesforce Classic Methods for Computer-Telephony Integration (CTI)
Syntax
sforce.console.setSelectedNavigationTab((optional)callback, navigatorTabId:(optional)string,
url:(optional)string)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var callback = function (result) {}
if (result.success) {
alert('Successful');
} else {
alert('something is wrong!');
}
};
sforce.console.setSelectedNavigationTab(callback,'nav-tab-4');
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
86
Methods for Salesforce Classic fireOnCallBegin()
IN THIS SECTION:
fireOnCallBegin()
Fires an event that notifies a call has begun. Use to get information or send information between an interaction log and a custom
console component. This method is only available in API version 31.0 or later.
fireOnCallEnd()
Fires an event that notifies a call has ended. Use to get information or send information between an interaction log and a custom
console component. This method executes when fireOnCallBegin() is called first. This method is only available in API
version 31.0 or later.
fireOnCallLogSaved()
Calls the eventHandler function registered with onCallLogSaved(). Use to get information or send information between
an interaction log and a custom console component.. This method is only available in API version 31.0 or later.
getCallAttachedData()
Returns the attached data of a call represented by the call object ID or null if there isn’t an active call. The data is returned in JSON
format. This method is for computer-telephony integration (CTI); it’s only available in API version 24.0 or later.
getCallObjectIds()
Returns any active call object IDs in the order in which they arrived or null if there aren’t any active calls. This method is for
computer-telephony integration (CTI); it’s only available in API version 24.0 or later.
onCallBegin()
Registers a function that is called when a call begins (comes in). This method is for computer-telephony integration (CTI); it’s only
available in API version 24.0 or later.
onCallEnd()
Registers a function that is called when a call ends. This method is for computer-telephony integration (CTI); it’s only available in API
version 24.0 or later.
onCallLogSaved()
Registers a function that is fired when an interaction log saves a call log. Use to get information or send information between an
interaction log and a custom console component. This method is only available in API version 31.0 or later.
onSendCTIMessage()
Registers a function that is fired when a message is sent with the sendCTIMessage(). Use to get information or send information
between an interaction log and a custom console component. This method is only available in API version 31.0 or later.
sendCTIMessage()
Sends a message to the CTI adapter or Open CTI. This method is for computer-telephony integration (CTI); it’s only available in API
version 24.0 or later.
setCallAttachedData()
Sets the call data associated with a call object ID. Use to get information or send information between an interaction log and a
custom console component.This method is only available in API version 31.0 or later.
setCallObjectIds()
Sets call object IDs, in ascending order of arrival. This method is only available in API version 31.0 or later.
fireOnCallBegin()
Fires an event that notifies a call has begun. Use to get information or send information between an interaction log and a custom console
component. This method is only available in API version 31.0 or later.
87
Methods for Salesforce Classic fireOnCallEnd()
Syntax
sforce.console.cti.fireOnCallBegin( callObjectId:String, callType:String, callLabel:String,
(optional)callback:Function )
Arguments
Name Type Description
callObjectId string The object ID of the call.
callType string String that specifies the call type, which must be internal, inbound or
outbound.
callLabel string String that specifies a call as it appears in the Attach Call drop-down button. For
example, Call Label — Inbound Call 12:52:31 PM.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testFireOnCallBegin();return false">
Click here to start a call</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFireOnCallBegin() {
sforce.console.cti.fireOnCallBegin('call.794937' , 'outbound' , 'label 1');
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
fireOnCallEnd()
Fires an event that notifies a call has ended. Use to get information or send information between an interaction log and a custom console
component. This method executes when fireOnCallBegin() is called first. This method is only available in API version 31.0 or
later.
88
Methods for Salesforce Classic fireOnCallLogSaved()
Syntax
sforce.console.cti.fireOnCallEnd( callObjectId:String, callDuration:Number,
callDisposition:String, (optional)callback:Function )
Arguments
Name Type Description
callObjectId string The object ID of the call.
callDisposition string String representing the call’s disposition, such as call successful, left voicemail, or
disconnected.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testFireOnCallEnd();return false">
Click here to end a call</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFireOnCallEnd() {
//Here, 'call.1' refers to a call that is in progress.
sforce.console.cti.fireOnCallEnd('call.1', 60, 'Set Appointment');
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
fireOnCallLogSaved()
Calls the eventHandler function registered with onCallLogSaved(). Use to get information or send information between
an interaction log and a custom console component.. This method is only available in API version 31.0 or later.
89
Methods for Salesforce Classic fireOnCallLogSaved()
Syntax
sforce.console.cti.fireOnCallLogSaved( id:String, (optional)callback:Function )
Arguments
Name Type Description
id string The object ID of the saved call log.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFireOnCallLogSaved() {
// Simulates that a call log was saved by passing the task object Id as input.
sforce.console.cti.fireOnCallLogSaved('00Txx000003qf8u', myCallback);
}
sforce.console.cti.onCallLogSaved(callback);
</script>
<a href="#" onClick="testFireOnCallLogSaved();return false">
Test fireOnCallLogSaved API!</a>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
90
Methods for Salesforce Classic getCallAttachedData()
getCallAttachedData()
Returns the attached data of a call represented by the call object ID or null if there isn’t an active call. The data is returned in JSON format.
This method is for computer-telephony integration (CTI); it’s only available in API version 24.0 or later.
Syntax
sforce.console.cti.getCallAttachedData( callObjectId, getCallType, (optional)
callback:Function )
Arguments
Name Type Description
callObjectId string The call object ID of the call that retrieves the attached data.
getCallType boolean true if the type of call is returned as either ‘INTERNAL,’ ‘INBOUND,’ or ‘OUTBOUND’;
false otherwise. This field is only available in API version 29.0 or later.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
/* Note: Open CTI needs to set call type to before getting it, and call type is
INTERNAL/INBOUND/OUTBOUND.
*/
};
91
Methods for Salesforce Classic getCallObjectIds()
</script>
<h1>CTI</h1>
<button onclick="testGetCallAttachedData()">getAttachedData</button>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the attached data was successful; false if returning the attached
data wasn’t successful.
type string The type of call. Possible values are 'INTERNAL', 'INBOUND', and 'OUTBOUND'.
getCallObjectIds()
Returns any active call object IDs in the order in which they arrived or null if there aren’t any active calls. This method is for
computer-telephony integration (CTI); it’s only available in API version 24.0 or later.
Syntax
sforce.console.cti.getCallObjectIds( (optional) callback:Function )
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
92
Methods for Salesforce Classic onCallBegin()
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
success boolean true if returning the active call object IDs was successful; false if returning the
active call object IDs wasn’t successful.
onCallBegin()
Registers a function that is called when a call begins (comes in). This method is for computer-telephony integration (CTI); it’s only available
in API version 24.0 or later.
Syntax
sforce.console.cti.onCallBegin( eventHandler:Function )
Arguments
Name Type Description
eventHandler function JavaScript method called when a call begins.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
93
Methods for Salesforce Classic onCallEnd()
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
onCallEnd()
Registers a function that is called when a call ends. This method is for computer-telephony integration (CTI); it’s only available in API
version 24.0 or later.
Syntax
sforce.console.cti.onCallEnd( eventHandler:Function )
Arguments
Name Type Description
eventHandler function JavaScript method called when a call ends.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
94
Methods for Salesforce Classic onCallLogSaved()
onCallLogSaved()
Registers a function that is fired when an interaction log saves a call log. Use to get information or send information between an interaction
log and a custom console component. This method is only available in API version 31.0 or later.
Syntax
sforce.console.cti.onCallLogSaved( eventHandler:Function )
Arguments
Name Type Description
eventHandler function For a standard interaction log, eventHandler is a function that is executed when
a call log is saved. For a custom interaction log, eventHandler is a function that
is executed when the fireOnCallLogSaved API is called in your Visualforce
page.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
sforce.console.cti.onCallLogSaved(callback);
</script>
<p>Registered onCallLogSaved listener...</p>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
95
Methods for Salesforce Classic onSendCTIMessage()
onSendCTIMessage()
Registers a function that is fired when a message is sent with the sendCTIMessage(). Use to get information or send information
between an interaction log and a custom console component. This method is only available in API version 31.0 or later.
Syntax
sforce.console.cti.onSendCTIMessage( eventHandler:Function )
Arguments
Name Type Description
eventHandler function JavaScript method called when a message is sent with the sendCTIMessage()
method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
};
sforce.console.cti.onSendCTIMessage(callback);
function sendCTIMessage() {
sforce.console.cti.sendCTIMessage('sending a message to CTI');
}
</script>
<a href="#" onClick="sendCTIMessage();return false">
Send a message to see your listener receiving it!</a>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
96
Methods for Salesforce Classic sendCTIMessage()
sendCTIMessage()
Sends a message to the CTI adapter or Open CTI. This method is for computer-telephony integration (CTI); it’s only available in API version
24.0 or later.
Syntax
sforce.console.cti.sendCTIMessage( msg, (optional) callback:Function )
Arguments
Name Type Description
msg string Message to send to the adapter.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
97
Methods for Salesforce Classic setCallAttachedData()
setCallAttachedData()
Sets the call data associated with a call object ID. Use to get information or send information between an interaction log and a custom
console component.This method is only available in API version 31.0 or later.
Syntax
sforce.console.cti.setCallAttachedData( callObjectId:String, callData:JSON string
callType:String, (optional)callback:Functional)
Arguments
Name Type Description
callObjectId string The object ID of the call.
callData string JSON string that specifies the data to attach to the call.
callType string String that specifies the call type, such as internal, inbound, or outbound.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testSetCallAttachedData();return false">
Click here to set call attached data </A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCallAttachedData() {
//callData must be a JSON string. We assume that your browser has
//access to a JSON library.
var callData = JSON.stringify({"ANI":"4155551212", "DNIS":"8005551212"});
98
Methods for Salesforce Classic setCallObjectIds()
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
setCallObjectIds()
Sets call object IDs, in ascending order of arrival. This method is only available in API version 31.0 or later.
Syntax
sforce.console.cti.setCallObjectIds( callObjectIds:Array, callback:Function )
Arguments
Name Type Description
callObjectId array An array of string IDs specifying the calls to set.
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="testSetCallObjectIds();return false">
Click here to set call object Ids</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function checkResult(result) {
if (result.success) {
alert('Call object ids set successfully!');
} else {
alert('Call object ids cannot be set!');
}
}
function testSetCallObjectIds() {
sforce.console.cti.setCallObjectIds(['call.1', 'call.2', 'call.3'],
checkResult);
}
</script>
</apex:page>
99
Methods for Salesforce Classic Methods for Application-Level Custom Console Components
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
IN THIS SECTION:
addToBrowserTitleQueue()
Adds a browser tab title to a list of titles, which rotates every three seconds. This method is only available in API version 28.0 or later.
blinkCustomConsoleComponentButtonText()
Blinks a button’s text on an application-level custom console component that’s on a page. This method is only available in API version
25.0 or later.
isCustomConsoleComponentPoppedOut()
Determines if a custom console component is popped out from a browser. To use this method, multi-monitor components must
be turned on. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce Classic” in the
online help. This method is only available in API version 30.0 or later.
isCustomConsoleComponentWindowHidden()
Determines if the application-level custom console component window is hidden. This method is available in API versions 25.0
through 31.0.
isCustomConsoleComponentHidden()
Determines if the application-level custom console component window is hidden. This method is available in API version 32.0 and
later. In API version 31.0 and earlier, this method was called isCustomConsoleComponentWindowHidden().
isInCustomConsoleComponent()
Determines if the page is in an application-level custom console component. This method is only available in API version 25.0 or
later.
onCustomConsoleComponentButtonClicked()
Registers a function to call when a button is clicked on an application-level custom console component. This method is only available
in API version 25.0 or later.
onFocusedPrimaryTab()
Registers a function to call when the focus of the browser changes to a different primary tab. This method is only available in API
version 25.0 or later.
100
Methods for Salesforce Classic addToBrowserTitleQueue()
removeFromBrowserTitleQueue()
Removes a browser tab title from the list of titles, which rotates every three seconds. This method is only available in API version
28.0 or later.
runSelectedMacro()
Executes the selected macro in the macro widget. This method is only available in API version 36.0 or later.
scrollCustomConsoleComponentButtonText()
Scrolls a button’s text on an application-level custom console component that’s on a page. This method is only available in API
version 25.0 or later.
selectMacro()
Selects and displays a specific macro in the macro widget. This method is only available in API version 36.0 or later.
setCustomConsoleComponentButtonIconUrl()
Sets the button icon URL of an application-level custom console component that’s on a page. This method is only available in API
version 25.0 or later.
setCustomConsoleComponentButtonStyle()
Sets the style of a button used to launch an application-level custom console component that’s on a page. This method is only
available in API version 25.0 or later.
setCustomConsoleComponentButtonText()
Sets the text on a button used to launch an application-level custom console component that’s on a page. This method is only
available in API version 25.0 or later.
setCustomConsoleComponentHeight()
Sets the window height of an application-level custom console component that’s on a page. This method is available in API version
32.0 or later.
setCustomConsoleComponentVisible()
Sets the window visibility of an application-level custom console component that’s on a page. This method is available in API version
32.0 and later. In API version 31.0 and earlier, this method was called setCustomConsoleComponentWindowVisible().
setCustomConsoleComponentWidth()
Sets the window width of an application-level custom console component that’s on a page. This method is available in API version
32.0 or later.
setCustomConsoleComponentPopoutable()
Sets a custom console component to be popped out or popped into a browser. To use this method, multi-monitor components
must be turned on. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce Classic” in
the online help. This method is only available in API version 30.0 or later.
setCustomConsoleComponentWindowVisible()
Sets the window visibility of an application-level custom console component that’s on a page. This method is available in API versions
25.0 through 31.0.
setSidebarVisible()
Shows or hides a console sidebar based on tabId and region. This method is available in API version 33.0 or later.
addToBrowserTitleQueue()
Adds a browser tab title to a list of titles, which rotates every three seconds. This method is only available in API version 28.0 or later.
101
Methods for Salesforce Classic blinkCustomConsoleComponentButtonText()
Syntax
sforce.console.addToBrowserTitleQueue( title:String, callback:Function )
Arguments
Name Type Description
title string Browser tab title that is displayed.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page >
<A HREF="#" onClick="testAddToBrowserTitleQueue();return false">
Click here to enqueue a browser title</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testAddToBrowserTitleQueue() {
var title = 'TestTitle';
sforce.console.addToBrowserTitleQueue(title);
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
callback function JavaScript method that’s called upon completion of the method.
blinkCustomConsoleComponentButtonText()
Blinks a button’s text on an application-level custom console component that’s on a page. This method is only available in API version
25.0 or later.
Syntax
sforce.console.blinkCustomConsoleComponentButtonText(alternateText:String, interval:number,
(optional)callback:Function)
102
Methods for Salesforce Classic isCustomConsoleComponentPoppedOut()
Arguments
Name Type Description
alternateText string The alternate text to display when the button text blinks.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testBlinkCustomConsoleComponentButtonText() {
//Blink the custom console component button text
sforce.console.blinkCustomConsoleComponentButtonText('Hello World', 10,
function(result){
if (result.success) {
alert('The text blinking starts!');
} else {
alert('Could not initiate the text blinking!');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
isCustomConsoleComponentPoppedOut()
Determines if a custom console component is popped out from a browser. To use this method, multi-monitor components must be
turned on. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce Classic” in the online
help. This method is only available in API version 30.0 or later.
103
Methods for Salesforce Classic isCustomConsoleComponentWindowHidden()
Syntax
sforce.console.isCustomConsoleComponentPoppedOut (callback:Function)
Arguments
Name Type Description
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function checkResult(result) {
if (result.success) {
alert('Is this component popped out: ' + result.poppedOut);
} else {
alert('Error invoking this method. Check the browser developer console for
more information.');
}
}
function checkPoppedOut() {
sforce.console.isCustomConsoleComponentPoppedOut(checkResult);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
isCustomConsoleComponentWindowHidden()
Determines if the application-level custom console component window is hidden. This method is available in API versions 25.0 through
31.0.
104
Methods for Salesforce Classic isCustomConsoleComponentWindowHidden()
Note: If this method is called from a popped out component in a Salesforce console where multi-montior components is turned
on, nothing will happen. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce
Classic” in the online help. Starting in API version 32.0, this method is no longer available and has been replaced by
isCustomConsoleComponentHidden(). For more information, see “isCustomConsoleComponentHidden().”
Syntax
sforce.console.isCustomConsoleComponentWindowHidden((optional) callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testIsCustomConsoleComponentWindowHidden() {
sforce.console.isCustomConsoleComponentWindowHidden(checkWindowVisibility);
}
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
105
Methods for Salesforce Classic isCustomConsoleComponentHidden()
isCustomConsoleComponentHidden()
Determines if the application-level custom console component window is hidden. This method is available in API version 32.0 and later.
In API version 31.0 and earlier, this method was called isCustomConsoleComponentWindowHidden().
Syntax
sforce.console.isCustomConsoleComponentHidden((optional) callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testIsCustomConsoleComponentHidden() {
sforce.console.isCustomConsoleComponentHidden(checkWindowVisibility);
}
</apex:page>
106
Methods for Salesforce Classic isInCustomConsoleComponent()
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
isInCustomConsoleComponent()
Determines if the page is in an application-level custom console component. This method is only available in API version 25.0 or later.
Syntax
sforce.console.isInCustomConsoleComponent((optional) callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testIsInCustomConsoleComponent() {
sforce.console.isInCustomConsoleComponent(checkInComponent);
}
</script>
107
Methods for Salesforce Classic onCustomConsoleComponentButtonClicked()
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
success boolean true if returning the page status was successful; false if returning the page
status wasn't successful.
onCustomConsoleComponentButtonClicked()
Registers a function to call when a button is clicked on an application-level custom console component. This method is only available
in API version 25.0 or later.
Syntax
sforce.console.onCustomConsoleComponentButtonClicked(eventHandler:Function)
Arguments
Name Type Description
callback function JavaScript method called when a button is clicked on a custom console component.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('The Custom Console Component button is clicked. The component ID
is: ' + result.id +
' and the component window is: ' + (result.windowHidden ? 'hidden' :
'visible'));
};
sforce.console.onCustomConsoleComponentButtonClicked(eventHandler);
</script>
</apex:page>
108
Methods for Salesforce Classic onFocusedPrimaryTab()
windowHidden boolean true if the custom console component window is hidden after the button is clicked;
false if the custom console component window is visible after the button is
clicked.
onFocusedPrimaryTab()
Registers a function to call when the focus of the browser changes to a different primary tab. This method is only available in API version
25.0 or later.
Syntax
sforce.console.onFocusedPrimaryTab(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when the focus of the browser changes to a different
primary tab.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('Focus changed to a different primary tab. The primary tab ID is:'
+ result.id + 'and the object Id is:' + result.objectId);
};
sforce.console.onFocusedPrimaryTab(eventHandler);
</script>
</apex:page>
109
Methods for Salesforce Classic removeFromBrowserTitleQueue()
objectId string The object ID of the primary tab on which the browser is focused or null if no object
exists.
removeFromBrowserTitleQueue()
Removes a browser tab title from the list of titles, which rotates every three seconds. This method is only available in API version 28.0 or
later.
Syntax
sforce.console.removeFromBrowserTitleQueue( title:String, callback:Function )
Arguments
Name Type Description
title string Browser tab title to remove.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
110
Methods for Salesforce Classic runSelectedMacro()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
callback function JavaScript method that’s called upon completion of the method.
runSelectedMacro()
Executes the selected macro in the macro widget. This method is only available in API version 36.0 or later.
Syntax
sforce.console.runSelectedMacro ((optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that is called when the method is completed
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="executeInWidget();return false">Click here to run a macro</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function executeInWidget() {
sforce.console.runSelectedMacro();
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
success boolean true if running the macro was successful; false otherwise
111
Methods for Salesforce Classic scrollCustomConsoleComponentButtonText()
scrollCustomConsoleComponentButtonText()
Scrolls a button’s text on an application-level custom console component that’s on a page. This method is only available in API version
25.0 or later.
Syntax
sforce.console.scrollCustomConsoleComponentButtonText(interval:number, pixelsToScroll:number,
isLeftScrolling:boolean, (optional)callback:Function)
Arguments
Name Type Description
interval number Controls how often the button text is scrolled in milliseconds.
pixelsToScroll number Controls how many pixels the button text scrolls.
isLeftScrolling boolean If true, the text scrolls left. If false, the text scrolls right.
callback function JavaScript method that’s called upon completion of the method.
Tip: Try to give buttons short names. Scrolling is limited to the width of the button. If a button name is too long, scrolling can
restart before the name finishes displaying.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testScrollCustomConsoleComponentButtonText() {
//Scroll the custom console component button text from right to left
sforce.console.scrollCustomConsoleComponentButtonText(500, 10, true,
function(result){
if (result.success) {
alert('The text scrolling starts!');
} else {
alert('Could not initiate the text scrolling!');
}
});
}
</script>
</apex:page>
112
Methods for Salesforce Classic selectMacro()
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
selectMacro()
Selects and displays a specific macro in the macro widget. This method is only available in API version 36.0 or later.
Syntax
sforce.console.selectMacro(macroId:String, (optional)callback:Function)
Arguments
Name Type Description
callback function JavaScript method that is called when the method is completed
Sample Code–Visualforce
<apex:page>
<A HREF="#" onClick="openInWidget('0JZ00123456789A');return false">Click here to select
a macro</A>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function openInWidget(id) {
sforce.console.selectMacro(id);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
success boolean true if selecting the macro was successful; false otherwise
113
Methods for Salesforce Classic setCustomConsoleComponentButtonIconUrl()
setCustomConsoleComponentButtonIconUrl()
Sets the button icon URL of an application-level custom console component that’s on a page. This method is only available in API version
25.0 or later.
Syntax
sforce.console.setCustomConsoleComponentButtonIconUrl(iconURL:String,
(optional)callback:Function)
Arguments
Name Type Description
iconUrl string A URL that points to an image that’s used as a button to launch a custom console
component.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentButtonIconUrl() {
sforce.console.setCustomConsoleComponentButtonIconUrl('http://imageserver/img.png');
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
114
Methods for Salesforce Classic setCustomConsoleComponentButtonStyle()
setCustomConsoleComponentButtonStyle()
Sets the style of a button used to launch an application-level custom console component that’s on a page. This method is only available
in API version 25.0 or later.
Syntax
sforce.console.setCustomConsoleComponentButtonStyle(style:String, (optional)callback:
Function)
Arguments
Name Type Description
style string The style of a button used to launch a custom console component. The styles
supported include font, font color, and background color. Font and font color isn’t
available for Internet Explorer® 7.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentButtonStyle() {
sforce.console.setCustomConsoleComponentButtonStyle('background:red;');
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
115
Methods for Salesforce Classic setCustomConsoleComponentButtonText()
setCustomConsoleComponentButtonText()
Sets the text on a button used to launch an application-level custom console component that’s on a page. This method is only available
in API version 25.0 or later.
Syntax
sforce.console.setCustomConsoleComponentButtonText(text:String, (optional)callback:Function)
Arguments
Name Type Description
text string Text that’s displayed on a button used to launch a custom console component.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentButtonText() {
//Change the custom console component button text to 'Hello World'
sforce.console.setCustomConsoleComponentButtonText('Hello World');
}
</script>
</apex:page>
Response
Name Type Description
success boolean true if setting the button text was successful; false if setting the button text
wasn't successful.
setCustomConsoleComponentHeight()
Sets the window height of an application-level custom console component that’s on a page. This method is available in API version 32.0
or later.
116
Methods for Salesforce Classic setCustomConsoleComponentVisible()
Note: If this method is called from a popped out component in a Salesforce console where multi-monitor components is turned
on, nothing will happen. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce
Classic” in the Salesforce Help.
Syntax
sforce.console.setCustomConsoleComponentHeight( height:number, (optional)callback:Function)
Arguments
Name Type Description
height number The new height in pixels.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentHeight() {
// Set the custom console component height
sforce.console.setCustomConsoleComponentHeight(100);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
setCustomConsoleComponentVisible()
Sets the window visibility of an application-level custom console component that’s on a page. This method is available in API version
32.0 and later. In API version 31.0 and earlier, this method was called setCustomConsoleComponentWindowVisible().
117
Methods for Salesforce Classic setCustomConsoleComponentWidth()
Syntax
sforce.console.setCustomConsoleComponentVisible(visible:Boolean,
(optional)callback:Function)
Arguments
Name Type Description
visible boolean true to make the custom console component window visible, false to hide
the custom console component window.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentVisible() {
// Make the custom console component window visible
sforce.console.setCustomConsoleComponentVisible(true);
}
</script>
</apex:page>
Response
Name Type Description
success boolean true if setting the button window visibility was successful; false if setting the
button window visibility wasn't successful.
setCustomConsoleComponentWidth()
Sets the window width of an application-level custom console component that’s on a page. This method is available in API version 32.0
or later.
Note: If this method is called from a popped out component in a Salesforce console where multi-monitor components is turned
on, nothing will happen. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce
Classic” in the Salesforce Help.
118
Methods for Salesforce Classic setCustomConsoleComponentPopoutable()
Syntax
sforce.console.setCustomConsoleComponentWidth( width:number, callback:Function)
Arguments
Name Type Description
width number The new width in pixels.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentWidth() {
// Set the custom console component width
sforce.console.setCustomConsoleComponentWidth(100);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
setCustomConsoleComponentPopoutable()
Sets a custom console component to be popped out or popped into a browser. To use this method, multi-monitor components must
be turned on. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce Classic” in the online
help. This method is only available in API version 30.0 or later.
Syntax
sforce.console.setCustomConsoleComponentPopoutable(popoutable:Boolean,
(optional)callback:Function)
119
Methods for Salesforce Classic setCustomConsoleComponentPopoutable()
Arguments
Name Type Description
popoutable boolean If true, the component can be popped out or popped into a browser. If false,
the component cannot be popped out or popped into a browser.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function checkResult(result) {
if (result.success) {
alert('The method was successfully invoked.');
} else {
alert('Error while invoking this method. Check the browser developer console
for more information.');
}
}
function enablePopout() {
sforce.console.setCustomConsoleComponentPopoutable(true, checkResult);
}
function disablePopout() {
sforce.console.setCustomConsoleComponentPopoutable(false, checkResult);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
120
Methods for Salesforce Classic setCustomConsoleComponentWindowVisible()
setCustomConsoleComponentWindowVisible()
Sets the window visibility of an application-level custom console component that’s on a page. This method is available in API versions
25.0 through 31.0.
Note: If this method is called from a popped out component in a Salesforce console where multi-montior components is turned
on, nothing will happen. For more information, see “Turn On Multi-Monitor Components for a Salesforce Console in Salesforce
Classic” in the Salesforce Help. Starting in API version 32.0, this method is no longer available and has been replaced by
setCustomConsoleComponentVisible(). For more information, see
setCustomConsoleComponentVisible().
Syntax
sforce.console.setCustomConsoleComponentWindowVisible(visible:Boolean,
(optional)callback:Function)
Arguments
Name Type Description
visible boolean true to make the custom console component window visible, false to hide
the custom console component window.
callback function JavaScript method that’s called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testSetCustomConsoleComponentWindowVisible() {
//Make the custom console component window visible
sforce.console.setCustomConsoleComponentWindowVisible(true);
}
</script>
</apex:page>
Response
Name Type Description
success boolean true if setting the button window visibility was successful; false if setting the
button window visibility wasn't successful.
121
Methods for Salesforce Classic setSidebarVisible()
setSidebarVisible()
Shows or hides a console sidebar based on tabId and region. This method is available in API version 33.0 or later.
Syntax
sforce.console.setSidebarVisible( visible:Boolean, (optional)tabId:String,
(optional)region:String, (optional)callback:Function)
Arguments
Name Type Description
visible boolean true to show the sidebar or false to hide the sidebar.
tabId string The ID of the tab on which to show or hide the sidebar.
region string The region on the console where the sidebar is located, such as left or right, top or
bottom. Regions are represented as:
• sforce.console.Region.LEFT
• sforce.console.Region.RIGHT
• sforce.console.Region.TOP
• sforce.console.Region.BOTTOM
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
sforce.console.setSidebarVisible(true,'scc-st-1',sforce.console.Region.LEFT,callback);
}
</script>
<A HREF="#" onClick="setSidebarVisible(); return false">SetSidebarToExpand</A>
</apex:page>
122
Methods for Salesforce Classic Methods for Push Notifications
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
IN THIS SECTION:
addPushNotificationListener()
Adds a listener for a push notification. A user can only register a listener once until he or she removes the listener, or the listener is
removed by another user. This method is only available in API version 26.0 or later.
removePushNotificationListener()
Removes a listener that gets added for a push notification. This method is only available in API version 26.0 or later.
123
Methods for Salesforce Classic addPushNotificationListener()
addPushNotificationListener()
Adds a listener for a push notification. A user can only register a listener once until he or she removes the listener, or the listener is
removed by another user. This method is only available in API version 26.0 or later.
For more information on push notifications, see Methods for Push Notifications on page 123.
Syntax
sforce.console.addPushNotificationListener( objects: array, eventHandler:Function )
Arguments
Name Type Description
objects array Objects set to receive notifications.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
Response
This method is asynchronous so it returns its response in an object in a callback method.
entityType string The type of object included in the push notification. For example, Account or Contact.
Objects available for push notifications are determined by the administrator who
set up a Salesforce console. For more information, see “Configure Push Notifications
for a Salesforce Console in Salesforce Classic” in the Salesforce online help.
124
Methods for Salesforce Classic removePushNotificationListener()
LastModifiedById string The user ID of the user who last modified the object in the push notification.
removePushNotificationListener()
Removes a listener that gets added for a push notification. This method is only available in API version 26.0 or later.
For more information on push notifications, see Methods for Push Notifications on page 123.
Syntax
sforce.console.removePushNotificationListener((optional) callback:Function )
Arguments
Name Type Description
callback function A function called when the removal of the push notification listener completes.
Sample Code–Visualforce
<apex:page standardController="Case">
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testRemovePushNotification() {
sforce.console.removePushNotificationListener(removeSuccess);
}
var removeSuccess = function removeSuccess(result) {
//Report whether removing the push notification listener is successful
if (result.success == true) {
alert('Removing push notification was successful');
} else {
alert('Removing push notification wasn't successful');
}
125
Methods for Salesforce Classic Methods for Console Events
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method.
sforce.console.ConsoleEvent.CLOSE_TAB Fired when a primary tab or subtab with a • id — The ID of the closed tab.
specified ID in the additionalParams
• objectID — The object ID of the
argument is closed. Or, fired when a primary
closed tab, if available.
tab or subtab with no specified ID is closed.
Available in API version 30.0 or later. Note: For some objects (such as Email and
Case Comment), the tab is opened and
closed immediately and no object ID is
generated for the tab. In those cases, this
field’s value is equal to the parent’s object
ID.
126
Methods for Salesforce Classic addEventListener()
IN THIS SECTION:
addEventListener()
Adds a listener for a custom event type or a standard event type when the event is fired. This method adds a listener for custom
event types in API version 25.0 or later; it adds a listener for standard event types in API version 30.0 or later.
fireEvent()
Fires a custom event. This method is only available in API version 25.0 or later.
removeEventListener()
Removes a listener for a custom event type or a standard event type. This method removes a listener for custom event types in API
version 25.0 or later; it removes a listener for standard event types in API version 30.0 or later.
addEventListener()
Adds a listener for a custom event type or a standard event type when the event is fired. This method adds a listener for custom event
types in API version 25.0 or later; it adds a listener for standard event types in API version 30.0 or later.
For the list of standard events, see Methods for Console Events on page 126.
Syntax
sforce.console.addEventListener( eventType: String, eventListener:Function,
(optional)additionalParams:Object )
127
Methods for Salesforce Classic addEventListener()
Arguments
Name Type Description
eventType string Custom event type for which eventListener listens.
additionalParams object Optional parameters accepted by this method. The supported properties on this
object are tabId: The ID of the tab to listen for the specified event.
This argument is only available in API version 30.0 or later.
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
128
Methods for Salesforce Classic fireEvent()
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
fireEvent()
Fires a custom event. This method is only available in API version 25.0 or later.
129
Methods for Salesforce Classic fireEvent()
Syntax
sforce.console.fireEvent( eventType:String, message:String, (optional)callback:Function
)
Arguments
Name Type Description
eventType string The type of custom event to fire.
message string The message which is sent with the fired event.
callback function JavaScript method called when the custom event is fired.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
function testFireEvent() {
//Fire an event of type 'SampleEvent'
sforce.console.fireEvent('SampleEvent', 'EventMessage', callback);
}
</script>
</apex:page>
Response
This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following
field:
130
Methods for Salesforce Classic removeEventListener()
removeEventListener()
Removes a listener for a custom event type or a standard event type. This method removes a listener for custom event types in API
version 25.0 or later; it removes a listener for standard event types in API version 30.0 or later.
For the list of standard events, see Methods for Console Events on page 126.
Syntax
sforce.console.removeEventListener( eventType: String, eventListener:Function,
(optional)additionalParams:Object )
Arguments
Name Type Description
eventType string Event type for which eventListener is removed.
additionalParams object Optional parameters accepted by this method. The supported properties on this
object are tabId: The ID of the tab to remove the listener for the specified event.
This argument is only available in API version 30.0 or later.
<script type="text/javascript">
var listener = function (result) {
alert('Message received from event: ' + result.message);
};
//Add a listener for the 'SampleEvent' event type
sforce.console.addEventListener('SampleEvent', listener);
function testRemoveEventListener() {
sforce.console.removeEventListener('SampleEvent', listener);
}
</script>
</apex:page>
Response
None
131
Methods for Salesforce Classic Methods for Live Agent
<script type="text/javascript">
var tabId;
};
function testRemoveEventListener() {
sforce.console.removeEventListener(sforce.console.ConsoleEvent.CLOSE_TAB,
onEnclosingPrimaryTabClose, { tabId : tabId });
}
</script>
</apex:page>
Response
None
Note: These methods don’t work for chats routed with Omni-Channel. Chats with Omni-Channel routing use the Methods for
Omni-Channel. If you’re using Lightning Experience, use the Methods for Omni-Channel in Lightning Experience.
132
Methods for Salesforce Classic Methods for Live Agent
IN THIS SECTION:
acceptChat()
Accepts a chat request. Available in API version 29.0 or later. This method isn't supported with Omni-Channel in API version 37.0 or
later.
cancelFileTransferByAgent()
Indicates that a file transfer request has been canceled by an agent. Available in API version 31.0 or later.
declineChat()
Declines a chat request. Available in API version 29.0 or later. This method isn't supported with Omni-Channel in API version 37.0 or
later.
endChat()
Ends a chat in which an agent is currently engaged. Available in API version 29.0 or later.
getAgentInput()
Returns the string of text which is currently in the agent’s text input area in the chat log of a chat with a specific chat key. Available
in API version 29.0 or later.
getAgentState()
Returns the agent's current Live Agent status, such as Online, Away, or Offline. Available in API version 29.0 or later.
getChatLog()
Returns the chat log of a chat associated with a specific chat key. Available in API version 29.0 or later.
getChatRequests()
Returns the chat keys of the chat requests that have been assigned to an agent. Available in API version 29.0 or later.
getDetailsByChatKey()
Returns the details of the chat associated with a specific chat key. Available in API version 29.0 or later.
getDetailsByPrimaryTabId()
Returns the details of the chat associated with a specific primary tab ID. Available in API version 29.0 or later.
getEngagedChats()
Returns the chat keys of the chats in which the agent is currently engaged. Available in API version 29.0 or later.
getMaxCapacity()
Returns the maximum chat capacity for the current agent, as specified in the agent's assigned agent configuration. Available in API
version 29.0 or later.
initFileTransfer()
Initiates the process of transferring a file from a customer to an agent. Available in API version 31.0 or later.
onAgentSend()
Registers a function to call when an agent sends a chat message through the Salesforce console. This method intercepts the message
and occurs before it is sent to the chat visitor. Available in API version 29.0 or later.
onAgentStateChanged()
Registers a function to call when agents change their Live Agent status, such as from Online to Away. Available in API version 29.0
or later.
onChatCanceled()
Registers a function to call when a chat visitor cancels a chat request. Available in API version 29.0 or later.
onChatCriticalWaitState()
Registers a function to call when a chat becomes critical to answer or a waiting chat is answered. Available in API version 29.0 or
later.
133
Methods for Salesforce Classic acceptChat()
onChatDeclined()
Registers a function to call when an agent declines a chat request. Available in API version 29.0 or later.
onChatEnded()
Registers a function to call when an engaged chat ends. Available in API version 29.0 or later.
onChatRequested()
Registers a function to call when an agent receives a chat request. Available in API version 29.0 or later.
onChatStarted()
Registers a function to call when an agent starts a new chat with a customer. Available in API version 29.0 or later.
onChatTransferredOut()
Registers a function to call when an engaged chat is transferred out to another agent. Available in API version 29.0 or later.
onCurrentCapacityChanged()
Registers a function to call when an agent's capacity for accepting chats changes—for example, if an agent accepts a new chat,
ends a currently engaged chat, or otherwise changes the number of chats to which they are assigned, or if a chat request is pushed
to their chat queue. Available in API version 29.0 or later.
onCustomEvent()
Registers a function to call when a custom event takes place during a chat. Available in API version 29.0 or later.
onFileTransferCompleted()
Registers a function to call when a file is transferred from a customer to an agent. Available in API version 31.0 or later.
onNewMessage()
Registers a function to call when a new message is sent from a customer, agent, or supervisor. Available in API version 29.0 or later.
onTypingUpdate()
Registers a function to call when the customer’s text in the chat window changes. If Sneak Peek is enabled, this function is called
whenever the customer edits the text in the chat window. If Sneak Peek is not enabled, this function is called whenever a customer
starts or stops typing in the chat window. Available in API version 29.0 or later.
sendCustomEvent()
Sends a custom event to the client-side chat window for a chat with a specific chat key. Available in API version 29.0 or later.
sendMessage()
Sends a new chat message from the agent to a chat with a specific chat key. Available in API version 29.0 or later.
setAgentInput()
Sets the string of text in the agent’s text input area in the chat log of a chat with a specific chat key.Available in API version 29.0 or
later.
setAgentState()
Sets an agent's Live Agent status, such as Online, Away, or Offline. Available in API version 29.0 or later.
Methods for Live Agent Chat Visitors
There are a few methods available that you can use to customize the chat visitor experience for Live Agent in a custom Visualforce
chat window. These methods apply to Salesforce Classic only.
acceptChat()
Accepts a chat request. Available in API version 29.0 or later. This method isn't supported with Omni-Channel in API version 37.0 or later.
134
Methods for Salesforce Classic acceptChat()
Syntax
sforce.console.chat.acceptChat(chatKey:String, (optional)callback:Function)
Arguments
Name Type Description
chatKey String The chat key for the chat request you wish to accept.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testAcceptChat();return false;">Accept Chat</a>
<script type="text/javascript">
function testAcceptChat() {
//Get the value for 'myChatKey'from the getChatRequests() or onChatRequested()
methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.acceptChat(chatKey, acceptSuccess);
}
function acceptSuccess(result) {
//Report whether accepting the chat was succesful
if (result.success == true) {
alert('Accepting the chat was successful');
} else {
alert('Accepting the chat was not successful');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
135
Methods for Salesforce Classic cancelFileTransferByAgent()
cancelFileTransferByAgent()
Indicates that a file transfer request has been canceled by an agent. Available in API version 31.0 or later.
Syntax
sforce.console.chat.cancelFileTransferByAgent(chatKey:String, (optional)callback:Function)
Arguments
Name Type Description
chatKey String The chat key for the chat for which the agent canceled the file transfer request.
callback function JavaScript method that is called when the method is completed.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testCancelFileTransfer();return false;">Cancel file transfer</a>
<script type="text/javascript">
function testCancelFileTransfer() {
//Gets the value for 'myChatKey'from the getChatRequests() or onChatRequested()
methods.
//These values are for example purposes only.
var chatKey = 'myChatKey';
sforce.console.chat.cancelFileTransferByAgent(chatKey, fileSuccess);
}
function fileSuccess(result) {
//Report whether canceling was successful
if (result.success == true) {
alert('Canceling file transfer was successful.');
} else {
alert('Canceling file transfer was not successful.');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
136
Methods for Salesforce Classic declineChat()
declineChat()
Declines a chat request. Available in API version 29.0 or later. This method isn't supported with Omni-Channel in API version 37.0 or later.
Syntax
sforce.console.chat.declineChat(chatKey:String, (optional)callback:Function)
Arguments
Name Type Description
chatKey String The chat key for the request you wish to decline.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testDeclineChat();return false;">Decline Chat</a>
<script type="text/javascript">
function testDeclineChat() {
//Get the value for 'myChatKey'from the getChatRequests() or onChatRequested()
methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.declineChat(chatKey, declineSuccess);
}
function declineSuccess(result) {
//Report whether declining the chat was succesful
if (result.success == true) {
alert('Declining the chat was successful');
} else {
alert('Declining the chat was not successful');
}
};
</script>
</apex:page>
137
Methods for Salesforce Classic endChat()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
endChat()
Ends a chat in which an agent is currently engaged. Available in API version 29.0 or later.
Syntax
sforce.console.chat.endChat(chatKey:String, (optional)callback:Function)
Arguments
Name Type Description
chatKey String The chat key for the engaged chat you wish to end.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testEndChat();return false;">End Chat</a>
<script type="text/javascript">
function testEndChat() {
//Get the value for 'myChatKey'from the getEngagedChats() or onChatStarted()
methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.endChat(chatKey, endSuccess);
}
function endSuccess(result) {
//Report whether ending the chat was succesful
if (result.success == true) {
alert('Ending the chat was successful');
} else {
alert('Ending the chat was not successful');
}
};
138
Methods for Salesforce Classic getAgentInput()
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
getAgentInput()
Returns the string of text which is currently in the agent’s text input area in the chat log of a chat with a specific chat key. Available in
API version 29.0 or later.
Syntax
sforce.console.chat.getAgentInput(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to retrieve the agent’s input text.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetAgentInput();">Get Agent Input</a>
<script type="text/javascript">
function testGetAgentInput() {
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.getAgentInput(chatKey, getAgentInputSuccess);
}
function getAgentInputSuccess(result) {
//Report whether getting the agent's input was successful
if (result.success == true) {
139
Methods for Salesforce Classic getAgentState()
agentInput = result.text;
alert('The text in the agent input is: ' + agentInput);
} else {
alert('Getting the agent input was not successful');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if getting the agent’s input was successful; false if getting the agent’s
input wasn’t successful.
getAgentState()
Returns the agent's current Live Agent status, such as Online, Away, or Offline. Available in API version 29.0 or later.
Syntax
sforce.console.chat.getAgentState(callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetAgentState();return false;">Get Agent State</a>
<script type="text/javascript">
function testGetAgentState() {
sforce.console.chat.getAgentState(function(result) {
if (result.success) {
alert('Agent State:' + result.state);
140
Methods for Salesforce Classic getChatLog()
} else {
alert('getAgentState has failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if getting the agent’s Live Agent status was successful; false if getting the
agent’s Live Agent status wasn’t successful.
getChatLog()
Returns the chat log of a chat associated with a specific chat key. Available in API version 29.0 or later.
Syntax
sforce.console.chat.getChatLog(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to retrieve the chat log.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetChatLog();">Get Chat Log</a>
<script type="text/javascript">
function testGetChatLog() {
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
141
Methods for Salesforce Classic getChatLog()
function getChatLogSuccess(result) {
//Report whether getting the chat log was succesful
if (result.success == true) {
chatLogMessage = result.messages[0].content;
alert('The first message in this chatLog is: ' + chatLogMessage);
} else {
alert('Getting the chat log was not successful');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
fields:
messages Array of An array of chat message objects containing all of the chat messages from the chat
message log.
objects
success Boolean true if getting the chat log was successful; false if getting the chat log wasn’t
successful.
customEvent
The customEvent object contains a single event from the chat log and the following properties:
data String The data of the custom event that was sent to the chat; corresponds to the data
argument of the liveagent.chasitor.sendCustomEvent() method
used to send this event from the chat window.
timestamp Date/Time The date and time a custom event was received.
142
Methods for Salesforce Classic getChatRequests()
message
The message object contains a single chat message from the chat log and the following properties:
name String The name of the user who sent the message in the chat log. This appears exactly as
it is displayed in the chat log.
type String The type of message that was received, such as Agent or Visitor.
timestamp Date/Time The date and time the chat message was received.
getChatRequests()
Returns the chat keys of the chat requests that have been assigned to an agent. Available in API version 29.0 or later.
Syntax
sforce.console.chat.getChatRequests(callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetChatRequests();return false;">Get Chat Requests</a>
<script type="text/javascript">
function testGetChatRequests() {
sforce.console.chat.getChatRequests(function(result) {
if (result.success) {
alert('Number of Chat Requests ' + result.chatKey.length);
} else {
alert('getChatRequests has failed');
}
});
}
</script>
</apex:page>
143
Methods for Salesforce Classic getDetailsByChatKey()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if getting chat requests was successful; false if getting chat requests wasn’t
successful.
getDetailsByChatKey()
Returns the details of the chat associated with a specific chat key. Available in API version 29.0 or later.
Syntax
sforce.console.chat.getDetailsByChatKey(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to retrieve details.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetDetailsByChatKey();">Get Chat Details</a>
<script type="text/javascript">
function testGetDetailsByChatKey() {
//Get the value for 'myChatKey' from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.getDetailsByChatKey(chatKey, getDetailsSuccess);
}
function getDetailsSuccess(result) {
//Report whether accepting the chat was succesful
if (result.success == true) {
ipAddress = result.details.ipAddress;
alert('The Visitor IP Address for this chat is: ' + ipAddress);
} else {
144
Methods for Salesforce Classic getDetailsByChatKey()
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
details Object An object that contains all the details for a chat associated with a particular primary
tab.
success Boolean true if retrieving the details was successful; false if retrieving the details wasn’t
successful.
details
The details object contains the following properties:
breadcrumbs Array of An array of breadcrumb objects representing a list of Web pages visited by
breadcrumb the visitor before and during the chat.
objects
customDetails Array of An array of customDetail objects that represent custom details that have
customDetail been passed in to this chat via the Deployment API or Pre-Chat Form API.
objects
geoLocation Object An object representing the details of a chat visitor’s location, derived from a
geoIP lookup on the chat visitor's IP address.
isEnded Boolean Specifies whether a chat has ended (true) or not (false).
isEngaged Boolean Specifies whether a chat is currently engaged (true) or not (false).
isPushRequest Boolean Specifies whether a chat was routed to an agent through a push-based routing
method such as Least Active or Most Available (true) or not (false).
145
Methods for Salesforce Classic getDetailsByChatKey()
liveChatButtonId String The 15-digit record ID for the chat button from which the chat request originated.
liveChatDeploymentId String The 15-digit record ID for the deployment from which the chat request originated.
requestTime Date/Time The date and time the chat was requested.
visitorInfo Object An object containing information about the visitor's web browser.
breadcrumb
A breadcrumb represents a Web page viewed by a chat visitor. The breadcrumb object contains the following properties:
time Date/Time The date and time a chat visitor visited a specific breadcrumb URL.
customDetail
Custom details are details have been passed into the chat through the Deployment API or Pre-Chat Form API. The customDetail
object contains the following properties:
value String The value of the custom detail as specified in the Deployment API or Pre-Chat Form
API.
transcriptFields Array of Strings The names of fields where the customer’s details on the chat transcript are saved.
entityMaps Array of An array of pre-created records used for mapping custom detail information.
entityMap
objects
entityMap
Entities are records that are created when a customer starts a chat with an agent. You can use the API to auto-populate these records
with customer details. The entityMap object contains the following properties:
146
Methods for Salesforce Classic getDetailsByChatKey()
isFastFillable Boolean Specifies whether the value can be used to populate the field when an agent creates
or edits a record (true) or not (false) (Live Agent console only).
isAutoQueryable Boolean If you’re using the Live Agent console, specifies whether to perform a a SOSL query
(in the Live Agent console) (true) or not (false) to find records with a
fieldName containing the value.
If you’re using the Salesforce console, specifies whether to perform a SOQL query
(in the Salesforce console) (true) or not (false) to find records with a
fieldName containing the value.
isExactMatchable Boolean Specifies whether to only search for records that have fields exactly matching the
field fieldName (true) or not (false).
geoLocation
The geoLocation object represents the details of a chat visitor’s location. It contains the following properties:
countryCode String The two-digit ISO-3166 country code for the chat visitor's country.
organization String The organization name of the chat visitor's internet service provider.
visitorInfo
The visitorInfo object represents information about the visitor's web browser. It contains the following properties:
originalReferrer String The original URL of the Web page from which the chat visitor requested a chat.
screenResolution String The screen resolution of the chat visitor's computer, as passed by the chat visitor’s
browser.
147
Methods for Salesforce Classic getDetailsByPrimaryTabId()
getDetailsByPrimaryTabId()
Returns the details of the chat associated with a specific primary tab ID. Available in API version 29.0 or later.
Syntax
sforce.console.chat.getDetailsByPrimaryTabId(primaryTabId:String, callback:Function)
Arguments
Name Type Description
primaryTabId String The ID of the primary tab associated with the chat for which to retrieve details.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetDetailsByPrimaryTabId();">Get Chat Details</a>
<script type="text/javascript">
function testGetDetailsByPrimaryTabId() {
//Get the value for 'myPrimaryTabId'from the getPrimaryTabIds() or
getEnclosingPrimaryTabId() methods.
//These values are for example purposes only
var primaryTabId = 'myPrimaryTabId';
sforce.console.chat.getDetailsByPrimaryTabId(primaryTabId, getDetailsSuccess);
function getDetailsSuccess(result) {
//Report whether accepting the chat was succesful
if (result.success == true) {
console.log(result);
chatKey = result.details.chatKey;
alert('The chatKey for this chat is: ' + chatKey);
} else {
alert('Getting the details was not Succesful');
}
};
148
Methods for Salesforce Classic getDetailsByPrimaryTabId()
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
details Object An object that contains all the details for a chat associated with a particular primary
tab.
success Boolean true if retrieving the details was successful; false if retrieving the details wasn’t
successful.
details
The details object contains the following properties:
breadcrumbs Array of An array of breadcrumb objects representing a list of Web pages visited by
breadcrumb the visitor before and during the chat.
objects
customDetails Array of An array of customDetail objects that represent custom details that have
customDetail been passed in to this chat via the Deployment API or Pre-Chat Form API.
objects
geoLocation Object An object representing the details of a chat visitor’s location, derived from a
geoIP lookup on the chat visitor's IP address.
isEnded Boolean Specifies whether a chat has ended (true) or not (false).
isEngaged Boolean Specifies whether a chat is currently engaged (true) or not (false).
isPushRequest Boolean Specifies whether a chat was routed to an agent through a push-based routing
method such as Least Active or Most Available (true) or not (false).
isTransferringOut Boolean Specifies whether a chat is currently in the process of being transferred to another
agent (true) or not (false).
liveChatButtonId String The 15-digit record ID for the chat button from which the chat request originated.
liveChatDeploymentId String The 15-digit record ID for the deployment from which the chat request originated.
149
Methods for Salesforce Classic getDetailsByPrimaryTabId()
requestTime Date/Time The date and time the chat was requested.
visitorInfo Object An object containing information about the visitor's web browser.
breadcrumb
A breadcrumb represents a Web page viewed by a chat visitor. The breadcrumb object contains the following properties:
time Date/Time The date and time a chat visitor visited a specific breadcrumb URL.
customDetail
Custom details are details that have been passed into the chat through the Deployment API or Pre-Chat Form API. The customDetail
object contains the following properties:
value String The value of the custom detail as specified in the Deployment API or Pre-Chat Form
API.
transcriptFields Array of Strings The names of fields where the customer’s details on the chat transcript are saved.
entityMaps Array of An array of pre-created records used for mapping the custom detail information.
entityMap
objects
entityMap
Entities are records that are created when a customer starts a chat with an agent. You can use the API to auto-populate these records
with customer details. The entityMap object contains the following properties:
isFastFillable Boolean Specifies whether the value can be used to populate the field when an agent creates
or edits a record (true) or not (false) (Live Agent console only).
150
Methods for Salesforce Classic getDetailsByPrimaryTabId()
isExactMatchable Boolean Specifies whether to only search for records that have fields exactly matching the
field fieldName (true) or not (false).
geoLocation
The geoLocation object represents the details of a chat visitor’s location. It contains the following properties:
countryCode String The two-digit ISO-3166 country code for the chat visitor's country.
organization String The organization name of the chat visitor's internet service provider.
visitorInfo
The visitorInfo object represents information about the visitor's web browser. It contains the following properties:
originalReferrer String The original URL of the Web page from which the chat visitor requested a chat.
screenResolution String The screen resolution of the chat visitor's computer, as passed by the chat visitor’s
browser.
sessionKey String the sessionKey of the visitor which will ultimately be stored on the LiveChatVisitor
record as a unique reference to this live chat visitor
151
Methods for Salesforce Classic getEngagedChats()
getEngagedChats()
Returns the chat keys of the chats in which the agent is currently engaged. Available in API version 29.0 or later.
Syntax
sforce.console.chat.getEngagedChats(callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetEngagedChats();return false;">Get Engaged Chats</a>
<script type="text/javascript">
function testGetEngagedChats() {
sforce.console.chat.getEngagedChats(function(result) {
if (result.success) {
alert('Number Engaged Chats: ' + result.chatKey.length);
} else {
alert('getEngagedChats has failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success boolean true if getting engaged chats was successful; false if getting engaged chats
wasn’t successful.
152
Methods for Salesforce Classic getMaxCapacity()
getMaxCapacity()
Returns the maximum chat capacity for the current agent, as specified in the agent's assigned agent configuration. Available in API
version 29.0 or later.
Syntax
sforce.console.chat.getMaxCapacity(callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetMaxCapacity();return false;">Get Max Capacity</a>
<script type="text/javascript">
function testGetMaxCapacity() {
sforce.console.chat.getMaxCapacity(function(result) {
if (result.success) {
alert('max capacity '+result.count);
} else {
alert('getMaxCapacity failed, agent my not be online');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success boolean true if getting the agent’s capacity was successful; false if getting the agent’s
capacity wasn’t successful.
153
Methods for Salesforce Classic initFileTransfer()
initFileTransfer()
Initiates the process of transferring a file from a customer to an agent. Available in API version 31.0 or later.
Syntax
sforce.console.chat.initFileTransfer(chatKey:String, entityId:String,
(optional)callback:Function)
Arguments
Name Type Description
chatKey String The chat key for the chat the file is transferred from.
entityId String The ID of the transcript object to attach the transferred file to.
callback function JavaScript method that is called when the method is completed.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testInitFileTransfer();return false;">Init file transfer</a>
<script type="text/javascript">
function testInitFileTransfer() {
//Gets the value for 'myChatKey'from the getChatRequests() or onChatRequested()
methods.
//These values are for example purposes only.
var chatKey = 'myChatKey'; var entityId = 'myEntityId';
sforce.console.chat.initFileTransfer(chatKey, entityId, fileSuccess);
}
function fileSuccess(result) {
//Reports whether initiating the file transfer was successful.
if (result.success == true) {
alert('Initiating file transfer was successful.');
} else {
alert('Initiating file transfer was not successful.');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
154
Methods for Salesforce Classic onAgentSend()
Note: A value of true doesn’t necessarily mean that the file was successfully
transferred to an agent. Rather, it indicates that the request to begin a file
transfer was sent successfully.
onAgentSend()
Registers a function to call when an agent sends a chat message through the Salesforce console. This method intercepts the message
and occurs before it is sent to the chat visitor. Available in API version 29.0 or later.
Note: This method is only called when an agent sends a message through the chat window interface. This method doesn’t apply
when a sendMessage() method is called in the API.
Syntax
sforce.console.chat.onAgentSend(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to call a function when the agent
sends a message.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
var theMessage = result.content;
alert('The agent is attempting to send the following message: ' +
result.content);
sforce.console.chat.sendMessage(chatKey, theMessage)
alert('The following message has been sent: ' + theMessage);
}
//Get the value for 'myChatKey' from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.onAgentSend(chatKey, eventHandler);
</script>
</apex:page>
155
Methods for Salesforce Classic onAgentStateChanged()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
name String The name of the agent who is attempting to send the message as it appears in the
chat log.
type String The type of message that was received—for example, agent.
timestamp Date/Time The date and time the agent attempted to send the chat message.
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onAgentStateChanged()
Registers a function to call when agents change their Live Agent status, such as from Online to Away. Available in API version 29.0 or
later.
Syntax
sforce.console.chat.onAgentStateChanged(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when the agent's Live Agent status has changed.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert("Agent's State has Changed to: " + result.state);
};
sforce.console.chat.onAgentStateChanged(eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
156
Methods for Salesforce Classic onChatCanceled()
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onChatCanceled()
Registers a function to call when a chat visitor cancels a chat request. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onChatCanceled(callback:Function)
Arguments
Name Type Description
callback function JavaScript method called upon completion of the method.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('The chat request has been canceled for this chatKey: ' + result.chatKey);
}
sforce.console.chat.onChatCanceled(eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
onChatCriticalWaitState()
Registers a function to call when a chat becomes critical to answer or a waiting chat is answered. Available in API version 29.0 or later.
157
Methods for Salesforce Classic onChatDeclined()
Syntax
sforce.console.chat.onChatCanceled(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which the critical wait state has changed.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('This chat has reached a critical wait');
}
//Get the value for 'myChatKey' from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.onChatCriticalWaitState(chatKey, eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
onChatDeclined()
Registers a function to call when an agent declines a chat request. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onChatDeclined(eventHandler:Function)
158
Methods for Salesforce Classic onChatEnded()
Arguments
Name Type Description
eventHandler function JavaScript method called when a chat request is declined.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('A chat request with this chatKey has been declined: ' + result.chatKey);
}
sforce.console.chat.onChatDeclined(eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onChatEnded()
Registers a function to call when an engaged chat ends. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onChatEnded(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when an engaged chat ends.
159
Methods for Salesforce Classic onChatRequested()
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('A chat with this chatKey has ended: ' + result.chatKey);
}
sforce.console.chat.onChatEnded(eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onChatRequested()
Registers a function to call when an agent receives a chat request. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onChatRequested(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when a chat request is assigned to an agent.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('There is a new incoming chat request with this chatKey: ' +
result.chatKey);
}
sforce.console.chat.onChatRequested(eventHandler);
160
Methods for Salesforce Classic onChatStarted()
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onChatStarted()
Registers a function to call when an agent starts a new chat with a customer. Available in API version 29.0 or later.
Usage
Syntax
sforce.console.chat.onChatStarted(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when a chat request is accepted and becomes an engaged
chat.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('A new engaged chat has started for this chatKey: ' + result.chatKey);
}
sforce.console.chat.onChatStarted(eventHandler);
</script>
</apex:page>
161
Methods for Salesforce Classic onChatTransferredOut()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onChatTransferredOut()
Registers a function to call when an engaged chat is transferred out to another agent. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onChatTransferredOut(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when a chat has been successfully transferred out to another
agent.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('A chat with this chatKey has been transferred out: ' + result.chatKey);
}
sforce.console.chat.onChatTransferredOut(eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event wasn’t successful.
162
Methods for Salesforce Classic onCurrentCapacityChanged()
onCurrentCapacityChanged()
Registers a function to call when an agent's capacity for accepting chats changes—for example, if an agent accepts a new chat, ends a
currently engaged chat, or otherwise changes the number of chats to which they are assigned, or if a chat request is pushed to their
chat queue. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onCurrentCapacityChanged(eventHandler:Function)
Arguments
Name Type Description
eventHandler function JavaScript method called when the agent's capacity for accepting chats has changed.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('Capacity Changed. Current Requests + Engaged Chats is now: ' +
result.count);
}
sforce.console.chat.onCurrentCapacityChanged(eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onCustomEvent()
Registers a function to call when a custom event takes place during a chat. Available in API version 29.0 or later.
163
Methods for Salesforce Classic onCustomEvent()
Syntax
sforce.console.chat.onCustomEvent(chatKey:String, type:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to call a function when a custom
event takes place.
type String The name of the custom event you want to listen for. This should match the name
of the custom event sent from the chat window.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('A new custom event has been received of type ' + result.type + ' and
with data: ' + result.data );
}
//Get the value for 'myChatKey' from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
var type = 'myCustomEventType';
sforce.console.chat.onCustomEvent(chatKey, type, eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
data String The data of the custom event that was sent to this chat; corresponds to the data
argument of the liveagent.chasitor.sendCustomEvent() method
used to send this event from the chat window.
source String The source of the custom event that was sent to this chat; corresponds to either the
agent or the chat visitor, depending on who triggered the custom event.
164
Methods for Salesforce Classic onFileTransferCompleted()
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onFileTransferCompleted()
Registers a function to call when a file is transferred from a customer to an agent. Available in API version 31.0 or later.
Syntax
sforce.console.chat.onFileTransferCompleted(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chat key for the chat the file was transferred from.
callback function JavaScript method that is called when the method is complete.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testOnFileComplete();return false;">test on file transfer
complete</a>
<script type="text/javascript">
function testOnFileComplete() {
//Gets the value for 'myChatKey'from the getChatRequests() or onChatRequested()
methods.
//These values are for example purposes only.
var chatKey = 'myChatKey';
sforce.console.chat.onFileTransferCompleted(chatKey, fileSuccess);
}
function fileSuccess(result) {
//Reports status of the file transfer.
if (result.success == true) {
alert('File transfer was successful.');
} else {
alert('File transfer was not successful.');
}
};
</script>
</apex:page>
165
Methods for Salesforce Classic onNewMessage()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
success Boolean true if firing event was successful; false if firing event was unsuccessful.
onNewMessage()
Registers a function to call when a new message is sent from a customer, agent, or supervisor. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onNewMessage(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey string The chatKey associated with the chat for which to call a function when a new
customer message is received.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('There is a new message in this chat: ' + result.content);
}
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.onNewMessage(chatKey, eventHandler);
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
166
Methods for Salesforce Classic onTypingUpdate()
name String The name of the user who sent the message. This appears exactly as it is displayed
in the chat log.
type String The type of message that was received, such as an Agent or Visitor message.
timestamp Date/Time The date and time the message was received.
success Boolean true if firing event was successful; false if firing event wasn’t successful.
onTypingUpdate()
Registers a function to call when the customer’s text in the chat window changes. If Sneak Peek is enabled, this function is called whenever
the customer edits the text in the chat window. If Sneak Peek is not enabled, this function is called whenever a customer starts or stops
typing in the chat window. Available in API version 29.0 or later.
Syntax
sforce.console.chat.onTypingUpdate(chatKey:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to call a function when a customer
begins typing a new message to the agent.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<script type="text/javascript">
var eventHandler = function (result) {
alert('There is a new typing update in this chat');
}
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
sforce.console.chat.onTypingUpdate(chatKey, eventHandler);
</script>
</apex:page>
167
Methods for Salesforce Classic sendCustomEvent()
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
sneakPeek String The text the chat visitor is currently typing into their input box in the chat window.
This is visible only if Sneak Peek is enabled for the agent.
success Boolean true if firing event was successful; false if firing event wasn’t successful.
sendCustomEvent()
Sends a custom event to the client-side chat window for a chat with a specific chat key. Available in API version 29.0 or later.
Syntax
sforce.console.chat.sendCustomEvent(chatKey:String, type:String, data:String,
callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat to which to send a custom event.
type String The name of the custom event you want to send to the chat window.
data String Additional data you want to send to the chat window along with the custom event.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testSendCustomEvent();">Send Custom Event</a>
<script type="text/javascript">
function testSendCustomEvent() {
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
var type = 'myCustomEventType'
var data = 'myCustomEventData'
168
Methods for Salesforce Classic sendMessage()
function sendCustomEventSuccess(result) {
//Report whether sending the custom event was successful
if (result.success == true) {
alert('The customEvent has been sent');
} else {
alert('Sending the customEvent was not successful');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
sendMessage()
Sends a new chat message from the agent to a chat with a specific chat key. Available in API version 29.0 or later.
Syntax
sforce.console.chat.sendMessage(chatKey:String, message:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey of the chat where the agent’s message is sent.
message String The message you would like to send from the agent to the customer in a chat.
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
169
Methods for Salesforce Classic setAgentInput()
<script type="text/javascript">
function testSendMessage() {
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
var text ='This is sample text to send as a message';
sforce.console.chat.sendMessage(chatKey, text, sendMessageSuccess);
}
function sendMessageSuccess(result) {
//Report whether getting the chat log was successful
if (result.success == true) {
alert('Message Sent');
} else {
alert('Sending the message was not successful');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
setAgentInput()
Sets the string of text in the agent’s text input area in the chat log of a chat with a specific chat key.Available in API version 29.0 or later.
Syntax
sforce.console.chat.setAgentInput(chatKey:String, text:String, callback:Function)
Arguments
Name Type Description
chatKey String The chatKey associated with the chat for which to set the agent’s input text.
170
Methods for Salesforce Classic setAgentState()
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testSetAgentInput();">Set Agent Input</a>
<script type="text/javascript">
function testSetAgentInput() {
//Get the value for 'myChatKey'from the
sforce.console.chat.getDetailsByPrimaryTabId() or other chat methods.
//These values are for example purposes only
var chatKey = 'myChatKey';
var text = 'This is example text to set the agent input'
sforce.console.chat.setAgentInput(chatKey, text, setAgentInputSuccess);
}
function setAgentInputSuccess(result) {
//Report whether setting the agent's input was succesful
if (result.success == true) {
alert('The text in the agent input has been updated');
} else {
alert('Setting the agent input was not Succesful');
}
};
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
setAgentState()
Sets an agent's Live Agent status, such as Online, Away, or Offline. Available in API version 29.0 or later.
171
Methods for Salesforce Classic Methods for Live Agent Chat Visitors
Syntax
sforce.console.chat.setAgentState(state:String, (optional)callback:Function)
Arguments
Name Type Description
state String Live Agent status you want to set the agent to—for example, Online, Away, or Offline.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testSetAgentState('Online');return false;">Set Agent Status to
Online</a>
<script type="text/javascript">
function testSetAgentState(state) {
sforce.console.chat.setAgentState(state, function(result) {
if (result.success) {
alert('Agent State Set to Online');
} else {
alert('setAgentState has failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
172
Methods for Salesforce Classic Methods for Live Agent Chat Visitors
IN THIS SECTION:
chasitor.addCustomEventListener()
Registers a function to call when a custom event is received in the chat window. Available in API version 29.0 or later.
chasitor.getCustomEvents()
Retrieves a list of custom events that have been received in this chat window during this chat session. Available in API version 29.0
or later.
chasitor.sendCustomEvent()
Sends a custom event to the agent console of the agent who is currently chatting with a customer. Available in API version 29.0 or
later.
chasitor.addCustomEventListener()
Registers a function to call when a custom event is received in the chat window. Available in API version 29.0 or later.
Syntax
liveagent.chasitor.addCustomEventListener(type:String, callback:Function)
Arguments
Sample Code–Visualforce
<script type="text/javascript">
function testAddCustomEventListener() {
//These values are for example purposes only
var type = 'myCustomEventType'
liveagent.chasitor.addCustomEventListener(type, customEventReceived)
}
function customEventReceived(result) {
eventType = result.getType();
eventData = result.getData();
alert('A custom event of type: ' + eventType + ' has been received with the
following data: ' + eventData);
};
testAddCustomEventListener();
</script>
173
Methods for Salesforce Classic Methods for Live Agent Chat Visitors
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
methods:
getData method Accesses the data of the custom event that was sent to this chat window. Returns
the data argument of the
sforce.console.chat.sendCustomEvent() method used to send
this event.
getSource method Accesses the source of the custom event that was sent to this chat window—for
example, agent or chat visitor.
getDate method Accesses the date of the custom event that was sent to this chat window. Returns
the date and time the event was received.
chasitor.getCustomEvents()
Retrieves a list of custom events that have been received in this chat window during this chat session. Available in API version 29.0 or
later.
Syntax
liveagent.chasitor.getCustomEvents()
Sample Code–Visualforce
<a href="#" onClick="testGetCustomEvents();">Get Custom Events</a>
<script type="text/javascript">
function testGetCustomEvents() {
events = liveagent.chasitor.getCustomEvents();
eventsCount = events.length;
alert('The following number of custom events have occurred: ' + eventsCount);
};
</script>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
methods and properties:
174
Methods for Salesforce Classic Methods for Live Agent Chat Visitors
getType method Accesses the type of the custom event that was sent to this chat window. Returns
the type argument of the
sforce.console.chat.sendCustomEvent() method used to send
this event.
getData method Accesses the data of the custom event that was sent to this chat window. Returns
the data argument of the
sforce.console.chat.sendCustomEvent() method used to send
this event.
getSource method Accesses the source of the custom event that was sent to this chat window—for
example, agent or chat visitor.
getDate method Accesses the date of the custom event that was sent to this chat window. Returns
the date and time the event was received.
chasitor.sendCustomEvent()
Sends a custom event to the agent console of the agent who is currently chatting with a customer. Available in API version 29.0 or later.
Syntax
liveagent.chasitor.sendCustomEvent(type:String, data:String)
Arguments
data string Additional data you want to send to the agent console along with the custom event.
Sample Code–Visualforce
<a href="#" onClick="testSendCustomEvent();">Send Custom Event</a>
<script type="text/javascript">
function testSendCustomEvent() {
type = 'myCustomEventType';
175
Methods for Salesforce Classic Methods for Omni-Channel
data = 'myCustomEventData';
liveagent.chasitor.sendCustomEvent(type, data);
alert('The custom event has been sent');
};
</script>
Response
This method returns no responses.
IN THIS SECTION:
acceptAgentWork
Accepts a work item that’s assigned to an agent. Available in API versions 32.0 and later.
closeAgentWork
Changes the status of a work item to “Closed” and removes it from the list of work items in the Omni-Channel widget. Available in
API versions 32.0 and later.
declineAgentWork
Declines a work item that’s assigned to an agent. Available in API versions 32.0 and later.
getAgentWorks
Returns a list of work items that are currently assigned to an agent and open in the agent’s workspace. Available in API versions 32.0
and later.
getAgentWorkload
In API version 35.0 and later, we can retrieve an agent’s currently assigned workload. Use this method for rerouting work to available
agents.
getServicePresenceStatusChannels
Retrieves the service channels that are associated with an Omni-Channel user’s current presence status. Available in API versions
32.0 and later.
getServicePresenceStatusId
Retrieves an agent’s current presence status. Available in API versions 32.0 and later.
login
Logs an agent into Omni-Channel with a specific presence status. Available in API versions 32.0 and later.
logout
Logs an agent out of Omni-Channel. Available in API versions 32.0 and later.
setServicePresenceStatus
Sets an agent's presence status to a status with a particular ID. In API version 35.0 and later, we log the user into presence if that user
is not already logged in. This will remove the need for you to make additional calls.
176
Methods for Salesforce Classic acceptAgentWork
acceptAgentWork
Accepts a work item that’s assigned to an agent. Available in API versions 32.0 and later.
Syntax
sforce.console.presence.acceptAgentWork(workId:String, (optional) callback:function)
Arguments
Name Type Description
workId String The ID of the work item the agent accepts.
callback function JavaScript method to call when an agent accepts the work item associated with the
workId.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testAcceptWork();return false;">Accept Assigned Work Item</a>
<script type="text/javascript">
function testAcceptWork() {
//First get the ID of the assigned work item to accept it
sforce.console.presence.getAgentWorks(function(result) {
if (result.success) {
var works = JSON.parse(result.works);
var work = works[0];
if (!work.isEngaged) {
//Now that we have the assigned work item ID, we can accept it
sforce.console.presence.acceptAgentWork(work.workId,
function(result) {
if (result.success) {
alert('Accepted work successfully');
} else {
alert('Accept work failed');
}
});
} else {
alert('The work item has already been accepted');
}
}
});
177
Methods for Salesforce Classic closeAgentWork
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
closeAgentWork
Changes the status of a work item to “Closed” and removes it from the list of work items in the Omni-Channel widget. Available in API
versions 32.0 and later.
Syntax
sforce.console.presence.closeAgentWork(workId:String, (optional) callback:function)
Arguments
Name Type Description
workId String The ID of the work item that’s closed.
callback function JavaScript method to call when the work item associated with the workId is
closed.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testCloseWork();return false;">Close Engaged Work Item</a>
<script type="text/javascript">
function testCloseWork() {
//First get the ID of the engaged work item to close it
sforce.console.presence.getAgentWorks(function(result) {
if (result.success) {
var works = JSON.parse(result.works);
var work = works[0];
if (work.isEngaged) {
//Now that we have the engaged work item ID, we can close it
sforce.console.presence.closeAgentWork(work.workId,function(result)
{
178
Methods for Salesforce Classic declineAgentWork
if (result.success) {
alert('Closed work successfully');
} else {
alert('Close work failed');
}
});
} else {
alert('The work item should be accepted first');
}
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
declineAgentWork
Declines a work item that’s assigned to an agent. Available in API versions 32.0 and later.
Syntax
sforce.console.presence.declineAgentWork(workId:String, (optional) declineReason:String,
(optional) callback:function)
Arguments
Name Type Description
workId String The ID of the work item that the agent declines.
declineReason String The provided reason for why the agent declined the work request.
callback function JavaScript method to call when an agent declines the work item associated with the
workId.
179
Methods for Salesforce Classic getAgentWorks
Sample Code–Visualforce
<apex:page >
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testDeclineWork();return false;">Decline Assigned Work Item</a>
<script type="text/javascript">
function testDeclineWork() {
//First, get the ID of the assigned work item to accept it
sforce.console.presence.getAgentWorks(function(result) {
if (result.success) {
var works = JSON.parse(result.works);
var work = works[0];
sforce.console.presence.declineAgentWork(work.workId, function(result)
{
if (result.success) {
alert('Declined work successfully');
} else {
alert('Decline work failed');
}
});
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
getAgentWorks
Returns a list of work items that are currently assigned to an agent and open in the agent’s workspace. Available in API versions 32.0 and
later.
Syntax
sforce.console.presence.getAgentWorks(callback:function)
180
Methods for Salesforce Classic getAgentWorks
Arguments
Name Type Description
callback function JavaScript method to call when the list of an agent’s work items is retrieved.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetWorks();return false;">Get Agent’s Current Work Items</a>
<script type="text/javascript">
function testGetWorks() {
//These values are for example purposes only.
sforce.console.presence.getAgentWorks(function(result) {
if (result.success) {
alert('Get work items successful');
var works = JSON.parse(result.works);
alert('First Agent Work ID is: ' + works[0].workId);
alert('Assigned Entity Id of the first Agent Work is: ' +
works[0].workItemId);
alert('Is first Agent Work Engaged: ' + works[0].isEngaged);
} else {
alert('Get work items failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
works JSON string of A JSON string of work objects that represents the work items assigned to the agent
work objects that are open in the agent’s workspace.
work
The work object contains the following properties:
181
Methods for Salesforce Classic getAgentWorkload
isEngaged Boolean Indicates whether an agent is working on a work item that’s been assigned to them
(true) or not (false).
getAgentWorkload
In API version 35.0 and later, we can retrieve an agent’s currently assigned workload. Use this method for rerouting work to available
agents.
Syntax
sforce.console.presence.getAgentWorkload(callback:function)
Arguments
Name Type Description
callback function JavaScript method to call when the agent’s configured capacity and work retrieved.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetAgentWorkload();return false;">
Get Agent’s configured capacity and current workload
</a>
<script type="text/javascript">
function testGetAgentWorkload() {
sforce.console.presence.getAgentWorkload(function(result) {
if (result.success) {
alert('Retrieved Agent Configured Capacity and Current Workload
successfully');
alert('Agent\'s configured capacity is: ' + result.configuredCapacity);
182
Methods for Salesforce Classic getServicePresenceStatusChannels
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
configuredCapacity Number Indicates the agent’s configured capacity (work that’s assigned to the current user)
through Presence Configuration.
work
The work object contains the following properties:
isEngaged Boolean Indicates whether an agent is working on a work item that’s been assigned to them
(true) or not (false).
getServicePresenceStatusChannels
Retrieves the service channels that are associated with an Omni-Channel user’s current presence status. Available in API versions 32.0
and later.
Syntax
sforce.console.presence.getServicePresenceStatusChannels(callback:function)
Arguments
Name Type Description
callback function JavaScript method to call when the channels associated with a presence status are
retrieved.
183
Methods for Salesforce Classic getServicePresenceStatusId
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetChannels();return false;">
Get Channels Associated with a Presence Status
</a>
<script type="text/javascript">
function testGetChannels() {
//These values are for example purposes only.
sforce.console.presence.getServicePresenceStatusChannels(function(result) {
if (result.success) {
alert('Retrieved Service Presence Status Channels successfully');
var channels = JSON.parse(result.channels);
//For example purposes, just retrieve the first channel
alert('First channel ID is: ' + channels[0].channelId);
alert('First channel developer name is: ' + channels[0].developerName);
} else {
alert('Get Service Presence Status Channels failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
channels JSON string of Returns the IDs and API names of the channels associated with the presence status.
channel
objects
getServicePresenceStatusId
Retrieves an agent’s current presence status. Available in API versions 32.0 and later.
Syntax
sforce.console.presence.getServicePresenceStatusId(callback:function)
184
Methods for Salesforce Classic login
Arguments
Name Type Description
callback function JavaScript method to call when the agent’s presence status is retrieved.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testGetStatusId();return false;">Get Omni-Channel Status ID</a>
<script type="text/javascript">
function testGetStatusId() {
sforce.console.presence.getServicePresenceStatusId(function(result) {
if (result.success) {
alert('Get Status Id successful');
alert('Status Id is: ' + result.statusId);
} else {
alert('Get Status Id failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
statusApiName String The API name of the agent’s current presence status.
login
Logs an agent into Omni-Channel with a specific presence status. Available in API versions 32.0 and later.
Syntax
sforce.console.presence.login(statusId:String, (optional) callback:function)
185
Methods for Salesforce Classic logout
Arguments
Name Type Description
statusId String The ID of the presence status. Agents must be given access to this presence status
through their associated profile or permission set.
callback function JavaScript method to call when the agent is logged in with the presence status
associated with statusId.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testLogin('0N5xx00000000081');return false;">Log In to
Omni-Channel</a>
<script type="text/javascript">
function testLogin(statusId) {
//Gets the Salesforce ID of the presence status entity which the current user
has been assigned through their permission set or profile.
//These values are for example purposes only.
sforce.console.presence.login(statusId, function(result) {
if (result.success) {
alert('Login successful');
} else {
alert('Login failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
logout
Logs an agent out of Omni-Channel. Available in API versions 32.0 and later.
Syntax
sforce.console.presence.logout((optional) callback:function)
186
Methods for Salesforce Classic setServicePresenceStatus
Arguments
Name Type Description
callback function JavaScript method to call when the agent is logged out of Omni-Channel.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testLogout();return false;">Log out of Omni-Channel</a>
<script type="text/javascript">
function testLogout() {
sforce.console.presence.logout(function(result) {
if (result.success) {
alert('Logout successfully');
} else {
alert('Logout failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
setServicePresenceStatus
Sets an agent's presence status to a status with a particular ID. In API version 35.0 and later, we log the user into presence if that user is
not already logged in. This will remove the need for you to make additional calls.
Syntax
sforce.console.presence.setServicePresenceStatus(statusId:String,
(optional) callback:function)
187
Methods for Salesforce Classic setServicePresenceStatus
Arguments
Name Type Description
statusId String The ID of the presence status you want to set the agent to. Agents must be given
access to this presence status through their associated profile or permission set.
callback function JavaScript method to call when the agent’s status is changed to the presence status
associated with statusId.
Sample Code–Visualforce
<apex:page>
<apex:includeScript value="/support/console/42.0/integration.js"/>
<a href="#" onClick="testSetStatus('0N5xx00000000081');return false;">Set Presence
Status</a>
<script type="text/javascript">
function testSetStatus(statusId) {
//Sets the user’s presence status to statusID. Assumes that the user was
assigned this presence status through Setup.
//These values are for example purposes only
sforce.console.presence.setServicePresenceStatus(statusId, function(result) {
if (result.success) {
alert('Set status successful');
alert('Current statusId is: ' + result.statusId);
alert('Channel list attached to this status is: ' + result.channels);
//printout in console for lists
} else {
alert('Set status failed');
}
});
}
</script>
</apex:page>
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
statusApiName String The API name of the agent’s current presence status.
188
Methods for Salesforce Classic Methods for Omni-Channel Console Events
channels JSON string of Returns the IDs and API names of the channels associated with the presence status.
channel
objects
sforce.console.ConsoleEvent. Fired when a user changes • statusId—the ID of the agent’s current presence status.
PRESENCE.STATUS_CHANGED his or her presence status.
• channels—channelJSON string of channel objects.
Available in API version
• statusName—the name of the agent’s current presence
32.0 or later.
status.
• statusApiName—the API name of the agent’s current
presence status.
sforce.console.ConsoleEvent. Fired when a user is • workItemId—the ID of the object that’s routed through
PRESENCE.WORK_ASSIGNED assigned a new work item. Omni-Channel. This object becomes a work assignment with
Available in API version a workId when it’s assigned to an agent.
32.0 or later. • workId—the ID of a work assignment that’s routed to an
agent.
sforce.console.ConsoleEvent. Fired when a user accepts • workItemId—the ID of the object that’s routed through
PRESENCE.WORK_ACCEPTED a work assignment, or Omni-Channel. This object becomes a work assignment with
when a work assignment a workId when it’s assigned to an agent.
is automatically accepted.
189
Methods for Salesforce Classic Methods for Omni-Channel Console Events
sforce.console.ConsoleEvent. Fired when a user declines • workItemId—the ID of the object that’s routed through
PRESENCE.WORK_DECLINED a work assignment. Omni-Channel. This object becomes a work assignment with
Available in API version a workId when it’s assigned to an agent.
32.0 or later. • workId—the ID of a work assignment that’s routed to an
agent.
sforce.console.ConsoleEvent. Fired when a user closes a • workItemId—the ID of the object that’s routed through
PRESENCE.WORK_CLOSED tab in the console that’s Omni-Channel. This object becomes a work assignment with
associated with a work a workId when it’s assigned to an agent.
item. When the tab for
that work item is closed, •
workId—the ID of a work assignment that’s routed to an
the status of the agent.
AgentWork object
associated with it
automatically changes to
“Closed.”
Available in API version
32.0 or later.
channel
The channel object contains the following functions:
developerName String Retrieves the developer name of the the service channel that’s associated with the
channelId.
190
CHAPTER 6 Methods for Lightning Experience
If your org is using Lightning Experience, use Lightning Console JavaScript API methods.
IN THIS SECTION:
Methods for Workspace Tabs and Subtabs in Lightning Experience
A Lightning console app displays Salesforce pages as workspace tabs or subtabs. A workspace tab displays the main work item or
record, such as an account. A subtab displays related records, such as an account’s contacts or opportunities.
Methods for the Utility Bar in Lightning Experience
The utility bar houses Lightning components, and gives your users quick access to tools they use often. The utility bar is available in
Lightning Experience only.
Methods for Omni-Channel in Lightning Experience
Omni-Channel lets your call center route any type of incoming work item to the most qualified, available agents.
IN THIS SECTION:
closeTab() for Lightning Experience
Closes a workspace tab or subtab. This method works only in Lightning console apps.
focusTab() for Lightning Experience
Focuses a workspace tab or subtab. This method works only in Lightning console apps.
getAllTabInfo() for Lightning Experience
Returns information about all open tabs. This method works only in Lightning console apps.
getEnclosingTabId() for Lightning Experience
Returns the ID of the enclosing tab. This method works only in Lightning console apps.
getFocusedTabInfo() for Lightning Experience
Returns information about the focused workspace tab or subtab. This method works only in Lightning console apps.
getTabInfo() for Lightning Experience
Returns information about the specified tab. This method works only in Lightning console apps.
getTabURL() for Lightning Experience
Returns the URL of the specified tab. This method works only in Lightning console apps.
191
Methods for Lightning Experience closeTab() for Lightning Experience
Arguments
Sample Code
This component has a button that, when pressed, closes the currently focused tab.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
<lightning:workspaceAPI aura:id="workspace"/>
<lightning:button label="Close Focused Tab" onclick="{!c.closeFocusedTab}"/>
</aura:component>
Controller code:
({
closeFocusedTab : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getFocusedTabInfo().then(function(response) {
var focusedTabId = response.tabId;
192
Methods for Lightning Experience focusTab() for Lightning Experience
workspaceAPI.closeTab({tabId: focusedTabId});
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
Arguments
Sample Code
This component has a button that, when pressed, opens a new tab and focuses it.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Focus New Tab" onclick="{! c.focusNewTab }" />
</aura:component>
Controller code:
({
focusNewTab : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.openTab({
url: '#/sObject/001R0000003HgssIAC/view',
label: 'Global Media'
}).then(function(response) {
workspaceAPI.focusTab({tabId : response});
})
.catch(function(error) {
console.log(error);
});
}
})
193
Methods for Lightning Experience getAllTabInfo() for Lightning Experience
Note: The relative URL used in this example is a placeholder. Make sure to include a leading hashtag “#” when adding a relative
URL. To try this example yourself, use a relative URL with a record ID from your org.
Response
This method returns a promise that, upon success, resolves to true.
Arguments
None.
Sample Code
This component has a button that, when pressed, gets the info of all open tabs and prints the resulting tabInfo object.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Get All Tab Info" onclick="{! c.getAllTabInfo }" />
</aura:component>
Controller code:
({
getAllTabInfo : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getAllTabInfo().then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to an array of tabInfo objects. A tabInfo object is a JSON array of
information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo object.
{ tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
194
Methods for Lightning Experience getEnclosingTabId() for Lightning Experience
iconAlt: string,
recordId: string,
url: string (URL),
subtabs: [
{
tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
},
{ ... }
],
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
}
Arguments
None.
Sample Code
This component has a button that, when pressed, retrieves the enclosing tab ID.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Get Enclosing Tab Id" onclick="{! c.getEnclosingTabId }" />
</aura:component>
Controller code:
({
getEnclosingTabId : function(component, event, helper) {
195
Methods for Lightning Experience getFocusedTabInfo() for Lightning Experience
Response
This method returns a promise that, upon success, resolves to the tabId of the enclosing tab, if within a tab, or false if not within
a tab.
Arguments
None.
Sample Code
This component has a button that, when pressed, closes the currently focused tab.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Close Focused Tab" onclick="{! c.closeFocusedTab }" />
</aura:component>
Controller code:
({
closeFocusedTab : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getFocusedTabInfo().then(function(response) {
var focusedTabId = response.tabId;
workspaceAPI.closeTab({tabId: focusedTabId});
})
.catch(function(error) {
console.log(error);
});
}
})
196
Methods for Lightning Experience getTabInfo() for Lightning Experience
Response
This method returns a promise that, upon success, resolves to a tabInfo object representing the focused tab. A tabInfo object
is a JSON array of information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo
object.
{ tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
subtabs: [
{
tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
},
{ ... }
],
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
}
197
Methods for Lightning Experience getTabInfo() for Lightning Experience
Arguments
Sample Code
This component has a button that, when pressed, opens a tab and uses the getTabInfo() method to print the new tab’s tabInfo
to the developer console.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Get Opened Tab Info" onclick="{! c.getOpenedTabInfo }" />
</aura:component>
Controller code:
({
getOpenedTabInfo : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.openTab({
url: '#/sObject/001R0000003HgssIAC/view',
focus: true
}).then(function(response) {
workspaceAPI.getTabInfo({
tabId: response
}).then(function(response) {
console.log(response);
});
})
.catch(function(error) {
console.log(error);
});
}
})
Note: The relative URL used in this example is a placeholder. Make sure to include a leading hashtag “#” when adding a relative
URL. To try this example yourself, use a relative URL with a record ID from your org.
Response
This method returns a promise that, upon success, resolves to a tabInfo object representing the specified tab. A tabInfo object
is a JSON array of information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo
object.
{ tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
198
Methods for Lightning Experience getTabURL() for Lightning Experience
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
subtabs: [
{
tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
},
{ ... }
],
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
}
Arguments
Sample Code
This component has a button that, when pressed, opens a tab and uses the getTabURL() method to print the new tab’s URL to the
developer console.
199
Methods for Lightning Experience isConsoleNavigation() for Lightning Experience
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Get Opened Tab URL" onclick="{! c.getOpenedTabURL }" />
</aura:component>
Controller code:
({
getOpenedTabURL : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.openTab({
url: '#/sObject/001R0000003HgssIAC/view',
focus: true
}).then(function(response) {
workspaceAPI.getTabURL({
tabId: response
}).then(function(response) {
console.log(response);
});
})
.catch(function(error) {
console.log(error);
});
}
})
Note: The relative URL used in this example is a placeholder. Make sure to include a leading hashtag “#” when adding a relative
URL. To try this example yourself, use a relative URL with a record ID from your org.
Response
This method returns a promise that, upon success, resolves to the URL of the specified tab.
Arguments
None.
Sample Code
This component has a button that, when pressed, prints whether the current app is using console navigation.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Is Console Navigation?" onclick="{! c.isConsoleNavigation }"
200
Methods for Lightning Experience isSubtab() for Lightning Experience
/>
</aura:component>
Controller code:
({
isConsoleNavigation : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.isConsoleNavigation().then(function(response) {
console.log(response);
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to true if the current app uses console navigation, and false otherwise.
Arguments
Sample Code
This component has a button that checks whether the foucsed tab is a subtab and opens a modal with the answer.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Is the Focused Tab a Subtab?" onclick="{! c.isFocusedTabSubtab
}" />
</aura:component>
Controller code:
({
isFocusedTabSubtab : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getFocusedTabInfo().then(function(response) {
workspaceAPI.isSubtab({
tabId: response.tabId
}).then(function(response) {
201
Methods for Lightning Experience openSubtab() for Lightning Experience
if (response) {
confirm("This tab is a subtab.");
}
else {
confirm("This tab is not a subtab.");
}
});
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to true if the tab is a subtab, and false otherwise.
Arguments
202
Methods for Lightning Experience openTab() for Lightning Experience
Sample Code
This component has a button that, when pressed, opens a subtab within a workspace tab.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Open Tab with Subtab" onclick="{! c.openTabWithSubtab }" />
</aura:component>
Controller code:
({
openTabWithSubtab : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.openTab({
url: '#/sObject/001R0000003HgssIAC/view',
focus: true
}).then(function(response) {
workspaceAPI.openSubtab({
parentTabId: response,
url: '#/sObject/005R0000000INjPIAW/view',
focus: true
});
})
.catch(function(error) {
console.log(error);
});
}
})
Note: The relative URL used in this example is a placeholder. Make sure to include a leading hashtag “#” when adding a relative
URL. To try this example yourself, use a relative URL with a record ID from your org.
Response
This method returns a promise that, upon success, resolves to the ID of the new subtab.
Arguments
203
Methods for Lightning Experience openTab() for Lightning Experience
Sample Code
This component has a button that when pressed, opens a tab.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global">
<lightning:workspaceAPI aura:id="workspace"/>
<lightning:button label="Open Tab" onclick="{!c.openTab}"/>
</aura:component>
204
Methods for Lightning Experience setTabHighlighted() for Lightning Experience
}
})
Note: The relative URL used in this example is a placeholder. To try this example yourself, use a relative URL with a record ID from
your org.
Response
This method returns a promise that, upon success, resolves to the tabId of the new tab.
Arguments
Sample Code
This component has a button that, when pressed, sets the focused tab as highlighted.
205
Methods for Lightning Experience setTabHighlighted() for Lightning Experience
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<force:workspaceAPI aura:id="workspace" />
<lightning:button label="Set Focused Tab Highlighted" onclick="{!
c.setFocusedTabHighlighted }" />
</aura:component>
Controller code:
({
setFocusedTabHighlighted : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getFocusedTabInfo().then(function(response) {
var focusedTabId = response.tabId;
workspaceAPI.setTabHighlighted({
tabId: focusedTabId,
highlighted: true
});
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, returns a tabInfo object representing the modified tab. A tabInfo object is
a JSON array of information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo
object.
{ tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
subtabs: [
{
tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
isSubtab: boolean,
206
Methods for Lightning Experience setTabIcon() for Lightning Experience
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
},
{ ... }
],
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
}
Arguments
icon string An SLDS icon key. See a full list of icon keys
on the SLDS reference site.
Sample Code
This component has a button that, when pressed, sets the icon of the focused tab to the SLDS “Approval” action icon.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Set Focused Tab Icon" onclick="{! c.setFocusedTabIcon }" />
</aura:component>
Controller code:
({
setFocusedTabIcon : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getFocusedTabInfo().then(function(response) {
var focusedTabId = response.tabId;
workspaceAPI.setTabIcon({
tabId: focusedTabId,
icon: "action:approval",
iconAlt: "Approval"
});
207
Methods for Lightning Experience setTabLabel() for Lightning Experience
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to a tabInfo object representing the modified tab. A tabInfo object
is a JSON array of information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo
object.
{ tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
subtabs: [
{
tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
url: string (URL),
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
},
{ ... }
],
isSubtab: boolean,
parentTabId: string,
customTitle: string,
customIcon: string (URL),
customIconAlt: string
}
208
Methods for Lightning Experience setTabLabel() for Lightning Experience
Arguments
Sample Code
This component has a button that, when pressed, sets the label of the focused tab to “Focused Tab”.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<lightning:button label="Set Focused Tab with Label" onclick="{! c.setFocusedTabLabel
}" />
</aura:component>
Controller code:
({
setFocusedTabLabel : function(component, event, helper) {
var workspaceAPI = component.find("workspace");
workspaceAPI.getFocusedTabInfo().then(function(response) {
var focusedTabId = response.tabId;
workspaceAPI.setTabLabel({
tabId: focusedTabId,
label: "Focused Tab"
});
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to a tabInfo object representing the modified tab. A tabInfo object
is a JSON array of information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo
object.
{ tabId: string,
active: boolean,
pinned: boolean,
closeable: boolean,
highlighted: boolean,
title: string,
icon: string (SLDS iconKey),
iconAlt: string,
recordId: string,
209
Methods for Lightning Experience Methods for the Utility Bar in Lightning Experience
IN THIS SECTION:
getAllUtilityInfo() for Lightning Experience
Returns the state of all utilities as an array of utilityInfo objects.
getEnclosingUtilityId() for Lightning Experience
Returns the ID of the enclosing utility, or false if not within a utility.
getUtilityInfo() for Lightning Experience
Returns the state of the current utility as a utilityInfo object.
minimizeUtility() for Lightning Experience
Minimizes a utility.
openUtility() for Lightning Experience
Opens a utility. If the utility is already open, this method has no effect. Only one utility can be open at a time. If another utility is
already open, it is minimized.
210
Methods for Lightning Experience getAllUtilityInfo() for Lightning Experience
Arguments
None.
Sample Code
This component has a button that, when pressed, retrieves all utilityInfo objects and opens the first utility, ordered by ID.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Get All Utility Info" onclick="{! c.getAllUtilityInfo }" />
</aura:component>
Controller code:
({
getAllUtilityInfo : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.getAllUtilityInfo().then(function(response) {
var myUtilityInfo = response[0];
utilityAPI.openUtility({
utilityId: myUtilityInfo.id
});
})
211
Methods for Lightning Experience getEnclosingUtilityId() for Lightning Experience
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to an array of utilityInfo objects, containing the following fields.
Arguments
None.
Sample Code
This component has a button that, when pressed, retrieves the enclosing utility’s ID.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Get Enclosing Utility ID" onclick="{! c.getEnclosingUtilityId
}" />
</aura:component>
212
Methods for Lightning Experience getUtilityInfo() for Lightning Experience
Controller code:
({
getEnclosingTabId : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.getEnclosingUtilityId().then(function(utilityId) {
console.log(utilityId);
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to the utilityId of the enclosing utility or false if not within a utility.
Arguments
Sample Code
This component has a button that, when pressed, retrieves the enclosing utility’s info and opens it if it’s not currently visible, and closes
it otherwise.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Get Utility Info" onclick="{! c.getUtilityInfo }" />
</aura:component>
Controller code:
({
getUtilityInfo : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.getUtilityInfo().then(function(response) {
if (response.utilityVisible) {
utilityAPI.minimizeUtility();
}
else {
utilityAPI.openUtility();
213
Methods for Lightning Experience minimizeUtility() for Lightning Experience
}
})
.catch(function(error) {
console.log(error);
});
}
})
Response
This method returns a promise that, upon success, resolves to a utilityInfo object representing the enclosing utility, containing
the following fields.
Arguments
Sample Code
This component minimizes the utility when the button is pressed.
214
Methods for Lightning Experience openUtility() for Lightning Experience
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Minimize Utility" onclick="{! c.minimizeUtility }" />
</aura:component>
Controller code:
({
minimizeUtility : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.minimizeUtility();
}
})
Response
This method returns a promise that, upon success, resolves to true.
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, opens the utility when the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Open Utility" onclick="{! c.openUtility }" />
</aura:component>
Controller code:
({
openUtility : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.openUtility();
}
})
215
Methods for Lightning Experience setPanelHeaderIcon() for Lightning Experience
Response
This method returns a promise that, upon success, resolves to true.
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets the icon of the utility panel to the SLDS “frozen”
icon when the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Panel Header Icon" onclick="{! c.setPanelHeaderIcon }"
/>
</aura:component>
Controller code:
({
setPanelHeaderIcon : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setPanelHeaderIcon({
icon: “frozen”
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
216
Methods for Lightning Experience setPanelHeight() for Lightning Experience
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets the label of the utility panel to “My Utility”
when the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Panel Header Label" onclick="{! c.setPanelHeaderLabel }"
/>
</aura:component>
Controller code:
({
setPanelHeaderLabel : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setPanelHeaderLabel({
label: “My Utility”
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
Arguments
217
Methods for Lightning Experience setPanelWidth() for Lightning Experience
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets the height of the utility to 500 pixels when
the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Panel Height" onclick="{! c.setPanelHeight }" />
</aura:component>
Controller code:
({
setPanelHeight : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setPanelHeight({
heightPX: 500
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets the width of the utility panel to 800 pixels
when the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Panel Width" onclick="{! c.setPanelWidth }" />
</aura:component>
218
Methods for Lightning Experience setUtilityHighlighted() for Lightning Experience
Controller code:
({
setPanelWidth : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setPanelWidth({
widthPX: 800
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets a utility as highlighted when the button is
pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Utility Highlighted" onclick="{! c.setUtilityHighlighted}"
/>
</aura:component>
Controller code:
({
setUtilityHighlighted : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setUtilityHighlighted({
highlighted: true
});
219
Methods for Lightning Experience setUtilityIcon() for Lightning Experience
}
})
Response
This method returns a promise that, upon success, resolves to true.
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets the icon of the utility to the SLDS
“insert_tag_field” icon when the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Utility Icon" onclick="{! c.setUtilityIcon }" />
</aura:component>
Controller code:
({
setUtilityIcon : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setUtilityIcon({
icon: “insert_tag_field”
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
220
Methods for Lightning Experience setUtilityLabel() for Lightning Experience
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, sets the label of the utility to “My Favorite Utility”
when the button is pressed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Set Utility Label" onclick="{! c.setUtilityLabel }" />
</aura:component>
Controller code:
({
setUtilityLabel : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.setUtilityLabel({
label: “My Favorite Utility”
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
221
Methods for Lightning Experience Methods for Omni-Channel in Lightning Experience
Arguments
Sample Code
This component, when added to a single-column Lightning page used in a utility bar, has a button that, when pressed, toggles modal
mode.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:utilityBarAPI aura:id="utilitybar" />
<lightning:button label="Toggle Modal Mode" onclick="{! c.toggleModalMode }" />
</aura:component>
Controller code:
({
toggleModalMode : function(component, event, helper) {
var utilityAPI = component.find("utilitybar");
utilityAPI.toggleModalMode({
enableModalMode: true
});
}
})
Response
This method returns a promise that, upon success, resolves to true.
IN THIS SECTION:
acceptAgentWork for Lightning Experience
Accepts a work item that’s assigned to an agent.
closeAgentWork for Lightning Experience
Changes the status of a work item to “Closed” and removes it from the list of work items in the Omni-Channel utility.
declineAgentWork for Lightning Experience
Declines a work item that’s assigned to an agent.
222
Methods for Lightning Experience acceptAgentWork for Lightning Experience
Arguments
Name Type Description
workId string The ID of the work item the agent accepts.
callback function JavaScript method to call when an agent accepts the work item associated with the
workId.
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Accept" onclick="{! c.acceptWork }" />
</aura:component>
Controller code:
({
acceptWork: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getAgentWorks({
callback: function(result) {
var works = JSON.parse(result.works);
var work = works[0];
223
Methods for Lightning Experience closeAgentWork for Lightning Experience
omniAPI.acceptAgentWork({
workId: work.workId,
callback: function(result2) {
if (result2.success) {
console.log("Accepted work successfully");
} else {
console.log("Accept work failed");
}
}
});
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
Arguments
Name Type Description
workId string The ID of the work item that’s closed.
callback function JavaScript method to call when the work item associated with the workId is
closed.
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Close" onclick="{! c.closeWork }" />
</aura:component>
224
Methods for Lightning Experience declineAgentWork for Lightning Experience
Controller code:
({
closeWork: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getAgentWorks({
callback: function(result) {
var works = JSON.parse(result.works);
var work = works[0];
omniAPI.closeAgentWork({
workId: work.workId,
callback: function(result2) {
if (result2.success) {
console.log("Closed work successfully");
} else {
console.log("Close work failed");
}
}
});
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
Arguments
Name Type Description
workId string The ID of the work item that the agent declines.
declineReason string The provided reason for why the agent declined the work request.
callback function JavaScript method to call when an agent declines the work item associated with the
workId.
225
Methods for Lightning Experience getAgentWorks for Lightning Experience
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Decline" onclick="{! c.declineWork }" />
</aura:component>
Controller code:
({
declineWork: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getAgentWorks({
callback: function(result) {
var works = JSON.parse(result.works);
var work = works[0];
omniAPI.declineAgentWork({
workId: work.workId,
callback: function(result2) {
if (result2.success) {
console.log("Declined work successfully");
} else {
console.log("Decline work failed");
}
}
});
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
Arguments
Name Type Description
callback function JavaScript method to call when the list of an agent’s work items is retrieved.
226
Methods for Lightning Experience getAgentWorks for Lightning Experience
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Get Agent works" onclick="{! c.getAgentWorks }" />
</aura:component>
Controller code:
({
getAgentWorks: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getAgentWorks({
callback: function(result) {
if (result.success) {
console.log('Get work items successful');
var works = JSON.parse(result.works);
console.log('First Agent Work ID is: ' + works[0].workId);
console.log('Assigned Entity Id of the first Agent Work is: ' +
works[0].workItemId);
console.log('Is first Agent Work Engaged: ' + works[0].isEngaged);
} else {
console.log('Get work items failed');
}
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
works JSON string of A JSON string of work objects that represents the work items assigned to the agent
work objects that are open in the agent’s workspace.
work
The work object contains the following properties:
227
Methods for Lightning Experience getAgentWorkload for Lightning Experience
isEngaged Boolean Indicates whether an agent is working on a work item that’s been assigned to them
(true) or not (false).
Arguments
Name Type Description
callback function JavaScript method to call when the agent’s configured capacity and work is retrieved.
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Get workload" onclick="{! c.getAgentWorkload }" />
</aura:component>
Controller code:
({
getAgentWorkload: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getAgentWorkload({
callback: function(result) {
if (result.success) {
console.log('Retrieved Agent Configured Capacity and Current Workload
successfully');
console.log('Agent\'s configured capacity is: ' +
result.configuredCapacity);
console.log('Agent\'s currently assigned workload is: ' +
result.currentWorkload);
} else {
console.log('Get Agent Workload failed');
}
}
});
}
})
228
Methods for Lightning Experience getServicePresenceStatusChannels for Lightning Experience
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
configuredCapacity number The agent’s configured capacity (work that’s assigned to the current user) through
Presence Configuration.
work
The work object contains the following fields:
isEngaged boolean Indicates whether an agent is working on a work item that’s been assigned to them
(true) or not (false).
Arguments
Name Type Description
callback function JavaScript method to call when the channels associated with a presence status are
retrieved.
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Get Status Channels" onclick="{! c.getStatusChannels }" />
</aura:component>
229
Methods for Lightning Experience getServicePresenceStatusId for Lightning Experience
Controller code:
({
getStatusChannels: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getServicePresenceStatusChannels({
callback: function(result) {
if (result.success) {
console.log('Retrieved Service Presence Status Channels successfully');
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
channels JSON string of Returns the IDs and API names of the channels associated with the presence status.
channel
objects
Arguments
Name Type Description
callback function JavaScript method to call when the agent’s presence status is retrieved.
230
Methods for Lightning Experience login for Lightning Experience
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Get Status" onclick="{! c.getStatus }" />
</aura:component>
Controller code:
({
getStatus: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.getServicePresenceStatusId({
callback: function(result) {
if (result.success) {
console.log('Get Status Id successful');
console.log('Status Id is: ' + result.statusId);
} else {
console.log('Get Status Id failed');
}
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
statusApiName string The API name of the agent’s current presence status.
Arguments
Name Type Description
statusId string The ID of the presence status. Agents must be given access to this presence status
through their associated profile or permission set.
231
Methods for Lightning Experience logout for Lightning Experience
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Login" onclick="{! c.login }" />
</aura:component>
Controller code:
({
login: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.login({
statusId: "0N5xx0000000001",
callback: function(result) {
if (result.success) {
console.log("Login successful");
} else {
console.log("Login failed");
}
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
Arguments
Name Type Description
callback function JavaScript method to call when the agent is logged out of Omni-Channel.
232
Methods for Lightning Experience setServicePresenceStatus for Lightning Experience
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Logout" onclick="{! c.logout }" />
</aura:component>
Controller code:
({
logout: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.logout({
callback: function(result) {
if (result.success) {
console.log("Logout successful");
} else {
console.log("Logout failed");
}
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
Arguments
Name Type Description
statusId string The ID of the presence status to which you want to set the agent. Agents must be
given access to this presence status through their associated profile or permission
set.
callback function JavaScript method to call when the agent’s status is changed to the presence status
associated with statusId.
233
Methods for Lightning Experience setServicePresenceStatus for Lightning Experience
Sample Code
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<lightning:button label="Set Status" onclick="{! c.setStatus }" />
</aura:component>
Controller code:
({
setStatus: function(cmp, evt, hlp) {
var omniAPI = cmp.find("omniToolkit");
omniAPI.setServicePresenceStatus({
statusId: "0N5xx0000000006",
callback: function(result) {
if (result.success) {
console.log('Set status successful');
console.log('Current statusId is: ' + result.statusId);
console.log('Channel list attached to this status is: ' +
result.channels);
} else {
console.log('Set status failed');
}
}
});
}
})
Response
This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following
properties:
statusApiName string The API name of the agent’s current presence status.
channels JSON string of Returns the IDs and API names of the channels associated with the presence status.
channel
objects
234
CHAPTER 7 Events for Lightning Experience
Use events and handlers in your Lightning components and controllers to respond to events like workspace tabs opening, closing, or
gaining focus.
IN THIS SECTION:
lightning:tabClosed
Indicates that a tab has been closed.
lightning:tabCreated
Indicates that a tab has been created successfully.
lightning:tabFocused
Indicates that a tab has been focused.
lightning:tabRefreshed
Indicates that a tab has been refreshed.
lightning:tabReplaced
Indicates that a tab has been replaced successfully.
lightning:tabUpdated
Indicates that a tab has been updated successfully.
Events for Omni-Channel
JavaScript can be executed when certain types of events occur in a console, such as when a user closes a tab. There are a few events
that are specific to Omni-Channel. These events apply to Lightning Experience only.
lightning:tabClosed
Indicates that a tab has been closed.
Response
Name Type Description
tabId string The ID of the closed tab.
235
Events for Lightning Experience lightning:tabCreated
Example: This example prints a line to the browser’s developer console when a tab is closed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<aura:handler event="lightning:tabClosed" action="{! c.onTabClosed }"/>
</aura:component>
Controller code:
({
onTabClosed : function(component, event, helper) {
var tabId = event.getParam('tabId');
console.log("Tab closed: " +tabId");
}
})
lightning:tabCreated
Indicates that a tab has been created successfully.
Response
Name Type Description
tabId string The ID of the new tab.
Example: This example prints a line to the browser’s developer console when a tab is created, and sets the label of the tab to
"New Tab" using the setTabLabel() method.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<aura:handler event="lightning:tabCreated" action="{! c.onTabCreated }"/>
</aura:component>
Controller code:
({
onTabCreated : function(component, event, helper) {
console.log("Tab created.");
var newTabId = event.getParam('tabId');
var workspaceAPI = component.find("workspace");
workspaceAPI.setTabLabel({
tabId: newTabId,
label: 'New Tab'
});
},
})
236
Events for Lightning Experience lightning:tabFocused
lightning:tabFocused
Indicates that a tab has been focused.
Response
Name Type Description
previousTabId string The ID of the previously focused tab.
Example: This example prints a line to the browser’s developer console when a tab is focused, and then returns that tab’s
tabInfo object using the getTabInfo() method.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<aura:handler event="lightning:tabFocused" action="{! c.onTabFocused }"/>
</aura:component>
Controller code:
({
onTabFocused : function(component, event, helper) {
console.log("Tab Focused");
var focusedTabId = event.getParam('currentTabId');
var workspaceAPI = component.find("workspace");
workspaceAPI.getTabInfo({
tabId : focusedTabId
}).then(function(response) {
console.log(response);
});
}
})
lightning:tabRefreshed
Indicates that a tab has been refreshed.
Response
Name Type Description
tabId string The ID of the refreshed tab.
237
Events for Lightning Experience lightning:tabReplaced
Example: This example prints a line to the browser’s developer console when a tab is refreshed, and then returns that tab’s
tabInfo object using the getTabInfo() method.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<aura:handler event="lightning:tabRefreshed" action="{! c.onTabRefreshed }"/>
</aura:component>
Controller code:
({
onTabRefreshed : function(component, event, helper) {
console.log("Tab Refreshed");
var refreshedTabId = event.getParam("tabId");
var workspaceAPI = component.find("workspace");
workspaceAPI.getTabInfo({
tabId : refreshedTabId
}).then(function(response) {
console.log(response);
});
}
})
lightning:tabReplaced
Indicates that a tab has been replaced successfully.
Response
Name Type Description
tabId string The ID of the replaced tab.
Example: This example prints a line to the browser’s developer console when a tab is replaced, and then returns that tab’s URL
using the getTabURL() method.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<aura:handler event="lightning:tabReplaced" action="{! c.onTabReplaced }"/>
</aura:component>
Controller code:
({
onTabReplaced : function(component, event, helper) {
console.log("Tab Replaced");
238
Events for Lightning Experience lightning:tabUpdated
lightning:tabUpdated
Indicates that a tab has been updated successfully.
Response
Name Type Description
tabId string The ID of the updated tab.
Example: This example prints a line to the browser’s developer console when a tab is updated, and then prints that tab’s tabId.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:workspaceAPI aura:id="workspace" />
<aura:handler event="lightning:tabUpdated" action="{! c.onTabUpdated }"/>
</aura:component>
Controller code:
({
onTabUpdated : function(component, event, helper) {
console.log("Tab Updated");
var updatedTabId = event.getParam("tabId");
console.log(updatedTabId);
},
})
IN THIS SECTION:
lightning:omniChannelLoginSuccess
Indicates that an agent has been logged into Omni-Channel successfully.
239
Events for Lightning Experience lightning:omniChannelLoginSuccess
lightning:omniChannelStatusChanged
Indicates that an agent has changed his or her presence status in Omni-Channel.
lightning:omniChannelLogout
Indicates that an agent has logged out of Salesforce.
lightning:omniChannelWorkAssigned
Indicates that an agent has been assigned a new work item.
lightning:omniChannelWorkAccepted
Indicates that an agent has accepted a work assignment, or that a work assignment has been automatically accepted.
lightning:omniChannelWorkDeclined
Indicates that an agent has declined a work assignment.
lightning:omniChannelWorkClosed
Indicates that an agent has closed a tab in the console that’s associated with a work item. When the tab is closed, the status of the
AgentWork object associated with it automatically changes to Closed.
lightning:omniChannelWorkloadChanged
Indicates that an agent’s workload has changed. This includes receiving new work items, declining work items, and closing items in
the console. It also indicates that there has been a change to an agent’s capacity or presence configuration, or that the agent has
gone offline in the Omni-Channel utility.
lightning:omniChannelLoginSuccess
Indicates that an agent has been logged into Omni-Channel successfully.
Response
Example: This example prints a line to the browser’s developer console when an Omni-Channel user logs into Omni-Channel
successfully.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelLoginSuccess" action="{! c.onLoginSuccess
}"/>
</aura:component>
Controller code:
({
onLoginSuccess : function(component, event, helper) {
console.log("Login success.");
var statusId = event.getParam('statusId');
console.log(statusId);
240
Events for Lightning Experience lightning:omniChannelStatusChanged
},
})
lightning:omniChannelStatusChanged
Indicates that an agent has changed his or her presence status in Omni-Channel.
Response
Example: This example prints status details to the browser’s developer console when an Omni-Channel user's presence status
is changed.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelStatusChanged" action="{! c.onStatusChanged
}"/>
</aura:component>
Controller code:
({
onStatusChanged : function(component, event, helper) {
console.log("Status changed.");
var statusId = event.getParam('statusId');
var channels = event.getParam('channels');
var statusName = event.getParam('statusName');
var statusApiName = event.getParam('statusApiName');
console.log(statusId);
console.log(channels);
console.log(statusName);
console.log(statusApiName);
},
})
241
Events for Lightning Experience lightning:omniChannelLogout
channel
The channel object contains the following properties:
lightning:omniChannelLogout
Indicates that an agent has logged out of Salesforce.
Response
None
Example: This example prints a line to the browser’s developer console when an Omni-Channel user logs out of Salesforce.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelLogout" action="{! c.onLogout }"/>
</aura:component>
Controller code:
({
onLogout : function(component, event, helper) {
console.log("Logout success.");
},
})
lightning:omniChannelWorkAssigned
Indicates that an agent has been assigned a new work item.
Response
242
Events for Lightning Experience lightning:omniChannelWorkAccepted
Example: This example prints work details to the browser’s developer console when an Omni-Channel user is assigned a new
work item.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelWorkAssigned" action="{! c.onWorkAssigned
}"/>
</aura:component>
Controller code:
({
onWorkAssigned : function(component, event, helper) {
console.log("Work assigned.");
var workItemId = event.getParam('workItemId');
var workId = event.getParam('workId');
console.log(workItemId);
console.log(workId);
},
})
lightning:omniChannelWorkAccepted
Indicates that an agent has accepted a work assignment, or that a work assignment has been automatically accepted.
Response
243
Events for Lightning Experience lightning:omniChannelWorkDeclined
Example: This example prints work details to the browser’s developer console when an Omni-Channel user accepts a work
assignment, or when a work assignment is automatically accepted.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelWorkAccepted" action="{! c.onWorkAccepted
}"/>
</aura:component>
Controller code:
({
onWorkAccepted : function(component, event, helper) {
console.log("Work accepted.");
var workItemId = event.getParam('workItemId');
var workId = event.getParam('workId');
console.log(workItemId);
console.log(workId);
},
})
lightning:omniChannelWorkDeclined
Indicates that an agent has declined a work assignment.
Response
Example: This example prints work details to the browser’s developer console when an Omni-Channel user declines a work
assignment.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelWorkDeclined" action="{! c.onWorkDeclined
}"/>
</aura:component>
244
Events for Lightning Experience lightning:omniChannelWorkClosed
Controller code:
({
onWorkDeclined : function(component, event, helper) {
console.log("Work declined.");
var workItemId = event.getParam('workItemId');
var workId = event.getParam('workId');
console.log(workItemId);
console.log(workId);
},
})
lightning:omniChannelWorkClosed
Indicates that an agent has closed a tab in the console that’s associated with a work item. When the tab is closed, the status of the
AgentWork object associated with it automatically changes to Closed.
Response
Example: This example prints work details to the browser’s developer console when an Omni-Channel user closes a tab in the
console that’s associated with a work item.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelWorkClosed" action="{! c.onWorkClosed
}"/>
</aura:component>
Controller code:
({
onWorkClosed : function(component, event, helper) {
console.log("Work closed.");
var workItemId = event.getParam('workItemId');
var workId = event.getParam('workId');
console.log(workItemId);
console.log(workId);
},
})
245
Events for Lightning Experience lightning:omniChannelWorkloadChanged
lightning:omniChannelWorkloadChanged
Indicates that an agent’s workload has changed. This includes receiving new work items, declining work items, and closing items in the
console. It also indicates that there has been a change to an agent’s capacity or presence configuration, or that the agent has gone
offline in the Omni-Channel utility.
Response
Example: This example prints workload details to the browser’s developer console when an agent’s workload changes.
Component code:
<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
<lightning:omniToolkitAPI aura:id="omniToolkit" />
<aura:handler event="lightning:omniChannelWorkloadChanged" action="{!
c.onWorkloadChanged }"/>
</aura:component>
Controller code:
({
onWorkloadChanged : function(component, event, helper) {
console.log("Workload changed.");
var configuredCapacity = event.getParam('configuredCapacity');
var previousWorkload = event.getParam('previousWorkload');
var newWorkload = event.getParam('newWorkload');
console.log(configuredCapacity);
console.log(previousWorkload);
console.log(newWorkload);
},
})
246
CHAPTER 8 Other Resources
In addition to this guide, there are other resources available for you as you learn how to use the console APIs.
IN THIS SECTION:
Console API Typographical Conventions
Typographical conventions are used in our code examples. Learn what Courier font, italics, and brackets mean.
SEE ALSO:
Salesforce Help: Salesforce Console
Salesforce Help: Glossary
Salesforce Developers: Getting Started with Salesforce Platform
Salesforce University: Training
Firebug Extension for Firefox
Force.com IDE Eclipse Plug-in
Convention Description
Courier font In descriptions of syntax, monospace font indicates items that you should type as shown,
except for brackets. For example:
Public class HelloWorld
Italics In descriptions of syntax, italics represent variables. You supply the actual value. In the following
example, three values need to be supplied: datatype variable_name [ = value];
If the syntax is bold and italic, the text represents a code element that needs a value supplied
by you, such as a class name or variable value:
Bold Courier font In code samples and syntax descriptions, bold courier font emphasizes a portion of the code
or syntax.
247
Other Resources Console API Typographical Conventions
Convention Description
<> In descriptions of syntax, less-than and greater-than symbols (< >) are typed exactly as shown.
<apex:pageBlockTable value="{!account.Contacts}" var="contact">
<apex:column value="{!contact.Name}"/>
<apex:column value="{!contact.MailingCity}"/>
<apex:column value="{!contact.Phone}"/>
</apex:pageBlockTable>
| In descriptions of syntax, the pipe sign means “or”. You can do one of the following (not all).
In the following example, you can create a new unpopulated set in one of two ways, or you
can populate the set:
Set<data_type> set_name
[= new Set<data_type>();] |
[= new Set<data_type{value [, value2. . .] };] |
;
248
INDEX
Events (continued)
A lightning:tabFocused 237
acceptAgentWork() 177, 223
lightning:tabRefreshed 237
acceptChat() 134
lightning:tabReplaced 238
addCustomEventListener() 173
lightning:tabUpdated 239
addEventListener() 127
addPushNotificationListener() 124 F
addToBrowserTitleQueue() 101
fireEvent() 129
Asynchronous calls 23
fireOnCallBegin() 87
Authentication 23
fireOnCallEnd() 88
fireOnCallLogSaved() 89
B focusNavigationTab() 82
Backward compatibility 20
focusPrimaryTabById() 34
Best practices 24
focusPrimaryTabByName() 35
blinkCustomConsoleComponentButtonText() 102
focusSidebarComponent() 36
focusSubtabById() 38
C focusSubtabByNameAndPrimaryTabID() 39
cancelFileTransferByAgent() 136 focusSubtabByNameAndPrimaryTabName() 40
Canvas 23
closeAgentWork() 178, 224 G
closeTab() 29
generateConsoleUrl() 41
Connecting to the Toolkit 23
getAgentInput() 139
Console API 1
getAgentState() 140
Custom console components 24, 100
getAgentWorks() 180, 182, 226, 228
getCallAttachedData() 91
D getCallObjectIds() 92
declineAgentWork() 179, 225 getChatLog() 141
declineChat() 137 getChatRequests() 143
disableTabClose 31 getCustomEvents() 174
getDetailsByChatKey() 144
E getDetailsByPrimaryTabId() 148
End-of-life 20 getEnclosingPrimaryTabId() 42
endChat() 138 getEnclosingPrimaryTabObjectId() 43
Error handling 10 getEnclosingTabId() 44
events 126 getEngagedChats() 152
Events getFocusedPrimaryTabId() 45
lightning:omniChannelLoginSuccess 240 getFocusedPrimaryTabObjectId() 46
lightning:omniChannelLogout 242 getFocusedSubtabId() 47
lightning:omniChannelStatusChanged 241 getFocusedSubtabObjectId() 48
lightning:omniChannelWorkAccepted 243 getMaxCapacity() 153
lightning:omniChannelWorkAssigned 242 getNavigationTabs() 83
lightning:omniChannelWorkClosed 245 getPageInfo() 49
lightning:omniChannelWorkDeclined 244 getPrimaryTabIds() 51
lightning:omniChannelWorkloadChanged 246 getSelectedNavigationTab() 84
lightning:tabClosed 235 getServicePresenceStatusChannels() 183, 229
lightning:tabCreated 236 getServicePresenceStatusId() 184, 230
249
Index
250
Index
251
Index
252
Index
T W
Typographical conventions 247 When to use the Salesforce Console Integration Toolkit 19
Working with the Salesforce Console Integration Toolkit 22
U
UI 2–3
253