How to subscribe to platform events in LWC?

By /

In Salesforce, when a user opens a record, there may be scenarios where a backend process triggers a Data Manipulation Language (DML) operation or similar activity (e.g., a DML operation in Asynchronous Apex), or when the same record is updated by another user or through an external API call. In such instances, it is crucial to notify the logged-in user about the update. This notification helps ensure the user is aware of the change and can take any necessary actions.

This can be implemented using Platform Events. By subscribing to Platform Events in Lightning Web Components (LWC), we can receive notifications whenever a Platform Event is published, either within Salesforce or from an external system.

Note: You will need to have automation/code to publish platform events after the DML completed in the Async operation or publish platform event by External System when they update the record.

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.

Scroll to Top