In Salesforce, we often need to receive notifications or event when there is certain DML/Event happened at some part of the Salesforce by another user or in the backend or through API call from external System.
This can be achieved through Platform events. We can subscribe to platform events, When subscribed to platform events we can receive the events if the platform event was published by someone in the Salesforce or through external system.
In order to subscribe to platform events in LWC, You need to import ‘lightning/empApi’ module. this empApi module provides subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled methods to work with. We can subscribe on load of the component or on click using subscribe method and unsubscribe using unsubscribe method of empApi module.
Syntax: import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled } from ‘lightning/empApi’;
This example subscribes to a streaming channel when you click the Subscribe button. It logs received event messages to the JavaScript console in your browser. The Unsubscribe button lets you stop the subscription and stop receiving event messages. This example uses the default streaming channel of /event/Test__e
and assumes that the Test__e
platform event is defined. Replace the default value with the desired channel name.
<template>
<lightning-card title="EmpApi Example" icon-name="custom:custom14">
<div class="slds-m-around_medium">
<p>
Use the buttons below to subscribe and unsubscribe to a
streaming channel!
</p>
<lightning-input
label="Channel Name"
value={channelName}
onchange={handleChannelName}
></lightning-input>
<lightning-button
variant="success"
label="Subscribe"
title="Subscribe"
onclick={handleSubscribe}
disabled={isSubscribeDisabled}
class="slds-m-left_x-small"
></lightning-button>
<lightning-button
variant="destructive"
label="Unsubscribe"
title="Unsubscribe"
onclick={handleUnsubscribe}
disabled={isUnsubscribeDisabled}
class="slds-m-left_x-small"
></lightning-button>
</div>
</lightning-card>
</template>
import { LightningElement } from 'lwc';
import { subscribe, unsubscribe, onError, setDebugFlag, isEmpEnabled } from 'lightning/empApi';
export default class EmpApiLWC extends LightningElement {
channelName = '/event/Test__e';
isSubscribeDisabled = false;
isUnsubscribeDisabled = !this.isSubscribeDisabled;
subscription = {};
// Tracks changes to channelName text field
handleChannelName(event) {
this.channelName = event.target.value;
}
// Initializes the component
connectedCallback() {
// Register error listener
this.registerErrorListener();
}
// Handles subscribe button click
handleSubscribe() {
// Callback invoked whenever a new event message is received
const messageCallback = function (response) {
console.log('New message received: ', JSON.stringify(response));
// Response contains the payload of the new message received
};
// Invoke subscribe method of empApi. Pass reference to messageCallback
subscribe(this.channelName, -1, messageCallback).then((response) => {
// Response contains the subscription information on subscribe call
console.log(
'Subscription request sent to: ',
JSON.stringify(response.channel)
);
this.subscription = response;
this.toggleSubscribeButton(true);
});
}
// Handles unsubscribe button click
handleUnsubscribe() {
this.toggleSubscribeButton(false);
// Invoke unsubscribe method of empApi
unsubscribe(this.subscription, (response) => {
console.log('unsubscribe() response: ', JSON.stringify(response));
// Response is true for successful unsubscribe
});
}
toggleSubscribeButton(enableSubscribe) {
this.isSubscribeDisabled = enableSubscribe;
this.isUnsubscribeDisabled = !enableSubscribe;
}
registerErrorListener() {
// Invoke onError empApi method
onError((error) => {
console.log('Received error from server: ', JSON.stringify(error));
// Error contains the server-side error
});
}
}
Usage Considerations
The lightning/empApi
module is supported in desktop browsers with web worker or shared worker support. It is not supported in the Salesforce mobile app
You can add the lightning/empApi
module only on the main window of a page. You can’t add the lightning/empApi
module on a child window. For example, in a screen flow, you can add the lightning/empApi
module only on the main screen but not on a button in a screen flow. Another example is a Visualforce page that contains a top-level window and child iframe windows. In this case, the lightning/empApi
module must be on the top-level window.