API Reference

Below are the API methods of the Web SDK.

Web SDK API Methods Overview

The Web SDK's API methods are listed below.

const ujet = new UJET({
  // check options in bellow documentation
  companyId: '',
  // ...
})

Options

Here is all the options that you can pass to new UJET.

companyId

Required

Get companyId from the Admin portal:

  1. Sign in to the Admin Portal with an admin account.

  2. Go to Settings > Developer settings

  3. Copy Company Key

    new UJET({ companyId: '{​{ COMPANY KEY }​}', })

tenant

Recommended

Tenant is the subdomain of your Admin portal, also known as your Environment. For example:

  1. Your CCAI Platform portal is https://acme.example.com/

  2. Then acme is the tenant

    new UJET({ companyId: '....', tenant: 'acme', })

host

Optional

host is the API endpoint that is used by Web SDK. If you have set tenant, there is no need to set host.

new UJET({
  companyId: '....',
  host: 'https://acme.api.example.com',
})

If you have set tenant, and not host, Web SDK will configure host value according to tenant:

https://{tenant}.api.example.com

authenticate

Optional

authenticate is a function which returns a JWT token with promise.

new UJET({
  // ...
  authenticate: getAuthToken,
})

function getAuthToken () {
  return fetch('/ujet/token').then(function(resp) {
    return resp.json()
  })
}

Authentication is Required in Web SDK, but this option is optional. We can call ujet.authenticate later in created event:

var ujet = new UJET({ ... })
ujet.on('created', function() {
  getAuthToken().then({ token } => {
    ujet.authenticate({ token })
  })
})

lang

Optional

The default language for the consumer:

new UJET({
  // ...
  lang: 'ja',
})

user

Optional

new UJET({
  companyId: '....',
  user: {
    identifier: '...',
    name: '...',
    email: '...',
  },
})

launcher

Optional

launcher option can be false or an object. Available options in launcher option:

right: string,
bottom: string,
cssText: string,
chatIcon: url,
closeIcon: url,
style: {
  '--background-color': color,
  '--icon-color': color,
}

To disable CCAI Platform default launcher, you can set this option to false:

const ujet = new UJET({
  companyId: '...',
  launcher: false,
})

// use your own button: `<button id="start-chat">Chat with Me</button>`
document.querySelector('#start-chat').addEventListener('click', function() {
  ujet.open()
})

Or, you can customize our built-in launcher:

new UJET({
  companyId: '...',
  launcher: {
    // cssText: 'body{color:red}',
    // chatIcon: 'https://example.com/logo.svg',
    // closeIcon: 'https://example.com/static/close.svg',
    // right: '50px',
    // bottom: '50px',
    style: {
      '--icon-color': '#FFF',
      '--background-color': '#F1684A',
    }
  },
})

logo

Recommended

Your company's logo URL:

new UJET({
  logo: 'https://example.com/logo.svg',
})

style

Optional

Use style option to customize Web SDK widget:

new UJET({
  // ...
  style: {
    // links: ['https://example.com/font.css'],

    '--primary-font': '',
    '--primary-color': '',
    '--link-color': '',
    '--logo-shadow': '',
  }
})

For style.links, contact Support to enable.

customData

Optional

Custom data can be sent together with a chat when it is started:

new UJET({
  // ...
  customData: {
    version: {
      label: 'Version',
      value: '1.1.0'
    },
    platform: {
      label: 'Platform',
      value: navigator.platform
    }
  }
})

disableAttachment

Optional

If set disableAttachment: true, the CCAI Platform Web SDK will not allow the consumer to upload photos, videos and other attachments in chats.

new UJET({
  companyId: '....',
  disableAttachment: true,
})

right

Optional

Position "right" of the widget, NOT the launcher. You need to adjust this value according to launcher.right.

new UJET({
  right: '50px',
})

bottom

Optional

Position "bottom" of the widget, NOT the launcher. You need to adjust this value according to launcher.bottom.

new UJET({
  bottom: '150px',
})

translation

Optional

Customize Web SDK built-in language translations:

new UJET({
  translation: {
    "en": {
      "ujet_start_title": "English!",
      "ujet_greeting": "Hi there!"
    },
    "es": {
      "ujet_start_title": "¡Español!",
      "ujet_greeting": "¡Hola!"
    },
    "fr": {
      "ujet_start_title": "Français!",
      "ujet_greeting": "Salut!"
    },
    "de": {
      "ujet_start_title": "Deutsche!",
      "ujet_greeting": "Hallo!"
    },
    "ja": {
      "ujet_start_title": "日本語！",
      "ujet_greeting": "こんにちは！"
    }
  }
})

Methods

Here is the methods of UJET instance:

.on(event, callback)

Run the callback when receives the given event:

ujet.on('ready', function() {
  console.log('widget is ready')
})

Find all events in events documentation.

.off(event, callback)

Remove the given callback from event listeners.

function ready() {
  console.log('widget is ready')
}

ujet.on('ready', ready)
ujet.off('ready', ready)

.authenticate(authData)

Send token value to the widget. This method is usually called in created event:

ujet.on('created', function() {
  fetchToken().then(function(token) {
    ujet.authenticate({ token: token })
  })
})

.authenticate(authFunction)

You can also pass a function to .authenticate method, this function should return a promise of the token:

ujet.on('created', function() {
  ujet.authenticate(function(callback) {
    return fetchToken().then(function(token) {
      return { token: token }
    })
  })
})

.start({ menuKey, ticketId })

The widget will be started when the consumer clicks the launcher, but it can also be started with code:

// if end user stayed in the web page for 10 senconds
setTimeout(function() {
  ujet.start({ menuKey: 'help' })
}, 10000)

If .start with a menuKey, the widget will go to that queue directly.

.open()

.open is similar with .start, but it will not accept any parameters.

setTimeout(function() {
  ujet.open()
}, 10000)

.close()

Minimize the widget programmatically:

ujet.on('chat:status', function(status) {
  if (status === 'timeout') {
    ujet.close()
  })
})

.destroy()

Destroy the whole Web SDK, remove it from current webpage.

.registerHook(event, fn)

The event in .registerHook is different with the one in .on. This function is usually used when you want to use your own launcher:

// <button id="launcher">Click to open</button>

const ujet = new UJET({
  // ...
  launcher: false,
})


const launcher = document.getElementById('launcher')
launcher.addEventListener('click', function() {
  if (ujet.status === 'open') {
    ujet.close()
  } else {
    ujet.open()
  }
});

ujet.registerHook('loading', function () {
  launcher.textContent = 'loading'
})

ujet.registerHook('open', function () {
  launcher.textContent = 'Click to close'
})

ujet.registerHook('close', function () {
  launcher.textContent = 'Click to open'
})

Translation

Here is a full list of available keys for customizing translation.

ujet_start_title
ujet_greeting