Create Custom Chat Events

Custom chat events let you have your own communication channel with your customers using the agent console to send and receive your own chat events. Create custom events using your own JavaScript and CSS files.

To create your events, use the following.

sendCustomEvent()—Sends a custom event to the client-side chat window for a chat with a specific chat key.
onCustomEvent()—Registers a function to call when a custom event takes place during a chat.
embedded_svc.liveagentAPI.sendCustomEvent()—Sends a custom event to the agent console of the agent who is currently chatting with a chat visitor.
embedded_svc.liveagentAPI.getCustomEvents()—Retrieves a list of custom events from both the agent and chat visitor that are received during a chat session.
embedded_svc.liveagentAPI.addCustomEventListener()—Registers a function to call when a custom event is received in the chat window.

You don’t have to add your own styling (our example doesn’t include any), but we recommend it.

We include two samples—one for sending an event from the agent to the customer, and one for sending an event from the customer to the agent. If you want to create both events for your chat window, combine them into one JavaScript file.

Note

Send an Event from an Agent to a Customer

The following example shows how you can create a custom event that’s sent from the agent to the customer. This example creates a link on a Visualforce page that, when clicked, sends an event to the customer.

Create a Visualforce page to send an event from an agent to a customer.

In this example, a custom event of type agent_to_customer_event_type is sent to the customer, with the data data from the agent.

1<apex:page>
2	<apex:includeScript value="/support/console/42.0/integration.js" />
3
4	<a href="#" onClick="sendEventFromAgentToCustomer();">Send an event from an agent to a customer</a>
5
6	<script type="text/javascript">
7		function sendEventFromAgentToCustomer() {
8			var chatKey = undefined; // Provide a chat key here
9			var eventType = "agent_to_customer_event_type";
10			var eventData = "data from the agent";
11
12			sforce.console.chat.sendCustomEvent(chatKey, eventType, eventData, function(result) {
13				if (!result || !result.success) {
14					console.log("Sending an event from an agent to a customer failed");
15					return;
16				}
17
18				console.log("The customEvent (" + eventType + ") has been sent");
19			});
20		}
21	</script>
22</apex:page>

Provide a chat key using an external JavaScript file.

In this example, the JavaScript file is called CustomEvents_fromAgentToCustomer.js.

1function customEventReceived(result) {
2	var eventType;
3	var eventData;
4
5	if (!result || !result.success) {
6		console.log("customEventReceived failed");
7		return;
8	}
9
10	eventType = result.type;
11	eventData = JSON.stringify(result.data);
12	console.log("A custom event of type '" + eventType + "' has been received with the following data: " + eventData);
13}
14
15function wireUpCustomEventListeners() {
16	embedded_svc.liveAgentAPI.addCustomEventListener("agent_to_customer_event_type", customEventReceived);
17}
18
19wireUpCustomEventListeners();

Upload your file as a static resource in Salesforce. Give it a name that’s easy to remember and doesn’t include spaces.
In this example, the static resource name for the JavaScript file is CustomEvents_fromAgentToCustomer.
Add your file to the Embedded Service code snippet (make sure you’re using version 5.0 or later).
Enter the static resource name, not the file name.
1embedded_svc.settings.externalScripts = ["CustomEvents_fromAgentToCustomer"];
Add the Visualforce page to the console.
From the console, add a tab and paste the URL of the preview page of the Visualforce page you are created in step 1.
Test your new event.
In this example, there’s a “Send an event from an agent to a customer” link in your Visualforce page. Reload your Visualforce page console tab and chat window, start a chat, and click the link in your Visualforce page console tab. The link triggers a call to sendEventFromAgentToCustomer() and sends the event to the customer.

Send an Event from a Customer to an Agent

The following example shows how you can create a custom event that’s sent from the customer to the agent. This example creates an event listener that, when the customer’s chat message field matches “trigger”, sends an event to the agent.

Create a Visualforce page to send an event from a customer to an agent.

In this example, a custom event of type customer_to_agent_event_type is sent to the customer, with the data data from the customer.

1<apex:page>
2	<apex:includeScript value="/support/console/42.0/integration.js" />
3	
4	<script type="text/javascript">
5		function registerListeners() {
6			var chatKey = undefined; // Provide a chat key here
7			var eventType = "customer_to_agent_event_type";
8
9			sforce.console.chat.onCustomEvent(chatKey, eventType, function(result) {
10				if (!result || !result.success) {
11					console.log("onCustomEvent (" + eventType
12						+ ") was not successful");
13					return;
14				}
15
16				console.log("A new custom event has been received of type "
17					+ result.type + " and with data: " + result.data);
18			});
19		}
20
21		registerListeners();
22	</script>
23</apex:page>

Provide a chat key using an external JavaScript file.

In this example, the JavaScript file is called CustomEvents_fromCustomerToAgent.js.

1function wireTextChangeListner() {
2	// Find the chasitor's chat input field
3	var obj = document.getElementsByClassName('chasitorText');
4
5	// Wire up the event listener
6	obj[0].oninput = function() {
7		switch(this.value) {
8			// When the chasitor types "trigger", an event is fired to the agent
9			case "trigger":	
10				embedded_svc.liveAgentAPI.sendCustomEvent(
11					"Customer_to_agent_event_type",
12					"data from the customer");
13				break;
14
15			default:
16				break;
17		}
18	};
19}
20
21wireTextChangeListner();

Upload your file as a static resource in Salesforce. Give it a name that’s easy to remember and doesn’t include spaces.
In this example, the static resource name for the JavaScript file is CustomEvents_fromCustomerToAgent.
Add your file to the Embedded Service code snippet (make sure you’re using version 5.0 or later).
Enter the static resource name, not the file name.
1embedded_svc.settings.externalScripts = ["CustomEvents_fromCustomerToAgent"];
Add the Visualforce page to the console.
From the console, add a tab and paste the URL of the preview page of the Visualforce page you created in step 1.
Test your new event.
Reload your Visualforce page and chat window, start a chat, and enter trigger in the chat message field as the customer. The event listener you created watches for changes in the chat message field, and the event is sent when the field matches trigger.

By listening to onChatStateLoaded and onCustomScriptsLoaded events (added as part of the code snippet), you can determine when the scripts are loaded to send or receive custom events with the agent. These events will also include whether or not the scripts are loaded on the primary tab.

Embedded Service for Web Developer Guide

Create Custom Chat Events

Send an Event from an Agent to a Customer

Send an Event from a Customer to an Agent

See Also