About the Realtime APIs

The Realtime APIs let you send and receive messages between a site backend and connected clients in real time. When a backend service publishes messages to a channel, clients subscribed to that channel receive them instantly.

With the Realtime APIs, you can:

• Publish messages from the backend to subscribers listening on a specified channel or resource.
• Control permissions that determine which subscribers can receive messages on specific channels or resources.
• Subscribe to channels and resources to receive messages in real time. You can also register handlers for incoming messages, subscription successes, and errors.

Learn more about how the modules work together.

Channels and channel resources

Channels are how publishers send messages to subscribers. Each channel has a unique name and can contain multiple resources. Subscribers can subscribe to channels, resources, or both.

Resources act as independent subchannels that let you send messages only to subscribers who listen on that resource. For example, a chat channel might use a separate resource for each chat room, allowing subscribers to listen to a specific room without receiving messages from other rooms.

Subscribers to a channel don't receive messages sent to a resource on that channel. Similarly, subscribers to a resource don't receive messages sent to its parent channel.

Permissions

Permissions follow a cascading model: Each channel and resource can have its own permissions handlers, but if a resource doesn't have a designated handler, it inherits its parent channel's handler. Similarly, when neither the resource nor its parent channel have permissions handlers, the default handler runs.

Learn more about controlling subscriber permissions with the Site API and permission resolution.

How the modules work together

Each module handles a different part of the messaging pipeline:

1. Publishers send messages on channels or resources.
2. Permission handlers on the site check which subscribers can receive them.
3. Subscribers with the right permissions receive messages.

Before messages can be sent, some setup is required.

Setup

To set up the messaging pipeline:

1. Define permission handlers that control which subscribers can receive messages on each channel or resource.
2. Subscribe to the channels or resources you want to listen on, and register a message handler that runs whenever the subscriber receives a message.

You can also register handlers for subscription successes, reconnections, and errors. Learn more about the subscriber lifecycle.

Messaging

Once the messaging pipeline is set up, the following occurs each time a message is sent:

1. A backend service calls publish() with a channel or resource and a message payload.
2. The realtime_check_permission hook runs for each subscriber, checking their permissions.
3. Subscribers with sufficient permissions receive the message, triggering their message handler.

Cross-app subscriptions

By default, subscribers can only subscribe to channels managed by the current app or by the site's backend code. However, subscribers can also subscribe to channels managed by a different Wix app, as long as that app is installed on the same site. You can subscribe to channels provided by apps created by Wix as well as 3rd-party Wix apps.

To subscribe to a channel managed by another app, specify that app's app ID. The app that provides that channel must implement the Realtime Permissions Provider service plugin to authorize cross-app subscriptions.

Before you begin

It's important to note the following points before starting to code:

• Messages don't persist across tab sessions. Closing the browser tab or window closes the connection.
• When previewing a site, read permissions are always true.

Terminology

• Channel: Named broadcast pipe that publishers send messages to and subscribers listen on.
• Resource: Independent subchannel in a channel. Messages on a resource don't reach the parent channel, and vice versa. Resources can inherit their parent channel's permissions handler.
• Message: Data published to a channel or resource.
• Publisher: Backend service that sends messages to subscribers.
• Subscriber: Client that listens for messages on a channel or resource.