Event Listeners
Set up notifications when certain Messaging for In-App and Web events are triggered. Use window.addEventListener to register a handler for a standard client event.
| Event Name | Event Details | Scenario |
|---|---|---|
onEmbeddedMessagingReady | {} | Fires when the Salesforce JavaScript API for Messaging is ready to use. At this point, you can make calls such as userVerificationAPI.setIdentityToken and setHiddenPrechatFields. To let you know that the API is ready for calls, this method is called in the following situations.
|
onEmbeddedMessagingButtonCreated | {} | Fires when a chat button is added to your site. The button may be hidden if you are outside business hours or if it's set to hide. |
onEmbeddedMessagingButtonClicked | {} | Fires the first time the chat button is clicked by the end user. |
onEmbeddedMessagingWindowMaximized | {} | Fires when the messaging conversation window is maximized. |
onEmbeddedMessagingWindowMinimized | {} | Fires when the messaging conversation window is minimized. |
onEmbeddedMessagingConversationStarted | {conversationId: "id"} | Fires when a messaging conversation starts. This event only applies to the browser tab where the conversation was created. |
onEmbeddedMessagingConversationOpened | {} | Fires when a messaging conversation is loaded into a browser tab, whether it moved to a new browser tab or was loaded in the browser tab where the conversation started. |
onEmbeddedMessagingConversationRouted | { SSE PAYLOAD } | Fires when a messaging conversation is routed or manually transferred from one internal recipient to another, such as from a bot to an agent. This event also fires if the routing or manual transfer is unsuccessful. See this example of the CONVERSATION_ROUTING_RESULT server-sent event (SSE) payload. |
onEmbeddedMessagingConversationParticipantChanged | { SSE PAYLOAD } | Fires when a new internal user, such as a bot or an agent, joins a conversation. Or, when an existing internal user leaves a conversation. See this example of the CONVERSATION_PARTICIPANT_CHANGED server-sent event (SSE) payload. |
onEmbeddedMessagingPreChatLoaded | { prechatDisplay : "Conversation" / "Session" } | Fires when the pre-chat form is displayed to the end user. |
onEmbeddedMessagingPreChatSubmitted | { prechatDisplay : "Conversation" / "Session" } | Fires when the end user submits the pre-chat form. |
onEmbeddedMessageSent | { SSE PAYLOAD } | Fires when an agent, a bot, or an end user sends a message. The message can be typed manually or sent in the form of a messaging component. This event also fires when an end user clicks on a messaging component, resulting in a second messaging component being sent. See this example of the CONVERSATION_MESSAGE server-sent event (SSE) payload. |
onEmbeddedMessageDelivered | { SSE PAYLOAD } | Fires when an end user receives a delivery receipt. Delivery receipts must be enabled in Setup. See this example of the CONVERSATION_DELIVERY_ACKNOWLEDGEMENT server-sent event (SSE) payload. |
onEmbeddedMessageRead | { SSE PAYLOAD } | Fires when an end user receives a read receipt. Read receipts must be enabled in Setup. See this example of the CONVERSATION_READ_ACKNOWLEDGEMENT server-sent event (SSE) payload. |
onEmbeddedMessagingTranscriptRequested | { conversationId: "id" } | Fires when an end user requests a transcript of their messaging conversation history. |
onEmbeddedMessagingTranscriptRequestFailed | { conversationId: "id" } | Fires when the transcript request fails. |
onEmbeddedMessagingTranscriptDownloadSuccessful | { conversationId: "id" } | Fires when the messaging conversation transcript is successfully downloaded. |
onEmbeddedMessagingConversationClosed | { SSE PAYLOAD } | Fires when an end user closes the messaging conversation. See this example of the CONVERSATION_CLOSE_CONVERSATION server-sent event (SSE) payload. |
onEmbeddedMessagingIdentityTokenExpired | {} | The client dispatches the onEmbeddedMessagingIdentityTokenExpired event when you interact with the client after both the Salesforce authorization token and identity token have expired. If the Salesforce authorization token expires, but the identity token is still valid, the client generates a new Salesforce authorization token and keeps the session active without sending the onEmbeddedMessagingIdentityTokenExpired event. If you want to continue the session but the identity token has expired, you can renew the token and send it to the client using the setIdentityToken method in the event handler. The messaging session and user data are cleared automatically if you don't respond within 30 seconds of the onEmbeddedMessagingIdentityTokenExpired event being dispatched. If you want to clear the session before the 30 seconds have expired explicitly, you can call the clearSession method. |
Learn more about server-sent event (SSE) payloads in Server-Sent Events.
The following code is an example of how these events can be used in your Messaging for Web code snippet.