Group Platform Events into One Stream with a Custom Channel

With a custom channel, you can receive a stream of event messages corresponding to one or more platform events defined in your Salesforce org. For example, if you’ve defined platform events corresponding to orders for different regions, one client can subscribe to all those events and process them. Custom channels are supported in CometD and Pub/Sub API clients only. You can also add filters (beta) to custom channels. By using only one client to subscribe to all events and using filters, your subscriptions are optimized.

Types of Events Supported

Custom channels are supported for high-volume custom platform events that you define. They aren’t supported for legacy standard-volume custom platform events or standard platform events, such as real-time event monitoring events.

PlatformEventChannel and PlatformEventChannelMember Objects in the API

Create a custom channel, and specify the platform events it contains in Tooling API and Metadata API.

PlatformEventChannel represents a custom channel. The ChannelType field indicates which members the custom channel can contain. A ChannelType value of event means that the channel can contain platform events via its channel members.

A custom channel can contain events for only one event product. You can’t mix events from different event products in one channel. For example, you can’t add platform events and change data capture events to the same channel.

PlatformEventChannelMember represents a member of a channel. It contains a custom platform event in the SelectedEntity field and is associated with the channel via the EventChannel field.

After you create a channel, you can't change its ChannelType field value.
When you delete a channel by deleting PlatformEventChannel, all its associated members (PlatformEventChannelMember entities) are also deleted.

Note

Example Diagram

This diagram shows the object relationships and definitions of the custom channel Order_Channel__chn and its members. The channel is set up to receive order events for North America, EMEA, and the APAC regions. A custom event is defined for each region: Order_NorthAmer__e, Order_EMEA__e, Order_APAC__e. Each of these platform events is added to the channel via PlatformEventChannelMember objects. An order management app can subscribe to the custom channel, Order_Channel__chn, and receive messages of the three platform events.

Custom order channel containing three platform events, one event per region

Subscribing to a Custom Channel

When you subscribe to the custom channel with CometD, provide the channel name in the format /event/ChannelName__chn, such as /event/Order_Channel__chn. Your subscriber receives event messages of all events that are part of the channel. In a CometD client, each event message contains the EventApiName field, which contains the type of the event. For example, this event message has an EventApiName of Order_EMEA__e, which means that it’s an Order_EMEA__e event.

1{
2  "schema": "e8jMOnID4xDThlaPBMx5gg",
3  "payload": {
4    "City__c": "London",
5    "CreatedById": "005RM000002Qu16YAC",
6    "Amount__c": 20,
7    "CreatedDate": "2022-03-29T13:45:19.230Z",
8    "Order_Number__c": "2"
9  },
10  "event": {
11    "EventApiName": "Order_EMEA__e",
12    "EventUuid": "218544ad-0472-4315-970f-8825a2802de6",
13    "replayId": 10306
14  }
15}

The EventApiName field is available in event messages received in CometD clients that use a Streaming API endpoint with API version 55.0 and later. It isn't available in event messages received in other subscribers, such as Apex triggers, flows, and Pub/Sub API. It isn't included in change data capture events and events that don't support custom channels. Also, the EventApiName field isn’t part of the event schema that the REST eventSchema resource or the describe call returns. To determine the type of the event received with Pub/Sub API, retrieve the event schema with the GetSchema RPC method using the schema ID contained in the received event. The schema name is in the schema_json field in the response and identifies the event type. For more information, see GetSchema RPC Method in the Pub/Sub API Developer Guide.

Custom Channel Allocations

You can create up to 100 custom channels regardless of your Salesforce org edition. For Performance, Unlimited, and Enterprise Editions, you can add up to 50 distinct platform events as part of channel members to a custom channel. For Developer Edition and Professional Edition with the API add-on, this allocation is 5 distinct platform events. If the same platform event is a member of multiple channels, it’s counted once toward the allocation. These allocations are separate from change data capture channel allocations.

Platform Events Developer Guide