Events in Salesforce


Note: This article applies to Genesys Cloud for Salesforce.

You can configure the integration to fire or listen for events either in the Salesforce console in Salesforce Classic or in all versions of Lightning Experience (with the postMessage API or Lightning Message Service). The types of events and the way that you fire or listen for them depends on the Salesforce user interface that you use.

Note: This article is an advanced customization topic meant for developers familiar with Salesforce.

Important: Genesys recommends that new development for Lightning Experience use Lightning Message Service (LMS), not the postMessage API. Salesforce plans to release LMS in Summer ’20. Genesys will eventually deprecate the use of the postMessage Web API.

Through the event model in the Salesforce Console Integration Toolkit, the integration fires and listens for events being raised around the following items:

  • Status changes (such as Available, Busy, Away, Out of Office, and On Queue)
  • Call activities (connected, disconnected, ACW required, ACW completed)
  • Interaction state changes (pickup, disconnect, mute, hold, secure pause)

Developers can create Visualforce pages that use these events. For example code, see Events in Salesforce Classic Console App in GitHub.

For information about the Salesforce console, see Customize a Console with Custom Components in Salesforce Classic in the Salesforce documentation.

For information about using the event model, see the Salesforce Console Integration Toolkit for Salesforce Classic in the Salesforce documentation.

The integration can fire the following events and send them to Salesforce.

Note: These event names begin with inin.salesforce.constants.consoleevent.pc., followed by the name in the list, for example, inin.salesforce.constants.consoleevent.pc.UPDATE_STATUS.

ACW_COMPLETED

ACW completed.

Parameters

Name Data type Description Notes
reason String The type of event.
interactionId String ID of the interaction.

Example

{
    "reason": "acw_completed",
    "interactionId": "44560c74-5e84-4062-94b6-5680cdeb54d5" 
}

ACW_REQUIRED

ACW required.

Parameters

Name Data type Description Notes
reason String The type of event.
interactionId String ID of the interaction.

Example

{ 
    "reason": "acw_required",
    "interactionId": "44560c74-5e84-4062-94b6-5680cdeb54d5"
}

INTERACTION_EVENT

Interaction state change.

Parameters

Name Data type Description Notes
reason String The type of action.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
category String The type of event. Valid values: change, add.
data Object

Example

{
    "reason": "interaction",
    "data": {
	"category": "change",
	"data": { }
    }
}

INTERACTION_CONNECTED

Interaction connected.

Parameters

Name Data type Description Notes
reason String The type of event.
interactionId String ID of the interaction.

Example

{
    "reason": "connected",
    "interactionId": “44560c74-5e84-4062-94b6-5680cdeb54d5″
}

INTERACTION_DISCONNECTED

Interaction disconnected.

Parameters

Name Data type Description Notes
reason String The type of event.
interactionId String ID of the interaction.

Example

{
    "reason": "disconnected",
    "interactionId": “44560c74-5e84-4062-94b6-5680cdeb54d5″
}

LOGGED_OUT

User logged out.

Parameters

Name Data type Description Notes
reason String The type of event.

Example

{
    "reason": "logged_out"
}

UPDATE_STATUS

User logged out.

Parameters

Name Data type Description Notes
reason String The type of event.
status String The agent's status.
id String ID of the selected status (primary or secondary).
sub_status String The agent's secondary status. If the integration uses secondary statuses, the response includes secondary status information.

Example

{
    "reason": "status_updated",
    "status": "AVAILABLE",
    "id": "44560c74-5e84-4062-94b6-5680cdeb54d5",
    "sub_status":"Available Work At Home"
}

The integration exposes the following actions about status changes and changes to an agent's status.

Note: These actions begin with inin.salesforce.constants.consoleevent., followed by the name in the list, for example, inin.salesforce.constants.consoleevent.changestatus.

addCustomAttributes

Adds custom attributes to interactions.

Parameters

Name Data type Description Notes
data Object See data object.

data object

Defines the actions.

Parameters

Name Data type Description Notes
id String ID of the interaction.
attributes Object Key-value pairs of custom interaction attributes.

Example

{ 
    "data": {
        "id": "1234-1234-1234-1234",
        "attributes": {
            "record_url": "/0000413456"
        }
    }
}

changestate

Updates the state of an interaction.

Parameters

Name Data type Description Notes
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
action String Desired state of the interaction.

Values: pickup, disconnect, hold, mute, securePause, blindTransfer, consultTransfer, concludeTransfer. 

Only use concludeTransfer for consult transfers.

id String ID of the interaction.
participantContext Object See participantContext object. Only use participantContext when action is set to blindTransfer or consultTransfer.

participantContext object

Defines the entity receiving the transfer.

Parameters

Name Data type Description Notes
transferTarget String ID of an agent or queue, or phone number for an external transfer.
transferTargetType String Type of transfer entity.

Values: userId, queueId, address.

Use address with a phone number for an external transfer in transferTarget.

Example 

{
    "data": {
        "action": "blindTransfer",
        "id": "1234-1234-1234-1234",
        "participantContext": {
            "transferTarget": "3175550123",
            "transferTargetType": "address"
        }
    }
}

changestatus

Updates user status.

Parameters

Name Data type Description Notes
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
id String ID of the interaction.

Example 

{
    "data": {
        "id": "1234-1234-1234-1234"
    }
}

Through the postMessage Web APIs, the integration can fire and listen for events being raised around status changes, interaction state changes, and subscriptions to Interaction, Notification, or UserActions events.

For example code, see Events in Salesforce Lightning App in GitHub.

Event name Description
Handshake If Enable Client Events is selected in the call center settings, the integration raises a handshake event whenever the client loads. The handshake event provides the context that Lightning components need to be able to fire events to the Genesys Cloud for Salesforce client.
Interaction

Fires interaction state changes.

Possible values: add, change, connect, disconnect, acw, deallocate, callbackPlaced, callbackCallEnded, blindTransfer, consultTransfer, completeConsultTransfer.

Notification

Fires notification state changes.

Possible values: interactionSelection, chatUpdate, interactionWindow.

UserAction

Fires user action state changes. 

Possible values: login, logout, station, status, modal, routingStatus, view.

For more information, see Events per subscription type (Developer Center) in the Genesys Cloud Embeddable Framework documentation.

Note: All callback parameters described in the Genesys Cloud Embeddable Framework documentation are available in the postMessage data payload along with the added root type. See the Communicate with Genesys Cloud for Salesforce section.

Administrators configure the call center settings so that the integration fires and listens for events.

  1. In the call center settings, for Client Event Message Type, select Window.postMessage API.

    This setting causes the integration to raise a handshake event whenever the client loads. 

  2. (Optional) Under Client Event Types, select other events (Interaction, Notification, and UserAction) to subscribe to. Click Arrow  to add them under Chosen.
  3. (Optional) Select Expand Chat Notification to receive an expanded payload for chat notification events.
  4. Click Save.

Note: If you add a Lighting component as a Utility Item to your Lightning app, be sure to select Start automatically. For more information, see Add a Utility Bar to Lighting Apps in the Salesforce documentation.

For more information, see Configure call center settings.

The Genesys Cloud for Salesforce client exposes the following actions raised through the postMessage Web APIs.

Interaction.addCustomAttributes

Adds custom attributes to interactions.

Parameters

Name Data type Description Notes
type String The type of action. PureCloud. + the action name.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
id String ID of the interaction.
attributes Object Key-value pairs of custom interaction attributes.

Example

{
    "type": "PureCloud.interaction.addCustomAttributes", 
    "data": {
        "id": "1234-1234-1234-1234",
        "attributes": {
            "record_url": "/0000413456"
        }
    }
}

Interaction.updateState

Updates the state of an interaction.

Parameters

Name Data type Description Notes
type String The type of action. PureCloud. + the action name.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
action String Desired state of the interaction.

Values: pickup, disconnect, hold, mute, securePause, blindTransfer, consultTransfer, concludeTransfer. 

Only use concludeTransfer for consult transfers.

id String ID of the interaction.
participantContext Object See participantContext object. Only use participantContext when action is set to blindTransfer or consultTransfer.

participantContext object

Defines the entity receiving the transfer.

Parameters

Name Data type Description Notes
transferTarget String ID of an agent or queue, or phone number for an external transfer.
transferTargetType String Type of transfer entity.

Values: userId, queueId, address.

Use address with a phone number for an external transfer in transferTarget.

Example 

{
    "type": "PureCloud.interaction.updateState", 
    "data": {
        "action": "blindTransfer",
        "id": "1234-1234-1234-1234",
        "participantContext": {
            "transferTarget": "3175550123",
            "transferTargetType": "address"
        }
    }
}

User.updateStatus

Updates user status.

Parameters

Name Data type Description Notes
type String The type of action. PureCloud. + the action name.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
id String ID of the interaction.

Example

{
    "type": "PureCloud.user.updateStatus", 
    "data": {
        "id": "1234-1234-1234-1234"
    }
}

Create a Lighting component so Salesforce can listen for and fire the events selected in the call center settings. 

  1. Add Apex, component, and JavaScript files to the Developer Console in Salesforce.

    You can download sample files from the PureCloud for Salesforce Einstein Example repository in GitHub.

    For more information, see Developer Console File Menu in the Salesforce documentation.

  2. Set the type and id for source in the JavaScript file.

    This setting allows you to change statuses in the client.

    source.postMessage({
        type: 'PureCloud.User.updateStatus',
        data: { id: status },
    }
  3. If your administrator configured the integration to fire Interaction, Notification, or UserActions events, subscribe to these events in the JavaScript file.

    For more information, see the subscribe method in the Genesys Cloud Embeddable Framework documentation (Developer Center).

Through Lightning Message Service, the integration can fire and listen for events being raised around status changes, interaction state changes, and subscriptions to Interaction, Notification, or UserActions events.

For example code, see Events in Salesforce Lightning App in GitHub.

Event name Description
Interaction

Fires interaction state changes.

Possible values: add, change, connect, disconnect, acw, deallocate, callbackPlaced, callbackCallEnded, blindTransfer, consultTransfer, completeConsultTransfer.

Notification

Fires notification state changes.

Possible values: interactionSelection, chatUpdate, interactionWindow.

UserAction

Fires user action state changes. 

Possible values: login, logout, station, status, modal, routingStatus, view.

For more information, see Events per subscription type (Developer Center) in the Genesys Cloud Embeddable Framework documentation.

Note: All callback parameters described in the Genesys Cloud Embeddable Framework documentation are available in the Lightning Message Service data payload along with the added root type. See the Communicate with Genesys Cloud for Salesforce section.

Administrators configure the call center settings so that the integration fires and listens for events.

  1. In the call center settings, for Client Event Message Type, select Lightning Message Channel

    This setting causes the integration to send messages on the message channel. 

  2. (Optional) Under Client Event Types, select other events (Interaction, Notification, and UserAction) to subscribe to. Click Arrow  to add them under Chosen.
  3. (Optional) Select Expand Chat Notification to receive an expanded payload for chat notification events.
  4. Click Save.

Note: If you add a Lighting component as a Utility Item to your Lightning app, be sure to select Start automatically. For more information, see Add a Utility Bar to Lighting Apps in the Salesforce documentation.

For more information, see Configure call center settings.

The Genesys Cloud for Salesforce client exposes the following actions raised through Lightning Message Service.

Interaction.addCustomAttributes

Adds custom attributes to interactions.

Parameters

Name Data type Description Notes
type String The type of action. PureCloud. + the action name.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
id String ID of the interaction.
attributes Object Key-value pairs of custom interaction attributes.

Example

{
    "type": "PureCloud.interaction.addCustomAttributes",
    "data": {
        "id": "1234-1234-1234-1234",
        "attributes": {
            "record_url": "/0000413456"
        }
    }
}

Interaction.updateState

Updates the state of an interaction.

Parameters

Name Data type Description Notes
type String The type of action. PureCloud. + the action name.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
action String Desired state of the interaction.

Values: pickup, disconnect, hold, mute, securePause, blindTransfer, consultTransfer, concludeTransfer. 

Only use concludeTransfer for consult transfers.

id String ID of the interaction.
participantContext Object See participantContext object. Only use participantContext when action is set to blindTransfer or consultTransfer.

participantContext object

Defines the entity receiving the transfer.

Parameters

Name Data type Description Notes
transferTarget String ID of an agent or queue, or phone number for an external transfer.
transferTargetType String Type of transfer entity.

Values: userId, queueId, address.

Use address with a phone number for an external transfer in transferTarget.

Example

{
    "type": "PureCloud.interaction.updateState", 
    "data": {
        "action": "blindTransfer",
        "id": "1234-1234-1234-1234",
        "participantContext": {
            "transferTarget": "3175550123",
            "transferTargetType": "address"
         }
    }
}

User.updateStatus

Updates user status.

Parameters

Name Data type Description Notes
type String The type of action. PureCloud. + the action name.
data Object See data object.

data object

Defines the action.

Parameters

Name Data type Description Notes
id String ID of the status.

Example

{
    "type": "PureCloud.user.updateStatus",
    "data": {
        "id": "1234-1234-1234-1234"
    }
}

To subscribe to the message channel, install version 3.12 or later of the PureCloud for Salesforce managed package. These versions of the managed package include the purecloud__ClientEvent__c channel that receives all messages. After you subscribe to purecloud__ClientEvent__c, Salesforce can listen for and fire the events selected in the call center settings. 

The method of implementation varies, depending on the components that you use. The following example code shows how to use LMS with a Lightning Aura component.

Subscribe to Lightning messages on the purecloud__ClientEvent__c channel for an Aura component.

<lightning:messageChannel type="purecloud__ClientEvent__c" aura:id="clientEventMessageChannel" onMessage="{!c.onClientEvent}" scope="APPLICATION"/>

To receive Lightning messages, create an onClientEvent.

({
    onClientEvent: function (component, message, helper) {
        var eventData = message.getParams();
        if (eventData) {
            if(eventData.type === 'Interaction' && eventData.data.id) {
		console.log(‘Interaction ID: ‘ + eventData.data.id);
            }
        }
    }
})

To send Lightning messages, publish the events that the Genesys Cloud for Salesforce client listens for. For a list of events, see the Communicate with Genesys Cloud for Salesforce section.

component.find('clientEventMessageChannel').publish({
    type: 'PureCloud.User.updateStatus',
    data: { id: status }
});

For other examples, see Lightning Message Service [Developer Preview] in the Salesforce Developers Blog.

For more information about the integration, see About Genesys Cloud for Salesforce.