NAV Navbar
Javascript Command queue
  • Overview
  • Configuration
  • Methods
  • Events
  • API interfaces
  • Visitor data integrity
  • Feedback
  • REST API
  • Overview

    Scroll down for code samples. Select a language from the tabs above or the mobile navigation menu.

    Do you want to have more control over chat widget or want to integrate Chaport closely with your user base? This documentation is what you need. It covers currently available methods, our concerns and more.

    Email: JS API Help

    Installation code looks like this:

    (function(w,d,v3){
    w.chaportConfig = { appId : '<insertYourId>' };
    
    if(w.chaport)return;v3=w.chaport={};v3._q=[];v3._l={};v3.q=function(){v3._q.push(arguments)};v3.on=function(e,fn){if(!v3._l[e])v3._l[e]=[];v3._l[e].push(fn)};var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://app.chaport.com/javascripts/insert.js';var ss=d.getElementsByTagName('script')[0];ss.parentNode.insertBefore(s,ss)})(window, document);
    

    Configuration

    You can pass any of the options below in your installation code.

    appId

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb'
    }
    

    Required, this option is by default included in the installation code, that you can retrieve at "Settings -> Installation code", and it shouldn't be modified.

    appearance

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      appearance: {
        windowColor: "#a077bc",
        teamName: "My test team",
        onlineWelcome: "Hello, we are online!",
        offlineWelcome: "We are not online.",
        position: ["left", 20, 20],
        textStatuses: true
      }
    }
    

    Optional. Allows overriding your account-wide appearance settings on a per-page/per-site basis.

    Type: object

    Property Type Notes
    windowColor string Hex color representation or one of ['dark-gray', 'gray', 'blue-gray', 'red', 'pink', 'purple', 'blue', 'light-blue', 'teal', 'green', 'orange' ]
    teamName string Team name in the widget header
    onlineWelcome string Online welcome in the widget header
    offlineWelcome string Offline welcome in the widget header
    position array Array with up to 3 elements. The first element is a string of either "left" or "right" (left bottom or right bottom position), second and third elements are optional X- and Y-offsets from the closest corner.
    textStatuses boolean Whether the widget should display Unread/Read/Sending in the form of text or checkmarks.

    devices

    // default root config
    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      devices: {
        exclude: [ 'ios' ],
        configs: {
          mobile: {
            // mobile config override
            // change chat launcher position
            appearance: {
              position: [ 'right', 0, 50 ]
            }
          }
        }
      },
      appearance: {
        position: [ 'right', 0, 0 ]
      }
    }
    

    Optional. Allows providing device-specific configuration options and allows hiding the widget on particular devices.

    Type: object

    Property Type Notes
    exclude array Array of devices that shouldn't display the widget.
    include array Array of devices that should display the widget. Ignored if exclude is specified.
    configs object Device type specific config overrides

    List of supported devices is: desktop, ios, android, mobile (matches both ios and android).

    language

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      language: {
        source: "html"
      }
    }
    

    Optional. Gives control over the language of the widget interface.

    Type: object

    Property Type Notes
    use string Specify a 2-letter language code that you want to use (e.g. "en", "es", etc)
    source string Can be either "html" or "header" (default).

    If source is "html", preferred language is taken from lang attribute of html tag element (reference).

    If source is "header", preferred language is chosen based on Accept-language HTTP header.

    source is ignored if use is specified.

    launcher

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      launcher: {
        show: false
      }
    }
    

    Optional. Allows changing the launcher.

    Type: object

    Property Type Notes
    show boolean Pass false to hide the default launcher.

    openIn

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      openIn: "_blank"
    }
    

    Optional. Specify to open the widget in a separate window, tab or iframe by default. Should be the name of a target window (_self, _blank, etc.).

    Type: string

    visitor

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      visitor: {
        name: "Jon Snow",
        email: "[email protected]",
        wightsKillCount: "Over 9000"
      }
    }
    

    Optional. You can use this key to pass your visitor's data during initialization.

    Type: object

    Property Type Notes
    name string full name of the visitor
    email string visitor's email
    phone string visitor's phone number
    notes string notes on the visitor
    other string any other field is treated as a custom field and allowed for both creates and updates

    API restricts custom field keys to Latin word characters (a-z, 0-9 and underscore), values must be of one of the following types [ string, number, boolean].

    name, email, phone and notes are create-only unless visitor data is supplemented with a hash.

    visitorIntegrityHash

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      visitor: {
        name: "Jon Snow",
        email: "[email protected]",
        wightsKillCount: "Over 9000"
      },
      visitorIntegrityHash: 'abc123a1b2c3d4e5f6'
    }
    

    Optional. Pass the hash to verify the visitor data integrity.

    Type: string

    Methods

    close

    window.chaport.on('ready', function () {
      window.chaport.close();
    })
    
    window.chaport.q('close');
    

    Collapses the chat widget.

    hideLauncher

    window.chaport.on('ready', function () {
      window.chaport.hideLauncher();
    })
    
    window.chaport.q('hideLauncher');
    

    Hide the default launcher.

    isOnline

    window.chaport.on('ready', function () {
      window.chaport.isOnline(function (isOnline) {
        console.log(isOnline ? 'Operators are online' : 'Operators are offline');
      });
    })
    
    window.chaport.q('isOnline', [ function (isOnline) {
      console.log(isOnline ? 'Operators are online' : 'Operators are offline');
    } ]);
    

    Calls your callback with a boolean value based on whether any of the operators are online or not.

    newPageView

    You can pass page details

    window.chaport.on('ready', function () {
      window.chaport.newPageView({
        url: "http://example.com/page2",
        title: "My test page"
      });
    })
    
    window.chaport.q('newPageView', [ {
      url: "http://example.com/page2",
      title: "My test page"
    } ]);
    

    Alternatively, current URL and document title are used as page URL and title if omitted.

    window.chaport.on('ready', function () {
      window.chaport.newPageView();
    })
    
    window.chaport.q('newPageView');
    

    Tells the widget that visitor opened a new page of a single page application.

    open

    window.chaport.on('ready', function () {
      window.chaport.open();
    })
    
    window.chaport.q('open');
    

    Expands the chat widget.

    openIn

    window.chaport.on('ready', function () {
      window.chaport.openIn("chat-iframe");
    })
    
    window.chaport.q('openIn', [ 'chat-iframe' ]);
    

    Opens the chat in a specified window.

    showLauncher

    window.chaport.on('ready', function () {
      window.chaport.showLauncher();
    })
    
    window.chaport.q('showLauncher');
    

    Show the default launcher.

    setVisitorData

    window.chaport.on('ready', function () {
      window.chaport.setVisitorData({
        email:   "[email protected]",
        name:    "Jon Snow",
        noSrsly: "JSon now" // custom field
      }, 'a1b2c3d4e5f6');
    })
    
    window.chaport.q('setVisitorData', [ {
      email:   "[email protected]",
      name:    "Jon Snow",
      noSrsly: "JSon now" // custom field
    }, 'a1b2c3d4e5f6' ]);
    

    Sends visitor's data to the server. It accepts the following arguments:

    Argument Description
    data visitor's data object (same as visitor configuration option)
    hash optional argument, pass to verify data integrity

    toggle

    window.chaport.on('ready', function () {
      window.chaport.toggle();
    })
    
    window.chaport.q('toggle');
    

    Toggles between expanded and collapsed states. If the widget is in neither (e.g. displays a message), it be expand. This method mimics the behavior of a click on the chat button.

    Events

    ready

    window.chaport.on('ready', listener)
    
    window.chaport.q('on', [ 'ready', listener ]);
    

    Fires right after the javascript API becomes available for use before the widget is rendered.

    chat.onlineChange

    window.chaport.on('chat.onlineChange', listener)
    
    window.chaport.q('on', [ 'chat.onlineChange', listener ]);
    

    Fires when operators' presence online status changes.

    chat.started

    window.chaport.on('chat.started', listener)
    
    window.chaport.q('on', [ 'chat.started', listener ]);
    

    Fires when the visitor starts a chat (i.e., it is not influenced by auto-invitations).

    widget.stateChange

    window.chaport.on('widget.stateChange', listener)
    
    window.chaport.q('on', [ 'widget.stateChange', listener ]);
    

    Fires every time the widget changes the visual state. Possible states are: "expanded", "collapsed", "semiExpanded" (auto-invitation is displayed on desktop), "unreadMessage" (any other unread message - smaller version).

    API interfaces

    This section covers ways you can interact with the JS API. Use the bar in the top right corner to switch between traditional javascript and command queue examples.

    Traditional

    This is what a basic traditional usage might look like:

    var cpt = window.chaport;
    cpt.on('ready', function () {
      cpt.setVisitorData({
        everyThingIsOptional: "Something important"
      });
      cpt.open();
    });
    

    Traditional API interface is the interface provided by a vast majority of solutions throughout the internet. You call API methods by calling a co-named method on an exposed object (in our case it's window.chaport). Same goes for properties (if we happen to add some in future). Event handlers are also operated using conventional methods on, off and once. For now, we've only added the on, however, should the need arise we will add off and once too.

    Command Queue

    This is how a basic command queue usage might look like:

    var cpt = window.chaport.q;
    cpt('setVisitorData', [ {
      everyThingIsOptional: "Something important"
    } ]);
    
    cpt('open');
    

    Another interface commonly referred to as Command queue is most famously implemented by Google Analytics. It has both pros and cons.

    pros:

    cons:

    Visitor data integrity

    How it works

    Generate hash on your server (example using PHP for simplicity)

    $hash = sha1($yourSalt . json_encode($visitorData));
    

    Pass the hash along with the data

    window.chaportConfig = {
      appId: '56e9162264e94eb633a095fb',
      visitor: <? echo json_encode($visitorData) ?>,
      visitorIntegrityHash: '<? echo $hash ?>'
    }
    

    To protect yourselves from your visitors forging their data via the JS API, you can use visitorIntegrityHash. The hash should be generated on your server using personal salt string, which you can request by sending an email to [email protected]

    Without the hash, name, email, phone and notes fields are create-only (i.e., they will only be saved if there is currently no value stored for that particular field).

    It is recommended to use the hash.

    Transition to using the hash

    Below are recommended steps you need to take to start using the hash and ensure the data integrity as painless as possible:

    1. Make sure that the visitor's data is passed correctly before requesting the personal salt or passing any hash along.

    2. Request personal salt via an email to [email protected]

    3. Initially, the hash is made optional, and the JS API at this point still allows you to pass data without passing any hash, albeit with named limitations.

    4. Generate and pass the hash. Make sure that any passed data is still properly saved. Important: always generate the hash on your server and never include the personal salt in html/javascript sent to a browser.

    5. Send us a request to make hash required on your account. After the request is processed, visitors will no longer be able to send any forged data using the browser console.

    Feedback

    What methods/events you need

    Let us know what event or method you are missing!

    Your use cases

    We are looking to hearing from you about your use cases!

    REST API

    REST API Overview

    Do you want to integrate your backend with Chaport to get visitors' data, chat transcripts and more? Read REST API docs.