Streaming API Developer Guide

Getting Started with Streaming API
Streaming API
Push Technology
Bayeux Protocol, CometD, and Long Polling
Streaming API Terms
How the Client Connects
Message Reliability
Message Durability
Streaming Event Features
Code Examples
Client Connection Considerations
PushTopic Events
Generic Events
Monitoring Event Usage
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Message Durability

Salesforce stores PushTopic events, generic events, and standard-volume events for 24 hours and high-volume events for 72 hours. High-volume events include platform events and Change Data Capture events. Standard-volume events are no longer available and include only events defined before Spring ’19. With API version 37.0 and later, you can retrieve events that are within the retention window through durable streaming.

Event Bus

With API version 37.0 and later, events are published to the event bus. Subscribers retrieve events from a channel on the event bus, including past events that are stored temporarily. The event bus decouples event publishers from event subscribers.

The Salesforce Event Bus

Event Replay Process

Each event message is assigned an opaque ID contained in the ReplayId field. The ReplayId field value, which is populated by the system when the event is delivered to subscribers, refers to the position of the event in the event stream. Replay ID values are not guaranteed to be contiguous for consecutive events. For example, the event following the event with ID 999 can have an ID of 1,025. A subscriber can store a replay ID value and use it on resubscription to retrieve events that are within the retention window. For example, a subscriber can retrieve missed events after a connection failure. Subscribers must not compute new replay IDs based on a stored replay ID to refer to other events in the stream.

This JSON message shows the replayId field in the event object for a generic event.

This JSON message shows the replayId field in the event object for a PushTopic event.

In API version 37.0 and later, the time format of the createdDate field value has changed to make it consistent with the time format used in the Salesforce app. The time portion now ends with a Z suffix instead of +0000. Both suffixes denote a UTC time zone.

Note

Platform event messages contain a replay ID when delivered to a CometD client. This JSON message shows the replayId field in the event object for the Low_Ink__e platform event.

This JSON message shows the replayId field in the event object for a Change Data Capture event.

Replaying Events

A subscriber can choose which events to receive, such as all events within the retention window or starting after a particular event. The default is to receive only the new events sent after subscribing. Events outside the retention period are discarded.

This high-level diagram shows how event consumers can read a stream of events by using various replay options.

Diagram showing a stream of events with replay options
Table 1. Replay Options
Replay Option Description Usage
Replay ID Subscriber receives all stored events after the event specified by its replayId value and new events. Catch up on missed events after a certain event message, for example, after a connection failure. To subscribe with a specific replay ID, save the replay ID of the event message after which you want to retrieve stored events. Then use this replay ID when you resubscribe.
-1 (Default if no replay option is specified.) Subscriber receives new events that are broadcast after the client subscribes. We recommend that clients subscribe with the -1 option to receive new event messages. If clients need to get earlier event messages, they can use any other replay option.
-2 Subscriber receives all events, including past events that are within the retention window and new events. Catch up on missed events and retrieve all stored events, for example, after a connection failure. Use this option sparingly. Subscribing with the -2 option when a large number of event messages are stored can slow performance.

To replay events, use the Streaming API endpoint.

When using the Streaming API endpoint, note these important considerations.

  • Durable streaming is supported when clients subscribe at the Streaming API endpoint using API version 37.0 or later. The PushTopic or platform event version affects only the fields available in the event message, but doesn’t affect the client subscription version.
  • To ensure continuity during instance refreshes and org migrations, we recommend using your org’s My Domain login URL in the Streaming API endpoint.

Note

The replay mechanism is implemented in a Salesforce-provided CometD extension. A sample extension is provided in JavaScript and another in Java. For example, you can register the extension as follows in JavaScript.
  • The argument passed to setReplay() is one of the replay options. We recommend that clients subscribe with the –1 option to receive new events or with a specific replay ID. If the channel contains many event messages, subscribing frequently with the –2 option can cause performance issues.
  • The first argument passed to registerExtension() is the name of the replay extension in your code. In the example, it’s set to myExtensionName, but it can be any string. You use this name to unregister the extension later on.
  • If the setReplay() function isn’t called, or the CometD extension isn’t registered, only new events are sent to the subscriber, which is the same as the –1 option.

Note

After calling the setReplay() function on the extension, the events that the subscriber receives depend on the replay value parameter passed to setReplay().

After a client times out because it hasn’t reconnected within 40 seconds or a network failure has occurred, it attempts a new handshake request and reconnects. The replay extension saves the replay ID of the last message received and uses it when resubscribing. That way, the client receives only messages that were sent after the timeout and doesn’t receive duplicate messages that were sent earlier.

Code Samples

Java Sample
For a Java client sample that uses the CometD extension, see Example: Subscribe to and Replay Events Using a Java Client (EMP Connector).
Lightning Component Sample
For a sample that uses the empApi Lightning component, see Example: Subscribe to and Replay Events Using a Lightning Component.
Visualforce Sample
For a sample and code walkthrough that uses Visualforce and a CometD extension in JavaScript, see Example: Subscribe to and Replay Events Using a Visualforce Page.