🎉 New! Integrate Beams with Chatkit for powerful push notifications—find out more

Extensible API for in-app chat


Build scalable realtime features


Programmatic push notifications



Read the docs to learn how to use our products


Explore our tutorials to build apps with Pusher products


Reach out to our support team for help and advice

Sign in
Sign up

Create a live chat widget with JavaScript

  • Alex Booker

  • Neo Ighodaro

March 8th, 2018
To follow this tutorial, it will be helpful to have a basic knowledge of HTML, JavaScript (jQuery) and Node.js. Familiarity with a command line interface will also be useful.

In this tutorial, we will explore how you can create a custom live chat system for your web application using Chatkit.

This tutorial will cover how to build a chat widget the customer will interact with, and how to create an admin panel where you and your team can talk to your customers.

In many cases, customers are disconnected from someone who can answer their questions in real time. Rather than watch potential customers click away, live chat support can provide the convenient answers that customers want, and keep them engaged. Unsurprisingly, talking to customers can help you understand their pain points so you can address them and crush your competition.

When we’re done, our entire application will look and function like this:

What you need

To follow along, it would be helpful to have:

  • A basic knowledge of HTML
  • A basic knowledge of JavaScript (in this tutorial, we’ll be using Node and jQuery)
  • Basic knowledge of the command-line

You’ll also need to sign up to Chatkit and create a Chatkit instance.

Create your Chatkit instance

You’re probably wondering “what is Chatkit?” Great question!

Chatkit is a tool that makes it easy to add real-time chat features to your application.

With just a few lines of code, you can add real-time messaging and with just a few more, you can enable advanced features like:

  • Read receipts
  • Typing indicators
  • “Who’s online” presence
  • Roles and permissions

To use Chatkit, you’ll first need to sign up then create a new Chatkit instance:

In the Inspector, create a new user called chatkit-dashboard (remember to hit “Save”):

Setup the client environment

To get started, let’s create a new directory. This will be the directory where our entire project will live.

In your terminal, create a new directory for your application, we will name ours acme:

mkdir live-chat-widget-js
cd live-chat-widget-js 

In this directory, create a new package.json file. This file is where we will add all our Node dependencies:

  "name": "live-chat-widget",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@pusher/chatkit-server": "^1.0.4",
    "express": "^4.16.4",
    "uuid": "^3.3.2"

In the above file, we define a couple of dependencies that will be required to run our Node application.

Install them by running npm install:

npm install

The next thing to do will be to create our Express application. If you’re unfamiliar with Express, you can learn more here.

Setup the server environment

In the root directory of your application, create a new file called index.js. In this file, we will define all the routes the application requires to function.

In the index.js file, we will start by importing all the necessary Node modules we added to the package.json file:

const path = require('path');
const express = require('express');
const bodyParser = require('body-parser');
const uuidv4 = require('uuid/v4');
const Chatkit = require('@pusher/chatkit-server');

The next thing we need to do is initialize Express and Chatkit. You should create a file called config.js and paste the following:

module.exports = {
    instanceLocator: 'v1:us1:example',
    key: 'your:key'

In the index.js, paste the following:

const app = express();
const chatkit = new Chatkit.default(require('./config.js'));

⚠️ Remember to replace the placeholder instanceLocator and key values with your actual credentials from the Chatkit dashbaord

Next, we need to register some Express middleware so that we can accept data from the client as well as serve static files. This will be quite familiar to you if you’re used to Express:

app.use(bodyParser.urlencoded({ extended: false }))
app.use(express.static(path.join(__dirname, 'assets')))

The next thing to create will be the routes. We will create routes for the API side of things and then to display HTML.

In index.js, paste the code below at the bottom of the file:

app.get('/', (req, res) => {
  res.sendFile('index.html', {root: __dirname + '/views'})

Simply, this route will render the homepage view (index.html) once we create it.

We’ll create the view in a second but first, let’s create some other endpoints that we'll need to communicate with Chatkit.

In index.js, add this new route before the one we added above:

app.post('/session/auth', (req, res) => {
  const authData = chatkit.authenticate({ userId: req.query.user_id });


Chatkit authentication is powerful and flexible, but we won’t dig too deeply in this tutorial. For the purposes of this tutorial, everyone has equal permissions.

This route will use the authenticate method on the chatkit instance to create a token for the user_id. You can read more about Chatkit tokens in our documentation.

The next endpoint we want to create is /session/load. After the one we just added, paste the code below:

app.post('/session/load', (req, res, next) => {
  // Attempt to create a new user with the email will serving as the ID of the user.
  // If there is no user matching the ID, we create one but if there is one we skip
  // creating and go straight into fetching the chat room for that user

  let createdUser = null;

      id: req.body.email,
      name: req.body.name,
    .then(user => {
      createdUser = user;

      getUserRoom(req, res, next, false);
    .catch(err => {
      if (err.error === 'services/chatkit/user_already_exists') {
        createdUser = {
          id: req.body.email,

        getUserRoom(req, res, next, true);


  function getUserRoom(req, res, next, existingAccount) {
    const name = createdUser.name;
    const email = createdUser.email;

    // Get the list of rooms the user belongs to. Check within that room list for one whos
    // name matches the users ID. If we find one, we return that as the response, else
    // we create the room and return it as the response.

        userID: createdUser.id,
      .then(rooms => {
        let clientRoom = null;

        // Loop through user rooms to see if there is already a room for the client
        clientRoom = rooms.filter(room => {
          return room.name === createdUser.id;

        if (clientRoom && clientRoom.id) {
          return res.json(clientRoom);

        // Since we can't find a client room, we will create one and return that.
            creatorId: createdUser.id,
            isPrivate: true,
            name: createdUser.id,
            userIds: ['Chatkit-dashboard',createdUser.id],
          .then(room => res.json(room))
          .catch(err => {
            next(new Error(`${err.error_type} - ${err.error_description}`));
      .catch(err => {
        next(new Error(`ERROR: ${err.error_type} - ${err.error_description}`));

In the route above we are doing a couple of things.

First, we take the user’s name and email, and use them to create a new Chatkit user using createUser.

Once the user exists, we call getUserRoom to fetch a Chatkit room for the user and agent. A Chatkit room can contain between 1 and 100 users. If you want to build a one-to-one chat like we do here, we can create a room with just two people in it.

In the getUserRoom function, we make a request to get a list of all the available rooms on the Chatkit application. If there is a room that matches the user’s email address then we return that room. If that room doesn’t exist then we create a new room with the user’s email address as the name of the room then return that room.

Add the chat UI

Earlier in the tutorial, we defined a route for the homepage. Now let’s write the HTML in a file called index.html in the views directory:

<!doctype html>
<html lang="en">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Acme Agency</title>
    <link href="https://getbootstrap.com/docs/4.0/dist/css/bootstrap.min.css" rel="stylesheet">
    <link rel="stylesheet" href="chat.css">
    <div class="site-wrapper">
      <div class="site-wrapper-inner">
        <div class="cover-container">
          <header class="masthead clearfix">
            <div class="inner">
              <h3 class="masthead-brand">ACME.</h3>
              <nav class="nav nav-masthead">
                <a class="nav-link active" href="#">Home</a>
                <a class="nav-link" href="#">Features</a>
                <a class="nav-link" href="#">Contact</a>
          <main role="main" class="inner cover">
            <h1 class="cover-heading">ACME.</h1>
            <p class="lead">ACME is a San Francisco based design agency. We build amazing web experiences.</p>
            <p class="lead">
              <a href="#" class="btn btn-lg btn-secondary">Learn more</a>
          <footer class="mastfoot">
            <div class="inner">
              <p>Cover template for <a href="https://getbootstrap.com/">Bootstrap</a>, by <a href="https://twitter.com/mdo">@mdo</a>. Photo by <a href="https://unsplash.com/photos/UxtIESWxLh8?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Jean Gerber</a></p>

    <div class="chatbubble">
        <div class="unexpanded">
            <div class="title">Chat with Support</div>
        <div class="expanded chat-window">
          <div class="login-screen container">
            <form id="loginScreenForm">
              <div class="form-group">
                <input type="text" class="form-control" id="fullname" placeholder="Name*" required>
              <div class="form-group">
                <input type="email" class="form-control" id="email" placeholder="Email Address*" required>
              <button type="submit" class="btn btn-block btn-primary">Start Chat</button>
          <div class="chats">
            <div class="loader-wrapper">
              <div class="loader">
            <ul class="messages clearfix">
            <div class="input">
              <form class="form-inline" id="messageSupport">
                <div class="form-group">
                  <input type="text" autocomplete="off" class="form-control" id="newMessage" placeholder="Enter Message">
                <button type="submit" class="btn btn-primary">Send</button>

    <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
    <script src="https://getbootstrap.com/docs/4.0/assets/js/vendor/popper.min.js"></script>
    <script src="https://getbootstrap.com/docs/4.0/dist/js/bootstrap.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/axios@0.17.0/dist/axios.min.js"></script>
    <script src=" https://unpkg.com/@pusher/chatkit-client"></script>
    <script src="chat.js"></script>

In the HTML above, we import a custom css file, chat.css, which you can download here.

Next, we use a Bootstrap template to create a make-believe landing page for our make-believe agency.

We have a .chatbubble div that contains all the code for our customer support chat room. We also have a loginScreenForm that displays the login screen with a Name and Email Address field.

When the start button is clicked, we show a loader animation while the data is sent to the server.

In the backend, we will create a new Chatkit session and a chatroom using the email address of the customer. When all that is complete, it loads up the chat room’s messages if any have been left there before.

The next thing we want to load is some custom JavaScript for the front-end from a file called chat.js.

Rather than include the complete code here, you’ll need to download chat.js (link above) and save it in the assets directory.

Here, we will break down the important parts:



let chat = {
    messages: [],
    room:  undefined,
    userId: undefined,
    currentUser: undefined,


const chatPage   = $(document)
const chatWindow = $('.chatbubble')
const chatHeader = chatWindow.find('.unexpanded')
const chatBody   = chatWindow.find('.chat-window')


const helpers = {}


chatHeader.on('click', helpers.ToggleChatWindow)
chatBody.find('#loginScreenForm').on('submit', helpers.LogIntoChatSession)
chatBody.find('#messageSupport').on('submit', helpers.SendMessageToSupport)

⚠️ Remember to replace the placeholder PUSHER_INSTANCE_LOCATOR value with your actual instance locator from the Chatkit dashboard

Above, we just define some variables we will be needing. The chat variable will be the main object to hold our messages, the current room object etc.

Next, we define a helpers object. We will be adding several methods to this JavaScript object. After the helpers definition, we start registering event handlers to various events from the page.

Let’s start adding methods to the helpers object. The first one will be ToggleChatWindow. This is a function that toggles the display of the chat window. It either minimizes it or maximises it depending on the current state. Here is the function:

ToggleChatWindow: function () {
        chatWindow.hasClass('opened') ? 'Minimize Chat Window' : 'Chat with Support'

The next one will be ShowAppropriateChatDisplay. In this function, we will show either the login screen or the chat screen. It decides which to show dependent on the chat.room object being set. If there is a room loaded then it shows the messages in the chat screen.

ShowAppropriateChatDisplay: function () {
    if (chat.room && chat.room.id) {
    } else {

The next method will be ShowInitiationDisplay. This function just makes sure the login screen is the one showing:

ShowAppropriateChatDisplay: function() {
      chat.room && chat.room.id
        ? helpers.ShowChatRoomDisplay()
        : helpers.ShowChatInitiationDisplay();

The next function to add to the helpers object is the ShowChatRoomDisplay function:

ShowChatRoomDisplay: function () {

    // Create a token provider to retrieve the token from our Node server
    const tokenProvider = new Chatkit.TokenProvider({
        url: "/session/auth",
        queryParams: { user_id: chat.userId },

    // Create an instance of the chatkit manager
    const chatManager = new Chatkit.ChatManager({
        instanceLocator: PUSHER_INSTANCE_LOCATOR,
        userId: chat.userId,

    // Connect to chatkit
        .then(currentUser => {
            // Successful connection
            chat.currentUser = currentUser

            // Fetch ,essages and add them to the UI
            currentUser.fetchMessagesFromRoom(chat.room, {}, messages => {
                // Hide the loading screen
                chatBody.find('.input, .messages').show()

                // Add messages to the UI
                messages.forEach(message => helpers.NewChatMessage(message))

                // Subscribe to the room and add a listener for new messages
                    id: chat.room.id, 
                    hooks: {
                        onMessage: message => helpers.NewChatMessage(message),
        .catch(err => { console.error(err) })

In the function above, we created a tokenProvider instance. This token provider sends a request to /session/auth with the user_id. The endpoint returns a JWT that the chat app can then use to make requests on behalf of the user.

After that, we connected to chatkit using the token provided. On successful connection, we fetch the messages from the room and then add the messages to the UI.

Lastly, we subscribe to the room so we can add listeners. The only listener we implement is onMessage. When a message is received, this function is called and the message is rendered. There are other listeners you can implement though, take a look at the docs for some more.

Next, let’s add the NewChatMessage function to the helpers object. In the function we will take a message object and add it to the UI. We will also save it to chat.messages. Here is the code:

NewChatMessage: function (message) {
    if (chat.messages[message.id] === undefined) {
        const messageClass = message.sender.id !== chat.userId ? 'support' : 'user'

            `<li class="clearfix message ${messageClass}">
                <div class="sender">${message.sender.name}</div>
                <div class="message">${message.text}</div>

        chat.messages[message.id] = message

The next function to add will be SendMessageToSupport. This function simply posts a message directly to the room:

SendMessageToSupport: function(evt) {

      const message = $('#newMessage')

        { text: message, roomId: chat.room.id },
        msgId => {
          console.log('Message added!');
        error => {
          console.log(`Error adding message to ${chat.room.id}: ${error}`);


The final method we will add to the helpers object is LogIntoChatSession. This method will allow us to log in to a chat session. It sends the user’s name and email address and then receives a room object in response. We then call ShowAppropriateChatDisplay after we have gotten the room:

 LogIntoChatSession: function(evt) {
      const name = $('#fullname')
      const email = $('#email')

      // Disable the form
        .find('#loginScreenForm input, #loginScreenForm button')
        .attr('disabled', true);

      if (
        name !== '' &&
        name.length >= 3 &&
        (email !== '' && email.length >= 5)
      ) {
        axios.post('/session/load', { name, email }).then(response => {
          chat.userId = email;
          chat.room = response.data;
      } else {
        alert('Enter a valid name and email.');


That’s all for the chat.js file. Again if you need the full version, it’s available here.

Test it out

If you followed the tutorial so far you should have been able to create the agency website with the chat widget at the bottom right of the screen.

Run the command below to start a Node server:

node index.js

When you visit http://localhost:3000 you should see something like this:

Now when you log in and send messages, they will be sent to Chatkit and you can see all the messages posted to the room.

In the rest of this tutorial, we’ll look at how to build an admin interface so a support agent can join the conversation.

Render the admin view

Next, we will focus on the admin-side of our chat. In this backend, we will be able to communicate with users who contact us using the chat widget we built in the previous part.

In index.js, add the following route:

app.get('/admin', (req, res) => {
    res.sendFile('admin.html', {root: __dirname + '/views'})

Simply, this route will render the admin page (admin.html) once we create it.

To keep this tutorial simple, we will leave the admin page public. In a real world scenario, you would want to ensure the user is authenticated and authorised before accessing this route.

Add the admin UI

Let’s build up the frontend for our admin panel. When we are done we will have something similar to this:

On the left we have the rooms that are available and on the right we have the chat window. When a chat room is selected, the chat will pop up on the right.

Create a new file views/admin.html and add the following:

<!doctype html>
<html lang="en">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link href="//getbootstrap.com/dist/css/bootstrap.min.css" rel="stylesheet">
    <link href="admin.css" rel="stylesheet">
        <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark">
            <a class="navbar-brand" href="#">Dashboard</a>
    <div class="container-fluid">
        <div class="row" id="mainrow">
            <nav class="col-sm-3 col-md-2 d-none d-sm-block bg-light sidebar">
                <ul class="nav nav-pills flex-column" id="rooms">
            <main role="main" class="col-sm-9 ml-sm-auto col-md-10 pt-3" id="main">
                <p>👈 Select a chat to load the messages</p>
                <div class="chat" style="margin-bottom:150px">
                    <h5 id="room-title"></h5>
                    <div class="response">
                        <form id="replyMessage">
                            <div class="form-group">
                                <input type="text" placeholder="Enter Message" class="form-control" name="message" />
                    <div class="table-responsive">
                      <table class="table table-striped">
                        <tbody id="chat-msgs">
    <script src="//code.jquery.com/jquery-3.2.1.slim.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/axios@0.17.0/dist/axios.min.js"></script>
    <script src="//unpkg.com/@pusher/chatkit-client"></script>
    <script src="admin.js"></script>

As you can see, both the conversation list and chat containers are empty. We’ll populate them dynamically later with the data we get from Chatkit 👍🏻

Style the admin page

In the above HTML, we reference a CSS file called assets/admin.css, which you can download here.

I won’t explain the CSS in this tutorial as we want to focus on building live chat.

Create the admin panel JavaScript

In the same HTML file, we reference a script called assets/admin.js, which you can download here

I haven’t included the entire code (copy and paste it from the above link) but we will break it down here:


let chat = {
    rooms: [],
    messages: [],
    currentUser: false,

const chatBody = $(document)
const chatRoomsList = $('#rooms')
const chatReplyMessage = $('#replyMessage')

const helpers = {}

chatReplyMessage.on('submit', helpers.replyMessage)
chatRoomsList.on('click', 'li', helpers.loadChatRoom)

⚠️ Remember to replace the placeholder PUSHER_INSTANCE_LOCATOR value with your actual credentials from the Chatkit dashbaord

Above we define some initial variables we’ll use later.

The chat variable will be the main object to hold our messages, the list of rooms, and the current user.

We also defined the helpers object. In here we will add some helper methods. Let’s start defining them.

The first one is the clearChatMessages function which is fairly straightforward:

clearChatMessages: () => {

The next helper method is the displayChatMessage method which displays a single chat message by adding it to the UI:

displayChatMessage: (message) => {
    if (chat.messages[message.id] === undefined) {
        chat.messages[message.id] = message

                    <div class="sender">
                        ${message.sender.name} @ 
                        <span class="date">${message.createdAt}</span>
                    <div class="message">${message.text}</div>

Here, we use jQuery but you could just as well use React, Vue, vanilla JavaScript etc.

The next method to add to the helpers object is the loadChatRoom method:

loadChatRoom: evt => {
      chat.currentRoom = chat.rooms[$(evt.target).data('room-id')];

      if (chat.currentRoom !== undefined) {

            roomId: chat.currentRoom.id,
          .then(msgs => {
            msgs.forEach(message => helpers.displayChatMessage(message));

              roomId: chat.currentRoom.id,
              hooks: {
                onMessage: message => helpers.displayChatMessage(message),


In this function, we try to load a chat room by fetching messages belonging to the room. Then, we add the messages to the UI and add a newMessage listener to catch new messages sent by Chatkit.

The next method is replyMessage. In this method we post a new message to the chat room:

replyMessage: evt => {

      const message = $('#replyMessage input')

        { text: message, roomId: chat.currentRoom.id },
        msgId => console.log('Message added!'),
        error =>
            `Error adding message to ${chat.currentRoom.id}: ${error}`

      $('#replyMessage input').val('');

The final method we have to add is loadChatManager:

loadChatManager: () => {
      const chatManager = new Chatkit.ChatManager({
        userId: 'Chatkit-dashboard',
        instanceLocator: PUSHER_INSTANCE_LOCATOR,
        tokenProvider: new Chatkit.TokenProvider({
          url: '/session/auth',
          userId: 'Chatkit-dashboard',

      chatManager.connect().then(user => {
        chat.currentUser = user;

        // Get all rooms and put a link on the sidebar...
        user.rooms.forEach(room => {
          if (!chat.rooms[room.id]) {
            chat.rooms[room.id] = room;

              `<li class="nav-item"><a data-room-id="${
              }" class="nav-link" href="#">${room.name}</a></li>`

In the method above, we instantiate a Chatkit.TokenProvider and tell it to fetch a token from the /session/auth endpoint we created earlier in the tutorial.

We specify that the userId is chatkit-dashboard, which the server uses to generate the token that will be used to connect to Chatkit.

When the connection is successful, we get all the joinable rooms for the current user and join them. If there are no joinable rooms, that endpoint will return an empty array.

That’s all for the admin.js file. Again, if you need the full version, it’s available here.

With those new files, we should have an admin section ready to be used in conjunction with the chat widget we created in the first part of the article.

Here is the preview again of how it will look:


In this tutorial, you learned how to build a customer support widget and administrator interface using JavaScript and Chatkit. Thanks to Chatkit, we didn’t have to write much server code at all, Chatkit does all the heavy lifting. For free, we get message retention, stability, and with a few adaptions, we could easily add read receipts, typing indicators, and more. Read more about Chatkit in our documentation.

The source code to the article is available on GitHub.

Clone the project repository
  • JavaScript
  • Node.js
  • jQuery
  • HTML
  • Chat
  • Chatkit


  • Channels
  • Chatkit
  • Beams

© 2020 Pusher Ltd. All rights reserved.

Pusher Limited is a company registered in England and Wales (No. 07489873) whose registered office is at 160 Old Street, London, EC1V 9BW.