Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

The name of the function or
 the function expression to run when a connection occurs.

handler

ConnectionHandler

Adds an event handler that runs when a connection or reconnection
 occurs.

A connection occurs on the first subscription to a channel or channel resource or 
 when an existing connection is lost and then restored.

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

wixRealtimeFrontend.onConnected( () => {
  // handle connection
  $w("#disconnectedMessage").hide();
} );

Add a connection handler

onConnected

void

The name of the function or
 the function expression to run when a disconnection occurs.

DisconnectionHandler

Adds an event handler that runs when a disconnection occurs.

A disconnection can occur, for example, if there is a network issue.

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

wixRealtimeFrontend.onDisconnected( () => {
  // handle disconnection
  $w("#disconnectedMessage").show();
} );

onDisconnected

The name of the function or
 the function expression to run when an error occurs.

ErrorHandler

Adds an event handler that runs when an error occurs.

An error can occur when attempting to resubscribe after a disconnection.
 Errors that occur during the initial subscription process cause the
 Promise returned by the [`subscribe()`](#subscribe) function to reject
 and do not trigger `onError()` event handlers.

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

wixRealtimeFrontend.onError( (error) => {
  let code = error.errorCode;
  let message = error.message;
  if(error.channel) {
    let channelName = error.channel.name;
    let resourceId = error.channel.resourceId;
  }
} );

Add an error handler

onError

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

channel

Channel

The name of the function or
 the function expression to run when something is published to the subscription's
 channel or channel resource.

MessageHandler

Subscribes to a channel or channel resource.

The `subscribe()` function subscribes to receive messages published on the
 specified channel or channel resource and sets a function that handles
 incoming messages when they are published to the channel. 

 When you subscribe to a channel you do not receive messages published to
 a resource on that same channel. To receive those messages, you must
 explicitly subscribe to the specific resource.

 The specified message handler is run each time a message is published on
 the given channel or channel resource. Use it to define what happens when
 messages are received.

 You can subscribe to a channel or channel resource more than once to add
 multiple message handlers. Each subscription returns a unique subscription
 ID which can be used later to unsubscribe from the specific subscription 
 with that ID, without affecting the other subscriptions on the same channel
 or channel resource.

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

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

wixRealtimeFrontend.subscribe(channel, (message, channel) => {
  let payload = message.payload;
  let channelName = channel.name;
  if(message.publisher) {
    let publisherId = message.publisher.id;
  }
})
.then((id) => {
  subscriptionId = id;
});

Subscribe to a resource on a channel

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

const channel = { name: 'hello-world' };

$w.onReady(function () {
  subscribe(channel, (message) => {
    $w('#receivedMessages').value += (message.payload + '\n');
  });
    
  $w('#publishMessageButton').onClick(async () => {
    if($w('#message').value) {
      $w('#publishMessageButton').disable();
      $w('#message').disable();

      await publishMessage(channel, $w('#message').value);
            
      $w('#message').value = undefined;
      $w('#message').enable();
      $w('#publishMessageButton').enable();
    }
  });
});


This example demonstrates how to send and receive messages across a single channel. 
 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 a single channel

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

$w.onReady(function() {
  const channel = {"name": "updates"};

  wixRealtimeFrontend.subscribe( channel, (message, channel) => {
    $w("#updateMessage").text = message.payload;
    $w("#updateBox").show();
  });

  $w("#hideUpdateButton").onClick( () => {
    $w("#updateBox").hide();
  });
});



This example demonstrates how to display a popup notification when a message is
 received on a channel that a visitor is subscribed to. The notification displays the
 contents of the message that was received.

 The example assumes the page contains a box that contains a text element and a button.
 The box is set to be hidden when the page loads.

 When a message is received, the text element's text value is set to the contents of 
 the message and the box is shown to display the message to the site visitor. When the
 button is clicked, the box is hidden again.

Display a popup notification when a message is received

subscribe

string

Fulfilled - An ID representing the subscription, used for unsubscribing.
Rejected - Error that caused the rejection, such as insufficient
 permissions.

options

UnsubscribeOptions

Unsubscribes from a channel or channel resource.

The `unsubscribe()` function unsubscribes from receiving messages published
 on the specified channel or channel resource. 

 + Use the `channel` property of the `UnsubscribeOptions` object
   passed to the `options` parameter to unsubscribe from all subscriptions to a
   specific channel or channel resource.

   When you unsubscribe from a channel you do not unsubscribe from the
   resources on that same channel. To no longer receive messages on a
   channel resource, you must explicitly unsubscribe from the specific resource.

 + Use the `subscriptionId` property of the `UnsubscribeOptions` object
   passed to the `options` parameter to unsubscribe from a specific subscription.

   This option is typically used when you have more than one subscription to the same
   channel or channel resource and you only want to unsubscribe from one of those subscriptions.

   Get a subscription's `subscriptionId` from the resolution of the Promise returned
   when creating the subscription with the [`subscribe()`](#subscribe) function.

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

const someChannel = {"name": "someChannel"};
let subscriptionId1;
let subscriptionId2;

// first subscription to a channel 
wixRealtimeFrontend.subscribe(someChannel, messageHandler1)
  .then( (id) => {
    subscriptionId1 = id;
  }) ;

// second subscription to the same channel
wixRealtimeFrontend.subscribe(someChannel, messageHandler2)
  .then( (id) => {
    subscriptionId2 = id;
  }) ;

// ...

wixRealtimeFrontend.unsubscribe({"channel": someChannel})
  .then( () => {
    // unsubscribed from all subscriptions to channel
  } );

// ...

function messageHandler1(message, channel){
  // handle channel messages
}

function messageHandler2(message, channel){
  // handle channel messages
}

Unsubscribe from all subscriptions to a channel

import wixRealtimeFrontend from 'wix-realtime-frontend';

// ...

const someChannel = {"name": "someChannel"};
let subscriptionId1;
let subscriptionId2;

// first subscription to a channel 
wixRealtimeFrontend.subscribe(someChannel, messageHandler1)
  .then( (id) => {
    subscriptionId1 = id;
  }) ;

// second subscription to the same channel
wixRealtimeFrontend.subscribe(someChannel, messageHandler2)
  .then( (id) => {
    subscriptionId2 = id;
  }) ;

// ...

wixRealtimeFrontend.unsubscribe({"subscriptionId": subscriptionId1})
  .then( () => {
    // unsubscribed from first subscription to channel
  } );

// ...

function messageHandler1(message, channel){
  // handle channel messages
}

function messageHandler2(message, channel){
  // handle channel messages
}

Unsubscribe from a specific subscription to a channel

unsubscribe

Fulfilled - When unsubscribed from the channel or channel resource.
Rejected - Error that caused the rejection.

# 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 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-frontend` module is used in conjunction with the 
 [`wix-realtime-backend`](wix-realtime-backend.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.
 
 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, import `wixRealtimeFrontend` from the `wix-realtime-frontend` module:

   ```javascript
   import wixRealtimeFrontend from 'wix-realtime-frontend';
   ```

velo_wix-realtime-frontend

Channel name. Cannot exceed 140 characters.

name

resourceId

Error

Error code.
 
 One of:

 + `1`: Connection error
 + `2`: Subscription error (error will also include a channel value)
 + `3`: Bad input

errorCode

number

message

error

Message

payload

publisher

Publisher

The channel the message was published on.

The channel, and optionally the resource, to 
 unsubscribe from. Use this property when unsubscribing from all subscriptions to a channel
 or channel resource.

ID of the subscription to unsubscribe from. Use this 
 property when unsubscribing from one of multiple subscriptions to a channel or channel
 resource.

onConnected( )