Chat box Settings
Visitor
Events

Javascript API

Our documentation to help you customize our chat box

Getting started

With the Pure Chat Javascript API, you can manipulate your chat box and better integrate with your website in a number of ways. In order to use the Pure Chat Javascript API, ensure that you have the latest chat box snippet installed on your site. The latest snippet is available from your chat box's installation page (go to "Customize Chat Box" and click "Install").

All interaction with the Pure Chat Javascript API is handled through an API object that is written to the window when your Pure Chat snippet has loaded. This object will persist on your page, unless it is manually deleted.

If you encounter any issues with our Javascript API implementation, please contact support@purechat.com.

Settings overview

All settings can be accessed or modified using "dot" syntax, similar to how properties would be accessed or modified on JSON objects. To get a setting, you would make a call to the "get()" function:

                        
                            <script>
                            
     var val = purechatApi.get('chatbox.unavailableBehavior');
</script>

To set a new value for a setting, you would make a call to the "set()" function:

                    
                        <script>
                        
     purechatApi.set('chatbox.unavailableBehavior', 'email');
</script>

If you're familiar with Backbone.JS, you'll notice that the syntax for getting and setting values is very similar. Binding to and unbinding from events (covered in the Events section) also uses Backbone.JS syntax.

NOTE: Getting or setting values with the Pure Chat API cannot be used until after the chatbox:ready event has been fired!

Chat box position

Change the position of the chat box on your website.

                    
                        <script>
                        
purechatApi.on('chatbox:ready', function () {
     // values - 'bottomLeft', 'bottomRight', 'topLeft', and 'topRight'

     // Makes the chatbox become docked to bottom-left side of screen
     purechatApi.set('chatbox.position', 'bottomLeft');
     var position = purechatApi.get('chatbox.position'); // Returns 'bottomLeft'
});
</script>

Start chat fields

Change which fields are required for a visitor to fill out before they can start a chat on your site.

                    
                    <script>
                    
// You can change askForName, askForEmail, askForPhoneNumber, and askForQuestion
// All of these values will take a boolean true / false as its value

purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.askForName', true); // This will enable the "Name" field inside of your chat box
     var askForName = purechatApi.get('chatbox.askForName'); // Returns true

     purechatApi.set('chatbox.askForQuestion', true); // This disabled the "Question" field inside of your chat box
     var askForQuestion = purechatApi.get('chatbox.askForQuestion'); // Returns false });
</script>

Unavailable behavior

Change what happens to your chat box when no one is available to take chats.

                    
                    <script>
                    
// values - 'hide', 'message', and 'email'

purechatApi.on('chatbox:ready', function () {
     var isHideOnUnavailable = purechatApi.get('chatbox.unavailableBehavior') == 'hide';
     if (isHideOnUnavailable) {
          purechatApi.set('chatbox.unavailableBehavior', 'email'); // Show email form instead
     }
});
</script>

Available / unavailable images

Change the image that is displayed when the chat box is collapsed. This is based on operator availability for the chat box.

                    
                    <script>
                    
// values - valid URL to an image

purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.availableCollapsedImageUrl', 'https://cdnca1.purechat.com/beta/Files/Download/bd2a28e9-fa83-41e6-b0c0-37cc759ff242.png'); // Sets the image when somebody is available

     purechatApi.set('chatbox.unavailableCollapsedImageUrl', 'https://cdnca1.purechat.com/beta/Files/Download/8cf083f0-4da3-4e2e-aa08-f0c1ee11322f.png'); // Sets the image when somebody is unavailable });
</script>

You can also choose to use the available image for the unavailable state.

                    
                    <script>
                    
// values - true / false

purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.useAvailableImageForBoth', true);
});
</script>

Chat box image properties

There are a number of properties that can affect the size and orientation of the chat box image. Changing any of these will cause the chat box to redraw its collapsed image with the new properties (if it is visible).

                    
                    <script>
                    
// values - integer

purechatApi.on('chatbox:ready', function () {

     // All of theses properties are also available for the unavailableImage by replacing "availableImage" with "unavailableImage"

     purechatApi.set('chatbox.availableImageXOffset', 10); // Changes the image's X offset position (use 0 for center)
     purechatApi.set('chatbox.availableImageYOffset', 40); // Changes the image's Y offset position (use 0 for center)
     purechatApi.set('chatbox.availableImageScale', 90); // Changes the image's scale (limited to values 0 - 100)
});
</script>

You can also change whether or not the collapsed image is displayed above or below the chat box tab itself.

                    
                        <script>
// values - true / false
purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.availableImageOnTop', false); // Makes the image appear behind the chat box if the two overlap
});
</script>

Minimize chat box button

Change whether to show the "minimize" button (button with down caret). This button makes the widget slide slightly off the page so that it uses less screen space.

                    
                    <script>
                    
// values - true / false

purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.showMinimizeButton', false); // Hides the minimize button
});
</script>

Closed chat options

Change whether to present your visitors with a download link to the transcript when the chat ends, or whether to allow your visitors to rate the chat when it has ended.

                    
                    <script>
                    

// values - true / false
purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.enableTranscriptDownload', false); // Disables transcript download link when chat ends
     purechatApi.set('chatbox.askForRating', true); // Enables end of chat smiley face ratings
});
</script>

Expand / collapse chat box

Change whether the chat box is currently expanded or collapsed.

                    
                    <script>
                    

// values - true / false
purechatApi.on('chatbox:ready', function () {
     purechatApi.set('chatbox.expanded', true); // Expanded the chat box (false collapses it)
});
</script>

Visitor Details

Change any of the contact information that is collected about the visitor. Setting visitor information will override any previous data.

                    
                    <script>
                    

// values - string
purechatApi.on('chatbox:ready', function () {
     purechatApi.set('visitor.name', 'Joe'); // Sets the visitor name to "Joe"
     purechatApi.set('visitor.email', 'joe@joesmarket.com'); // Sets the visitor's email address to "joe@joesmarket.com"
     purechatApi.set('visitor.phoneNumber', '6025551234'); // Sets the visitor's phone number "6025551234"
     purechatApi.set('visitor.question', 'I need some help with an order I have already made'); // Sets the visitor's question to "I need some help with an order I have already made"
});
</script>

Chat box ready

Fired whenever the chat box has been rendered and appended to the DOM.

                    
                    <script>
                    
purechatApi.on('chatbox:ready', function (args) {
     // Do any of your manipulation to settings here!
     console.log(args.chatboxId); // Prints the ID of the chatbox to the console window
});
</script>

Operator availability change

Fired whenever an operator comes online and is available to take a chat, or whenever all operators go offline for a chat box.

                    
                    <script>
                    
purechatApi.on('chatbox.available:change', function (args) {
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.available) // Prints true if available, false if unavailable
});
</script>

Operator join / leave chat

Fired whenever an operator joins or leaves the chat with the visitor.

                    
                    <script>
                    
purechatApi.on('chat:operatorJoin', function (args) {
     console.log('An operator joined the chat!');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.operatorName) // Prints the name of the operator that joined
});
</script>

                    
                    <script>
                    
purechatApi.on('chat:operatorLeave', function (args) {
     console.log('An operator left the chat :()');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.operatorName) // Prints the name of the operator that left the chat
});
</script>

Chat start / end / rate

Fired whenever a visitor starts a chat, a visitor's chat ends, or a visitor rates a chat that was just completed.

                    
                    <script>
                    
// Chat start
purechatApi.on('chat:start', function (args) {
     console.log('Visitor started a new chat!');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.name) // Prints the name of the visitor that started the chat
     console.log(args.email) // Prints the email of the visitor that started the chat
     console.log(args.phoneNumber) // Prints the email address of the visitor that started the chat
     console.log(args.question) // Prints the question the visitor entered when he / she started the chat
});
</script>

                    
                    <script>
                    
// Chat end
purechatApi.on('chat:end', function (args) {
     console.log("Visitor's chat has ended :(");
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.name) // Prints the name of the visitor that started the chat
     console.log(args.email) // Prints the email of the visitor that started the chat
     console.log(args.phoneNumber) // Prints the email address of the visitor that started the chat
     console.log(args.question) // Prints the question the visitor entered when he / she started the chat
});
</script>

                    
                    <script>
                    
// Chat rate
purechatApi.on('chat:rate', function (args) {
     console.log("Visitor has rated the chat");
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.rating == 1 ? ':)' : ':(') // Prints a smiley face if the visitor rated the chat positively, or frowney face if negative
});
</script>

Chat box minimize / collapse / expand / popout

Fired whenever the visitor expands, collapses, or minimizes the chat box. An event will also fire when the visitor pops the chat into a new window.

                    
                    <script>
                    
// Chat box minimize (slide out of the way)
purechatApi.on('chatbox:minimize', function (args) {
     console.log('Chatbox was minimized');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>

                    
                    <script>
                    
// Chat box collapse
purechatApi.on('chatbox:collapse', function (args) {
     console.log('Chatbox was collapsed');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>

                    
                    <script>
                    
// Chat box expand
purechatApi.on('chatbox:expand', function (args) {
     console.log('Chatbox was expanded!');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>

                    
                    <script>
                    
// Chat box popped-out into new window
purechatApi.on('chatbox:poppedOut', function (args) {
     console.log('Chatbox was popped out into a new window.');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>

Visitor details change

Fired whenever any of the visitor's details have changed. This can occur programmatically, or an operator can change the details during the chat.

You can listen to a change event on a specific property, or a general change event for all visitor details.

                    
                    <script>
                    
// Listen to a change event on a specific property
purechatApi.on('visitor.name:change', function (args) {
     console.log("Visitor's name was changed");
     console.log(args.name) // Prints the new visitor name
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});

purechatApi.on('visitor.email:change', function (args) {
     console.log("Visitor's email address was changed");
     console.log(args.email) // Prints the new visitor email address
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});

purechatApi.on('visitor.phoneNumber:change', function (args) {
     console.log("Visitor's phoneNumber was changed");
     console.log(args.phoneNumber) // Prints the new visitor phone number
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});

purechatApi.on('visitor.question:change', function (args) {
     console.log("Visitor's question was changed");
     console.log(args.question) // Prints the updated visitor question
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>

                    
                    <script>
                    
// Any visitor detail has changed
purechatApi.on('chat:change', function (args) {
     console.log("Some visitor detail has changed");
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.name) // Prints the visitor's name
     console.log(args.email) // Prints the visitor's email address
     console.log(args.phoneNumber) // Prints the visitor's phone number
     console.log(args.question) // Prints the visitor's question
});
</script>

Unavailable email send

Fired whenever a visitor sends an email from the chat box when no operators are available.

                    
                    <script>
                    
purechatApi.on('email:send', function (args) {
     console.log('An email was sent while you were unavailable');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
     console.log(args.name) // Prints the visitor's name
     console.log(args.email) // Prints the visitor's email address
     console.log(args.phoneNumber) // Prints the visitor's phone number
     console.log(args.question) // Prints the visitor's question
});
</script>

Chat box resize

Fired whenever the chat box has been resized.

                    
                    <script>
                    
purechatApi.on('chatbox:resize', function (args) {
     console.log('Chat box was resized');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>

Chat box restart

Fired whenever a visitor restarts the chat box after a closed chat.

                    
                    <script>
                    
purechatApi.on('chatbox:restart', function (args) {
     console.log('Chat box was restarted by the visitor');
     console.log(args.chatboxId) // Prints the ID of the chatbox to the console window
});
</script>