Salesforce Console Integration Toolkit Developer Guide

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

setTabIcon()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

setTabLink()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

setTabStyle()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

setTabTextStyle()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

setTabTitle()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 4: Methods for Navigation Tabs

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

focusNavigationTab()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

getNavigationTabs()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

getSelectedNavigationTab()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

refreshNavigationTab()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

setSelectedNavigationTab()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 5: Methods for Computer-Telephony Integration (CTI)

. . . . . . . . . . . . . . . . . . 72

fireOnCallBegin()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

fireOnCallEnd()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

fireOnCallLogSaved()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

getCallAttachedData()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

getCallObjectIds()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

onCallBegin()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

onCallEnd()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

onSendCTIMessage()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

sendCTIMessage()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

setCallAttachedData()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

setCallObjectIds()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Chapter 6: Methods for Application-Level Custom Console Components

. . . . . . . . . . 86

addToBrowserTitleQueue()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

blinkCustomConsoleComponentButtonText()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

isCustomConsoleComponentPoppedOut()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Contents

isCustomConsoleComponentWindowHidden()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

isCustomConsoleComponentHidden()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

isInCustomConsoleComponent()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

onCustomConsoleComponentButtonClicked()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

onFocusedPrimaryTab()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

removeFromBrowserTitleQueue()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

runSelectedMacro()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

scrollCustomConsoleComponentButtonText()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

selectMacro()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

setCustomConsoleComponentButtonIconUrl()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

setCustomConsoleComponentButtonStyle()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

setCustomConsoleComponentButtonText()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

setCustomConsoleComponentHeight()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

setCustomConsoleComponentVisible()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

setCustomConsoleComponentWidth()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

setCustomConsoleComponentPopoutable()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

setCustomConsoleComponentWindowVisible()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

setSidebarVisible()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Chapter 7: Methods for Push Notifications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

addPushNotificationListener()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

removePushNotificationListener()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Chapter 8: Methods for Console Events

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

addEventListener()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

fireEvent()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

removeEventListener()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Chapter 9: Methods for Live Agent

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

acceptChat()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

cancelFileTransferByAgent()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

declineChat()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

endChat()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

getAgentInput()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

getAgentState()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

getChatLog()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

getChatRequests()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

getDetailsByChatKey()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

getDetailsByPrimaryTabId()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

getEngagedChats()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

getMaxCapacity()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

initFileTransfer()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

onAgentSend()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

onAgentStateChanged()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Contents

onChatCanceled()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

onChatCriticalWaitState()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

onChatDeclined()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

onChatEnded()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

onChatRequested()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

onChatStarted()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

onChatTransferredOut()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

onCurrentCapacityChanged()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

onCustomEvent()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

onFileTransferCompleted()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

onNewMessage()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

onTypingUpdate()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

sendCustomEvent()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

sendMessage()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

setAgentInput()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

setAgentState()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Methods for Live Agent Chat Visitors

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

chasitor.addCustomEventListener()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

chasitor.getCustomEvents()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

chasitor.sendCustomEvent()

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Chapter 10: Methods for Omni-Channel

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

acceptAgentWork

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

closeAgentWork

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

declineAgentWork

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

getAgentWorks

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

getAgentWorkload

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

getServicePresenceStatusChannels

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

getServicePresenceStatusId

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

logout

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

setServicePresenceStatus

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Methods for Omni-Channel Console Events

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Glossary

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

CHAPTER 1

Introducing the Salesforce Console

Integration Toolkit

The Salesforce console is designed for users in fast-paced environments who need to find, update, and create records in Salesforce quickly. The Salesforce Console Integration Toolkit provides you with programmatic access to the Salesforce console so that you can extend it to meet your business needs. With the Salesforce Console Integration Toolkit, you can open and close tabs in the console to streamline a business process. For example, the toolkit lets you integrate third-party systems with the console, opening up an external application in the same window, in a tab.

To use this guide, it helps if you have a basic familiarity with:

•

JavaScript

•

Visualforce

•

Web services

•

Software development

•

The Salesforce console

EDITIONS

Available in: Salesforce

Classic (in Setup and the app menu) and in Lightning

Experience (only in the App

Launcher)

Available in: Professional,

Enterprise, Performance,

Unlimited, and Developer

Editions

This guide explains how to use the Salesforce Console Integration Toolkit in JavaScript to embed API calls and processes. The toolkit is available for use with third-party domains, such as www.yourdomain.com

; however, the examples in this guide are in Visualforce.

The functionality it describes is available to your organization if you have:

•

Enterprise, Unlimited, Performance, or Developer Edition with the Service Cloud

•

The Salesforce console

The Salesforce Console Integration Toolkit is a browser-based JavaScript API. It uses browsers as clients to display pages as tabs in the console. The Salesforce Console Integration Toolkit:

•

Matches the API version for any given release. For example, if the current version of SOAP API is 20.0, then there's also a version 20.0

of the Salesforce Console Integration Toolkit.

•

Supports any browser that the Salesforce console supports. For more information, see “Salesforce Console” in the Salesforce online help.

Note: To enable the toolkit for third-party domains, add the domains to the whitelist of the Salesforce console. See “Whitelist

Domains for a Salesforce Console” in the Salesforce online help.

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. Previous versions may or may not receive fixes. When a new version is released, the previous version remains available.

Other Resources

In addition to this guide, there are other resources available for you as you learn how to use the Salesforce Console Integration Toolkit.

Introducing the Salesforce Console Integration Toolkit When to Use the Salesforce Console Integration Toolkit

Salesforce Console Integration Toolkit Typographical Conventions

The Salesforce Console Integration Toolkit guide uses a few typographical conventions.

Sample Visualforce Page Using the Salesforce Console Integration Toolkit

This example shows how to change the Salesforce console user interface using the Salesforce Console Integration Toolkit.

When to Use the Salesforce Console Integration Toolkit

The Salesforce Console Integration Toolkit helps advanced administrators and developers implement custom functionality for the

The following table lists additional features that developers can use to implement custom functionality for Salesforce organizations.

Feature

SOAP API

Description

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's 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

Apex

Use Apex if you want to:

•

Create Web services.

•

Create email services.

•

Perform complex validation over multiple objects.

•

Create complex business processes that are not supported by workflow.

•

Create custom transactional logic (logic that occurs over the entire transaction, not just with a single record or object).

•

Attach custom logic to another operation, such as saving a record, so that it occurs whenever the operation is executed, regardless of whether it originates in the user interface, a Visualforce page, or from SOAP API.

For more information, see the

Apex Developer Guide

Introducing the Salesforce Console Integration Toolkit Salesforce Console Integration Toolkit Support Policy

Salesforce Console Integration Toolkit Support Policy

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

For example, the Summer '10 release included API version 19.0 and the Winter ’11 release included API version 20.0.

The version of the Salesforce Console Integration Toolkit matches the API version for any given release. So if the current version of the

API is 20.0, there's also a version 20.0 of the 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 20.0, which shipped with the Winter ’11 release, will continue to work with Salesforce Console Integration Toolkit version 20.0 on the Summer ’11 release and on future releases. However, that same application may not work with Salesforce Console Integration Toolkit version 21.0 without modifications to the application.

End-of-Life

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.

Introducing the Salesforce Console Integration Toolkit Other Resources

Other Resources

In addition to this guide, there are other resources available for you as you learn how to use the Salesforce Console Integration Toolkit.

•

Online help: See Salesforce Console

•

Developer website: https://developer.salesforce.com/gettingstarted

•

Firebug extension to Firefox: Firebug for Firefox

•

Eclipse plug-in: Force.com IDE

Note:

Salesforce Education Services offers a suite of training courses to enable developers to design, create, integrate, and extend applications built on the Force.com platform. Be sure to visit http://www.salesforce.com/training to learn more.

Salesforce Console Integration Toolkit Typographical Conventions

The Salesforce Console Integration Toolkit guide uses a few typographical conventions.

Convention

Courier font

Description

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: public static class

YourClassHere

{ ... }

Bold Courier font

< >

{ }

In code samples and syntax descriptions, bold courier font emphasizes a portion of the code or syntax.

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, braces ({ }) are typed exactly as shown.

<apex:page >

Hello {!$User.FirstName}!

</apex:page >

Introducing the Salesforce Console Integration Toolkit

Convention

[ ]

Sample Visualforce Page Using the Salesforce Console

Integration Toolkit

Description

In descriptions of syntax, anything included in brackets is optional. In the following example, specifying

value

is optional:

data_type variable_name

[ =

value

];

| 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

. . .] };] |

;

Sample Visualforce Page Using the Salesforce Console Integration

Toolkit

This example shows how to change the Salesforce console user interface using the Salesforce Console Integration Toolkit.

1. Create a Visualforce page.

2. Cut and paste the following sample code into your Visualforce page.

This code demonstrates various functions of the Salesforce Console Integration Toolkit:

<apex:page standardController= "Case" >

<apex:includeScript value= "/support/console/ 38.0/integration.js

"/>

'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);

}

//Sets the title of the current tab to "Example" function setTitle() { sforce.console.setTabTitle( 'Example' );

}

Introducing the Salesforce Console Integration Toolkit Sample Visualforce Page Using the Salesforce Console

Integration Toolkit

//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 >

<A HREF= "#" onClick= "openPrimaryTab();return false" >Open A Primary Tab </A >

<p/ > <A HREF= "#" onClick= "openSubtab();return false" >Open A Subtab </A >

<p/ > <A HREF= "#" onClick= "setTitle();return false" >Set Title to Example </A >

<p/ > <A HREF= "#" onClick= "closeTab();return false" >Close This Tab </A >

</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:

CHAPTER 2 Working with the Salesforce Console

Integration Toolkit

Use the Salesforce Console Integration Toolkit to do the following in the Salesforce console.

•

Open a new primary tab or subtab that displays a specified URL

•

Set the title of a primary tab or a subtab

•

Return the ID of a primary tab or subtab

•

Close a specified primary tab or subtab

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 Force.com 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 Force.com Canvas.

Best Practices

Salesforce recommends that you adhere to a few best practices as you use the Salesforce Console Integration Toolkit.

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.

•

For Visualforce pages or any source other than a custom onclick

JavaScript button, specify a

tag that points to the toolkit file:

<apex:page >

" type=" text/javascript "></script>

...

</apex:page >

For Visualforce, a relative path is sufficient to include integration.js

, and is recommended.

Working with the Salesforce Console Integration Toolkit Asynchronous Calls with the Salesforce Console Integration

Toolkit

•

For a third-party domain:

" type=" text/javascript "></script>

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.

The version of the Salesforce Console Integration Toolkit is in the URL.

Asynchronous Calls with the Salesforce Console Integration Toolkit

Asynchronous syntax: method( '

arg1

','

arg2

', ...,

callback_method

);

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);

Working with Force.com 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 Force.com Canvas.

Force.com 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 Force.com Canvas, is the ability to choose authentication methods. For more information, see the

Force.com 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. See Add Console

Components to Apps .

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. See Whitelist Domains for a Salesforce

Console .

3. Call

Sfdc.canvas.client.signedrequest()

to store the signed request needed by the console integration toolkit

API. For example, if the Force.com Canvas method of authentication is a signed request, do the following:

Sfdc.canvas.client.signedrequest( '<%=signedRequest%>' )

If the Force.com 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 Force.com Canvas Developer’s Guide:

Sfdc.canvas.client.signedrequest(msg)

Working with the Salesforce Console Integration Toolkit Best Practices

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 retrieve the entityId

for OAuth, do the following: var entityId = msg.payload.environment.parameters.entityId;

To see an example on how to retrieve msg.payload

, see “Getting Context in Your Canvas App” in the Force.com Canvas Developer’s

Guide.

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.

•

To display Visualforce pages properly in the Salesforce Console, we recommend you:

–

Accept the default setting showHeader= "true"

and set sidebar= "false"

on the apex:page

tag.

–

Set

Behavior

on custom buttons and links that include methods from the toolkit to display in an existing window without a sidebar or header. For more information, see Define Custom Buttons and Links” in the Salesforce online help.

•

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 “Console

Components” in the Salesforce online help.

•

To enable the toolkit for third-party domains, add the domains to the whitelist of the Salesforce console. See “Whitelist Domains for a Salesforce Console” in the Salesforce online help.

•

When working with the Salesforce Console Integration Toolkit, we recommend that you keep in mind that it doesn’t support nested iframes.

CHAPTER 3 Methods for Primary Tabs and Subtabs

A Salesforce console displays Salesforce pages as primary tabs or subtabs. A primary tab displays the main item to work on, such as an account. A subtab displays related items, such as an account’s contacts or opportunities.

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 38.0 or later. Note: 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.

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.

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

Methods for Primary Tabs and Subtabs

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.

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

openSubtabByPrimaryTabName()

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.

Methods for Primary Tabs and Subtabs

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.

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.

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 on a Visualforce page so that users can continue working without being logged out. This method is only available in API version 24.0 or later.

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.

Methods for Primary Tabs and Subtabs

Arguments

Name

id callback

Type

string function closeTab()

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

)

Description

ID of the primary tab or subtab to close.

For API version 35.0 or later, the JavaScript method that’s called upon completion of the method.

Sample Code API 20.0 or Later–Visualforce

<apex:page standardController= "Case" >

Click here to close this tab </A >

<apex:includeScript value= "/support/console/20.0/integration.js" />

//First find the ID of the current tab to close it sforce.console.getEnclosingTabId(closeSubtab);

} var closeSubtab = function closeSubtab(result) {

//Now that we have the tab ID, we can close it var tabId = result.id; sforce.console.closeTab(tabId);

};

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

Methods for Primary Tabs and Subtabs closeTab()

Response

None

Sample Code API Version 35.0 or Later–Visualforce

<apex:page standardController= "Case" >

Click here to close this tab </A >

<apex:includeScript value= "/support/console/35.0/integration.js" />

}

}; function testCloseTab() {

//First find the ID of the current tab to close it sforce.console.getEnclosingTabId(closeSubtab);

} var closeSubtab = function closeSubtab(result) {

//Now that we have the tab ID, we can close it var tabId = result.id; sforce.console.closeTab(tabId, callback);

};

</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:

Name

success error

Type

boolean string

Description

true

if the tab was re-opened, false

otherwise.

Error message if the tab couldn’t be closed.

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.

Methods for Primary Tabs and Subtabs disableTabClose()

disableTabClose()

Syntax sforce.console.disableTabClose(disable: boolean , (optional) callback:

Function

)

tabId:String

, (optional)

Arguments

Name

disable tabId callback

Type

boolean string function

Description

Specifies whether to disable the tab. If true

, the user can’t close the tab. If false

, the user can close the tab.

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.

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 >

}

// For use within a tab 's sidebar (you don' t need tab ID) function testDisableTabCloseTrueWithoutId() { sforce.console.disableTabClose(true, false, displayResultsCallback);

Methods for Primary Tabs and Subtabs

} function testDisableTabCloseFalseWithoutId() { sforce.console.disableTabClose(false, false, displayResultsCallback);

}

// For use anywhere (you need the tab ID)

// 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" ); sforce.console.disableTabClose(true, tabId, displayResultsCallback);

} 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 >

<h2 >API Callback Result </h2 >

<br/ >

<br/ >

<p >The tab ID will be auto-detected by context, or the event will fail.

</p >

<ul >

Disable closing for the enclosing tab </a > </li >

Re-enable closing for the enclosing tab </a > </li >

</ul >

<h2 >With Tab ID Provided </h2 >

<p >When the event context doesn 't have a detectable tab ID, you can supply it yourself.

</p >

<ul >

Disable closing for a specific tab (via tab ID) </a > </li > disableTabClose()

Methods for Primary Tabs and Subtabs focusPrimaryTabById()

Re-enable closing for a specific tab (via tab ID) </a > </li >

</ul >

</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:

Name

success message

Type

boolean string

Description

true

if the action completed successfully, false

otherwise.

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

id callback

Type

string function

Description

ID of the primary tab to go to.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to go to an open primary tab by id </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//Get the value for 'scc-pt-0' from the openPrimaryTab method

Methods for Primary Tabs and Subtabs focusPrimaryTabByName()

//This value is for example purposes only var primaryTabId = 'scc-pt-0' ; sforce.console.focusPrimaryTabById(primaryTabId, focusSuccess);

} var focusSuccess = function focusSuccess(result) {

//Report whether going to the open primary tab was successful if (result.success == true) { alert( 'Going to the primary tab was successful' );

} else { alert( 'Going to the primary tab was not successful' );

}

};

</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:

Name

success

Type

boolean

Description

true

if going to the primary tab was successful; false

if going to the primary tab wasn't successful.

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

name callback

Type

string function

Description

Name of the primary tab to go to.

JavaScript method that’s called upon completion of the method.

Methods for Primary Tabs and Subtabs focusSidebarComponent()

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to go to a primary tab by name </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//Get the value for 'myPrimaryTab' from the openPrimaryTab method

//This value is for example purposes only var primaryTabName = 'myPrimaryTab' ; sforce.console.focusPrimaryTabByName(primaryTabName, focusSuccess);

} var focusSuccess = function focusSuccess(result) {

//Report whether going to the primary tab was successful if (result.success == true) { alert( 'Going to the primary tab was successful' );

} else { alert( 'Going to the Primary tab was not successful' );

}

};

</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:

Name

success

Type

boolean

Description

true

if going to the primary tab was successful; false

if going to the primary tab wasn't successful.

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 the Salesforce Help. This method is only available in API version 34.0

or later.

Methods for Primary Tabs and Subtabs focusSidebarComponent()

Syntax sforce.console.focusSidebarComponent(componentInfo:

string

(optional)tabId:

string

, callback:

Function

)

Arguments

Name

componentInfo

Type

string tabId callback string function

Description

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' }

•

{componentType: 'HIGHLIGHTS_PANEL' }

•

{componentType: 'KNOWLEDGE_ONE' }

•

{componentType: 'MILESTONE_WIDGET' }

•

{componentType: 'TOPICS_WIDGET' }

•

{componentType: 'VISUALFORCE' }

Types that require additional parameters:

•

{componentType: 'CANVAS' , canvasAppId:

'09Hxx0000000001' }

•

{componentType: 'RELATED_LIST' , listName:

'Solution' }

•

{componentType: 'LOOKUP' , fieldName: 'Account' }

•

{componentType: 'VISUALFORCE' , pageName: 'VF1' }

The ID of the tab on which to focus the browser.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/34.0/integration.js" />

}else{ alert( 'Something is wrong!' );

}

}; function focusKnowledgeComponent() {

Methods for Primary Tabs and Subtabs focusSubtabById()

}

</script > sforce.console.focusSidebarComponent(JSON.stringify({componentType:

'KNOWLEDGE_ONE' }), "scc-st-2" , callback);

<A HREF= "#" onClick= "focusSidebarComponent(); return false" >Focus Knowledge Component </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:

Name

success

Type

boolean

Description

true

if focusing the sidebar component was successful; false

otherwise.

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

id callback

Type

string function

Description

ID of the subtab to go to.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to go to a subtab by id </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

}

Methods for Primary Tabs and Subtabs focusSubtabByNameAndPrimaryTabId() var focusSuccess = function focusSuccess(result) {

//Report whether going to the subtab was successful if (result.success == true) { alert( 'Going to the subtab was successful' );

} else { alert( 'Going to the subtab was not successful' );

}

};

</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:

Name

success

Type

boolean

Description

true

if going to the subtab was successful; false

if going to the subtab wasn't successful.

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

name primaryTabId callback

Type

string string function

Description

Name of the subtab to go to.

ID of the primary tab in which the subtab opened.

JavaScript method that’s called upon completion of the method.

Methods for Primary Tabs and Subtabs focusSubtabByNameAndPrimaryTabName()

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to go to a subtab by name and primary tab ID </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

} var focusSuccess = function focusSuccess(result) {

//Report whether going to the subtab was successful if (result.success == true) { alert( 'Going to the subtab was successful' );

} else { alert( 'Going to the subtab was not successful' );

}

};

</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:

Name

success

Type

boolean

Description

true

if going to the subtab was successful; false

if going to the subtab wasn't successful.

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.

Methods for Primary Tabs and Subtabs focusSubtabByNameAndPrimaryTabName()

Syntax sforce.console.focusSubtabByNameAndPrimaryTabName(

name:String

primaryTabName:String

,(optional)callback:

Function

)

Arguments

Name

name primaryTabName callback

Type

string string function

Description

Name of the subtab to go to.

Name of the primary tab in which the subtab opened.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to go to a subtab by name and primary tab name </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

} var focusSuccess = function focusSuccess(result) {

//Report whether going to the subtab was successful if (result.success == true) { alert( 'Going to the subtab was successful' );

} else { alert( 'Going to the subtab was not successful' );

}

};

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

Methods for Primary Tabs and Subtabs generateConsoleUrl()

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if going to the subtab was successful; false

if going to the subtab wasn't successful.

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 the online help. This method is only available in API version 28.0 or later.

Syntax sforce.console.generateConsoleUrl(

urls:String

, (optional)callback:

Function

)

Arguments

Name

urls callback

Type

string function

Description

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.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/28.0/integration.js" />

Click here to generate a console URL </A >

} function testGenerateConsoleURL() { sforce.console.generateConsoleUrl([/apex/pagename, /entityId, www.externalUrl.com, Standard Salesforce Url/entityId], showConsoleUrl);

</script >

</apex:page >

}

Methods for Primary Tabs and Subtabs getEnclosingPrimaryTabId()

Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:

Name

consoleUrl success callback

Type

string boolean function

Description

Console URL that represents the array of URLs passed into Salesforce.

true

if the URL was generated successfully, false

if otherwise.

JavaScript method that’s called upon completion of the method.

getEnclosingPrimaryTabId()

Syntax sforce.console.getEnclosingPrimaryTabId((optional)

callback:function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to close this primary tab </A >

<apex:includeScript value= "/support/console/20.0/integration.js" />

//First find the ID of the current primary tab to close it sforce.console.getEnclosingPrimaryTabId(closeSubtab);

} var closeSubtab = function closeSubtab(result) {

//Now that we have the primary tab ID, we can close it var tabId = result.id; sforce.console.closeTab(tabId);

};

</script >

</apex:page >

Methods for Primary Tabs and Subtabs getEnclosingPrimaryTabObjectId()

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:

Name

Type

string

Description

The ID of the current primary tab that contains this tab.

getEnclosingPrimaryTabObjectId()

Syntax sforce.console.getEnclosingPrimaryTabObjectId((optional)callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to get enclosing primary tab object ID </A >

<apex:includeScript value= "/support/console/24.0/integration.js" />

} var showObjectId = function showObjectId(result) {

};

</script >

</apex:page >

// Display the object ID alert ( 'Object ID: ' + result.id);

Methods for Primary Tabs and Subtabs getEnclosingTabId()

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:

Name

id success

Type

string boolean

Description

The ID of the current primary tab that contains this subtab.

true

if returning the enclosing primary tab was successful; false

if returning the enclosing primary tab wasn't successful.

getEnclosingTabId()

Syntax sforce.console.getEnclosingTabId()

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to close this tab </A >

<apex:includeScript value= "/support/console/20.0/integration.js" />

//First find the ID of the current tab to close it sforce.console.getEnclosingTabId(closeSubtab);

} var closeSubtab = function closeSubtab(result) {

//Now that we have the tab ID, we can close it var tabId = result.id; sforce.console.closeTab(tabId);

Methods for Primary Tabs and Subtabs getFocusedPrimaryTabId()

};

</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:

Name

Type

string

Description

The ID of the current primary tab or subtab.

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.

Syntax sforce.console.getFocusedPrimaryTabId((optional) callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to get the focused primary tab ID </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

} var showTabId = function showTabId(result) {

//Display the tab ID alert( 'Tab ID: ' + result.id);

};

Methods for Primary Tabs and Subtabs getFocusedPrimaryTabObjectId()

</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:

Name

id success

Type

string boolean

Description

The ID of the primary tab on which the browser is focused. If no primary tab is open, the ID is null.

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.

Syntax sforce.console.getFocusedPrimaryTabObjectId((optional) callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to get the focused primary tab object ID </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

} var showObjectId = function showObjectId(result) {

Methods for Primary Tabs and Subtabs getFocusedSubtabId()

};

//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:

Name

id success

Type

string boolean

Description

The object ID of the primary tab on which the browser is focused. If there is no primary tab open, the ID is null.

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.

Syntax sforce.console.getFocusedSubtabId((optional)callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to get the ID of the focused subtab </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

Methods for Primary Tabs and Subtabs getFocusedSubtabObjectId() 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:

Name

id success

Type

string boolean

Description

The ID of the subtab on which the browser is focused. If no subtab is open, the ID is null.

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.

Syntax sforce.console.getFocusedSubtabObjectId((optional)callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to get the object ID of the focused subtab </A >

<apex:includeScript value= "/support/console/24.0/integration.js" />

Methods for Primary Tabs and Subtabs getPageInfo() sforce.console.getFocusedSubtabObjectId(showObjectId);

}

};

</script >

</apex:page > var showObjectId = function showObjectId(result) {

// Display the object ID alert ( 'Object ID: ' + result.id);

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:

Name

id success

Type

string boolean

Description

The object ID of the subtab on which the browser is focused. If no subtab is open, the ID is null.

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()

must be passed as the first parameter to this method.This method is only available in API version 26.0 or later.

Syntax sforce.console.getPageInfo(

tabId:String

, (optional)callback:

Function

)

Arguments

Name

tabId callback

Type

string function

Description

ID of the tab from which page information is returned.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Methods for Primary Tabs and Subtabs getPrimaryTabIds()

Click here to get page information </A >

<apex:includeScript value= "/support/console/26.0/integration.js" />

//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);

} var showPageInfo = function showPageInfo(result) { alert( 'Page Info: ' + result.pageInfo);

</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:

Name

pageInfo

Type

string

Description

Returns the URL of the current page as a JSON string, and includes any applicable object ID, object name, object type, and for API version 33.0 or later, the object tab name. For example:

{ "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

For example:

{ "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.

Methods for Primary Tabs and Subtabs

Syntax sforce.console.getPrimaryTabIds((optional) callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

getSubtabIds()

Sample Code–Visualforce

<apex:page >

Click here to get the primary tab IDs </A >

<apex:includeScript value= "/support/console/26.0/integration.js" />

} var showTabId = function showTabId(result) {

//Display the primary tab IDs alert( 'Primary Tab IDs: ' + result.ids);

};

</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:

Name

ids success

Type

string boolean

Description

An array of open primary tab IDs , in order of appearance.

true

if returning the IDs of open primary tabs was successful; false

if returning the IDs of open primary tabs wasn't successful.

getSubtabIds()

Methods for Primary Tabs and Subtabs getTabLink()

Syntax sforce.console.getSubtabIds( (optional)

primaryTabId:String

, (optional) callback:

Function

)

Arguments

Name

primaryTabId callback

Type

string function

Description

ID of the primary tab from which the subtab IDs are returned.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to get the subtab IDs </A >

<apex:includeScript value= "/support/console/26.0/integration.js" />

//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);

} var showTabId = function showTabId(result) {

//Display the subtab IDs alert( 'Subtab IDs: ' + result.ids);

</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:

Name

ids success

Type

string boolean

Description

An array of open subtab IDs.

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.

Methods for Primary Tabs and Subtabs getTabLink()

Syntax sforce.console.getTabLink(

level:String

, (optional)

tabId:String

(optional)callback:

Function

)

Arguments

Name

level

Type

string tabId callback string function

Description

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 “Salesforce Console Tabs” in the online help.

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.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/28.0/integration.js" />

Click here to get tab link </A >

} var getTabLink = function getTabLink(result) { sforce.console.getTabLink(sforce.console.TabLink.PARENT_AND_CHILDREN, result.id, showTabLink);

} var showTabLink = function showTabLink(result) { var link = result.tabLink;

};

</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:

Methods for Primary Tabs and Subtabs

Name

tabLink success callback

Type

string boolean function isInConsole()

Description

The retrieved URL.

true

if the link was retrieved successfully, false

if retrieving was unsuccessful.

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" >

Click here to check if the page is in the Service Cloud console </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

} else { 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.

Methods for Primary Tabs and Subtabs onEnclosingTabRefresh()

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

eventHandler

Type

function

Description

JavaScript method called when the enclosing tab refreshes.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/24.0/integration.js" />

}; alert( 'Enclosing tab has refreshed:' + result.id

+ 'and the object Id is:' + result.objectId); sforce.console.onEnclosingTabRefresh(eventHandler);

</script >

</apex:page >

Event Handler Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:

Name

id objectId

Type

string string

Description

The ID of the refreshed tab.

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.

Methods for Primary Tabs and Subtabs

Syntax sforce.console.onFocusedSubtab(eventHandler:

Function

)

Arguments

Name

eventHandler

Type

function

Description

JavaScript method called when the focus of the browser changes to a different subtab.

onTabSave()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/24.0/integration.js" />

+ result.id + 'and the object Id is:' + result.objectId);

}; sforce.console.onFocusedSubtab(eventHandler);

</script >

</apex:page >

Event Handler Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:

Name

id objectId

Type

string string

Description

The ID of the subtab on which the browser is focused.

The object ID of the subtab on which the browser is focused or null if no object exists.

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

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

Methods for Primary Tabs and Subtabs onTabSave() 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.

Important: When using onTabSave()

with setTabUnsavedChanges()

•

Calling sforce.console.setTabUnsavedChanges(false,...)

closes the specified subtab. We recommend placing the call to sforce.console.setTabUnsavedChanges()

at the end of the callback method, as any subsequent save logic might not execute.

•

onTabSave()

works only on subtabs or their sidebar components. It doesn’t work on primary tabs.

•

Not calling sforce.console.setTabUnsavedChanges()

will have a severe effect on the user interface. For example, closing a primary tab with a subtab for which sforce.console.setTabUnsavedChanges()

has not been called prevents a

Saving...

modal dialog box from closing.

•

Any callback passed to sforce.console.setTabUnsavedChanges()

will not execute if the specified tab saves successfully and closes.

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 “Console Components” in the Salesforce online help.

Syntax sforce.console.onTabSave(callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method called to handle the save operation.

Sample Code–Visualforce

<apex:page >

Click here to register save handler </a >

<apex:includeScript value= "/support/console/36.0/integration.js" />

} var handleSave = function handleSave(result) { alert( 'save handler called from tab with id ' + result.id +

' and objectId ' + result.objectId);

//Perform save logic here

//Mark tab as 'clean' sforce.console.setTabUnsavedChanges(false, undefined, result.id);

};

</script >

</apex:page >

Methods for Primary Tabs and Subtabs

Response

Name

id objectId

Type

string string

Description

ID of the subtab being saved.

Object ID of the subtab being saved, if applicable; null otherwise.

openConsoleUrl()

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

string consoleUrl active tabLabels tabNames callback string boolean string string function

Description

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.

Console URL that represents the array of URLs passed into Salesforce.

If true

, the opened primary tab displays immediately. If false

, the opened primary tab displays in the background and the current tab maintains focus.

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 (

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 (

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/28.0/integration.js" />

Click here to open a console URL </A >

Methods for Primary Tabs and Subtabs openPrimaryTab()

} 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:

Name

success

Type

boolean

Description

true

if the console URL was opened successfully, false

otherwise.

openPrimaryTab()

•

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.

Syntax sforce.console.openPrimaryTab(

id:String

url:URL

active:Boolean

(optional)

tabLabel:String

, (optional)callback:

Function

, (optional)

name

)

Arguments

Name

Type

string

Description

ID of the primary tab to override.

Use null

to create a new primary tab.

Methods for Primary Tabs and Subtabs

Name

url active tabLabel callback name

Type

URL boolean string function string openPrimaryTab()

Description

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.

URL of the opened primary tab.

is called on a case, the case opens as subtab on its parent account's primary tab.

Note that users can open an external URL if it has been added to the console’s whitelist. For more information, see “Whitelist Domains for a Salesforce Console” in the online help.

If true

, the opened primary tab displays immediately. If false

, the opened primary tab displays in the background and the current tab maintains focus.

Optional label of the opened primary tab. If a label isn't specified,

External

Page

displays.

Add labels as text; HTML isn't supported.

JavaScript method called upon completion of the method.

Optional name of the opened primary tab.

This argument is only available in API version 22.0 and later.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to open a new primary tab </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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' );

} var openSuccess = function openSuccess(result) {

//Report whether opening the new tab was successful if (result.success == true) { alert( 'Primary tab successfully opened' );

} else { alert( 'Primary tab cannot be opened' );

}

};

Methods for Primary Tabs and Subtabs openSubtab()

</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:

Name

success id

Type

boolean string

Description

true

if the tab successfully opened; false

if the tab didn't open.

ID of the primary tab. IDs are only valid during a user session; IDs become invalid when a user leaves the Salesforce console.

openSubtab()

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

)

Arguments

Name

primaryTabId url

Type

string

URL

Description

ID of the primary tab in which the subtab opened.

URL of the opened subtab.

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 primary tab, and openSubtab()

is called on a case, the case opens as a primary tab.

Note that users can open an external URL if it has been added to the console’s whitelist. For more information, see “Whitelist Domains for a Salesforce Console” in the online help.

Methods for Primary Tabs and Subtabs

Name

active tabLabel

Type

boolean string id callback name string function string openSubtab()

Description

If true

, the opened subtab displays immediately. If false

, the opened subtab displays in the background and the current tab maintains focus.

Optional label of the opened subtab. If a label isn't specified,

External Page displays.

Add labels as text; HTML isn't supported.

ID of the subtab to override.

Use null

to create a new subtab.

JavaScript method called upon completion of the method.

Optional name of the opened subtab.

This argument is only available in API version 22.0 and later.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to open a new subtab </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//First find the ID of the primary tab to put the new subtab in sforce.console.getEnclosingPrimaryTabId(openSubtab);

} var openSubtab = function openSubtab(result) {

//Now that we have the primary tab ID, we can open a new subtab in it var primaryTabId = result.id; sforce.console.openSubtab(primaryTabId , 'http://www.salesforce.com' , false,

'salesforce' , null, openSuccess, 'salesforceSubtab' );

}; var openSuccess = function openSuccess(result) {

//Report whether we succeeded in opening the subtab if (result.success == true) { alert( 'subtab successfully opened' );

} else { alert( 'subtab cannot be opened' );

}

};

</script >

</apex:page >

Methods for Primary Tabs and Subtabs 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:

Name

success id

Type

boolean string

Description

true

if the subtab successfully opened; false

if the subtab didn't open.

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

primaryTabName url

Type

string

URL active boolean

Description

Name of the primary tab in which the subtab opened.

URL of the opened subtab.

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 primary tab, and openSubtab()

is called on a case, the case opens as a primary tab.

Note that users can open an external URL if it has been added to the console’s whitelist. For more information, see “Whitelist Domains for a Salesforce Console” in the online help.

If true

, the opened subtab displays immediately. If false

, the opened subtab displays in the background and the current tab maintains focus.

Methods for Primary Tabs and Subtabs

Name

tabLabel

Type

string id callback name string function string openSubtabByPrimaryTabName()

Description

Optional label of the opened subtab. If a label isn't specified,

External Page displays.

Add labels as text; HTML isn't supported.

ID of the subtab to override.

Use null

to create a new subtab.

JavaScript method called upon completion of the method.

Optional name of the opened subtab.

This argument is only available in API version 22.0 and later.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to open a new subtab by primary tab name </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//First open a primary tab by name sforce.console.openPrimaryTab(null, 'http://www.yahoo.com' , true, 'Yahoo' , openSubtab, 'yahoo' );

} var openSubtab = function openSubtab(result) {

//Open the subtab by the name specified in function testOpenSubtabByPrimaryTabName() sforce.console.openSubtabByPrimaryTabName( 'yahoo' , 'http://www.salesforce.com' , true,

'salesforce' , null, openSuccess);

}; var openSuccess = function openSuccess(result) {

//Report whether we succeeded in opening the subtab if (result.success == true) { alert( 'subtab successfully opened' );

}

};

</script >

</apex:page >

} else { alert( 'subtab cannot be opened' );

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.

Methods for Primary Tabs and Subtabs refreshPrimaryTabById()

Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:

Name

success id

Type

boolean string

Description

true

if the subtab successfully opened; false

if the subtab didn't open.

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(

:String,

active

:Boolean, (optional)

callback

:Function,

(optional)

fullRefresh

:Boolean)

Arguments

Name

id active callback

Type

string boolean function

Description

ID of the primary tab to refresh.

If true

, the refreshed primary tab displays immediately. If false

, the refreshed primary tab displays in the background.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to refresh a primary tab by id </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

}

Methods for Primary Tabs and Subtabs refreshPrimaryTabByName() var refreshSuccess = function refreshSuccess(result) {

//Report whether refreshing the primary tab was successful if (result.success == true) { alert( 'Primary tab refreshed successfully' );

} else { alert( 'Primary did not refresh' );

}

};

</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:

Name

success

Type

boolean

Description

true

if the primary tab refreshed successfully; false

if the primary tab didn't refresh.

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)

Arguments

Name

name active callback

Type

string boolean function

Description

Name of the primary tab to refresh.

If true

, the refreshed primary tab displays immediately. If false

, the refreshed primary tab displays in the background.

JavaScript method that’s called upon completion of the method.

Methods for Primary Tabs and Subtabs refreshSubtabById()

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to refresh a primary tab by name </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

} var refreshSuccess = function refreshSuccess(result) {

//Report whether refreshing the primary tab was successful if (result.success == true) { alert( 'Primary tab refreshed successfully' );

} else { alert( 'Primary tab did not refresh' );

}

};

</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:

Name

success

Type

boolean

Description

true

if the primary tab refreshed successfully; false

if the primary tab didn't refresh.

refreshSubtabById()

Methods for Primary Tabs and Subtabs refreshSubtabById()

Syntax sforce.console.refreshSubtabById(

:String,

active

:Boolean, (optional)

callback

:Function,

(optional)

fullRefresh

:Boolean)

Arguments

Name

id active callback fullRefresh

Type

string boolean function boolean

Description

ID of the subtab to refresh.

If true

, the refreshed subtab displays immediately. If false

, the refreshed subtab displays in the background.

JavaScript method that’s called upon completion of the method.

Enables a full refresh of the entire case feed.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to refresh a subtab by id </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

} var refreshSuccess = function refreshSuccess(result) {

//Report whether refreshing the subtab was successful if (result.success == true) { alert( 'Subtab refreshed successfully' );

} else { alert( 'Subtab did not refresh' );

}

};

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

Methods for Primary Tabs and Subtabs refreshSubtabByNameAndPrimaryTabId()

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if the subtab refreshed successfully; false

if the subtab didn't refresh.

refreshSubtabByNameAndPrimaryTabId()

Syntax sforce.console.refreshSubtabByNameAndPrimaryTabId(

name

:String,

primaryTabId

:String,

active

:Boolean, (optional)

callback

:Function, (optional)

fullRefresh

:Boolean)

Arguments

Name

name primaryTabId active callback fullRefresh

Type

string string boolean function boolean

Description

Name of the subtab to refresh.

ID of the primary tab in which the subtab opened.

If true

, the refreshed subtab displays immediately. If false

, the refreshed subtab displays in the background.

JavaScript method that’s called upon completion of the method.

Enables a full refresh of the entire case feed.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to refresh a subtab by name and primary tab ID </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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' ;

Methods for Primary Tabs and Subtabs refreshSubtabByNameAndPrimaryTabName() sforce.console.refreshSubtabByNameAndPrimaryTabId(subtabName, primaryTabId, true, refreshSuccess);

} var refreshSuccess = function refreshSuccess(result) {

//Report whether refreshing the subtab was successful if (result.success == true) { alert( 'Subtab refreshed successfully' );

} else { alert( 'Subtab did not refresh' );

}

};

</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:

Name

success

Type

boolean

Description

true

if the subtab refreshed successfully; false

if the subtab didn't refresh.

refreshSubtabByNameAndPrimaryTabName()

Syntax sforce.console.refreshSubtabByNameAndPrimaryTabName(

name

:String,

primaryTabName

:String,

active

:Boolean, (optional)

callback

:Function, (optional)

fullRefresh

:Boolean)

Arguments

Name

name primaryTabName

Type

string string

Description

Name of the subtab to refresh.

Name of the primary tab in which the subtab opened.

Methods for Primary Tabs and Subtabs refreshSubtabByNameAndPrimaryTabName()

Name

active callback fullRefresh

Type

boolean function boolean

Description

If true

, the refreshed subtab displays immediately. If false

, the refreshed subtab displays in the background.

JavaScript method that’s called upon completion of the method.

Enables a full refresh of the entire case feed.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to refresh a subtab by name and primary tab name </A >

<apex:includeScript value= "/support/console/22.0/integration.js" />

//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);

} var refreshSuccess = function refreshSuccess(result) {

//Report whether refreshing the subtab was successful if (result.success == true) { alert( 'Subtab successfully refreshed' );

} else { alert( 'Subtab did not refresh' );

}

};

</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:

Name

success

Type

boolean

Description

true

if the subtab refreshed successfully; false

if the subtab didn't refresh.

Methods for Primary Tabs and Subtabs 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

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/35.0/integration.js" />

} else { alert( 'No tab was re-opened.' );

}

}; 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:

Name

success

Type

boolean

Description

true

if the tab was reopened, false

otherwise.

Methods for Primary Tabs and Subtabs resetSessionTimeOut()

resetSessionTimeOut()

Resets a session timeout on a Visualforce page so that users can continue working without being logged out. 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" >

Click here to reset session timeout </A >

<apex:includeScript value= "/support/console/24.0/integration.js" />

};

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

Syntax sforce.console.setTabUnsavedChanges(unsaved:

Boolean

, callback:

Function

(optional)subtabId:

String

)

Methods for Primary Tabs and Subtabs

Arguments

Name

unsaved callback subtabId

Type

boolean function string setTabUnsavedChanges()

Description

If true

, the tab is marked as having unsaved changes.

JavaScript method that’s called upon completion of the method.

The ID of the subtab that is marked as having unsaved changes.

This argument is only available in API version 25.0 or later.

Sample Code API Version 23.0 or Later–Visualforce

<apex:page standardController= "Case" >

Click here to indicate this tab has unsaved changes </A >

<apex:includeScript value= "/support/console/23.0/integration.js" />

}; 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:

Name

success

Type

boolean

Description

true

if update was successful; false

if update wasn't successful.

Sample Code API Version 25.0 or Later–Visualforce

<apex:page standardController= "Case" >

Click here to indicate this tab has unsaved changes </A >

Methods for Primary Tabs and Subtabs setTabIcon()

<apex:includeScript value= "/support/console/25.0/integration.js" />

}; function setTabDirty(result) { sforce.console.setTabUnsavedChanges(true, displayResult, result.id);

}; function displayResult(result) { if (result.success) {

};

</script >

</apex:page > alert( 'Tab status has been successfully updated' );

} else { alert( 'Tab status couldn’t be updated' );

}

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

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if returning the focused subtab ID was successful; false

if if returning the focused subtab ID wasn't successful.

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

)

Arguments

Name

iconUrl

Type

string

Description

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.

Methods for Primary Tabs and Subtabs setTabIcon()

Name

tabId callback

Type

string function

Description

The ID of the tab on which to set the icon. If null or undefined, the enclosing tab’s

ID is used.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to change the enclosing tab’s icon </A > <BR/ >

Click here to reset the enclosing tab’s icon </A >

<apex:includeScript value= "/support/console/28.0/integration.js" />

} 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:

Name

success

Type

boolean

Description

true

if setting the tab’s icon was successful, false

if setting the tab’s icon wasn’t successful.

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.

Methods for Primary Tabs and Subtabs setTabLink()

setTabLink()

Syntax sforce.console.setTabLink((optional)callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page standardController= "Account" >

<apex: detail />

<apex:includeScript value= "/support/console/28.0/integration.js" />

};

</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:

Name

success callback

Type

boolean function

Description

true

if the link was set successfully, false

if setting was unsuccessful.

JavaScript method that’s called upon completion of the method.

setTabStyle()

Methods for Primary Tabs and Subtabs setTabStyle()

Syntax sforce.console.setTabStyle(style:

String

, tabId:

String

, (optional)callback:

Function

)

Arguments

Name

style tabId callback

Type

string string function

Description

A CSS specification string used to style the tab. If null or undefined, the tab’s default style is used.

The ID of the tab on which to set the style. If null or undefined, the enclosing tab’s

ID is used.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to change the enclosing tab’s background color to red </A > <BR/ >

Click here to reset the enclosing tab’s style </A >

<apex:includeScript value= "/support/console/28.0/integration.js" />

} 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:

Methods for Primary Tabs and Subtabs

Name

success

Type

boolean setTabTextStyle()

Description

true

if setting the tab’s style was successful, false

if setting the tab’s style wasn’t successful.

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()

Syntax sforce.console. setTabTextStyle(style:

String

, tabID:

String

, (optional)callback:

Function

))

Arguments

Name

style tabId callback

Type

string string function

Description

A CSS specification string used to set a tab’s text style. If null or undefined, the tab’s default text style is used.

The ID of the tab on which to set the text style. If null or undefined, the enclosing tab’s ID is used.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to change the enclosing tab’s text style </A > <BR/ >

Click here to reset the enclosing tab’s text style </A >

<apex:includeScript value= "/support/console/28.0/integration.js" />

} else { alert( 'Tab text style cannot be set!' );

}

Methods for Primary Tabs and Subtabs setTabTitle() function testSetTabTextStyle() { sforce.console.setTabTextStyle( 'color:blue;font-style:italic;' , null, checkResult);

} function testResetTabTextStyle() { sforce.console.setTabTextStyle(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:

Name

success

Type

boolean

Description

true

if setting the tab’s text style was successful, false

if setting the tab’s text style wasn’t successful.

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

tabTitle tabId

Type

string string

Description

Title of a primary tab or subtab.

The ID of the tab in which to set the title.

This argument is only available in API version 25.0 or later.

Sample Code–Visualforce API Version 20.0 or Later

<apex:page standardController= "Case" >

Methods for Primary Tabs and Subtabs setTabTitle()

Click here to change this tab 's title</A>

<apex:includeScript value= "/support/console/20.0/integration.js" />

//Set the current tab 's title sforce.console.setTabTitle( 'My New Title' );

}

</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

Sample Code–Visualforce API Version 25.0 or Later

<apex:page >

Click here to change the title of the focused primary tab </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

}

</script >

</apex:page >

}); sforce.console.setTabTitle( 'My New Title' , result.id);

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

Response

None

CHAPTER 4 Methods for Navigation Tabs

A Salesforce console displays a navigation tab from which users can select objects to view lists or home pages. Administrators choose the objects that users can access from a navigation tab. For more information, see “Salesforce Console Navigation Tab” and “Set up a

Salesforce Console App” in the online help.

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.

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

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

Methods for Navigation Tabs getNavigationTabs() alert( 'success' );

} else{ alert( 'Something is wrong.' );

}

}; sforce.console.focusNavigationTab(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:

Name

success

Type

boolean

Description

true

if returning the object IDs was successful; false

otherwise.

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

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

Methods for Navigation Tabs getSelectedNavigationTab()

+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:

Name

menuItems success

Type

object boolean

Description

The IDs of objects in the navigation tab.

true

if returning the IDs of objects in the navigation tab was successful, false otherwise.

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

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

Methods for Navigation Tabs refreshNavigationTab()

} else { alert( 'something is wrong!' );

}

}; sforce.console.getSelectedNavigationTab(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:

Name

navigationTabId listViewUrl label selected success

Type

string object object boolean boolean

Description

The object ID of the selected object.

The list view URL of the selected object.

The label of the selected object.

true

if returning the selected field of the object was successful, false

otherwise.

true

if returning the object IDs was successful, false

otherwise.

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

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

Methods for Navigation Tabs setSelectedNavigationTab() alert( 'success' );

} else{ alert( 'Something is wrong.' );

}

}; sforce.console.refreshNavigationTab(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:

Name

success

Type

boolean

Description

true

if refreshing the navigation tab was successful, false

otherwise.

setSelectedNavigationTab()

Sets the navigation tab with a specific ID or URL. This method is only available in API version 31.0 or later.

Syntax sforce.console.setSelectedNavigationTab((optional)callback, navigatorTabId:(optional)

string

, url:(optional)

string

)

Arguments

Name

callback navigatorTabId url

Type

function string string

Description

JavaScript method that’s called upon completion of the method.

The ID of the navigation tab to be selected.

The URL of the navigation tab to be selected.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

} else {

Methods for Navigation Tabs setSelectedNavigationTab() 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:

Name

success

Type

boolean

Description

true

if setting the navigation tab with a specific ID or URL was successful, false otherwise.

CHAPTER 5 Methods for Computer-Telephony

Integration (CTI)

Salesforce Call Center seamlessly integrates Salesforce with Computer-Telephony Integration systems. Whether developers create a CTI system with Open CTI or the CTI Toolkit, console users access telephony features through a SoftPhone, which is a call-control tool that appears in the footer of a console. For more information, see “Salesforce Open CTI” and “Salesforce Call Center” in the Salesforce Help.

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

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

Registers a function that is fired when a message is sent with the sendCTIMessage()

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()

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

Methods for Computer-Telephony Integration (CTI) fireOnCallBegin()

setCallObjectIds()

Sets call object IDs, in ascending order of arrival. This method is only available in API version 31.0 or later.

fireOnCallBegin()

Syntax sforce.console.cti.fireOnCallBegin( callObjectId:

String

, callType:

String

, callLabel:

String

(optional)callback:

Function

)

Arguments

Name

callObjectId callType callLabel callback

Type

string string string function

Description

The object ID of the call.

String that specifies the call type, which must be internal

, inbound

or outbound

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

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to start a call </A >

<apex:includeScript value= "/support/console/31.0/integration.js" />

}

</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:

Methods for Computer-Telephony Integration (CTI)

Name

success

Type

boolean

Description

true

if firing the event is successful, false

otherwise.

fireOnCallEnd()

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.

Syntax sforce.console.cti.fireOnCallEnd( callObjectId:

String

, callDuration:

Number

, callDisposition:

String

, (optional)callback:

Function

)

Arguments

Name

callObjectId callDuration callDisposition callback

Type

string number string function

Description

The object ID of the call.

Number specifying the duration of the call.

String representing the call’s disposition, such as call successful, left voicemail, or disconnected.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to end a call </A >

<apex:includeScript value= "/support/console/31.0/integration.js" />

//Here, 'call.1' refers to a call that is in progress.

sforce.console.cti.fireOnCallEnd( 'call.1' , 60, 'Set Appointment' );

}

</script >

</apex:page >

Methods for Computer-Telephony Integration (CTI) fireOnCallLogSaved()

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if firing the event is successful, false

otherwise.

fireOnCallLogSaved()

Calls the eventHandler

function registered with

. 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.fireOnCallLogSaved( id:

String

, (optional)callback:

Function

)

Arguments

Name

id callback

Type

string function

Description

The object ID of the saved call log.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

}; function testFireOnCallLogSaved() {

// Simulates that a call log was saved by passing the task object Id as input.

sforce.console.cti.fireOnCallLogSaved( '00Txx000003qf8u' , myCallback);

} var callback = function (result) { alert( 'Call Log was saved! Object Id saved is : ' + result.id);

}; sforce.console.cti.onCallLogSaved(callback);

</script >

Methods for Computer-Telephony Integration (CTI) getCallAttachedData()

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:

Name

success

Type

boolean

Description

true

if firing the event is successful, false

otherwise.

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

callObjectId getCallType callback

Type

string boolean function

Description

The call object ID of the call that retrieves the attached data.

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.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

/* Note: Open CTI needs to set call type to before getting it, and call type is

INTERNAL/INBOUND/OUTBOUND.

*/ var callback2 = function (result) { alert( 'Call attached data is ' + result.data + '\n Call Type is ' + result.type);

Methods for Computer-Telephony Integration (CTI) getCallObjectIds()

};

/* Retrieving call ID of first call that came in and

* calling getCallAttachedData() to retrieve call data.

*/ var callback1 = function (result) { if (result.ids && result.ids.length > 0) { sforce.console.cti.getCallAttachedData(result.ids[0], callback2,

{getCallType:true});

}

};

//Note that we are using the CTI submodule here function testGetCallAttachedData() { sforce.console.cti.getCallObjectIds(callback1);

};

</script >

<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:

Name

data success type

Type

string boolean string

Description

The attached data of a call in JSON format.

true

if returning the attached data was successful; false

if returning the attached data wasn’t successful.

The type of call. Possible values are 'INTERNAL', 'INBOUND', and 'OUTBOUND'.

getCallObjectIds()

Syntax sforce.console.cti.getCallObjectIds( (optional) callback:

Function

)

Methods for Computer-Telephony Integration (CTI)

Arguments

Name

callback

Type

function

Description

JavaScript method called upon completion of the method.

onCallBegin()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/24.0/integration.js" />

};

//Note that we are using the CTI submodule here sforce.console.cti.getCallObjectIds(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:

Name

ids success

Type

string boolean

Description

The call object IDs of active calls or null if no call is active.

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

)

Methods for Computer-Telephony Integration (CTI)

Arguments

Name

eventHandler

Type

function

Description

JavaScript method called when a call begins.

onCallEnd()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/24.0/integration.js" />

};

//Note that we are using the CTI submodule here sforce.console.cti.onCallBegin(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:

Name

Type

string

Description

The call object ID of the call which has begun.

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

eventHandler

Type

function

Description

JavaScript method called when a call ends.

Methods for Computer-Telephony Integration (CTI) onCallLogSaved()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/24.0/integration.js" />

};

//Note that we are using the CTI submodule here sforce.console.cti.onCallEnd(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:

Name

id duration disposition

Type

string string string

Description

The call object ID of the call which has ended.

The duration of the call.

The disposition of the call.

onCallLogSaved()

Syntax sforce.console.cti.onCallLogSaved( eventHandler:

Function

)

Arguments

Name

eventHandler

Type

function

Description

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.

Methods for Computer-Telephony Integration (CTI) onSendCTIMessage()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

}; 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:

Name

Type

string

Description

Call log object ID that was saved.

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

eventHandler

Type

function

Description

JavaScript method called when a message is sent with the sendCTIMessage() method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

Methods for Computer-Telephony Integration (CTI) var callback = function (result) { alert( 'sendCTIMessage API sent the following message: ' + result.message);

}; sforce.console.cti.onSendCTIMessage(callback); function sendCTIMessage() { sforce.console.cti.sendCTIMessage( 'sending a message to CTI' );

}

</script >

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:

Name

message

Type

string

Description

The message that was sent with the sendCTIMessage()

method.

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

msg callback

Type

string function

Description

Message to send to the adapter.

JavaScript method called when the message is sent.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/24.0/integration.js" />

82 sendCTIMessage()

Methods for Computer-Telephony Integration (CTI) setCallAttachedData()

} else { alert( 'CTI message was not sent successfully.' );

}

};

//Note that we are using the CTI submodule here sforce.console.cti.sendCTIMessage('/ANSWER?LINE_NUMBER= 1 ', 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:

Name

success

Type

boolean

Description

true

if sending the message was successful; false

if sending the message wasn’t successful.

setCallAttachedData()

Syntax sforce.console.cti.setCallAttachedData( callObjectId:

String

, callData:

JSON string

callType:

String

, (optional)callback:

Functional

)

Arguments

Name

callObjectId callData callType callback

Type

string string string function

Description

The object ID of the call.

JSON string that specifies the data to attach to the call.

String that specifies the call type, such as internal

, inbound

, or outbound

JavaScript method called upon completion of the method.

Methods for Computer-Telephony Integration (CTI) setCallObjectIds()

Sample Code–Visualforce

<apex:page >

Click here to set call attached data </A >

<apex:includeScript value= "/support/console/31.0/integration.js" />

//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" });

}

</script >

</apex:page >

//Set the call attached data associated to call id 'call.1' sforce.console.cti.setCallAttachedData( 'call.1' , callData, 'outbound' );

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if the event firing was successful; false

otherwise.

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

callObjectId callback

Type

array function

Description

An array of string IDs specifying the calls to set.

JavaScript method called upon completion of the method.

Methods for Computer-Telephony Integration (CTI) setCallObjectIds()

Sample Code–Visualforce

<apex:page >

Click here to set call object Ids </A >

<apex:includeScript value= "/support/console/31.0/integration.js" />

} else { alert( 'Call object ids cannot be set!' );

}

} function testSetCallObjectIds() { sforce.console.cti.setCallObjectIds([ 'call.1' , 'call.2' , 'call.3' ], 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:

Name

success

Type

boolean

Description

true

if setting the call IDs was successful; false

otherwise.

CHAPTER 6 Methods for Application-Level Custom

Console Components

Custom console components let you customize, extend, or integrate the footer, sidebars, highlights panels, and interaction logs of a

Salesforce console using Visualforce, canvas apps, lookup fields, or related lists. Administrators can add components to either:

•

Page layouts to display content on specific pages

•

Salesforce console apps to display content across all pages and tabs

For more information, see “Console Components” in the Salesforce Help.

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

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.

Methods for Application-Level Custom Console Components addToBrowserTitleQueue()

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

Syntax sforce.console.addToBrowserTitleQueue( title:

String

, callback:

Function

)

Methods for Application-Level Custom Console Components

Arguments

Name

title callback

Type

string function blinkCustomConsoleComponentButtonText()

Description

Browser tab title that is displayed.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to enqueue a browser title </A >

<apex:includeScript value= "/support/console/28.0/integration.js" />

}

</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:

Name

success callback

Type

boolean function

Description

If true

, the title was successfully added to the browser title queue. If false

, the title wasn’t added to the browser title queue.

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

)

Methods for Application-Level Custom Console Components

Arguments

Name

alternateText interval callback

Type

string number function isCustomConsoleComponentPoppedOut()

Description

The alternate text to display when the button text blinks.

Controls how often the text blinks in milliseconds.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to blink the button text on a custom console component </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

//Blink the custom console component button text sforce.console.blinkCustomConsoleComponentButtonText( 'Hello World' , 10, function(result){

}

});

</script >

</apex:page > if (result.success) { alert( 'The text blinking starts!' );

} else { alert( 'Could not initiate the text blinking!' );

}

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if blinking, the button text was successful; false

if blinking the button text wasn't successful.

isCustomConsoleComponentPoppedOut()

Methods for Application-Level Custom Console Components isCustomConsoleComponentWindowHidden()

Syntax sforce.console.isCustomConsoleComponentPoppedOut (callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Is this component popped out?

</A > <BR/ >

<apex:includeScript value= "/support/console/30.0/integration.js" />

} 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:

Name

success poppedOut

Type

boolean boolean

Description

true

if returning the component’s pop out status was successful; false

otherwise.

true

if the component is popped out; false

otherwise.

isCustomConsoleComponentWindowHidden()

Determines if the application-level custom console component window is hidden. This method is available in API versions 25.0 through

31.0.

Methods for Application-Level Custom Console Components 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 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

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to check if the custom console component window is hidden </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

} var checkWindowVisibility = function checkWindowVisibility(result) {

//Display the window visibility if (result.success) { alert( 'Is window hidden: ' + result.hidden);

} else { alert( 'Error!' );

}

</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:

Methods for Application-Level Custom Console Components

Name

hidden success

Type

boolean boolean isCustomConsoleComponentHidden()

Description

true

if the custom console component window is hidden; false

if the custom console component window is visible.

true

if returning the custom console component window visibility was successful; false

if returning the custom console component window visibility wasn't successful.

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

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to check if the custom console component window is hidden </A >

<apex:includeScript value= "/support/console/32.0/integration.js" />

} var checkWindowVisibility = function checkWindowVisibility(result) {

//Display the window visibility if (result.success) { alert( 'Is window hidden: ' + result.hidden);

} else { alert( 'Error!' );

}

</script >

Methods for Application-Level Custom Console Components isInCustomConsoleComponent()

</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:

Name

hidden success

Type

boolean boolean

Description

true

if the custom console component window is hidden; false

if the custom console component window is visible.

true

if the isCustomConsoleComponentHidden()

call was successful; false

if the isCustomConsoleComponentHidden()

call wasn’t successful.

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

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to check if the page is in an app-level custom console component </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

} var checkInComponent = function checkInComponent(result) {

Methods for Application-Level Custom Console Components onCustomConsoleComponentButtonClicked()

};

//Check if in component alert( 'Is in custom console component: ' + result.inCustomConsoleComponent);

</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:

Name Type

inCustomConsoleComponent boolean success boolean

Description

true

if the page is in a custom console component; false

if the page isn’t in a custom console component.

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

callback

Type

function

Description

JavaScript method called when a button is clicked on a custom console component.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/25.0/integration.js" />

' and the component window is: ' + (result.windowHidden ?

'hidden' :

Methods for Application-Level Custom Console Components onFocusedPrimaryTab()

'visible' ));

}; sforce.console.onCustomConsoleComponentButtonClicked(eventHandler);

</script >

</apex:page >

Event Handler Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

id windowHidden

Type

string boolean

Description

The ID of the custom console component which includes the page.

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

eventHandler

Type

function

Description

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/25.0/integration.js" />

Methods for Application-Level Custom Console Components removeFromBrowserTitleQueue()

+ result.id + 'and the object Id is:' + result.objectId);

}; sforce.console.onFocusedPrimaryTab(eventHandler);

</script >

</apex:page >

Event Handler Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:

Name

id objectId

Type

string string

Description

The ID of the primary tab on which the browser is focused.

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

title callback

Type

string function

Description

Browser tab title to remove.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/28.0/integration.js" />

<A HREF= "#" onClick= "testAddToBrowserTitleQueue();return false" > {

Click here to enqueue a browser title </A >

Click here to remove browser title </A >

Methods for Application-Level Custom Console Components runSelectedMacro() var title = 'TestTitle' ; function testAddToBrowserTitleQueue() { sforce.console.addToBrowserTitleQueue(title);

} function testRemoveFromBrowserTitleQueue() { sforce.console.removeFromBrowserTitleQueue(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:

Name

success callback

Type

boolean function

Description

If true

, the title was successfully removed from the browser title queue. If false

, the title wasn’t removed from the browser title queue.

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

callback

Type

function

Description

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/36.0/integration.js" />

}

Methods for Application-Level Custom Console Components scrollCustomConsoleComponentButtonText()

</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:

Name

cause success

Type

string boolean

Description

Explanation of function failure, if applicable true

if running the macro was successful; false

otherwise

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

interval pixelsToScroll isLeftScrolling callback

Type

number number boolean function

Description

Controls how often the button text is scrolled in milliseconds.

Controls how many pixels the button text scrolls.

If true

, the text scrolls left. If false

, the text scrolls right.

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 >

Click here to scroll the button text on a custom console component </A >

Methods for Application-Level Custom Console Components selectMacro()

<apex:includeScript value= "/support/console/25.0/integration.js" />

//Scroll the custom console component button text from right to left sforce.console.scrollCustomConsoleComponentButtonText(500, 10, true, function(result){ if (result.success) {

}

</script >

</apex:page >

}

}); alert( 'The text scrolling starts!' );

} else { alert( 'Could not initiate the text scrolling!' );

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

success

Type

boolean

Description

true

if scrolling the button text was successful; false

if scrolling the button text wasn't successful.

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

callback macroID

Type

function string

Description

JavaScript method that is called when the method is completed

ID of the macro that’s selected

Methods for Application-Level Custom Console Components setCustomConsoleComponentButtonIconUrl()

Sample Code–Visualforce

<apex:page >

<A HREF= "#" onClick= "openInWidget(‘0JZ00123456789A’);return false" >Click here to select a macro </A >

<apex:includeScript value= "/support/console/36.0/integration.js" />

}

</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:

Name

cause success

Type

string boolean

Description

Explanation of function failure, if applicable true

if selecting the macro was successful; false

otherwise

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

iconUrl callback

Type

string function

Description

A URL that points to an image that’s used as a button to launch a custom console component.

JavaScript method that’s called upon completion of the method.

100

Methods for Application-Level Custom Console Components setCustomConsoleComponentButtonStyle()

Sample Code–Visualforce

<apex:page >

Click here to set the custom console component button icon </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

}

</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:

Name

success

Type

boolean

Description

true

if setting the button icon URL was successful; false

if setting the button icon URL wasn't successful.

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

style callback

Type

string function

Description

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

JavaScript method that’s called upon completion of the method.

101

Methods for Application-Level Custom Console Components setCustomConsoleComponentButtonText()

Sample Code–Visualforce

<apex:page >

Click here to set the style of a button used to launch a custom console component </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

}

</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:

Name

success

Type

boolean

Description

true

if setting the button style was successful; false

if setting the button style wasn't successful.

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

text callback

Type

string function

Description

Text that’s displayed on a button used to launch a custom console component.

JavaScript method that’s called upon completion of the method.

102

Methods for Application-Level Custom Console Components setCustomConsoleComponentHeight()

Sample Code–Visualforce

<apex:page >

Click here to set the text on a button used to launch a custom console component </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

//Change the custom console component button text to 'Hello World' sforce.console.setCustomConsoleComponentButtonText( 'Hello World' );

}

</script >

</apex:page >

Response

Name

success

Type

boolean

Description

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.

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 the Salesforce

Help.

Syntax sforce.console.setCustomConsoleComponentHeight( height:

number

, (optional)callback:

Function

)

Arguments

Name

height callback

Type

number function

Description

The new height in pixels.

Javascript method called upon completion of the method.

103

Methods for Application-Level Custom Console Components setCustomConsoleComponentVisible()

Sample Code–Visualforce

<apex:page >

Click here to set the custom console component height to 100px </A >

<apex:includeScript value= "/support/console/32.0/integration.js" />

// 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:

Name

success

Type

boolean

Description

true

if the method call was successful; false

otherwise.

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()

Syntax sforce.console.setCustomConsoleComponentVisible(visible:

Boolean

(optional)callback:

Function

)

Arguments

Name

visible callback

Type

boolean function

Description

true

to make the custom console component window visible, false

to hide the custom console component window.

JavaScript method that’s called upon completion of the method.

104

Methods for Application-Level Custom Console Components setCustomConsoleComponentWidth()

Sample Code–Visualforce

<apex:page >

Click here to make the custom console component window visible </A >

<apex:includeScript value= "/support/console/32.0/integration.js" />

// Make the custom console component window visible sforce.console.setCustomConsoleComponentVisible(true);

}

</script >

</apex:page >

Response

Name

success

Type

boolean

Description

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.

Help.

Syntax sforce.console.setCustomConsoleComponentWidth( width:

number

, callback:

Function

)

Arguments

Name

width callback

Type

number function

Description

The new width in pixels.

Javascript method called upon completion of the method.

105

Methods for Application-Level Custom Console Components setCustomConsoleComponentPopoutable()

Sample Code–Visualforce

<apex:page >

Click here to set the custom console component width to 100px </A >

<apex:includeScript value= "/support/console/32.0/integration.js" />

// 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:

Name

success

Type

boolean

Description

true

if the method call was successful; false

otherwise.

setCustomConsoleComponentPopoutable()

Syntax sforce.console.setCustomConsoleComponentPopoutable(popoutable:

Boolean

(optional)callback:

Function

)

Arguments

Name

popoutable callback

Type

boolean function

Description

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.

JavaScript method that’s called upon completion of the method.

106

Methods for Application-Level Custom Console Components setCustomConsoleComponentWindowVisible()

Sample Code–Visualforce

<apex:page >

Click here to enable pop out or pop in functionality </A > <BR/ >

Click here to disable pop out or pop in functionality </A >

<apex:includeScript value= "/support/console/30.0/integration.js" />

} 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:

Name

success

Type

boolean

Description

true

if enabling pop out or pop in functionality for the component was successful; false

otherwise.

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.

Help. Starting in API version 32.0, this method is no longer available and has been replaced by setCustomConsoleComponentVisible()

. For more information, see

setCustomConsoleComponentVisible()

107

Methods for Application-Level Custom Console Components setSidebarVisible()

Syntax sforce.console.setCustomConsoleComponentWindowVisible(visible:

Boolean

(optional)callback:

Function

)

Arguments

Name

visible callback

Type

boolean function

Description

true

to make the custom console component window visible, false

to hide the custom console component window.

JavaScript method that’s called upon completion of the method.

Sample Code–Visualforce

<apex:page >

Click here to make the custom console component window visible </A >

<apex:includeScript value= "/support/console/25.0/integration.js" />

//Make the custom console component window visible sforce.console.setCustomConsoleComponentWindowVisible(true);

}

</script >

</apex:page >

Response

Name

success

Type

boolean

Description

true

if setting the button window visibility was successful; false

if setting the button window visibility wasn't successful.

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

)

108

Methods for Application-Level Custom Console Components

Arguments

Name

visible tabId region

Type

boolean string string callback function setSidebarVisible()

Description

true

to show the sidebar or false

to hide the sidebar.

The ID of the tab on which to show or hide the sidebar.

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

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/33.0/integration.js" />

}else { alert( 'something is wrong!' );

}

}; function setSidebarVisible() { sforce.console.setSidebarVisible(true, 'scc-st-1' ,sforce.console.Region.LEFT,callback);

}

</script >

<A HREF= "#" onClick= "setSidebarVisible(); return false" >SetSidebarToExpand </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:

Name

success

Type

boolean

Description

true

if the method call was successful; false

otherwise.

109

CHAPTER 7 Methods for Push Notifications

Push notifications are visual indicators on lists and detail pages in a console that show when a record or field has changed during a user’s session. For example, if two support agents are working on the same case, and one agent changes the

Priority

, a push notification appears to the other agent so he or she spots the change and doesn’t duplicate the effort.

When administrators set up a Salesforce console, they choose when push notifications display, and which objects and fields trigger push notifications. Developers can use push notification methods to customize push notifications beyond the default visual indicators supplied by Salesforce. For example, developers can use the methods below to create personalized notifications about objects accessible to specific console users, thereby eliminating the need for email notifications. For more information, see “Configure Push Notifications for a Salesforce Console” in the Salesforce Help.

Consider the following when using push notification methods:

•

Push notification listener response is only available for the objects and fields selected to trigger push notifications for a console.

•

When a Visualforce page includes a listener added by the addPushNotificationListener()

method, the page receives notifications. The listener receives notifications when there is an update by any user to the objects selected for triggering console push notifications and the current user has access to the modified record. This functionality is slightly different from push notifications set up in the Salesforce user interface in that:

–

Listeners receive update notifications for changes made by all users.

–

Listeners receive notifications when an object’s fields are updated or created, even if those fields aren’t selected to trigger push notifications; and the notifications don’t include details about what changed. For example, if

Status

on the Case object is set to trigger a push notification, but

Priority

on the Case object changes, a listener receives a notification that the case changed without specifying details.

–

Listeners don’t obey the

Choose How Lists Refresh

and

Choose How Detail Pages Refresh

push notifications settings in a Salesforce console.

–

The only way to stop receiving notifications is to remove listeners using the removePushNotificationListener() method.

•

Push notifications aren't available in the console in Professional Edition.

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.

addPushNotificationListener()

For more information on push notifications, see

Methods for Push Notifications

on page 110.

110

Methods for Push Notifications addPushNotificationListener()

Syntax sforce.console.addPushNotificationListener( objects: array, eventHandler:

Function

)

Arguments

Name

objects eventHandler

Type

array function

Description

Objects set to receive notifications.

JavaScript method called when there is a push notification.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/26.0/integration.js" />

};

//Add a push notification listener for Case and Account sforce.console.addPushNotificationListener([ 'Case' , 'Account' ], eventHandler);

</script >

</apex:page >

Response

This method is asynchronous so it returns its response in an object in a callback method.

Name

id entityType

Type

LastModifiedById

Type

string string string string

Description

The object ID of the push notification.

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 the Salesforce online help.

The field of the object included in the push notification. For example, the

Account

Name

field on Account. Notifications occur when the field is either updated or created.

Fields on 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 the Salesforce online help.

The user ID of the user who last modified the object in the push notification.

111

Methods for Push Notifications removePushNotificationListener()

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

Syntax sforce.console.removePushNotificationListener((optional) callback:

Function

)

Arguments

Name

callback

Type

function

Description

A function called when the removal of the push notification listener completes.

Sample Code–Visualforce

<apex:page standardController= "Case" >

Click here to remove push notification </A >

<apex:includeScript value= "/support/console/26.0/integration.js" />

} var removeSuccess = function removeSuccess(result) {

//Report whether removing the push notification listener is successful if (result.success == true) {

};

</script >

</apex:page > alert( 'Removing push notification was successful' );

} else { alert( 'Removing push notification wasn' t successful ');

}

Response

This method is asynchronous so it returns its response in an object in a callback method.

Name

success

Type

boolean

Description

true

if removing the push notification listener was successful; false

if removing the push notification listener wasn’t successful.

112

CHAPTER 8 Methods for Console Events

JavaScript can be executed when certain types of events occur in a console, such as when a user closes a tab. The following standard events are supported:

Event Description Payload

sforce.console.ConsoleEvent.OPEN_TAB

Fired when a primary tab or subtab is opened.

Available in API version 30.0 or later.

•

— The ID of the opened tab.

•

objectId

— The object ID of the opened tab, if available.

sforce.console.ConsoleEvent.CLOSE_TAB

Fired when a primary tab or subtab with a specified ID in the additionalParams argument is closed. Or, fired when a primary tab or subtab with no specified ID is closed.

Available in API version 30.0 or later.

•

— The ID of the closed tab.

•

objectID

— The object ID of the closed tab, if available.

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.

•

tabObjectId

— The object ID of the closed tab, if available.

Note: tabObjectId

is generally the same as objectID

. However, for tabs that close upon submission, no tabObjectId

is generated. In those cases, the value of this field is either empty or null. For an Email, the value is empty.

For a Case Comment, the value is null.

sforce.console.ConsoleEvent.CONSOLE_LOGOUT

Delays the execution of logging out of a console when a user clicks Logout. When

Logout is clicked:

1. An overlay appears, which tells a user that logout is in progress.

2. Callbacks are executed that have been registered by using sforce.console.ConsoleEvent.CONSOLE_LOGOUT

3. Console logout logic is executed.

None

If the callback contains synchronous blocking code, the console logout code isn’t executed until the blocking code is executed. As a best

113

Methods for Console Events

Event

addEventListener()

Description

practice, avoid synchronous blocking code or long code execution during logout.

Available in API version 31.0 or later.

Payload

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()

For the list of standard events, see

Methods for Console Events on page 113.

Syntax sforce.console.addEventListener( eventType:

(optional)additionalParams:

Object

)

String

, eventListener:

Function

Arguments

Name

eventType eventListener additionalParams

Type

string function object

Description

Custom event type for which eventListener listens.

JavaScript method called when an eventType is fired.

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.

114

Methods for Console Events addEventListener()

Sample Code API Version 25.0 or Later–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/25.0/integration.js" />

};

//Add a listener for the 'SampleEvent' event type sforce.console.addEventListener( 'SampleEvent' , listener);

</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:

Name

message

Type

string

Description

The message which is sent with the fired event.

If the response is from a custom keyboard shortcut, the message

includes the following information on which the browser is focused, in this order:

1. Object ID of the primary tab

2. ID of the primary tab

3. Object ID of the subtab

4. ID of the subtab

For more information, see “Customize Keyboard Shortcuts for a Salesforce Console” in the online help.

Sample Code API Version 30.0 or Later–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/30.0/integration.js" />

+ ', Object ID: ' + (result.objectId ? result.objectId : 'not available' ));

};

//Add a listener to handle the closing of the enclosing primary tab sforce.console.getEnclosingPrimaryTabId(function (result) { if (result.id) { sforce.console.addEventListener(sforce.console.ConsoleEvent.CLOSE_TAB, onEnclosingPrimaryTabClose, { tabId : result.id });

} else {

115

Methods for Console Events fireEvent()

}

});

</script >

</apex:page > alert( 'Could not find an enclosing primary TAB!' );

Response

This method is asynchronous, so it returns its response in an object in a callback method. The response object contains the following field:

Name

message

Type

string

Description

The message which is sent with the fired event.

If the response is from a console event, the message

includes payload details as described in

Methods for Console Events on page 113.

If the response is from a custom keyboard shortcut, the message

includes the following information on which the browser is focused, in this order:

1. Object ID of the primary tab

2. ID of the primary tab

3. Object ID of the subtab

4. ID of the subtab

For more information, see “Customize Keyboard Shortcuts for a Salesforce Console” in the online help.

fireEvent()

Fires a custom event. This method is only available in API version 25.0 or later.

Syntax sforce.console.fireEvent( eventType:

String

, message:

String

, (optional)callback:

Function

)

Arguments

Name

eventType message callback

Type

string string function

Description

The type of custom event to fire.

The message which is sent with the fired event.

JavaScript method called when the custom event is fired.

116

Methods for Console Events removeEventListener()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/25.0/integration.js" />

Click here to fire an event of type 'SampleEvent' </A > var callback = function(result) { if (result.success) { alert( 'The custom event is fired!' );

} else { alert( 'The custom event could not be fired!' );

}

}; 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:

Name

success

Type

boolean

Description

true

if firing the event is successful, false

if firing the event wasn’t successful.

removeEventListener()

For the list of standard events, see

Methods for Console Events on page 113.

Syntax sforce.console.removeEventListener( eventType:

(optional)additionalParams:Object )

String

, eventListener:

Function

117

Methods for Console Events

Arguments

Name

eventType eventListener additionalParams

Type

string function object removeEventListener()

Description

Event type for which eventListener is removed.

Event listener to remove.

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.

Sample Code API Version 25.0 or Later–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/25.0/integration.js" />

Click here to remove an event listener for the 'SampleEvent' event type </A >

};

//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

Sample Code API Version 30.0 or Later–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/30.0/integration.js" />

Click here to remove an event listener for the console 'CLOSE_TAB' event type </A >

118

Methods for Console Events removeEventListener()

+ ',

Object ID: ' + (result.objectId ? result.objectId : ' not available '));

};

//Add a listener to handle the closing of the enclosing primary tab sforce.console.getEnclosingPrimaryTabId(function (result) { if (result.id) { tabId = result.id; sforce.console.addEventListener(sforce.console.ConsoleEvent.CLOSE_TAB, onEnclosingPrimaryTabClose, { tabId : tabId });

} else { alert( 'Could not find an enclosing primary TAB!' );

}

}); function testRemoveEventListener() { sforce.console.removeEventListener(sforce.console.ConsoleEvent.CLOSE_TAB, onEnclosingPrimaryTabClose, { tabId : tabId });

}

</script >

</apex:page >

Response

None

119

CHAPTER 9 Methods for Live Agent

Live Agent lets you connect with customers or website visitors in real time through Web-based chat. For more information, see “Add

Live Agent to the Salesforce Console” in the Salesforce Help.

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.

120

Methods for Live Agent

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.

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.

121

Methods for Live Agent acceptChat()

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.

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.

Syntax sforce.console.chat.acceptChat(chatKey:String, (optional)callback:

Function

)

Arguments

Name

chatKey callback

Type

String function

Description

The chat key for the chat request you wish to accept.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testAcceptChat();return false;" >Accept Chat </a >

//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' );

}

};

</script >

</apex:page >

} else { alert( 'Accepting the chat was not successful' );

122

Methods for Live Agent cancelFileTransferByAgent()

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

success

Type

Boolean

Description

true

if accepting the chat was successful; false

if accepting the chat wasn’t successful.

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

chatKey callback

Type

String function

Description

The chat key for the chat for which the agent canceled the file transfer request.

JavaScript method that is called when the method is completed.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

<a href= "#" onClick= "testCancelFileTransfer();return false;" >Cancel file transfer </a >

//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 {

123

Methods for Live Agent declineChat()

}

};

</script >

</apex:page > alert( 'Canceling file transfer was not successful.' );

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

success

Type

Boolean

Description

true

if canceling the file transfer request was successful; false

if canceling the file transfer request wasn’t successful.

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

chatKey callback

Type

String function

Description

The chat key for the request you wish to decline.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testDeclineChat();return false;" >Decline Chat </a >

//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);

}

124

Methods for Live Agent function declineSuccess(result) {

//Report whether declining the chat was succesful if (result.success == true) { alert( 'Declining the chat was successful' );

}

};

</script >

</apex:page >

} else { alert( 'Declining the chat was not successful' );

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

success

Type

Boolean

Description

true

if declining the event was successful; false

if declining the event wasn’t successful.

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

chatKey callback

Type

String function

Description

The chat key for the engaged chat you wish to end.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

125 endChat()

Methods for Live Agent getAgentInput() methods.

function testEndChat() {

//Get the value for 'myChatKey' from the getEngagedChats() or onChatStarted()

//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' );

}

};

</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:

Name

success

Type

Boolean

Description

true

if ending the chat was successful; false

if ending the chat wasn’t successful.

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

chatKey callback

Type

String function

Description

The chatKey

associated with the chat for which to retrieve the agent’s input text.

JavaScript method called upon completion of the method.

126

Methods for Live Agent getAgentState()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetAgentInput();" >Get Agent Input </a >

//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) {

} else { alert( 'Getting the agent input was not successful' );

} agentInput = result.text; alert( 'The text in the agent input is: ' + agentInput);

};

</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:

Name

text success

Type

String

Boolean

Description

The text that is currently in an agent’s text input area.

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

)

127

Methods for Live Agent

Arguments

Name

callback getChatLog()

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetAgentState();return false;" >Get Agent State </a >

} 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:

Name

state success

Type

String

Boolean

Description

String representing the current agent state—for example, Online, Away, or Offline.

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

)

128

Methods for Live Agent

Arguments

Name

chatKey callback

Type

String function

Description

The chatKey

associated with the chat for which to retrieve the chat log.

JavaScript method called upon completion of the method.

getChatLog()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

//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.getChatLog(chatKey, getChatLogSuccess);

} 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:

Name

customEvents

Type Description

Array of

customEvent

objects

An array of custom event objects representing the custom events that occurred during a chat.

129

Methods for Live Agent

Name

messages success getChatRequests()

Type

Array of

message

objects

Boolean

Description

An array of chat message objects containing all of the chat messages from the chat log.

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:

Property

source type data timestamp

Type

String

Date/Time

Description

The person who initiated the custom event, either the chat visitor or the agent.

The type of custom event that occurred.

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.

The date and time a custom event was received.

message

The message

object contains a single chat message from the chat log and the following properties:

Property

content name type timestamp

Type

String

Date/Time

Description

The text content of a message in the chat log.

The name of the user who sent the message in the chat log. This appears exactly as it is displayed in the chat log.

The type of message that was received, such as Agent or Visitor.

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

)

130

Methods for Live Agent

Arguments

Name

callback getDetailsByChatKey()

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetChatRequests();return false;" >Get Chat Requests </a >

} else { alert( 'getChatRequests 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:

Name

chatKey success

Type

Array

Boolean

Description

Array of chatKey

values, one for each of the current chat requests.

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

)

131

Methods for Live Agent

Arguments

Name

chatKey callback

Type

String function getDetailsByChatKey()

Description

The chatKey

associated with the chat for which to retrieve details.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetDetailsByChatKey();" >Get Chat Details </a >

//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 { alert( 'Getting the details 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:

Name

primaryTabId

details

success

Type

String

Object

Boolean

Description

The ID of the primary tab associated with the chat.

An object that contains all the details for a chat associated with a particular primary tab.

true

if retrieving the details was successful; false

if retrieving the details wasn’t successful.

132

Methods for Live Agent getDetailsByChatKey()

details

The details

object contains the following properties:

Property

acceptTime breadcrumbs chatKey customDetails

geoLocation

ipAddress isEnded isEngaged isPushRequest isTransferringOut liveChatButtonId

Type

Date/Time

Array of

breadcrumb

objects

String

Array of

customDetail

objects

Object

Description

The date and time an agent accepted the chat request.

An array of breadcrumb

objects representing a list of Web pages visited by the visitor before and during the chat.

The chat key associated with the chat.

An array of customDetail

objects that represent custom details that have been passed in to this chat via the Deployment API or Pre-Chat Form API.

String

Boolean

String liveChatDeploymentId

String name

String requestTime

visitorInfo

Date/Time

Object

An object representing the details of a chat visitor’s location, derived from a geoIP lookup on the chat visitor's IP address.

The IP address of the chat visitor in dot-decimal format.

Specifies whether a chat has ended ( true

) or not ( false

Specifies whether a chat is currently engaged ( true

) or not ( false

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

Specifies whether a chat is currently in the process of being transferred to another agent ( true

) or not ( false

The 15-digit record ID for the chat button from which the chat request originated.

The 15-digit record ID for the deployment from which the chat request originated.

The name of the chat visitor.

The date and time the chat was requested.

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:

Property

location time

Type

String

Date/Time

Description

The URL of a Web page viewed by a chat visitor.

The date and time a chat visitor visited a specific breadcrumb URL.

133

Methods for Live Agent getDetailsByChatKey()

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:

Property

label value

transcriptFields entityMaps

Type

String

Description

The name of the custom detail as specified in the Deployment API or Pre-Chat Form

API.

The value of the custom detail as specified in the Deployment API or Pre-Chat Form

API.

Array of Strings The names of fields where the customer’s details on the chat transcript are saved.

Array of

entityMap

objects

An array of pre-created records used for mapping custom detail information.

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:

Property

entityName fieldName isFastFillable isAutoQueryable isExactMatchable

Type

String

Boolean

Description

The record to search for or create.

The name of the field associated with the details.

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

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.

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:

Property

city

Type

String

Description

The name of the chat visitor’s city.

134

Methods for Live Agent

Property

countryCode countryName latitude longitude organization region

Type

String

String getDetailsByPrimaryTabId()

Description

The two-digit ISO-3166 country code for the chat visitor's country.

The name of chat visitor’s country.

The chat visitor's approximate latitude.

The chat visitor's approximate longitude.

The organization name of the chat visitor's internet service provider.

The chat visitor’s region, such as state or province.

visitorInfo

The visitorInfo

object represents information about the visitor's web browser. It contains the following properties:

Property

browserName language originalReferrer screenResolution sessionKey

Type

String

Description

The name and version of the chat visitor's web browser.

The language of the chat visitor's web browser.

The original URL of the Web page from which the chat visitor requested a chat.

The screen resolution of the chat visitor's computer, as passed by the chat visitor’s browser.

the sessionKey of the visitor which will ultimately be stored on the LiveChatVisitor record as a unique reference to this live chat visitor

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

primaryTabId callback

Type

String function

Description

The ID of the primary tab associated with the chat for which to retrieve details.

JavaScript method called upon completion of the method.

135

Methods for Live Agent getDetailsByPrimaryTabId()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetDetailsByPrimaryTabId();" >Get Chat Details </a >

//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' );

}

};

</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:

Name

primaryTabId

details

success

Type

String

Object

Boolean

Description

The ID of the primary tab associated with the chat.

An object that contains all the details for a chat associated with a particular primary tab.

true

if retrieving the details was successful; false

if retrieving the details wasn’t successful.

details

The details

object contains the following properties:

136

Methods for Live Agent getDetailsByPrimaryTabId()

Property

acceptTime breadcrumbs chatKey customDetails

geoLocation

ipAddress isEnded isEngaged isPushRequest isTransferringOut liveChatButtonId

Type

Date/Time

Array of

breadcrumb

objects

String

Array of

customDetail

objects

Object

Description

The date and time an agent accepted the chat request.

An array of breadcrumb

objects representing a list of Web pages visited by the visitor before and during the chat.

The chat key associated with the chat.

An array of customDetail

objects that represent custom details that have been passed in to this chat via the Deployment API or Pre-Chat Form API.

String

Boolean

String liveChatDeploymentId

String name requestTime

visitorInfo

String

Date/Time

Object

An object representing the details of a chat visitor’s location, derived from a geoIP lookup on the chat visitor's IP address.

The IP address of the chat visitor in dot-decimal format.

Specifies whether a chat has ended ( true

) or not ( false

Specifies whether a chat is currently engaged ( true

) or not ( false

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

Specifies whether a chat is currently in the process of being transferred to another agent ( true

) or not ( false

The 15-digit record ID for the chat button from which the chat request originated.

The 15-digit record ID for the deployment from which the chat request originated.

The name of the chat visitor.

The date and time the chat was requested.

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:

Property

location time

Type

String

Date/Time

Description

The URL of a Web page viewed by a chat visitor.

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:

137

Methods for Live Agent getDetailsByPrimaryTabId()

Property

label value

transcriptFields entityMaps

Type

String

Description

The name of the custom detail as specified in the Deployment API or Pre-Chat Form

API.

The value of the custom detail as specified in the Deployment API or Pre-Chat Form

API.

Array of Strings The names of fields where the customer’s details on the chat transcript are saved.

Array of

entityMap

objects

An array of pre-created records used for mapping the custom detail information.

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:

Property

entityName fieldName isFastFillable isAutoQueryable isExactMatchable

Type

String

Boolean

Description

The record to search for or create.

The name of the field associated the details.

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

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.

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:

Property

city countryCode countryName latitude

Type

String

Description

The name of the chat visitor’s city.

The two-digit ISO-3166 country code for the chat visitor's country.

The name of chat visitor’s country.

The chat visitor's approximate latitude.

138

Methods for Live Agent

Property

longitude organization region

Type

String

Description

The chat visitor's approximate longitude.

The organization name of the chat visitor's internet service provider.

The chat visitor’s region, such as state or province.

getEngagedChats()

visitorInfo

The visitorInfo

object represents information about the visitor's web browser. It contains the following properties:

Property

browserName language originalReferrer screenResolution sessionKey

Type

String

Description

The name and version of the chat visitor's web browser.

The language of the chat visitor's web browser.

The original URL of the Web page from which the chat visitor requested a chat.

The screen resolution of the chat visitor's computer, as passed by the chat visitor’s browser.

the sessionKey of the visitor which will ultimately be stored on the LiveChatVisitor record as a unique reference to this live chat visitor

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

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetEngagedChats();return false;" >Get Engaged Chats </a >

139

Methods for Live Agent getMaxCapacity() 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:

Name

chatKey success

Type

array boolean

Description

Array of chatKey

values, one for each of the currently engaged chats.

true

if getting engaged chats was successful; false

if getting engaged chats wasn’t successful.

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

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testGetMaxCapacity();return false;" >Get Max Capacity </a >

140

Methods for Live Agent initFileTransfer() 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:

Name

count success

Type

integer boolean

Description

Agent's current, maximum chat capacity.

true

if getting the agent’s capacity was successful; false

if getting the agent’s capacity wasn’t successful.

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

chatKey entityId callback

Type

String

String function

Description

The chat key for the chat the file is transferred from.

The ID of the transcript object to attach the transferred file to.

JavaScript method that is called when the method is completed.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

141

Methods for Live Agent onAgentSend()

<a href= "#" onClick= "testInitFileTransfer();return false;" >Init file transfer </a >

//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.' );

}

};

</script >

</apex:page >

} else { alert( 'Initiating file transfer was not successful.' );

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

success

Type

Boolean

Description

true

if the request to transfer a file was sent successfully; false

if the request wasn’t sent successfully.

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()

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

)

142

Methods for Live Agent

Arguments

Name

chatKey callback

Type

String function onAgentSend()

Description

The chatKey

associated with the chat for which to call a function when the agent sends a message.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}

//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 >

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

content name type timestamp success

Type

String

Date/Time

Boolean

Description

The text of the agent’s message.

The name of the agent who is attempting to send the message as it appears in the chat log.

The type of message that was received—for example, agent.

The date and time the agent attempted to send the chat message.

true

if firing event was successful; false

if firing event wasn’t successful.

143

Methods for Live Agent onAgentStateChanged()

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

eventHandler

Type

function

Description

JavaScript method called when the agent's Live Agent status has changed.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}; 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:

Name

state success

Type

String

Boolean

Description

String that represents the agent’s current Live Agent status—for example, Online,

Away, or Offline. When an agent switches from Offline to Away, you may see two returned values (Online then Away) instead of one (Away).

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.

144

Methods for Live Agent

Syntax sforce.console.chat.onChatCanceled(callback:

Function

)

Arguments

Name

callback

Type

function

Description

JavaScript method called upon completion of the method.

onChatCriticalWaitState()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

} 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:

Name

chatKey

Type

string

Description

The chat key for the chat request that has been canceled.

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.

Syntax sforce.console.chat.onChatCanceled(chatKey:

String

, callback:

Function

)

Arguments

Name

chatKey

Type

String

Description

The chatKey

associated with the chat for which the critical wait state has changed.

145

Methods for Live Agent

Name

callback

Type

function

Description

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}

//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 > onChatDeclined()

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

state

Type

Boolean

Description

Indicates whether the chat is in critical wait state ( true

) or not ( false

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

)

Arguments

Name

eventHandler

Type

function

Description

JavaScript method called when a chat request is declined.

146

Methods for Live Agent onChatEnded()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

} 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:

Name

chatKey success

Type

String

Boolean

Description

The chat key for the chat request that has been declined.

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

eventHandler

Type

function

Description

JavaScript method called when an engaged chat ends.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}

147

Methods for Live Agent onChatRequested() 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:

Name

chatKey success

Type

String

Boolean

Description

The chat key for the engaged chat that has ended.

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

eventHandler

Type

function

Description

JavaScript method called when a chat request is assigned to an agent.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

} sforce.console.chat.onChatRequested(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:

148

Methods for Live Agent

Name

chatKey success

Type

String

Boolean onChatStarted()

Description

The chat key for the incoming chat request.

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

eventHandler

Type

function

Description

JavaScript method called when a chat request is accepted and becomes an engaged chat.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

} sforce.console.chat.onChatStarted(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:

Name

chatKey success

Type

String

Boolean

Description

The chat key for the chat request that has become an engaged chat.

true

if firing event was successful; false

if firing event wasn’t successful.

149

Methods for Live Agent onChatTransferredOut()

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

eventHandler

Type

function

Description

JavaScript method called when a chat has been successfully transferred out to another agent.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

} 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:

Name

chatKey success

Type

String

Boolean

Description

The chat key for the chat that has been transferred.

true

if firing event was successful; false

if firing event wasn’t successful.

onCurrentCapacityChanged()

150

Methods for Live Agent onCustomEvent()

Syntax sforce.console.chat.onCurrentCapacityChanged(eventHandler:

Function

)

Arguments

Name

eventHandler

Type

function

Description

JavaScript method called when the agent's capacity for accepting chats has changed.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

} 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:

Name

count success

Type

integer

Boolean

Description

The number of chats in which the agent is currently engaged plus the number of chat requests currently assigned to the agent.

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.

Syntax sforce.console.chat.onCustomEvent(chatKey:String, type:String, callback:

Function

)

151

Methods for Live Agent

Arguments

Name

chatKey type callback

Type

String

String function onCustomEvent()

Description

The chatKey

associated with the chat for which to call a function when a custom event takes place.

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.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}

//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:

Name

type data source timestamp success

Type

String

Date/Time

Boolean

Description

The type of the custom event that was sent to this chat; corresponds to the type argument of the liveagent.chasitor.sendCustomEvent()

method used to send this event from the chat window.

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.

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.

The time and date the event was received.

true

if firing event was successful; false

if firing event wasn’t successful.

152

Methods for Live Agent onFileTransferCompleted()

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

chatKey callback

Type

String function

Description

The chat key for the chat the file was transferred from.

JavaScript method that is called when the method is complete.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/31.0/integration.js" />

<a href= "#" onClick= "testOnFileComplete();return false;" >test on file transfer complete </a >

//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 >

Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following properties:

153

Methods for Live Agent

Name

attachmentId success

Type

String

Boolean onNewMessage()

Description

The ID of the object created for the transferred file.

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

chatKey callback

Type

string function

Description

The chatKey

associated with the chat for which to call a function when a new customer message is received.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}

//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:

Name

content

Type

String

Description

The text of a message in the chat log.

154

Methods for Live Agent

Name

name type timestamp success onTypingUpdate()

Type

String

Date/Time

Boolean

Description

The name of the user who sent the message. This appears exactly as it is displayed in the chat log.

The type of message that was received, such as an Agent or Visitor message.

The date and time the message was received.

true

if firing event was successful; false

if firing event wasn’t successful.

onTypingUpdate()

Syntax sforce.console.chat.onTypingUpdate(chatKey:

String

, callback:

Function

)

Arguments

Name

chatKey callback

Type

String function

Description

The chatKey

associated with the chat for which to call a function when a customer begins typing a new message to the agent.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

}

//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 >

155

Methods for Live Agent 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:

Name

isTyping sneakPeek success

Type

Boolean

String

Boolean

Description

Indicates whether a chat visitor is typing ( true

) or not ( false

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.

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

chatKey type data callback

Type

String

String function

Description

The chatKey

associated with the chat to which to send a custom event.

The name of the custom event you want to send to the chat window.

Additional data you want to send to the chat window along with the custom event.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testSendCustomEvent();" >Send Custom Event </a >

//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'

156

Methods for Live Agent sendMessage() var data = 'myCustomEventData' sforce.console.chat.sendCustomEvent(chatKey, type, data, sendCustomEventSuccess);

} 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:

Name

success

Type

Boolean

Description

true

if sending the custom event was successful; false

if sending the custom event wasn’t successful.

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

chatKey message callback

Type

String

String function

Description

The chatKey

of the chat where the agent’s message is sent.

The message you would like to send from the agent to the customer in a chat.

JavaScript method called upon completion of the method.

157

Methods for Live Agent setAgentInput()

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testSendMessage();" >Send Message </a >

//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:

Name

success

Type

Boolean

Description

true

if sending the message was successful; false

if sending the message wasn’t successful.

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

)

158

Methods for Live Agent

Arguments

Name

chatKey text callback

Type

String

String function setAgentInput()

Description

The chatKey

associated with the chat for which to set the agent’s input text.

The string of text which you want to set into an agent's input.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testSetAgentInput();" >Set Agent Input </a >

//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:

Name

success

Type

Boolean

Description

true

if setting the agent’s input was successful; false

if setting the agent’s input wasn’t successful.

159

Methods for Live Agent setAgentState()

setAgentState()

Sets an agent's Live Agent status, such as Online, Away, or Offline. Available in API version 29.0 or later.

Syntax sforce.console.chat.setAgentState(state:

String

, (optional)callback:

Function

)

Arguments

Name

state callback

Type

String function

Description

Live Agent status you want to set the agent to—for example, Online, Away, or Offline.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/29.0/integration.js" />

<a href= "#" onClick= "testSetAgentState('Online');return false;" >Set Agent Status to

Online </a >

} 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:

Name

success

Type

Boolean

Description

true

if setting the agent’s Live Agent status was successful; false

if setting the agent’s Live Agent status wasn’t successful.

160

Methods for Live Agent Methods for Live Agent Chat Visitors

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.

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

Name

type callback

Type

string function

Description

The type of custom event you want to listen for.

JavaScript method called upon completion of the method.

Sample Code–Visualforce

//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);

};

161

Methods for Live Agent chasitor.getCustomEvents() testAddCustomEventListener();

</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:

Name

getType getData getSource getDate

Type

method method method method

Description

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.

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.

Accesses the source of the custom event that was sent to this chat window—for example, agent or chat visitor.

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 >

162

Methods for Live Agent chasitor.sendCustomEvent()

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:

Name

events getType getData getSource getDate

Type Description

Array of event

objects

An array of event

objects. Each object represents a custom event that has occurred in this chat. Data on each message object can be accessed by the following methods:

•

getType()

•

getData()

•

getSource()

•

getDate() method method method 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.

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.

Accesses the source of the custom event that was sent to this chat window—for example, agent or chat visitor.

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

Name

type data

Type

string string

Description

The name of the custom event to send to the agent console.

Additional data you want to send to the agent console along with the custom event.

163

Methods for Live Agent

Sample Code–Visualforce

<a href= "#" onClick= "testSendCustomEvent();" >Send Custom Event </a >

};

</script >

Response

This method returns no responses.

chasitor.sendCustomEvent()

164

CHAPTER 10 Methods for Omni-Channel

Omni-Channel is a comprehensive customer service solution that lets your call center route any type of incoming work item—including cases, chats, phone calls, or leads—to the most qualified, available agents in your organization. Omni-Channel provides a customizable customer service solution that integrates seamlessly into the Salesforce console and benefits your customers and support agents.

For more information on Omni-Channel, see Set Up Omni-Channel.

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.

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.

Methods for Omni-Channel Console Events

JavaScript can be executed when certain types of events occur in a console, such as when a user closes a tab. In addition to the standard methods for console events, there are a few events that are specific to Omni-Channel.

165

Methods for Omni-Channel 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

workId callback

Type

String function

Description

The ID of the work item the agent accepts.

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/34.0/integration.js" />

<a href= "#" onClick= "testAcceptWork();return false;" >Accept Assigned Work Item </a >

//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' );

}

});

}

</script >

</apex:page >

166

Methods for Omni-Channel closeAgentWork

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

success

Type

Boolean

Description

true

if accepting the work item was successful; false

if accepting the work item wasn’t successful.

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

workId callback

Type

String function

Description

The ID of the work item that’s closed.

JavaScript method to call when the work item associated with the workId

is closed.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/34.0/integration.js" />

<a href= "#" onClick= "testCloseWork();return false;" >Close Engaged Work Item </a >

//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)

{ if (result.success) { alert( 'Closed work successfully' );

} else {

167

Methods for Omni-Channel declineAgentWork

});

}

</script >

</apex:page >

} alert( 'Close work failed' );

});

} else {

} alert( 'The work item should be accepted first' );

}

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

success

Type

Boolean

Description

true

if closing the work item was successful; false

if closing the work item wasn’t successful.

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

workId declineReason callback

Type

String

String function

Description

The ID of the work item that the agent declines.

The provided reason for why the agent declined the work request.

JavaScript method to call when an agent declines the work item associated with the workId

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/34.0/integration.js" />

<a href= "#" onClick= "testDeclineWork();return false;" >Decline Assigned Work Item </a >

168

Methods for Omni-Channel getAgentWorks

{

//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:

Name

success

Type

Boolean

Description

true

if declining the work item was successful; false

if declining the work item wasn’t successful.

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

)

Arguments

Name

callback

Type

function

Description

JavaScript method to call when the list of an agent’s work items is retrieved.

169

Methods for Omni-Channel getAgentWorks

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/34.0/integration.js" />

<a href= "#" onClick= "testGetWorks();return false;" >Get Agent’s Current Work Items </a >

//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:

Name

success works

Type

Boolean

JSON string of

work

objects

Description

true

if retrieving the agent’s work items was successful; false

if retrieving the agent’s work items wasn’t successful.

A JSON string of work

objects that represents the work items assigned to the agent that are open in the agent’s workspace.

work

The work

object contains the following properties:

Name

workItemId workId isEngaged

Type

String

Boolean

Description

The ID of the object that’s routed through Omni-Channel. This object becomes a work assignment with a workId

when it’s assigned to an agent.

The ID of a work assignment that’s routed to an agent.

Indicates whether an agent is working on a work item that’s been assigned to them

( true

) or not ( false

170

Methods for Omni-Channel getAgentWorkload

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

callback

Type

function

Description

JavaScript method to call when the agent’s configured capacity and work retrieved.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/35.0/integration.js" />

</a >

Get Agent’s configured capacity and current workload

} else { alert( 'Get Agent Workload 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:

171

Methods for Omni-Channel

Name

success

Type

Boolean configuredCapacity

Number currentWorkload

Number getServicePresenceStatusChannels

Description

true

if retrieving the agent’s work items was successful; false

if retrieving the agent’s work items wasn’t successful.

Indicates the agent’s configured capacity (work that’s assigned to the current user) through Presence Configuration.

Indicates the agent’s currently assigned workload.

work

The work

object contains the following properties:

Name

workItemId workId isEngaged

Type

String

Boolean

Description

The ID of the object that’s routed through Omni-Channel. This object becomes a work assignment with a workId

when it’s assigned to an agent.

The ID of a work assignment that’s routed to an agent.

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

callback

Type

function

Description

JavaScript method to call when the channels associated with a presence status are retrieved.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/34.0/integration.js" />

Get Channels Associated with a Presence Status

172

Methods for Omni-Channel getServicePresenceStatusId

</a >

//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);

});

}

</script >

</apex:page >

} else { alert( 'Get Service Presence Status Channels 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:

Name

success channels

Type

Boolean

JSON string of channel objects

Description

true

if retrieving the current presence status channels was successful; false

if the retrieving the current presence status channels wasn’t successful.

Returns the IDs and API names of the channels associated with the presence status.

getServicePresenceStatusId

Retrieves an agent’s current presence status. Available in API versions 32.0 and later.

Syntax sforce.console.presence.getServicePresenceStatusId(callback:

function

)

Arguments

Name

callback

Type

function

Description

JavaScript method to call when the agent’s presence status is retrieved.

173

Methods for Omni-Channel

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/34.0/integration.js" />

<a href= "#" onClick= "testGetStatusId();return false;" >Get Omni-Channel Status ID </a >

} 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:

Name

success statusName statusApiName statusId

Type

Boolean

String

Description

true

if retrieving the presence status ID was successful; false

if the retrieving the presence status ID wasn’t successful.

The name of the agent’s current presence status.

The API name of the agent’s current presence status.

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

)

174

Methods for Omni-Channel

Arguments

Name

statusId callback

Type

String function

Description

The ID of the presence status. Agents must be given access to this presence status through their associated profile or permission set.

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/32.0/integration.js" />

<a href= "#" onClick= "testLogin('0N5xx00000000081');return false;" >Log In to

Omni-Channel </a >

//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:

Name

success

Type

Boolean

Description

true

if the login was successful; false

if the login wasn’t successful.

logout

logout

Logs an agent out of Omni-Channel. Available in API versions 32.0 and later.

175

Methods for Omni-Channel setServicePresenceStatus

Syntax sforce.console.presence.logout((optional) callback:

function

)

Arguments

Name

callback

Type

function

Description

JavaScript method to call when the agent is logged out of Omni-Channel.

Sample Code–Visualforce

<apex:page >

<apex:includeScript value= "/support/console/32.0/integration.js" />

<a href= "#" onClick= "testLogout();return false;" >Log out of Omni-Channel </a >

} 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:

Name

success

Type

Boolean

Description

true

if the logout was successful; false

if the logout wasn’t successful.

setServicePresenceStatus

176

Methods for Omni-Channel setServicePresenceStatus

Syntax sforce.console.presence.setServicePresenceStatus(statusId:

String

(optional) callback:

function

)

Arguments

Name

statusId callback

Type

String function

Description

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.

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/32.0/integration.js" />

<a href= "#" onClick= "testSetStatus('0N5xx00000000081');return false;" >Set Presence

Status </a >

//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:

177

Methods for Omni-Channel Methods for Omni-Channel Console Events

Name

success statusName statusApiName statusId channels

Type

Boolean

String

JSON string of channel objects

Description

true

if setting the agent’s status was successful; false

if setting the agent’s status wasn’t successful.

The name of the agent’s current presence status.

The API name of the agent’s current presence status.

The ID of the agent’s current presence status.

Returns the IDs and API names of the channels associated with the presence status.

Methods for Omni-Channel Console Events

Omni-Channel Console Events

Event Description

sforce.console.ConsoleEvent.

PRESENCE.LOGIN_SUCCESS

Fired when an

Omni-Channel user logs into Omni-Channel successfully.

Available in API version

32.0 or later.

Payload

•

statusId

—the ID of the agent’s current presence status.

sforce.console.ConsoleEvent.

PRESENCE.STATUS_CHANGED

Fired when a user changes his or her presence status.

Available in API version

32.0 or later.

•

statusId

—the ID of the agent’s current presence status.

•

channels

—channelJSON string of channel objects.

•

statusName

—the name of the agent’s current presence status.

•

statusApiName

—the API name of the agent’s current presence status.

sforce.console.ConsoleEvent.

PRESENCE.LOGOUT

Fired when a user logs out of Salesforce.

Available in API version

32.0 or later.

None sforce.console.ConsoleEvent.

PRESENCE.WORK_ASSIGNED

Fired when a user is assigned a new work item.

Available in API version

32.0 or later.

•

workItemId

—the ID of the object that’s routed through

Omni-Channel. This object becomes a work assignment with a workId

when it’s assigned to an agent.

178

Methods for Omni-Channel Methods for Omni-Channel Console Events

Event Description Payload

•

workId

—the ID of a work assignment that’s routed to an agent.

sforce.console.ConsoleEvent.

PRESENCE.WORK_ACCEPTED

Fired when a user accepts a work assignment, or when a work assignment is automatically accepted.

Available in API version

32.0 or later.

•

workItemId

—the ID of the object that’s routed through

Omni-Channel. This object becomes a work assignment with a workId

when it’s assigned to an agent.

•

workId

—the ID of a work assignment that’s routed to an agent.

sforce.console.ConsoleEvent.

PRESENCE.WORK_DECLINED

Fired when a user declines a work assignment.

Available in API version

32.0 or later.

•

workItemId

—the ID of the object that’s routed through

Omni-Channel. This object becomes a work assignment with a workId

when it’s assigned to an agent.

•

workId

—the ID of a work assignment that’s routed to an agent.

sforce.console.ConsoleEvent.

PRESENCE.WORK_CLOSED

Fired when a user closes a tab in the console that’s associated with a work item. When the tab for that work item is closed, the status of the

AgentWork object associated with it automatically changes to

“Closed.”

Available in API version

32.0 or later.

•

workItemId

—the ID of the object that’s routed through

Omni-Channel. This object becomes a work assignment with a workId

when it’s assigned to an agent.

•

workId

—the ID of a work assignment that’s routed to an agent.

sforce.console.ConsoleEvent.

PRESENCE.WORKLOAD_CHANGED

Fired when an agent’s workload changes. This includes receiving new work items, declining work items, and closing items in the console. It’s also fired when there’s a change to an agent’s capacity or

Presence Configuration or when the agent goes offline in the

Omni-Channel widget.

•

ConfiguredCapacity

—the configured capacity for the agent.

•

PreviousWorkload

—the agent’s workload before the change.

•

NewWorkload

—the agent’s new workload after the change.

channel

The channel

object contains the following functions:

179

Methods for Omni-Channel

Name

channelId developerName

Type

String

Methods for Omni-Channel Console Events

Description

Retrieves the ID of a service channel that’s associated with a presence status.

Retrieves the developer name of the the service channel that’s associated with the channelId

180

GLOSSARY

A

Administrator (System Administrator)

One or more individuals in your organization who can configure and customize the application. Users assigned to the System

Administrator profile have administrator privileges.

Application Programming Interface (API)

The interface that a computer system, library, or application provides to allow other computer programs to request services from it and exchange data.

Asynchronous Calls

A call that does not return results immediately because the operation may take a long time. Calls in the Metadata API and Bulk API are asynchronous.

B

Boolean Operators

You can use Boolean operators in report filters to specify the logical relationship between two values. For example, the AND operator between two values yields search results that include both values. Likewise, the OR operator between two values yields search results that include either value.

C

Custom Links

Custom links are URLs defined by administrators to integrate your Salesforce data with external websites and back-office systems.

Formerly known as Web links.

D

Database

An organized collection of information. The underlying architecture of the Force.com platform includes a database where your data is stored.

Database Table

A list of information, presented with rows and columns, about the person, thing, or concept you want to track. See also Object.

Developer Edition

A free, fully-functional Salesforce organization designed for developers to extend, integrate, and develop with the Force.com platform.

Developer Edition accounts are available on developer.salesforce.com

181

Glossary

Salesforce Developers

The Salesforce Developers website at developer.salesforce.com

provides a full range of resources for platform developers, including sample code, toolkits, an online developer community, and the ability to obtain limited Force.com platform environments.

E

Enterprise Edition

A Salesforce edition designed for larger, more complex businesses.

F

Field

A part of an object that holds a specific piece of information, such as a text or currency value.

Field-Level Security

Settings that determine whether fields are hidden, visible, read only, or editable for users. Available in Professional, Enterprise,

Unlimited, Performance, and Developer Editions.

Force.com

The Salesforce platform for building applications in the cloud. Force.com combines a powerful user interface, operating system, and database to allow you to customize and deploy applications in the cloud for your entire enterprise.

G

Group Edition

A product designed for small businesses and workgroups with a limited number of users.

H

No Glossary items for this entry.

I

See Salesforce Record ID.

Instance

The cluster of software and hardware represented as a single logical server that hosts an organization's data and runs their applications.

The Force.com platform runs on multiple instances, but data for any single organization is always stored on a single instance.

Interaction Log

An area in a Salesforce console where you can jot notes about the main record you're working on without clicking a button, viewing a new tab, or scrolling to the Notes & Attachments related list. Interaction logs are archived on the Activity History related list for easy review and retrieval. Administrators can customize interaction logs to include task fields.

182

Glossary

J

No Glossary items for this entry.

K

No Glossary items for this entry.

L

Logged-in User

In a SOAP API context, the username used to log into Salesforce. Client applications run with the permissions and sharing of the logged-in user. Also referred to as an integration user.

M

Metadata

Information about the structure, appearance, and functionality of an organization and any of its parts. Force.com uses XML to describe metadata.

Multitenancy

An application model where all users and apps share a single, common infrastructure and code base.

N

Navigation Tab

A tab with a drop-down button in a Salesforce console that lets you select and view object home pages.

O

Object

An object allows you to store information in your Salesforce organization. The object is the overall definition of the type of information you are storing. For example, the case object allow you to store information regarding customer inquiries. For each object, your organization will have multiple records that store the information about specific instances of that type of data. For example, you might have a case record to store the information about Joe Smith's training inquiry and another case record to store the information about Mary Johnson's configuration issue.

Organization

A deployment of Salesforce with a defined set of licensed users. An organization is the virtual space provided to an individual customer of Salesforce. Your organization includes all of your data and applications, and is separate from all other organizations.

183

Glossary

P

Personal Edition

Product designed for individual sales representatives and single users.

Platform Edition

A Salesforce edition based on Enterprise, Unlimited, or Performance Edition that does not include any of the standard Salesforce apps, such as Sales or Service & Support.

Primary Tab

A tab in a Salesforce console that displays the main item to work on, such as an account.

Production Organization

A Salesforce organization that has live users accessing data.

Professional Edition

A Salesforce edition designed for businesses who need full-featured CRM functionality.

Q

No Glossary items for this entry.

R

Record

A single instance of a Salesforce object. For example, “John Jones” might be the name of a contact record.

S

Salesforce Record ID

A unique 15- or 18-character alphanumeric string that identifies a single record in Salesforce.

Sandbox

A nearly identical copy of a Salesforce production organization for development, testing, and training. The content and size of a sandbox varies depending on the type of sandbox and the editioin of the production organization associated with the sandbox.

Salesforce Console

The Salesforce console is designed for users in fast-paced environments who need to find, update, and create records quickly. It improves upon the Agent Console in the Console tab by displaying records and related items as tabs on one screen.

Session ID

An authentication token that is returned when a user successfully logs in to Salesforce. The Session ID prevents a user from having to log in again every time he or she wants to perform another action in Salesforce. Different from a record ID or Salesforce ID, which are terms for the unique ID of a Salesforce record.

Session Timeout

The period of time after login before a user is automatically logged out. Sessions expire automatically after a predetermined length of inactivity, which can be configured in Salesforce from Setup by clicking Security Controls. The default is 120 minutes (two hours).

The inactivity timer is reset to zero if a user takes an action in the Web interface or makes an API call.

Sharing

Allowing other users to view or edit information you own. There are different ways to share data:

184

Glossary

•

Sharing Model—defines the default organization-wide access levels that users have to each other’s information and whether to use the hierarchies when determining access to data.

•

Role Hierarchy—defines different levels of users such that users at higher levels can view and edit information owned by or shared with users beneath them in the role hierarchy, regardless of the organization-wide sharing model settings.

•

Sharing Rules—allow an administrator to specify that all information created by users within a given group or role is automatically shared to the members of another group or role.

•

Manual Sharing—allows individual users to share records with other users or groups.

•

Apex-Managed Sharing—enables developers to programmatically manipulate sharing to support their application’s behavior.

See Apex-Managed Sharing.

SOAP (Simple Object Access Protocol)

A protocol that defines a uniform way of passing XML-encoded data.

Standard Object

A built-in object included with the Force.com platform. You can also build custom objects to store information that is unique to your app.

System Log

Part of the Developer Console, a separate window console that can be used for debugging code snippets. Enter the code you want to test at the bottom of the window and click Execute. The body of the System Log displays system resource information, such as how long a line took to execute or how many database calls were made. If the code did not run to completion, the console also displays debugging information.

T

Test Organization

See Sandbox.

Trigger

A piece of Apex that executes before or after records of a particular type are inserted, updated, or deleted from the database. Every trigger runs with a set of context variables that provide access to the records that caused the trigger to fire, and all triggers run in bulk mode—that is, they process several records at once, rather than just one record at a time.

U

Unlimited Edition

Unlimited Edition is Salesforce’s solution for maximizing your success and extending that success across the entire enterprise through the Force.com platform.

URL (Uniform Resource Locator)

The global address of a website, document, or other resource on the Internet. For example, http://www.salesforce.com.

V

Version

A number value that indicates the release of an item. Items that can have a version include API objects, fields and calls; Apex classes and triggers; and Visualforce pages and components.

185

Glossary

Visualforce

A simple, tag-based markup language that allows developers to easily define custom pages and components for apps built on the platform. Each tag corresponds to a coarse or fine-grained component, such as a section of a page, a related list, or a field. The components can either be controlled by the same logic that is used in standard Salesforce pages, or developers can associate their own logic with a controller written in Apex.

W

Web Service

A mechanism by which two applications can easily exchange data over the Internet, even if they run on different platforms, are written in different languages, or are geographically remote from each other.

Web Services API

A Web services application programming interface that provides access to your Salesforce organization's information. See also SOAP

API and Bulk API.

Wrapper Class

A class that abstracts common functions such as logging in, managing sessions, and querying and batching records. A wrapper class makes an integration more straightforward to develop and maintain, keeps program logic in one place, and affords easy reuse across components. Examples of wrapper classes in Salesforce include theAJAX Toolkit, which is a JavaScript wrapper around the Salesforce

SOAP API, wrapper classes such as

CCritical Section

in the CTI Adapter for Salesforce CRM Call Center, or wrapper classes created as part of a client integration application that accesses Salesforce using the SOAP API.

WSDL (Web Services Description Language) File

An XML file that describes the format of messages you send and receive from a Web service. Your development environment's SOAP client uses the Salesforce Enterprise WSDL or Partner WSDL to communicate with Salesforce using the SOAP API.

X

No Glossary items for this entry.

Y

No Glossary items for this entry.

Z

No Glossary items for this entry.

186

INDEX

A acceptAgentWork()

166

acceptChat()

122

addCustomEventListener()

161

addEventListener()

114

addPushNotificationListener()

addToBrowserTitleQueue()

Asynchronous calls

Authentication

Backward compatibility

Best practices

blinkCustomConsoleComponentButtonText()

C cancelFileTransferByAgent()

123

closeAgentWork()

167

closeTab()

Connecting to the Toolkit

Custom console components

9 ,

D declineAgentWork()

168

declineChat()

124

disableTabClose

Domains multiple

whitelist

End-of-life

endChat()

125

events

113

F fireEvent()

116

fireOnCallBegin()

fireOnCallEnd()

fireOnCallLogSaved()

focusNavigationTab()

focusPrimaryTabById()

focusPrimaryTabByName()

focusSidebarComponent()

focusSubtabById()

187 focusSubtabByNameAndPrimaryTabID()

focusSubtabByNameAndPrimaryTabName()

Force.com canvas

G generateConsoleUrl()

getAgentInput()

getAgentState()

getAgentWorks()

getCallAttachedData()

getCallObjectIds()

getChatLog()

128

getChatRequests()

130

getCustomEvents()

162

getDetailsByChatKey()

131

getDetailsByPrimaryTabId()

135

getEnclosingPrimaryTabId()

getEnclosingPrimaryTabObjectId()

getEnclosingTabId()

getEngagedChats()

139

getFocusedPrimaryTabId()

getFocusedPrimaryTabObjectId()

getFocusedSubtabId()

getFocusedSubtabObjectId()

getMaxCapacity()

140

getNavigationTabs()

getPageInfo()

getPrimaryTabIds()

getSelectedNavigationTab()

getServicePresenceStatusChannels()

172

getServicePresenceStatusId()

173

getSubtabIds()

getTabLink()

I initFileTransfer()

141

integration.js

Introduction

isCustomConsoleComponentHidden()

isCustomConsoleComponentPoppedOut()

isCustomConsoleComponentWindowHidden()

isInConsole()

isInCustomConsoleComponent()

Live Agent

Index

logout()

Methods acceptAgentWork()

166

acceptChat()

122

addCustomEventListener()

161

addEventListener()

114

addPushNotificationListener()

addToBrowserTitleQueue()

app-level custom console components

blinkCustomConsoleComponentButtonText()

call center

cancelFileTransferByAgent()

123

closeAgentWork()

167

closeTab()

computer-telephony integration (CTI)

console events

113

custom console components

declineAgentWork()

168

declineChat()

124

disableTabClose

endChat()

events

fireEvent()

fireOnCallBegin()

fireOnCallEnd()

fireOnCallLogSaved()

focusNavigationTab()

focusPrimaryTabById()

focusPrimaryTabByName()

focusSidebarComponent()

focusSubtabById()

focusSubtabByNameAndPrimaryTabId()

focusSubtabByNameAndPrimaryTabName()

generateConsoleUrl()

getAgentInput()

getAgentState()

getAgentWorks()

getCallAttachedData()

getCallObjectIds()

getChatLog()

128

getChatRequests()

130

getCustomEvents()

162

getDetailsByChatKey()

131

getDetailsByPrimaryTabId()

135

getEnclosingPrimaryTabId()

getEnclosingPrimaryTabObjectId()

188

Methods (continued) getEnclosingTabId()

getEngagedChats()

139

getFocusedPrimaryTabId()

getFocusedPrimaryTabObjectId()

getFocusedSubtabId()

getFocusedSubtabObjectId()

getMaxCapacity()

140

getNavigationTabs()

getPageInfo()

getPrimaryTabIds()

getSelectedNavigationTab()

getServicePresenceStatusChannels()

172

getServicePresenceStatusId()

173

getSubtabIds()

getTabLink()

initFileTransfer()

141

isCustomConsoleComponentHidden()

isCustomConsoleComponentPoppedOut()

isCustomConsoleComponentWindowHidden()

isInConsole()

isInCustomConsoleComponent()

Live Agent

logout()

navigation tabs

Omni-Channel

165

Omni-Channel console events

178

onAgentSend()

142

onAgentStateChanged()

onCallBegin()

onCallEnd()

onCallLogSaved()

onChatCanceled()

onChatCriticalWaitState()

onChatDeclined()

onChatEnded()

onChatRequested()

onChatTransferredOut()

onCurrentCapacityChanged()

onCustomConsoleComponentButtonClicked()

onCustomEvent()

151

onEnclosingTabRefresh()

onFileTransferCompleted()

153

onFocusedPrimaryTab()

onFocusedSubtab()

onNewMessage()

154

onSendCTIMessage()

onTabSave()

Index

Methods (continued) onTypingUpdate()

155

openConsoleUrl()

openPrimaryTab()

openSubtab()

openSubtabByPrimaryTabName()

primary tabs

push notifications

refreshNavigationTab()

refreshPrimaryTabById()

refreshPrimaryTabByName()

refreshSubtabById()

refreshSubtabByNameAndPrimaryTabId()

refreshSubtabByNameAndPrimaryTabName()

removeEventListener()

117

removeFromBrowserTitleQueue()

removePushNotificationListener()

112

reopenLastClosedTab()

resetSessionTimeOut()

runSelectedMacro()

scrollCustomConsoleComponentButtonText()

selectMacro()

sendCTIMessage()

sendCustomEvent()

sendMessage()

setAgentInput()

setAgentState()

setCallAttachedData()

setCallObjectIds()

setCustomConsoleComponentButtonIconUrl()

100

setCustomConsoleComponentButtonStyle()

101

setCustomConsoleComponentButtonText()

102

setCustomConsoleComponentHeight()

103

setCustomConsoleComponentPopoutable()

106

setCustomConsoleComponentVisible()

104

setCustomConsoleComponentWidth()

105

setCustomConsoleComponentWindowVisible()

107

setSelectedNavigationTab()

setServicePresenceStatus()

176

setSidebarVisible()

108

setTabIcon()

setTabLink()

setTabStyle()

setTabTextStyle()

setTabTitle()

setTabUnsavedChanges()

subtabs

189

OAuth

Omni-Channel

165

Omni-Channel events

178

onAgentSend()

142

onAgentStateChanged()

onCallBegin()

onCallEnd()

onCallLogSaved()

onChatCanceled()

onChatCriticalWaitState()

onChatDeclined()

onChatEnded()

onChatRequested()

onChatTransferredOut()

onCurrentCapacityChanged()

onCustomConsoleComponentButtonClicked()

onCustomEvent()

151

onEnclosingTabRefresh()

onFileTransferCompleted()

153

onFocusedPrimaryTab()

onFocusedSubtab()

onNewMessage()

154

onSendCTIMessage()

onTabSave()

onTypingUpdate()

155

openConsoleUrl()

openPrimaryTab()

openSubtab()

openSubtabByPrimaryTabName()

Other resources

Push notifications