PubNub ChatEngine Quickstart Tutorial

Learn the basics of PubNub ChatEngine, chat SDK and APIs for building chat for JavaScript, iOS and Android
PubNub ChatEngine Quickstart Tutorial

PubNub ChatEngine Quickstart Tutorial

ChatEngine makes it easy to build powerful, cross-platform chat on PubNub. It provides essential components (messages, users, typing indicators), microservices infrastructure (chatbots and programmability) and the network to build and scale production-ready chat apps.

This quickstart will walk you through building a basic chat app with ChatEngine. We’ll use vanilla JavaScript, but worry not, ChatEngine supports iOS and Android as well.

All the functional code is provided here via Codepen.

  1. First, configure your account for ChatEngine and get your publish/subscribe keys. Start by creating an account and activating ChatEngine:

    Now that you've configured your account, we can dive into the app. At the end of this guide, you'll have a functioning chat app that looks like this:

    See the Pen ChatEngine Embed Final App W/ Demo Keys by PubNub (@PubNub) on CodePen.

  2. The first step to every ChatEngine client is instantiating an instance of ChatEngine and connecting to PubNub.

    ChatEngine = ChatEngineCore.create({
        publishKey: '<YOUR PUBLISH KEY>',
        subscribeKey: '<YOUR SUBSCRIBE KEY>'
    // Provide a unique id and other profile information for your user here.
    const uuid = String(new Date().getTime());
    ChatEngine.connect(uuid, {
        nickName: "YourUsersNickNameHere",
        favoriteColor: "Red"

    Connecting to PubNub brings the client online. You can think of it as being in a lobby. It requires that you provide a unique identifier for the client and an object that will be shared with all other clients to describe the user for this client.

    The connect call is asynchronous and fires a $.ready event when it successfully connects. Any code that follows should listen for this event and execute code in its handler.

  3. Now that you're connected to the PubNub network, you can create and join a chat and start chatting. The first step is enabling users to receive messages.

    The example below shows you how to create/join a chat, listen and receive messages, and send messages to this chat.

    ChatEngine.on('$.ready', function(data) {
        // store my new user as `me`
        me =;
        // create a new ChatEngine Chat
        myChat = new ChatEngine.Chat('chatengine-demo-room');
        // when we recieve messages in this chat, render them
        myChat.on('message', (message) => {
        // emit the `message` event to everyone in the Chat
        myChat.emit('message', {
            text: "Hi everyone!"
  4. Presence shows online/offline status for users in the chat app. Think of this as your classic "buddy list."

    All you have to do is provide callbacks for $.online.* and $.offline.*. ChatEngine will fire these when users come online or go offline.

    // when a user comes online, render them in the online list
    myChat.on('$.online.*', (data) => {
        $('#people-list ul').append(peopleTemplate(data.user));
    // when a user goes offline, remove them from the online list
    myChat.on('$.offline.*', (data) => {
        $('#people-list ul').find('#' + data.user.uuid).remove();
  5. Chat history stores previously sent messages. In this step, we’ll retain 50 messages for chat users.

    // wait for our chat to connect
    myChat.on('$.connected', () => {
        // search for 50 old `message` events{
            reverse: true,
            event: 'message',
            limit: 50
        }).on('message', (data) => {
            // when messages are returned, render them like normal messages

Congratulations! You now have a functioning chat app powered by ChatEngine. So what's next?

We've got tutorials for a wide variety of languages and services in our tutorials portal to add more features. Here are our most popular: