Demo

Step 0: Install and Initialize Beebotte

Beebotte provides a javascript library to add real-time communication between a browser (webpage) and Beebotte platform. You need to first include the javascript client library in your HTML page.

<script src='socket.io-1.1.0.js'></script>
<script src='//beebotte.com/bbt.js' ></script>

Set up the credentials to access the API. As the created channel is public, you only need the API key to read data.

var bbt = new BBT('API_KEY', {auth_endpoint: '/bbt_auth', username: 'my nickname'});

When initializing the library, you can specify the authentication end-point (auth_endpoint) for your application. Remember, you are adding realtime chat functionality to your application. Your users are not necessarly on beebotte. It is your responsibility to grant permissions to authenticated users.

You may also setup user friendly identifier that will be used as a nickname in the chat application.

Step 1: Subscribe to Chat Messages

In this tutorial, we consider we have a broadcast chat application where a message is sent to all online users. In order to receive messages sent to this broadcast channel, you need to register to it first.

//Subscribe to public broadcast messages
bbt.subscribe( {channel: 'chat', resource: 'message'}, function(message){
  //console.log(message.data);
  //process the message data here
});

To subscribe to real-time data, you need to specify the channel and resource where the data is being sent. In this example, we assume the data messages are public. Subscribing to public messages does not require any authentication. If you want to restrict who accesses your chat application, you need to set the message types to private. This is done by adding a 'private-' prefix to the channel name as below:

//Subscribe to private broadcast messages
bbt.subscribe( {channel: 'private-chat', resource: 'message'}, function(err, message){
  //process the message data here
});

Step 2: Send Chat Messages

Sending chat messages from the client side requires write permission to be granted. Your application is reponsible for granting permissions to your users, this can be done by setting write to true in the subscription:

/* Request write access to the resource. Permissions are granted at the resource level */
bbt.subscribe(
  {channel: 'private-chat', resource: 'message', write: true},
  function(err, msg) {//process the message data here}
);

The subscribe API will first contact the authentication end-point of your application to request write permission for the specified resource. If the permission is granted, It will send its permission grant to Beebotte. After this, you will be able to send chat messages like this:

bbt.publish({channel: 'chat', resource: 'message'}, 'your message'});

This will send a public message on the broadcast resource. To send a private message, you need only to add 'private-' prefix to the channel name:

bbt.publish({channel: 'private-chat', resource: 'message'}, 'your message'});

By granting users a permission to directly send messages to Beebotte, you will not be able to control what they actualy send. If you want to have control on what can be sent or not, the messages need to go through your application and not be sent directly to Beebotte. In other words, the messages will be sent to your application where you can filter them if they do not respect your policy. Then, you can send the conform messages to Beebotte in order to be routed to online users. This can be done as follows:

On the client side:

//Send message with ajax (this is not specific to Beebotte)
$.post('http://your_app/chat', {msg: 'your message'});

On the server side (assuming you are using nodejs):

app.post( '/chat', function( req, res, next ) {
  if( !req.body.msg ) return next(new Error('Bad Request').http_code(400));
  bclient.publish({
    channel: 'chat',
    resource: 'message',
    data: req.body.msg
  }, function(err, res) {
    if(err) console.log(err);
  });
  res.send( 'OK' );
});

Step 3: Work with Presence notifications

In addition to sending and receiving messages, you might want to add the list of online users. This can be done by registering to presence notifications as follows:

//Subscribe to presence notifications
bbt.subscribe( {channel: 'presence-chat', resource: 'message', function(message){
  //process the presence message here
  if(message.data.event === 'join') {
    //New user joined
  } else if(message.data.event === 'connected') {
    //Connected notification from a user
  }else if(message.data.event === 'leave') {
    //User left the application
  }
});

Next step

Find out more about the cool things you can do in the tutorials. Check the demos and start playing with the API for further details.