Quick Start: JavaScript

  • Jan 9, 2017
  • Starting Guide
  • JavaScript
  • Tutorial

Get your free API key

Before you can use the Realtime Messaging API you need to register, create a "Realtime Messaging Subscription" and make a note of your Realtime application key (this document will refer to it as APP_KEY).

A note about security

This Quick Start Guide assumes your APP_KEY has authentication disabled (by default and for simplity reasons all Realtime application keys have authentication disabled when they are created).

This means you can use any token to connect to a Realtime server. In the examples below we'll use testToken.

When you're ready for production you should enable authentication (we'll cover this on the Security section ahead).

Include the Realtime client library

Include the ortc.js script tag on each page where you would like to establish a connection to a Realtime server:


Open a connection to Realtime

Before you can start sending and receiving messages you need to open a connection to a Realtime server. Use the following code replacing APP_KEY with your Realtime application key:

ortcClient = RealtimeMessaging.createClient();
ortcClient.connect('INSERT_YOUR_APP_KEY_HERE', 'testToken');

Subscribe to a channel

Realtime Messaging is a pub/sub system based on channels (aka as topics). This means that each connected client can only receive messages on channels that were subscribed. To subscribe a channel you simply define the channel name and which callback function should handle each message received.

However you must guarantee that your client is propertly connected before you subscribe a channel by implementing the onConnected event. This event will be invoked when the connection is ready for subscriptions and/or sending messages.

The following code shows how to subscribe to channel myChannel using the onConnected event. Add it right after your ortcClient.connect call:

ortcClient.onConnected = function (ortc) {
  console.log("Connected to " + ortcClient.getUrl());

  ortcClient.subscribe('myChannel', true, function (ortc, channel, message) {

Open your page in any browser to execute it. The previous code will show each message received through myChannel in your browser console log.

To send messages to test you can use the simple console available in the Realtime Account Management website or the advanced console available at console.realtime.co

Send a message to a channel

As soon as you are connected you can start sending messages directly from your webpage using the send method. Here's an example:

var myMessage = {
    foo: "bar"

ortcClient.send('myChannel', JSON.stringify(myMessage));			

Note that Realtime messages are text-based (UTF-8 encoded). This means you can send any string (including JSON strings).

If you wish to send an object you should stringify it using JSON.stringify. Don't forget to parse it back to an object on the subscriber side when the message is received (using the JSON.parse method)

To receive messages sent from your app you can use the simple console available in the Realtime Account Management website or the advanced console available at console.realtime.co. Don't forget to subscribe the channel myChannel

The complete example

Here you have the previous example complete source code. Just save it as an html file and open it in a browser near you. Don't forget to inspect the console log to see the logged messages.

  Realtime JavaScript quick start



More JavaScript resources

The Realtime JavaScript SDK has more methods, like requesting the presence data of a given channel, that are beyond the scope of this quick starting guide. Please refer to the complete JavaScript console example in GitHub to test the entire SDK features.

Back to Overview - Next: Android Quick Start

If you find this interesting please share: