How to subscribe to platform events in LWC?

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.