Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

The channel, and optionally the resource, to 
 publish to.

channel

Channel

payload

options

PublishOptions

Publishes a message to a channel or channel resource.

The `publish()` function publishes a message to the specified channel or
 channel resource. 

 When site visitors subscribe to a channel, they do not 
 receive messages published to a resource on that same channel. Similarly, 
 when site visitors subscribe to a channel resource, they do not 
 receive messages published to that same channel without a specified resource.

 To publish a message to specific users only, specify the users by ID in
 the `PublishOptions` object sent to the `options` parameter.

 To include the ID of the user who triggered the publish in the published message,
 set the `includePublisher` property of the `PublishOptions` object to `true`.

import wixRealtimeBackend from 'wix-realtime-backend';

// ...

const channel = {"name": "someChannel"};

wixRealtimeBackend.publish(channel, "My message")
  .then(() => {
    // published
  });

Publish to a resource on a channel

import wixRealtimeBackend from 'wix-realtime-backend';

// ...

const channel = {"name": "someChannel"};

const message = {
  "firstKey": "firstValue",
  "secondKey": "secondValue"
};

const user1 = // get ID of first user to publish to
const user2 = // get ID of second user to publish to

const options = {
  "users" : [user1, user2],
  "includePublisher": true
};

wixRealtimeBackend.publish(channel, message, options)
  .then( () => {
    // published
  } );

Publish to specific users on a channel and include publisher information

import { subscribe } from 'wix-realtime-frontend';
import { publishMessage } from 'backend/realtime';

const channelA = { name: 'a' };
const channelB = { name: 'b' };
const channelB1 = { name: 'b', resourceId: '1' };
const channelB2 = { name: 'b', resourceId: '2' };

$w.onReady(function () {
  subscribeToChannels();
  setupPublishButtons();
});

function subscribeToChannels() {
  subscribe(channelA, messageHandler);
  subscribe(channelB, messageHandler);
  subscribe(channelB1, messageHandler);
  subscribe(channelB2, messageHandler);
}

function setupPublishButtons() {
  $w('#publishButtonA').onClick(event => {
    publish(event.target, channelA);
  });

  $w('#publishButtonB').onClick(event => {
    publish(event.target, channelB);
  });

  $w('#publishButtonB1').onClick(event => {
    publish(event.target, channelB1);
  });

  $w('#publishButtonB2').onClick(event => {
    publish(event.target, channelB2);
  });
}

async function publish(button, channel) {
  if ($w('#message').value) {
    button.disable();
    $w('#message').disable();

    await publishMessage(channel, $w('#message').value);

    $w('#message').value = undefined;
    $w('#message').enable();
    button.enable();
  }
}

function messageHandler(message, channel) {
  let textBoxId;

  if (channel.name === 'a') {
    textBoxId = '#receivedMessagesA';
  } else { // Channel B - check resource ID
    if (channel.resourceId === '1') {
      textBoxId = '#receivedMessagesB1';
    } else if (channel.resourceId === '2') {
      textBoxId = '#receivedMessagesB2';
    } else {
      textBoxId = '#receivedMessagesB';
    }
  }

  $w(textBoxId).value += (message.payload + '\n');
}

You can test out the code in our [example template](https://manage.wix.com/edit-template/from?originTemplateId=a527f79a-9a33-46f9-a246-2d6c8dc37e5e&templateId=3a469df1-5a74-47ae-bb5e-5e21d6a4d5ef&autoDevMode=true).

Send and receive messages across multiple channels and channel resources

publish

When the message is published to the channel or channel resource, `void` is returned. Does not indicate that the message was received.

void

The channel, and optionally the resource,
 to check permissions for.

The subscriber to check permissions
 for.

subscriber

Subscriber

Checks permissions for a subscriber on a channel or channel resource.

The `realtime_check_permission` hook is triggered when a site visitor subscribes
 to a channel to check what permissions the subscriber will have.

 The `realtime_check_permission()` function is not a function that you call from
 your code. You define the function in a file named **realtime-permissions.js**
 in your site's Backend section.



__Important:__
- If this function isn't defined, all subscribers will receive the default permissions: `{"read": true}`.
- In Wix Studio, you don't need to define this function, but you must create a backend file named **realtime-permissions.js**. Without this file, subscriptions will fail.




 Implement permissions logic for channels and subscribers by either:

 + Including all permissions logic in the body of this function.
 + Use the `PermissionsRouter` to add permissions
   logic per channel. Then call [`check()`](wix-realtime-backend.PermissionsRouter.html#check) in the body of
   this function and return the permissions object it returns.


> **Note:** When previewing your site, permissions for read are always granted.

// In realtime-permissions.js

export function realtime_check_permission(channel, subscriber) {
  // set default permissions
  let permissions =  {"read": true};
  
  if(channel.name === "MembersOnly") {
    if(subscriber.type === "Member"){
      permissions.read = true; 
    }
    else {
      permissions.read = false;
    }
  }
  
  return permissions;
}

Grant permissions for a channel based on subscriber type

// In realtime-permissions.js

import {permissionsRouter} from 'wix-realtime-backend';

permissionsRouter.default( (channel, subscriber) => {
  return {"read": true};
} );

const membersOnlyChannel = {"name": "MembersOnly"};

permissionsRouter.add(membersOnlyChannel, (channel, subscriber) => {
  if(subscriber.type === "Member") {
    return {"read": true};
  }
  else {
    return {"read": false};
  }
});

export function realtime_check_permission(channel, subscriber) {
  return permissionsRouter.check(channel,subscriber);
}

Grant permissions for a channel based on subscriber type using the permissions router

// In realtime-permissions.js

import { members } from `wix-members-backend`;

export async function realtime_check_permission(channel, subscriber) {
  // set default permissions
  let permissions =  { "read": true };

  if(channel.name === "BobsOnly") {
    let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });
    if(member.contactDetails.firstName === "Bob") {
      permissions.read = true;
    }
    else {
      permissions.read = false;
    }
  }
  
  return permissions;
}

Grant permissions based on user data

// In realtime-permissions.js

import { members } from `wix-members-backend`;
import { permissionsRouter } from 'wix-realtime-backend';

permissionsRouter.default((channel, subscriber) => {
  return {"read": true};
});

const membersOnlyChannel = {"name": "MembersOnly"};

permissionsRouter.add( membersOnlyChannel, async (channel, subscriber) => {
  let member = await members.getMember(subscriber.id, { fieldsets: ['FULL'] });
  
  if(channel.resourceId === "BobsOnly") {
    if(member.contactDetails.firstName === "Bob") {
      return { "read": true };
    }
    else {
      return { "read": false };
    }
  }
  else {
    return { "read": true };
  }
} );

export function realtime_check_permission(channel, subscriber) {
  return permissionsRouter.check(channel, subscriber);
}

Grant permissions based on user data using the permissions router

import { subscribe } from 'wix-realtime-frontend';
import { publishMessage } from 'backend/realtime';

const updatesChannel = {name: 'updates'};
const updatesMembersChannel = {name: 'updates', resourceId: 'members'};
const updatesAdminsChannel = {name: 'updates', resourceId: 'admins'};
const updatesGuestsChannel = {name: 'updates', resourceId: 'guests'};

$w.onReady(function () {
  subscribeToChannels();
  setupPublishButtons();
});

function subscribeToChannels() {
  subscribe(updatesChannel, messageHandler)
    .catch(() => console.log('Not subscribed to updates channel'));
  subscribe(updatesMembersChannel, messageHandler)
    .catch(() => console.log('Not subscribed to members channel'));
  subscribe(updatesAdminsChannel, messageHandler)
    .catch(() => console.log('Not subscribed to admins channel'));
  subscribe(updatesGuestsChannel, messageHandler)
    .catch(() => console.log('Not subscribed to guest channel'));
}

function messageHandler(message, channel) {
  const channelName = channel.name;
  const channelResource = channel.resourceId ? `-${channel.resourceId}` : '';
  let newMessageLine = `${channelName}${channelResource}: ${message.payload}\n`;
  $w('#receivedMessages').value += newMessageLine;
}

function setupPublishButtons() {
  $w('#updateButton').onClick(event => {
    publish(event.target, updatesChannel);
  });

  $w('#memberUpdateButton').onClick(event => {
    publish(event.target, updatesMembersChannel);
  });

  $w('#adminUpdateButton').onClick(event => {
    publish(event.target, updatesAdminsChannel);
  });

  $w('#guestUpdateButton').onClick(event => {
    publish(event.target, updatesGuestsChannel);
  });
}

async function publish(button, channel) {
  if ($w('#message').value) {
    button.disable();
    $w('#message').disable();

    await publishMessage(channel, $w('#message').value);

    $w('#message').value = undefined;
    $w('#message').enable();
    button.enable();
  }
}

Check permissions across multiple channels and channel resources

realtime_check_permission

The permissions granted to the subscriber on the channel or channel resource.

ChannelPermissions

# Introduction
Using the Realtime API you can create channels and channel resources where messages
 can be published. Site visitors who subscribe to a channel receive the published
 messages published to that channel. When a message is received you can handle the message any
 way you choose, such as displaying the contents of the message or changing the state
 of page elements depending on the contents of the message. You can also manage the
 permissions of who can read from specific channels.

 The `wix-realtime-backend` module is used in conjunction with the 
 [`wix-realtime-frontend`](wix-realtime-frontend.html) module.

 Get hands-on experience with the Realtime API on our [Hello Realtime](https://www.wix.com/velo/example/hello-realtime) example page. 

 Typical uses of the Realtime API include implementing a messaging system or
 as an alternative to using a polling mechanism.

 The Realtime API uses the following terminology:

 + **Channel**: A specific channel on which messages are published. Each channel
   has a unique name. Site visitors can subscribe to a channel to receive the 
   messages that are published on it. When site visitors subscribe to a channel, they do not 
   receive messages published to a resource on that same channel.
 + **Channel resource**: A subchannel on which messages are published. Subchannels
   can share a name with a channel and other subchannels, but they have a unique
   resource ID. When site visitors subscribe to a channel resource, they do not 
   receive messages published to that same channel without a specified resource.
   Channel resources inherit their parent channel's permissions, unless specified
   otherwise.
 + **Message**: A message published on a channel or channel resource. A message can
   be of any type, such as a string, number, or object. Channel subscribers receive
   the messages published on the channel.
 + **Publish**: Sending a message over a channel or channel resource.
 + **Subscribe**: A site visitor subscribes to receive the messages published on a 
   channel or channel resource.
 + **Permissions router**: The permissions router is used to define the permissions
   you want to grant to subscribers on channels and channel resources.
 + **Permissions handler**: Handles a permissions check for a specific user on a 
   specific channel or channel resource.
 
 For a tutorial on using the Realtime API, see 
 [Sending Messages with the Realtime API](https://support.wix.com/en/article/velo-tutorial-sending-messages-with-the-realtime-api).

 To use the Realtime API in the backend, import `wixRealtimeBackend` from the `wix-realtime-backend` module:

   ```javascript
   import wixRealtimeBackend from 'wix-realtime-backend';
   ```

velo_wix-realtime-backend

Sets a permissions handler for a specific channel or channel resource.

The handler set by the `add()` function is used for permission checks by the permissions
 router for the channel or channel resource specified in the `channel` property.

 Adding a handler to a specific channel without a specified resource adds a handler for
 all permissions checks on the channel and all permissions checks on any of the channel's
 resources that do not have their own permissions handlers.

 For example, suppose you have the following channel, resources, and permissions:

 + channel: A, permissions: handler X is specified using the `add()` function
 + channel: A, resource: 1, permissions: handler Y is specified using the `add()` function
 + channel: A, resource: 2, permissions: no handler is specified


 Permissions will be checked as follows:

 + A: use handler X
 + A, 1: use handler Y
 + A, 2: use handler X

Checks the permissions for a subscriber on a channel or channel resource.

The `check()` function returns a Promise that resolves to the permissions for the
 specified user on the specified channel or channel resource.

 The check is performed as follows:

 1. If a permissions handler for the specified channel or channel resource exists,
    it's invoked and its result is returned.
 1. If no handler is found for the specified channel resource, but a handler
    exists for the resource's channel, it's invoked and its result is returned.
 1. If no handler is found for the specified channel, but a default permissions handler
    exists, it's invoked and its result is returned.
 1. If the default handler has not been found, the default permissions are returned.

    The default permissions are:
    `{"read": true}`


 This function is typically called in the body of the
 [`realtime_check_permission()`](#realtime_check_permission) function like so:

 ```JavaScript
 export function realtime_check_permission(channel, subscriber) {
   return permissionsRouter.check(channel,subscriber);
 }
 ```

check

Sets a permissions handler for default permissions.

The handler set by the `default()` function is used for permission checks by the permissions
 router for all channels where an explicit handler has not been added. For channel resources,
 if no explicit handler has been set, the resource will inherit the permissions of its parent
 channel.

 For example, suppose you have the following channel, resources, and permissions:

 + channel: A, permissions: no handler specified
 + channel: A, resource: 1, permissions: no handler specified
 + channel: A, resource: 2, permissions: handler is specified


 Permissions will be checked as follows:

 + A: use the handler set by `default()` function
 + A, 1: use the handler set by `default()` function
 + A, 2: use the handler set by `add()` function for this resource


 If no default handler is set, subscribers to channels without explicit permissions handlers will
 receive the following permissions:
 `{"read": true}`

default

# Introduction
Use the permissions router to define the permissions you want to grant to subscribers
 on channels or channel resources. You can set permissions on the channel and channel
 resource level. If you do not define permissions for a particular channel resource,
 that resource inherits the permissions of its parent channel.

 Typically you use the permissions router in the **realtime-permissions.js** file in
 your site's backend to:

 + Set default permissions for all channels and channel resources where no explicit
   permissions are defined.
 + Add permissions logic for specific channels or channel resources.
 + Check the permissions for a specific subscriber on a specific channel.

 > **Note:** Although it is recommended, you do not need to use the permissions router to set permissions. You can also define all your permissions logic in the [`realtime_check_permission()`](#realtime_check_permission) function.

PermissionsRouter

Returns the realtime permissions router.

Use the permissions router to define the permissions you want to grant to subscribers
 on channels or channel resources. You can set permissions on the channel and channel
 resource level. If you do not define permissions for a particular channel resource,
 that resource inherits the permissions of its parent channel.

 Typically you use the permissions router in the **realtime-permissions.js** file in
 your site's backend to:

 + Set default permissions for all channels and channel resources where no explicit
   permissions are defined.
 + Add permissions logic for specific channels or channel resources.
 + Check the permissions for a specific subscriber on a specific channel.

 > **Note:** Although it is recommended, you do not need to use the permissions router to set permissions. You can also define all your permissions logic in the [`realtime_check_permission()`](#realtime_check_permission) function.

permissionsRouter

Channel name. Cannot exceed 140 characters. Cannot include spaces or special characters.

name

string

resourceId

Whether the subscriber has read permissions. Defaults to `true`.

read

boolean

PermissionsHandler

Whether to include information about the message publisher.
 Defaults to `false`.

includePublisher

User IDs of specific users to publish to.

users

The type of subscriber.

 One of:

 + `"Admin"`: Subscriber is the site owner.
 + `"Member"`: Subscriber is a logged-in site member.
 + `"Visitor"`: Subscriber in not logged in.

publish( )