Working with the ChatBox

The previous docs have outlined the core functionality of the Natterly chatbox and how to get it setup on your website. Anyone should be able to follow along with these docs and get Natterly set up on their site.

The advanced options below however, are for web developers who want to get the maximum amount of flexibility out of their Natterly chatbox.

Working with your new chatbox

The Natterly chatbox is just made up of simple DOM nodes, like anything else on your page. There are no iframes involved, and this gives you as the site developer a lot of freedom to manipulate the chatbox as you see fit.

For example, if you need to hide the chatbox all you need is some simple JavaScript:

// By default the ID of the root node is `natterlyRootNode`
// if you have embedded the chatbox into your own container then that container will be your root node.
var chatboxRootNode = document.getElementById('natterlyRootNode');
// Hide the chatbox
chatboxRootNode.style.display = 'none';
// Show the chatbox
chatboxRootNode.style.display = 'block';

Anything you can do to a normal DOM node, you can do with your Natterly chatbox.

Opening the Chatbox via JS

Sometimes you might want to have a link on your page that when clicked, will open the Natterly Chatbox. All you need to do to get this functionality is call the chatbox.open() function.

// this will open the chatbox
chatbox.open();

// you can pass in an optional callback to handle errors

chatbox.open(function(err) {
  if (err) {
    // there was an error, either the chatbox was already open,
    // or there are no available agents. `err` is an array of errors
    console.log(err);
  } else {
    // The chatbox was opened successfully
  }
}

Hooking into client events

The Natterly chatbox works by receiving events sent down a websocket connection. If there is custom logic that you wish to run on certain events, then you can hook into this system and provide your own event callbacks.

For example, perhaps you want to show a dialog after a chat is closed, in order for the customer to leave feedback relating to their chat. To do this, you could hook into the ChatClosed event.

chatbox.client.on('ChatClosed', function(data) {
  // Your logic for handling the `ChatClosed` event
  // `data` will contain data relating to the closed chat
});

Removing an event callback

You may also want to remove an event callback. This is easily achieved, you just have to pass the appropriate callback and the event name to chatbox.client.off():

var chatClosedCallback = function() { /*...*/ };
// add the event listener
chatbox.client.on('ChatClosed', chatClosedCallback);
// remove the event listener
chatbox.client.off('ChatClosed', chatClosedCallback);

List of useful client events

Below are a list of useful events that you can add event listeners to. Note that there are additional events, but these are to primarily be used internally by Natterly and as such are subject to change.

  • "Welcome" - Fired when the chatbox is first connected to the websocket.
  • "SessionJoined" - Fired when a Natterly session is joined, this is a useful event to listen to in order to confirm that Natterly has loaded and connected.
  • "Message" - Fired when a new message is received, either from the visitor or from an agent.
  • "ChatInitiated" - Fired when a new chat is initiated, either by the visitor or by an agent.
  • "ChatAssigned" - Fired when a chat is assigned an agent.
  • "ChatClosed" - Fired when a chat is closed.

Checking the state of the chatbox

To check if your site has agents available to chat you can use the chatbox.available boolean.

To check if your site is connected to the websocket you can use the chatbox.connected boolean.

Car left 1 Car left 2 Car left 3 Car left 4 Car right 1 Car right 2 Car right 3
Windmill Windmill Windmill