PubNub ChatEngine Quickstart Tutorial

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

ChatEngine makes it easy to build powerful, cross-platform chat with 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 for this quick start, however ChatEngine supports iOS, Android, and a number of frameworks 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, let’s 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. To get started, install the ChatEngine dependencies. Put this line of HTML before your main JavaScript file reference:

    HTML

     

    If you intend to use ES6 JavaScript with Webpack or Browserify, run this on your command line:

    npm i chat-engine --save
        

    Next, in your JavaScript file use:

     import ChatEngineCore from 'chat-engine';
        

    Then, simply create an instance of ChatEngine and connect to the PubNub Network.

    let myChat;
    let publish;
    
    // setup up PubNub API keys
    ChatEngine = ChatEngineCore.create({
       publishKey: 'Enter-PUB-Key-Here',
       subscribeKey: 'Enter-SUB-Key-Here'
    });
    
    // 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 a user 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 ChatEngine.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 messaging. The next step is to enable users to receive messages.

    The example below creates a chat and the client joins. After the chat is connected to PubNub, the client registers event handlers to listen for and receive messages. At the bottom, a greeting message is sent to the chat.

    
    ChatEngine.on('$.ready', (data) => {
       // store my user as me
       me = data.me;
    
       // create a new ChatEngine chat room
       myChat = new ChatEngine.Chat('chat-engine-demo-room');
    
       // connect to the chat room
       myChat.on('$.connected', () => {
           console.log('The chat is connected!');
           // when we receive messages in this chat, render them
           myChat.on('message', (message) => {
               console.log('Incoming Message: ', message);
           });
    
           // send a message to everyone in the chat room
           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, log who is online
    myChat.on('$.online.*', (data) => {
        console.log("User is Online: ", data.user);
    });
    // when a user goes offline, log who went offline
    myChat.on('$.offline.*', (data) => {
        console.log("User is Offline: ", data.user);
    });
    
        
  5. Chat history stores previously sent messages. In this step, we will retain 50 messages for chat users.

        // wait for our chat to connect
    myChat.on('$.connected', () => {
       // search for 50 old message emits / publishes on the channel
       myChat.search({
           reverse: true,
           event: 'message',
           limit: 50
       }).on('message', (data) => {
           // when messages are returned, log them like normal messages
           console.log(data);
       });
    });
    
        

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

  1. You can learn about ChatEngine concepts and view documentation here
  2. View all the functional code via Codepen
  3. View tutorials for a wide variety of languages and services in our tutorials portal to add more features. Here are our most popular:

Try PubNub Today