@livechat/customer-sdk

SDK for connecting to LiveChat as a customer

Usage no npm install needed!

<script type="module">
  import livechatCustomerSdk from 'https://cdn.skypack.dev/@livechat/customer-sdk';
</script>

README

Introduction

LiveChat Customer SDK is a set of tools that helps you build a custom chat widget. Under the hood, it makes use of the LiveChat Customer Chat API. Customer SDK lets you communicate with LiveChat services directly from the browser environment using JavaScript without the need to develop your backend.

Is it for me?

If you need to customize the LiveChat Widget, using LiveChat Customer SDK is one of the options to do this. If you need a fully customizable solution and you feel brave, dive into LiveChat Customer SDK. We provide methods and events for deep integration with the LiveChat environment.

Keep in mind that interacting with this API requires some development skills.

Customer SDK allows you to create frontend apps, so if you're looking for server-side solutions, you should explore the LiveChat Customer Chat API instead. If you want to dive deeper into the LiveChat Platform, you might find the Platform Overview article handy.

About LiveChat Customer SDK

We provide an asynchronous API. Most methods return a Promise. You can subscribe to the emitted events with the on and off methods. Not familiar with promises? Read this article to learn more.

We authenticate your sessions with the use of customer-auth package and expose the created auth object to the returned SDK instance. In general, you don't have to worry about it or use the exposed object. If you need to get the authentication token, you can get it through the SDK like this:

customerSDK.auth.getToken().then(token => {
  console.log(token)
})

Questions

If you have any questions, you can start a chat with our 24/7 Support.

How to start

This tutorial is here to help you get started with LiveChat Customer SDK.

Create an application

First, you need to create an application in Developer Console (select the Web app (frontend, e.g. JavaScript) type). Then, you will have to give it the access to the customers:own scope and the correct URI to the Redirect URI whitelist.

Install Customer SDK

You can use the LiveChat Customer SDK in two different ways:

Using npm

npm install --save @livechat/customer-sdk

Import the SDK in your code:

import * as CustomerSDK from '@livechat/customer-sdk'

Or use the node-style require call:

const CustomerSDK = require('@livechat/customer-sdk')

Using a script tag - UMD module hosted on unpkg's CDN

<script src="https://unpkg.com/@livechat/customer-sdk@3.1.0"></script>

If you just want to look around and play with the SDK, check out our sample chat widget implementation.

For the time being you need to register your application in the Developers Console as a "Web app (frontend, eg. JavaScript)" type. Then, you have to pass the configured redirectUri to the init, along with the regular required properties (licenseId and clientId).

Using the API

To use the API you will first need to create an instance using the init function. You will need to provide your licenseId and clientId when creating a Customer SDK instance.

Other optional configuration parameters are also available:

parameters type default description
licenseId number Your license number, you receive this value when creating a new livechat account.
clientId string Your client id, you receive this value when you register your application in the LiveChat Developer Console.
autoConnect boolean true Optional; should the library try to reconnect on it's own.
groupId number 0 Optional; the id of the group you wish to connect to.
region 'dal' | 'fra' 'dal' Optional; the server region your license is at.
redirectUri string Optional; should only be used inside ReactNative, this is the URI which your webview is redirected to after authorization.
customerDataProvider () => CustomerData Optional; should only be used if you need to send customer data during login. In general, updateCustomer() should be prefered for sending customer data.
identityProvider () => CustomerAuth Optional; allows for providing own instance of the CustomerAuth object which contains the customer access token handlers. See Custom Identity Provider for more information.

CustomerData:

parameters type description
name string Optional
email string Optional
sessionFields object Key: value pairs

CustomerAuth:

parameters type description
getFreshToken () => Promise Should resolve with freshly requested customer access token.
getToken () => Promise Should resolve with currently stored customer access token.
hasToken () => Promise Should resolve with a boolean value representing if a token has been already acquired.
invalidate () => Promise Should handle token invalidation and/or clearing the locally cached value.

The init function will return a Customer SDK instance:

const customerSDK = CustomerSDK.init({
  licenseId: LICENSE_ID,
  clientId: CLIENT_ID,
})

With customerSDK, you can attach events:

customerSDK.on('new_event', newEvent => {
  console.log(newEvent)
})

Or execute methods:

const chatId = 'OU0V0P0OWT'
customerSDK
  .sendEvent({
    chatId,
    event: {
      type: 'message',
      text: 'Hi!',
    },
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Using the API in React Native

If you want to use LiveChat Customer SDK in React Native, keep in mind that we use cookies to authenticate your sessions, so we need some sort of browser environment for that. We've prepared a special wrapper for you to use in React Native. It opens a WebView component to get an authentication token. All you have to do is import it from our authentication package (no need to install it - the SDK depends on it, so you already have it) and mount it in your React Native application:

import { AuthWebView } from '@livechat/customer-auth'
import { init } from '@livechat/customer-sdk'

export default class App extends React.Component {
  customerSDK = null

  componentDidMount() {
    this.customerSDK = init({
      licenseId: LICENSE_ID,
      clientId: CLIENT_ID,
      redirectUri: REDIRECT_URI,
    })
    // you can start using customerSDK from now
  }

  render() {
    return (
      <View>
        <AuthWebView />
      </View>
    )
  }
}

If you are looking for something simpler, you can use a LiveChat for React Native library. This is a React Native component to easily add the LiveChat Widget with basic functionality to your application.

Key Concepts

The LiveChat system includes four basic types of entities - users, chats, threads, and events.

  • Chats consist of threads and threads consist of events.
  • Threads are parts of chats.
  • Users can add events to chats, which then are automatically added to threads.
  • Users can participate in many chats at the same time.

Threads are a vital part of the LiveChat architecture. Grouping events in threads allows us to provide the continuous chat experience (i.e. the Customer always has the option to continue the conversation) while still maintaining smaller, logical chunks of events (e.g. for reporting and caching purposes). Handling operations such as loading archival events from the chat history can be challenging, but you won't have to worry about managing threads most of the time. Customer SDK provides wrappers for common tasks and most methods expect to receive chat IDs. You will only get notified about thread metadata if you explicitly ask for it.

You can read more about key concepts of the LiveChat messaging in the Messaging Overview.

User

Agent

{
  id: 'ed9d4095-45d6-428d-5093-f8ec7f1f81b9',
  type: 'agent',
  name: 'Jane Doe',
  jobTitle: 'Agent',
  avatar: 'https://cdn.livechat.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a7.png',
}

Customer

{
  id: 'ed9d0195-45d6-428d-5093-f8ec7f1471b9',
  type: 'customer',
  name: 'Jon Doe',
  avatar: 'https://cdn.livechat.com/cloud/?uri=https://livechat.s3.amazonaws.com/default/avatars/a6.png',
  fields: {
    custom_property: 'BasketValue=10usd',
  }
}

Chat

{
  id: 'OU0V0P0OWT',
  users: [{
    id: 'ed9d4095-45d6-428d-5093-f8ec7f1f81b9',
    // ... more user properties
  }],
  lastSeenTimestamps: {
    'ed9d4095-45d6-428d-5093-f8ec7f1f81b9': 1503062591000, // might be null
  },
  threads: ['OU0V0U3IMN'],
}

Event

{
  type: 'message',
  text: 'hi!',
    author: 'ed9d4095-45d6-428d-5093-f8ec7f1f81b9', // assigned by server
  id: 'OU0V0U3IMN_1', // assigned by server
    timestamp: 1503062591000, // assigned by server
    customId: '814.3316641404942', // optional
    thread: 'OU0V4R0OXP',
  properties: {},
}

Threads

{
  id: 'OU0V0U3IMN',
  active: true,
  order: 3,
  users: ['ed9d4095-45d6-428d-5093-f8ec7f1f81b9'],
  lastSeenTimestamps: {
    'ed9d4095-45d6-428d-5093-f8ec7f1f81b9': 1503062591000, // might be null
  },
  events: [ /* events */ ],
}

Methods

acceptGreeting

You can use this method to inform that a Customer has seen a greeting. Based on that, the Reports section displays only the greetings seen by Customers instead of all the sent greetings. If a Customer started a chat from a greeting but you didn't execute acceptGreeting method, the greeting counts as seen in Reports anyway.

As arguments to this method you should use uniqueId & greetingId received in the incoming_greeting or connected event.

customerSDK
  .acceptGreeting({
    greetingId: 7,
    uniqueId: 'Q10X0W041P',
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type
greetingId number
uniqueId string

Errors

  • GREETING_NOT_FOUND - a given uniqueId couldn't be found on the server

cancelGreeting

Cancels a greeting (an invitation to the chat). For example, Customers could cancel greetings by clicking close icon on the displayed greeting.

customerSDK
  .cancelGreeting({
    uniqueId: 'Q10X0W041P',
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type
uniqueId string

Errors

  • GREETING_NOT_FOUND - given uniqueId could not be found on the server

cancelRate

Cancels rate-related thread properties.

customerSDK
  .cancelRate({
    chatId: 'ON0X0R0L67',
    properties: ['score', 'comment'],
  })
  .then(response => {
    console.log(response)
  })
  .catch(() => {
    console.log(error)
  })

Errors

  • MISSING_CHAT_THREAD - the targeted chat is empty and has no threads.

connect

Starts the connection process to our servers. It is needed when:

  • the argument autoConnect: false has been passed to the init method
  • you get disconnected for a reason that suspends reconnection attempts (e.g. inactivity_timeout)

deactivateChat

customerSDK
  .deactivateChat({ id: 'ON0X0R0L67' })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
id string Chat ID in which thread should get closed

Returned value:

properties type
success boolean

deleteChatProperties

Deletes given chat properties.

customerSDK
  .deleteChatProperties({
    id: 'ON0X0R0L67',
    properties: {
      property_namespace: ['sample'],
    },
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
id string ID of the chat whose properties you want to delete.
properties object Chat properties to delete

Returned value:

properties type
success boolean

deleteEventProperties

Deletes given event properties.

customerSDK
  .deleteEventProperties({
    chatId: 'ON0X0R0L67',
    threadId: 'OS0C0W0Z1B',
    eventId: 'Q50W0A0P0Y',
    properties: {
      property_namespace: ['sample'],
    },
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string ID of the chat whose properties you want to delete.
threadId string ID of the thread whose properties you want to delete.
eventId string ID of the event whose properties you want to delete.
properties object Properties to delete

Returned value:

properties type
success boolean

deleteThreadProperties

Deletes given chat thread properties.

customerSDK
  .deleteThreadProperties({
    chatId: 'ON0X0R0L67',
    threadId: 'OS0C0W0Z1B',
    properties: {
      property_namespace: ['sample'],
    },
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string ID of the chat whose properties you want to delete.
threadId string ID of the thread whose properties you want to delete.
properties object Properties to delete

Returned value:

properties type
success boolean

destroy

Clears any stored resources, removes all listeners, and disconnects from the network. After using this method, you won't be able to use the destroyed Customer SDK instance.

customerSDK.destroy()

disconnect

Disconnects from the server.

customerSDK.disconnect()

getChat

Returns the chat data about the requested chat ID together with a single thread's data. If the method is called with the threadId parameter, then this particular thread is being returned. If no threadId is given, the latest thread is automatically returned.

customerSDK
  .getChat({
    chatId: 'ON0X0R0L67',
  })
  .then(chat => {
    const { id, access, users, properties, thread } = chat
    console.log({ id, access, users, properties, thread })
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string
threadId string optional

Returned value:

properties type description
id string Chat ID
access object Chat initial access
users object[] Users objects referenced in the chat
properties object Chat properties
thread object

getChatHistory

Helps loading in historical thread events.

First, call getChatHistory to access the history object of a particular chat. The returned history object has only one method, next, which gives you a Promise with a { done, value } object.

  • done - indicates if there is anything more to load
  • value - an object with an array of threads, each containing an array of its events

Then, you can keep calling history.next() multiple times to load previous historical events. They're going to be grouped into threads and might require merging with already loaded events. This is useful for implementing an infinite scroll or otherwise showing your Customer's archival chats. Keep in mind, though, that you generally shouldn't call next while the history is loading - we queue those requests, so the previous one must resolve before we proceed with the next one.

The structure such as our history object is called an async iterator.

let wholeChatHistoryLoaded = false

const history = customerSDK.getChatHistory({ chatId: 'OU0V0P0OWT' })

history.next().then(result => {
  if (result.done) {
    wholeChatHistoryLoaded = true
  }

  const { threads } = result.value

  const events = threads
    .map(thread => thread.events || [])
    .reduce((acc, current) => acc.concat(current), [])

  console.log(events)
})

Parameters:

parameters type description
chatId string Chat ID of the requested history object

getCustomer

Returns the info about the Customer requesting it.

customerSDK
  .getCustomer()
  .then(customer => {
    console.log(customer)
  })
  .catch(error => {
    console.log(error)
  })

Returned value:

properties type description
type 'customer'
id string
name string Returned only if set
email string Returned only if set
avatar string Returned only if set
sessionFields object
statistics object
statistics.chatsCount number
statistics.threadsCount number
statistics.visitsCount number
statistics.pageViewsCount number
statistics.greetingsShownCount number
statistics.greetingsAcceptedCount number

getForm

Allows you to fetch a form template for a given group and form type.

customerSDK
  .getForm({
    groupId: 0,
    type: 'prechat',
  })
  .then(response => {
    if (response.enabled) {
      // prechat form is enabled for this group in the configurator
      console.log(response.form)
    }
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type
groupId number
type 'prechat', 'postchat' or 'ticket'

Returned value:

properties type description
enabled boolean
form object Available only when a given form is enabled
form.id string
form.fields object[]

getPredictedAgent

customerSDK
  .getPredictedAgent({
    groupId: 0,
  })
  .then(agent => {
    console.log(agent)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
groupId number Optional

Returned value:

properties type description
agent object
agent.id string
agent.name string
agent.jobTitle string
agent.type 'agent'
agent.isBot boolean
queue boolean True when the current group has reached concurrent chat limit

Errors

  • GROUP_OFFLINE - the requested group is offline, and it was not possible to return a predicted Agent for it.
  • GROUP_UNAVAILABLE - thrown when manual routing is enabled for the group and a predicted Agent is requested for it. If you call startChat or resumeChat accordingly, you'll end up in the queue.

getUrlInfo

It returns the info on a given URL.

customerSDK
  .getUrlInfo({ url: 'https://www.livechat.com' })
  .then(urlDetails => {
    if (urlDetails.title) {
      console.log(`The title of requested URL is: ${urlDetails.title}`)
    }
    if (urlDetails.description) {
      console.log(
        `The description of requested URL is: ${urlDetails.description}`,
      )
    }
    if (urlDetails.imageUrl) {
      console.log(
        `The preview image of requested URL is available under: ${urlDetails.imageUrl}`,
      )
      if (urlDetails.imageWidth && urlDetails.imageHeight) {
        console.log(`Its width is: ${urlDetails.imageWidth}`)
        console.log(`Its height is: ${urlDetails.imageHeight}`)
      }
    }
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type
url string

Returned value:

properties type description
url string
title string Optional
description string Optional
imageUrl string Optional
imageWidth number Optional
imageHeight number Optional

off

Unsubscribes from emitted events, which are described here.

on

Subscribes to emitted events, which are described here.

once

Subscribes to emitted events, which are described here. Unsubscribes immediately after the callback gets called.

listChats

It returns summaries of the chats a Customer participated in.

customerSDK
  .listChats({
    pageId: 'MTU5MTEwMTUxNDM5NTk5OTpkZXNj',
    limit: 10,
  })
  .then(({ chatsSummary, totalChats }) => {
    console.log(chatsSummary)
    console.log(totalChats)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
pageId string Optional; the cursor returned from the previous listChats calls
limit number Optional; the limit of returned results. Default is set to 10 and maximum is 25

Returned value:

properties type description
chatsSummary object[]
chatsSummary[].id string Chat ID
chatsSummary[].active boolean
chatsSummary[].users object[] Users objects referenced in the chat
chatsSummary[].lastEvent object Event
chatsSummary[].lastEventsPerType object Map of event types to event objects
chatsSummary[].lastSeenTimestamps object Map of user IDs to optional lastSeenTimestamps
chatsSummary[].lastThread string Thread ID
totalChats number

listGroupStatuses

Returns availability statuses of the requested groups.

customerSDK
  .listGroupStatuses({
    groupIds: [3, 10],
  })
  .then(statusMap => {
    console.log(`Status of the group 3: ${statusMap[3]}`)
    console.log(`Status of the group 10: ${statusMap[10]}`)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
groupsIds number[] Optional; if omitted, statuses of all groups are returned.

Returned value:

properties type description
statusMap object Map of group numbers to availability statuses

listThreads

Returns a list of thread objects together with the previous and next page ID cursors that can be used to load more threads. If you want to load consecutive events, consider using getChatHistory.

customerSDK
  .listThreads({
    chatId: 'ON0X0R0L67',
  })
  .then(response => {
    console.log(response.threads)
    console.log(response.previousPageId)
    console.log(response.nextPageId)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string
pageId string Optional, the cursor returned from the previous listThreads calls
sortOrder 'desc' | 'asc' Optional, default: 'desc'
limit number Optional, default: 3, can't be used together with minEventsCount
minEventsCount number Optional, can't be used together with limit

Returned value:

properties type description
threads object[]
threads[].id string Thread ID
threads[].chatId string Chat ID
threads[].active boolean Active state
threads[].createdAt string Thread creation date in RFC 3339 date-time format
threads[].userIds string[] User IDs
threads[].events object[] Events
threads[].properties object Chat properties
threads[].access object
threads[].queue object Optional
threads[].queue.position number Current position in the queue
threads[].queue.waitTime number Estimated waiting time for an agent to be assigned to the chat, in seconds
threads[].queue.queuedAt string RFC 3339 date-time format
previousPageId string
nextPageId string

markEventsAsSeen

Marks events as seen by the current Customer up to the given date.

customerSDK
  .markEventsAsSeen({
    chatId: 'ON0X0R0L67',
    seenUpTo: '2017-10-12T15:19:21.010200Z',
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string ID of the chat in which you want to mark events as seen.
seenUpTo string RFC 3339 date-time format; you should use the event's createdAt value as the argument.

Returned value:

properties type
success boolean

rateChat

Sends chat rating and a comment for the most recent chat thread.

customerSDK
  .rateChat({
    chatId: 'ON0X0R0L67',
    rating: {
      score: 1,
      comment: 'Agent helped me a lot!',
    },
  })
  .then(() => {
    console.log('Rating has been set')
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId Destination chat ID
rating
rating.score 0 or 1 Rating value: 0 for a bad rating and 1 for a good rating
rating.comment string Optional comment

Returned value:

properties type
success boolean

Errors

  • MISSING_CHAT_THREAD - the targeted chat cannot be rated because it has no threads.

resumeChat

Resumes an archived chat.

customerSDK
  .resumeChat({
    chat: {
      id: 'OU0V0P0OWT',
      thread: {
        events: [],
      },
    },
  })
  .then(chat => {
    console.log(chat)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
data.active boolean Optional; defaults to true but can be used to create threads that are immediately inactive
data.continuous boolean Optional
data.chat.id string
data.chat.access Access Optional
data.chat.properties object Optional, Default properties docs
data.chat.thread.events Event[] Optional; you can pass initial events which will immediately become part of the created thread.
data.chat.thread.properties object Optional, Default properties docs

Errors

  • CHAT_ALREADY_ACTIVE - the chat is already active and you can't activate it again.
  • GROUPS_OFFLINE - a group in the targeted chat is offline. It can happen for licenses without continuous chats enabled.

sendEvent

Sends a provided object as an event with a specified type.

const event = {
  type: 'message',
  // ... other properties specific for the event's type
}

customerSDK
  .sendEvent({
    chatId: 'ON0X0R0L67',
    event,
  })
  .then(event => {
    console.log(event)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string Destination chat ID
event
event.type string Type of the event
attachToLastThread boolean Optional

sendRichMessagePostback

Sends information to the server about a user's interaction with a rich message button.

customerSDK
  .sendRichMessagePostback({
    chatId: 'ON0X0R0L67',
    threadId: 'OS0C0W0Z1B',
    eventId: 'OS0C0W0Z1B01',
    postback: {
      id: 'OS0C0W0Z1B01002',
      toggled: true,
    },
  })
  .then(() => {
    console.log('success')
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type default description
chatId string postback chat ID
threadId string postback thread ID
eventId string postback event ID
postback
postback.id string Postback button ID
postback.toggled boolean true Postback toggled

sendTicketForm

Can be used to send a filled ticket form.

customerSDK
  .sendTicketForm({
    groupId: 10,
    filledForm: {
      type: 'filled_form',
      formId: '',
      fields: [
        {
          type: 'subject',
          id: '0',
          label: 'Subject:',
          answer: 'Order number 123',
        },
        {
          type: 'email',
          id: '1',
          label: 'Your email:',
          answer: 'john.doe@example.com',
        },
        {
          type: 'checkbox',
          id: '2',
          label: 'Question:',
          answers: [
            { id: '0', label: 'First answer' },
            { id: '1', label: 'Second answer' },
          ],
        },
        {
          type: 'textarea',
          id: '3',
          label: 'Your message:',
          answer:
            'Could I get a status update on this order? Have you already shipped it?',
        },
      ],
    },
  })
  .then(response => {
    console.log(`Created a ticket with id: ${response.id}`)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
filledForm.type 'filled_form'
filledForm.formId string
filledForm.fields FilledFormField[]
groupId number Optional
timeZone string Optional, valid IANA Time Zone

Returned value:

properties type description
id string ID of the created ticket

setCustomerSessionFields

Sends the request to set customer's session fields. They are available for the duration of the session.

customerSDK.setCustomerSessionFields({
  sessionFields: {
    foo: 'bar',
    test: 'qwerty',
  },
})

Parameters:

parameters type
sessionFields object

setSneakPeek

You can use it to update the sneak peek in the Agent App. It is sent to the server only if the target chat is active. This method doesn't return a promise.

customerSDK.setSneakPeek({
  chatId: 'ON0X0R0L67',
  sneakPeekText: 'what is the price for your ',
})

Parameters:

parameters type description
chatId string Target chat ID
sneakPeekText string Message preview broadcasted to the Agent

startChat

Starts a new chat. For one Customer, you can only start one chat. In order to activate a previously started chat, use resumeChat.

customerSDK
  .startChat({
    chat: {
      thread: {
        events: [],
      },
    },
  })
  .then(chat => {
    console.log(chat)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
active boolean Optional, defaults to true but can be used to create threads that are immediately inactive
continuous boolean Optional
chat.access access Optional
chat.properties object Optional, Default properties docs
chat.thread.events event[] Optional; initial events that will immediately become a part of the created thread.
chat.thread.properties object Optional, Default properties docs

Errors

  • CHAT_LIMIT_REACHED - the maximum limit of chats per Customer has been reached, and it's not possible to start a new one. You should activate one of the existing chats. The limit is 1.
  • GROUPS_OFFLINE - a group in the target chat is offline. It can happen for licenses, which don't allow Customers to chat during their unavailability.

updateChatProperties

const properties = {
  property_namespace: {
    sample: 'property',
  },
}
customerSDK
  .updateChatProperties({ id: 'ON0X0R0L67', properties })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
id string ID of the chat whose properties you want to update.
properties object Default properties docs

updateCustomer

Updates the specified Customer properties and fields.

const properties = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  sessionFields: {
    custom_property: 'BasketValue=10usd',
    any_key_is_ok: 'sample custom field',
  },
}
customerSDK.updateCustomer(properties)

Parameters:

parameters type description
properties
properties.name string Optional
properties.email string Optional
properties.sessionFields object Optional; custom fields with string values

Errors

  • CUSTOMER_SESSION_FIELDS_LIMIT_REACHED - total amount of session fields would have been exceeded after requested update

updateCustomerPage

Updates information about the Customer page using the provided page object.

const page = {
  url: 'https://developers.livechat.com/',
  title: 'LiveChat for Developers',
}
customerSDK.updateCustomerPage(page)

Parameters:

parameters type
page
page.url string
page.title string

updateEventProperties

Updates given properties of an event.

const properties = {
  property_namespace: {
    sample: 'property',
  },
}
customerSDK
  .updateEventProperties({
    chatId: 'ON0X0R0L67',
    threadId: 'OS0C0W0Z1B',
    eventId: 'Q50W0A0P0Y',
    properties,
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string ID of the chat whose properties you want to update.
threadId string ID of the thread whose properties you want to update.
eventId string ID of the event whose properties you want to update.
properties object Default properties docs

updateThreadProperties

const properties = {
  property_namespace: {
    sample: 'property',
  },
}
customerSDK
  .updateThreadProperties({
    chatId: 'ON0X0R0L67',
    threadId: 'OS0C0W0Z1B',
    properties,
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
chatId string ID of the chat whose properties you want to update.
threadId string ID of the thread whose properties you want to update.
properties object Default properties docs.

uploadFile

Returns both a promise and a cancel. You can use cancel to abort a file upload. It also lets you pass the onProgress callback function. Keep in mind that the maximum accepted file size is 10 MB.

It returns a URL that expires after 24 hours unless the URL is used in sendEvent

const { promise, cancel } = customerSDK.uploadFile({
  file,
  onProgress: progress => console.log(`upload progress: ${progress}`),
})

document.getElementById('cancel-upload').onclick = () => {
  cancel()
}

promise
  .then(response => {
    console.log(response.url)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

parameters type description
file blob
onProgress function Receives a progress value

onProgress parameters:

parameters type min max
progress number 0 1

Returned value:

properties type
url string

In React Native, instead of passing a blob you need to pass an object of such a shape:

const file = {
  uri: uriFromCameraRoll,
  type: 'image/jpeg', // optional
  name: 'photo.jpg', // optional
}

Events

You can listen for emitted events by subscribing to them using the on method with your custom callback. For example, your function can be executed every time a message is received.

Availability updated

Informs about a changed availability status.

customerSDK.on('availability_updated', ({ availability }) => {
  console.log('availability_updated', availability)
})

Payload:

properties type description
availability string 'online' or 'offline'

Chat deactivated

Informs that thread has been closed.

customerSDK.on('chat_deactivated', payload => {
  const { chatId } = payload
  console.log('chat_deactivated', { chatId })
})

Payload:

properties type description
chatId string Chat ID

Chat properties deleted

Informs about deleted chat properties.

customerSDK.on('chat_properties_deleted', payload => {
  const { chatId, properties } = payload
  console.log('chat_properties_deleted', { chatId, properties })
})

Payload:

properties type description
chatId string Chat ID
properties object Chat properties

Chat properties updated

Informs about updated chat properties.

customerSDK.on('chat_properties_updated', payload => {
  const { chatId, properties } = payload
  console.log('chat_properties_updated', { chatId, properties })
})

Payload:

properties type description
chatId string Chat ID
properties object Chat properties

Chat transferred

Informs that a chat was transferred to a different group or an Agent.

customerSDK.on('chat_transferred', payload => {
  const { chatId, threadId, transferredTo } = payload
  console.log('chat_transferred', {
    chatId,
    threadId,
    transferredTo,
  })
})

Payload:

properties type description
chatId string
threadId string
reason string
requesterId string returned only if reason is equal to 'manual'
transferredTo
transferredTo.agentIds string[] optional
transferredTo.groupIds number[] optional
queue optional
queue.position number Current place in the queue
queue.waitTime number Estimated waiting time for an agent to be assigned to the chat, in seconds
queue.queuedAt string RFC 3339 date-time format

Connected

Informs that the connection has been established.

customerSDK.on('connected', payload => {
  const { customer, availability, greeting } = payload
  console.log('connected', { customer, availability, greeting })
})

Payload:

argument type description
customer object Customer object, the same as the response from getCustomer
availability string 'online' or 'offline'
greeting greeting Optional greeting received before the thread started

Greeting:

argument type description
id number Greeting template identifier
text string Text content of the greeting message
uniqueId string Unique event ID of the greeting
displayedFirstTime boolean
accepted boolean
agent.id string
agent.name string
agent.avatar string
agent.jobTitle string
agent.isBot boolean

Connection recovered

Informs that Customer SDK has recovered from an "unstable" connection state. It's always preceded by the "connection_unstable" event.

customerSDK.on('connection_recovered', () => {
  console.log('connection_recovered')
})

This event doesn't carry any additional payload.

Connection unstable

Informs that Customer SDK has detected that connection quality is poor. It doesn't mean that it has disconnected from the server just yet.

customerSDK.on('connection_unstable', () => {
  console.log('connection_unstable')
})

This event doesn't carry any additional payload.

Customer ID

Informs about the ID of the Customer.

customerSDK.on('customer_id', id => {
  console.log('customer id is', id)
})

Payload:

argument type
id string

Customer page updated

The Customer moved to another page, for example by following a link on your website.

customerSDK.on('customer_page_updated', payload => {
  const { url, title, openedAt } = payload
  console.log('customer_page_updated', { url, title, openedAt })
})

Payload:

properties type
url string URL of the Customer current website
title string Title of the Customer current website
openedAt string Date of the last update in RFC 3339 date-time format

Customer updated

Informs that Customer's data was updated. Each property in payload is available only if it was updated.

customerSDK.on('customer_updated', customer => {
  if (customer.name) {
    console.log(`Name got updated to: ${customer.name}`)
  }
  if (customer.email) {
    console.log(`Email got updated to: ${customer.email}`)
  }
  if (customer.avatar) {
    console.log(`Avatar got updated to: ${customer.avatar}`)
  }
  if (customer.fields) {
    console.log(`Fields got updated:`)
    console.log(customer.fields)
  }
})

Payload:

properties type
name string
email string
avatar string
fields object

Disconnected

Informs that SDK has disconnected from the server. The event provides the disconnection reason.

customerSDK.on('disconnected', payload => {
  const { reason } = payload
  console.log('disconnected', { reason })
})

Payload:

properties type description
reason string disconnection reasons

Event properties deleted

Informs about the event properties that were deleted.

customerSDK.on('event_properties_deleted', payload => {
  const { chatId, threadId, eventId, properties } = payload
  console.log('event_properties_deleted', {
    chatId,
    threadId,
    eventId,
    properties,
  })
})

Payload:

properties type description
chatId string Chat ID
threadId string Thread ID
eventId string Event ID
properties object Event properties

Event properties updated

Informs about the event properties that were updated.

customerSDK.on('event_properties_updated', payload => {
  const { chatId, threadId, eventId, properties } = payload
  console.log('event_properties_updated', {
    chatId,
    threadId,
    eventId,
    properties,
  })
})

Payload:

properties type description
chatId string Chat ID
threadId string Thread ID
eventId string Event ID
properties object Event properties

Event updated

Informs that an event was updated.

customerSDK.on('event_updated', payload => {
  const { chatId, threadId, event } = payload
  console.log('event_updated', { chatId, threadId, event })
})

Payload:

properties type description
chatId string Chat ID
threadId string Thread ID
event object The entire updated event

Events marked as seen

Informs that the events were seen by the particular user.

customerSDK.on('events_marked_as_seen', payload => {
  const { chatId, userId, seenUpTo } = payload
  console.log('events_marked_as_seen', { chatId, userId, seenUpTo })
})

Payload:

properties type description
chatId string Chat ID
userId string User ID
seenUpTo string RFC 3339 date-time format

Greeting accepted

Informs about a greeting accepted by the Customer.

customerSDK.on('greeting_accepted', payload => {
  console.log('greeting_accepted', payload.uniqueId)
})

Payload:

properties type
uniqueId string

Greeting canceled

Informs about a greeting canceled by the Customer. It is also emitted when a new greeting automatically cancels the currently displayed one.

customerSDK.on('greeting_canceled', payload => {
  console.log('greeting_canceled', payload.uniqueId)
})

Payload:

properties type
uniqueId string

Incoming chat

Informs about a newly started chat thread. The payload contains the chat data structure and an object describing the new thread. If the chat was started with some initial events, they will be included in the thread object.

customerSDK.on('incoming_chat', payload => {
  const { chat } = payload
  const { id, access, users, properties, thread } = chat
  console.log('incoming_chat', { id, access, users, properties, thread })
})

Payload:

properties type description
chat.id string Chat ID
chat.access object Chat initial access
chat.users object[] Users objects referenced in the chat
chat.properties object Chat properties
chat.thread object

Incoming event

Informs about an incoming event sent to a chat. You should distinguish received events by their types.

customerSDK.on('incoming_event', payload => {
  const { chat, event } = payload
  switch (event.type) {
    case 'message':
      console.log('new message - ', event.text)
      break
    default:
      break
  }
})

Payload:

properties type description
type string Event type
... Other properties

Incoming greeting

Informs about an incoming greeting.

customerSDK.on('incoming_greeting', payload => {
  const { text, agent } = payload
  const { name } = agent
  console.log(`Received a greeting with "${text}" text content from ${name}.`)
})

Payload:

properties type description
id number Greeting template ID
text string Greeting text content
uniqueId string Greeting unique ID
displayedFirstTime boolean Describes if the greeting was generated for the first time.
accepted boolean Chat properties
agent object Agent user

Incoming rich message postback

Informs about an incoming rich message postback.

customerSDK.on('incoming_rich_message_postback', payload => {
  const { chatId, threadId, eventId, userId, postback } = payload
  console.log('incoming_rich_message_postback', {
    chatId,
    threadId,
    eventId,
    userId,
    postback,
  })
})

Payload:

properties type description
chatId string Chat ID of the sent postback
threadId string Thread ID of the sent postback
eventId string Event ID of the sent postback
userId number User who has sent a rich message postback
postback.id boolean ID of the sent postback
postback.toggled boolean Describes if the sent postback was toggled.

Incoming typing indicator

Informs that one of the chat users is currently typing a message. The message hasn't been sent yet. The push payload contains the typing indicator object.

customerSDK.on('incoming_typing_indicator', payload => {
  if (payload.typingIndicator.isTyping) {
    console.log(
      `user with ${payload.typingIndicator.authorId} id is writing something in ${payload.chatId}`,
    )
  } else {
    console.log(
      `user with ${payload.typingIndicator.authorId} id stopped writing in ${payload.chatId}`,
    )
  }
})

Payload:

properties type description
chatId string Chat ID
typingIndicator
typingIndicator.authorId string User ID
typingIndicator.isTyping boolean

Queue position updated

Informs that the queue position has been updated.

customerSDK.on('queue_position_updated', payload => {
  console.log(payload.chatId)
  console.log(payload.threadId)
  console.log(payload.queue.position)
  console.log(payload.queue.waitTime)
})

Payload:

properties type description
chatId string Chat ID
threadId string Thread ID
queue
queue.position number Current place in the queue
queue.waitTime number Estimated waiting time for an agent to be assigned to the chat, in seconds

Thread properties deleted

Informs about deleted thread properties.

customerSDK.on('thread_properties_deleted', payload => {
  const { chatId, threadId, properties } = payload
  console.log('thread_properties_deleted', { chatId, threadId, properties })
})

Payload:

properties type description
chatId string Chat ID
threadId string Thread ID
properties object Chat thread properties

Thread properties updated

Informs about updated thread properties.

customerSDK.on('thread_properties_updated', payload => {
  const { chatId, threadId, properties } = payload
  console.log('thread_properties_updated', { chatId, threadId, properties })
})

Payload:

properties type description
chatId string Chat ID
threadId string Thread ID
properties object Thread properties

User added to chat

Informs that a user was added to a chat.

customerSDK.on('user_added_to_chat', payload => {
  const { chatId, user, present } = payload
  console.log('user_added_to_chat', { chatId, user, present })
})

Payload:

properties type description
chatId string Chat ID
user object User
present boolean

User data

Contains the information about the User data.

custom