JavaScriptJavaScriptiOSChatEngineGet Started

npm install chat-engine

PubNub ChatEngine is an object oriented event emitter based framework for building chat applications in Javascript. It reduces the time to build chat applications drastically and provides essential components like typing indicators, online presence monitoring and message history out of the box.

The real time server component is provided by PubNub. ChatEngine is designed to be extensible and includes a plugin framework to make adding new features simple.

PubNub ChatEngine is an object oriented event emitter based framework for building chat applications in Javascript. PubNub ChatEngine makes it easy to build Slack, Flowdock, Discord, Skype, Snapchat, or WhatsApp with ease.

The real time server component is provided by Socket.io or PubNub. PubNub ChatEngine is extensible and includes a plugin framework to make dropping in features simple.

Include PubNub ChatEngine

<script src="https://cdn.jsdelivr.net/npm/chat-engine@0.9.18/dist/chat-engine.min.js"></script>

Or in NodeJS:

let ChatEngineCore = require('chat-engine');

The ChatEngine library will then be available as window.ChatEngineCore.

Refer to our QuickStart Tutorial to deploy a ChatEngine application in about 5 minutes.

Follow the instructions below to create a simple chat lobby where you can see who's online and invite one another to private chats.

First, we need to connect to ChatEngine via ChatEngine#connect. The values input into ChatEngine#connect create a new User called Me that this client will act as.

ChatEngine.connect('ian', {
    team: 'red'
});

This will connect to ChatEngine with Me#uuid equal to ian a Me#state of {team: red}.

Because ChatEngine must do some work to connect to the server, we must wait for it to respond before working with Chats and Users.

When ChatEngine is ready, it will emit $.ready. We can subscribe to this event with ChatEngine#on.

ChatEngine.on('$.ready', (data) => {
    console.log('ChatEngine ready to go!');
});

The $ represents a system event. You can read more about system events in the tutorial on Namespaces. You can subscribe to all system events via ChatEngine.on('$.*'), read more in the tutorial on Wildcards.

When ChatEngine#on is fired, Me is supplied as data.me in the response.

ChatEngine.connect('ian', {
    team: 'red'
});

ChatEngine.on('$.ready', (data) => {
    let me = data.me; // ian
});

All calls made to ChatEngine are made on behalf of Me.

Let's create Chat for us to join. We'll make a Chat through which our users can communicate.

let lobby = new ChatEngine.Chat('lobby');

This will create a new Chat. We'll be connected to it automatically.

So how do we see other other people online? Well Me is automatically recorded as joining our Chat, and any other person who runs this program will see ian as a user online on the Chat.

You can get a list of online users via Chat#users.

console.log(lobby.users);

Will output:

{
    ian: {
        // this is a User objet
    }
}

If we were to open another window and connect as stephen, we would see stephen in lobby.users.

ChatEngine.connect('stephen', {
    team: 'blue'
});

Let's chat with stephen.

In order to chat, all we need to do is use the Chat#emit method to send a message over the internet to all other clients who have the program running.

lobby.emit('message', {
    text: 'hey'
});

The first parameter, message, is an event name that is just a string identifier. It helps us tell the difference between different events. See Events Namespaces and Wildcards for more.

The second parameter is a JSON string that represents the message payload. This data is sent over the internet to all subscribing parties.

We can get notified a new message by using Chat#on. The text value is available as payload.data.text.

lobby.on('message', (payload) => {
    console.log(payload.data.text)
});

We can also get the User that sent the message and the Chat the message was sent to. For more on this, see Event Payload.

lobby.on('message', (payload) => {
    console.log(payload.sender.uiud, 'sent a message to', payload.chat.channel, 'with value', payload.data);
});

But hey, what if we want more information about the user that sent the message. Remember how we supplied {team: 'red'} during ChatEngine#connect?

ChatEngine.connect('ian', {
    team: 'red'
});

We can get that value with User#state. This value will be the same on every machine because state is synced between everybody.

lobby.on('message', (payload) => {
    console.log(payload.sender.uuid, 'sent a message', payload.data.text);
    console.log('they are on team', payload.sender.state.team);
});

What if we want to invite stephen into a private chat? We can find stephen from our list of users in the lobby. See Chat#users

We can use stephen's uuid to get his User.

let stephen = lobby.users['stephen'];

Ok, let's make a new chat and invite him to it. We'll create a new Chat and then fire the Chat#invite which invites a User to a Chat.

let privateChat = new ChatEngine.Chat('private');
privateChat.invite(stephen);

So how does stephen know that he got invited? Chat#invite sends stephen a direct message that nobody else can see over a special Chat called User#direct.

stephen can find out when someone invites him by subscribing to the $.invite event via Me#direct. The key for the new chat that we created is available as payload.data.channel.

me.direct.on('$.invite', (payload) => {
    let invitedChat = new $scope.ChatEngine.Chat(payload.data.channel);

    invitedChat.emit('message', {
        text: 'hello everybody!'
    });
});

What if we want to support Markdown in our messages? We can use a ChatEngine plugin. Plugins are loaded via the Chat#plugin, User#plugin, or Me#plugin.

First we include it in the script.

let ceMarkdown = require('chat-engine-markdown');

Then we create a new Chat and attach the plugin to it via Chat#plugin.

let pluginchat = new ChatEngine.Chat('markdown-chat');
pluginchat.plugin(ceMarkdown({}));

And now, when someone sends a message via Chat#emit...

pluginchat.emit('message', {
    text: 'This is some *markdown* **for sure**.'
});

The markdown plugin will parse markdown and replace it as HTML.

pluginchat.on('message', (payload) => {
    // payload.data.text == 'This is some <em>markdown</em> <strong>for sure</strong>.'
});

Check out the tutorials on Plugins and how Build a Plugin.

ChatEngine is the back end to your chat app and does not include a template system. However, the event based system and data synchronization make it super easy to hook into a template system.

Check out the guide on Templating.