Communicate Across Salesforce UI Technologies with Lightning Message Service (Beta)

Use the Lightning Message Service API to communicate across the DOM, between Aura components, Visualforce pages, and Lightning web components. Lightning Message Service also enables communication between a component in a main Lightning page with one in a pop-out utility bar. If you’re switching from Salesforce Classic to Lightning Experience, you can now build Lightning web components that can communicate with existing Visualforce pages or Aura components.

A Lightning web component uses a Lightning Message Channel to access the Lightning Message Service API. Reference Lightning Message Channel with the scoped module @salesforce/messageChannel. In Visualforce, use the global variable $MessageChannel. In Aura, use lightning:messageChannel in your component.

Where: This feature is available in Lightning Experience. To create a Lightning message channel, use Enterprise, Performance, Unlimited, and Developer editions.

Note

Note

As a beta feature, Lightning Message Service is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. Lightning Message Service is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for Lightning Message Service in the Lightning Platform group in the Trailblazer Community.

Why: In Lightning Experience, you often have multiple components on a page. Previously, if you wanted a Visualforce page to communicate with a Lightning web component in Lightning Experience, you needed to implement a custom publish-subscribe solution. Now, you can use the Lightning Message Service API to handle that communication.

How: Assuming you created a message channel called SampleMessageChannel__c using the Metadata API, here's how to subscribe a Visualforce page to a message channel on which a Lightning web component publishes.

Create a Lightning web component called publisherComponent that publishes on SampleMessageChannel__c, which is the API name of the message channel. The component imports methods to publish on a message channel from the lightning/messageService module. This module accesses the Lightning Message Service API. Next, import the message channel from @salesforce/messageChannel/SampleMessageChannel__c and assign it to the identifier SAMPLEMC.

The handleClick() method holds the data to be published on the message channel. Here, the data is a recordId with the value "some string" and recordData, whose value is the key-value pair value: "some data". Publish the data by calling the publish() method imported from the lightning/messageService module.

// publisherComponent.js
import { LightningElement, wire } from 'lwc';
import { publish, MessageContext } from 'lightning/messageService';
import SAMPLEMC from "@salesforce/messageChannel/SampleMessageChannel__c";

export default class PublisherComponent extends LightningElement {
    @wire(MessageContext)
    messageContext;

    handleClick() {
        const message = {
            recordId: "some string",
            recordData: {
                value: "some data"
            }
        };
        publish(this.messageContext, SAMPLEMC, message);
    }
}

In your component’s HTML template file, include a Publish button that calls the handleClick() method. Clicking the button publishes the record data to SampleMessageChannel__c. The subscribing Visualforce page then receives that data.

<-- publisherComponent.html -->
<template>
    <lightning-card title="MyLwcPublisher" icon-name="custom:custom14">
        <div class="slds-m-around_medium">
            <p>MessageChannel: SampleMessageChannel</p>
            <br>
            <lightning-button label="Publish" onclick={handleClick}></lightning-button>
        </div>
    </lightning-card>
</template>

Here’s how to subscribe and unsubscribe a Visualforce page from a message channel SampleMessageChannel__c on which a Lightning web component publishes.

<apex:page>
    <div>
        <p>Subscribe to SampleMessageChannel</p>
        <button onclick="subscribeMC()">Subscribe</button>
        <p>Unsubscribe from SampleMessageChannel</p>
        <button onclick="unsubscribeMC()">Unsubscribe</button>
        <br/>
        <br/>
        <p>Received message:</p>
        <textarea id="MCMessageTextArea" rows="10" style="disabled:true;resize:none;width:100%;"/>
    </div>
    <script>
        // Load the MessageChannel token in a variable
        var SAMPLEMC = "{!$MessageChannel.SampleMessageChannel__c}";
        var subscriptionToMC;
        // Display message in the textarea field
        function onMCPublished(message) {
            var textArea = document.querySelector("#MCMessageTextArea");
            textArea.innerHTML = message ? JSON.stringify(message, null, '\t') : 'no message payload';
        }

        function subscribeMC() {
            if (!subscriptionToMC) {
                subscriptionToMC = sforce.one.subscribe(SAMPLEMC, onMCPublished, {scope: "APPLICATION"});
            }
        }

        function unsubscribeMC() {
            if (subscriptionToMC) {
                sforce.one.unsubscribe(subscriptionToMC);
                subscriptionToMC = null;
            }
        }
    </script>

</apex:page>
Important

Important

If you worked with Lightning Message Service in developer preview, note the following breaking change in the beta release. The Lightning Message Service API’s subscribe() method now includes a scope parameter. By setting the scope to application, the subscribing component can receive messages on a message channel from anywhere in the application. Application is the only available value. Here are the updated method signatures for subscribe().

Visualforce
subscribe(channelName, listenerMethod, {scope: "APPLICATION"})
Aura
<lightning:messageChannel onMessage="{!c.listenerMethod}" scope="APPLICATION"/>
Lightning Web Components
subscribe(messageContext, channelName, listenerMethod, {scope: APPLICATION_SCOPE})
See the developer guides for more information.