Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including @livechat/livechat-visitor-sdk with all npm packages installed. Try it out:

var livechatVisitorSdk = require("@livechat/livechat-visitor-sdk")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@livechat/livechat-visitor-sdk v0.36.2

Chat Widget Visitor SDK to perform a chat as a visitor


weight: 10

Introduction

Chat Widget Visitor SDK allows you to perform a chat via LiveChat as a visitor using JavaScript.

You can use this to create your own chat widget.

Is it for me?

If you need to customize the LiveChat widget, using Chat Widget Visitor SDK is one of the options to do this.

Keep in mind, however, that interacting with this API requires significant development skills.

  • If you only want to modify the look and feel of the chat widget, check our powerful yet easy to use chat widget configurator.

  • If you want to integrate the chat widget with your application, you can use the the existing JS API.

However, if you need a fully custom solution and you feel brave, dive into Chat Widget Visitor SDK: we provide methods and callbacks for deep integration with the LiveChat environment.

About Chat Widget Visitor SDK

Chat Widget Visitor SDK is promise-based; all asynchronous methods return a promise. To get a promise fulfillment result, subscribe your handler to the promise's then method. Check out this article to learn more about promises.

Important! Some methods and callbacks are not implemented yet.

Tools

  • React Chat UI Kit - set of React components to easily build nice-looking chat windows

Examples

Resources


weight: 20

How to start

Install Visitor SDK

You can use Chat Widget Visitor SDK in two different ways:

Using npm

npm install --save @livechat/livechat-visitor-sdk

Now, you can import SDK in your code:

import * as LivechatVisitorSDK from "@livechat/livechat-visitor-sdk";

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

<script src="https://unpkg.com/@livechat/livechat-visitor-sdk@0.36.0/dist/livechat-visitor-sdk.min.js"></script>

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

Use SDK

Now run the init function with configuration, replacing LICENSE_NUMBER with your LiveChat license number. The function will return the visitorSDK interface:

const visitorSDK = LivechatVisitorSDK.init({
  license: LICENSE_NUMBER,
})

With visitorSDK, you can attach callbacks or execute methods.

visitorSDK.on('new_message', newMessage => {
  console.log(newMessage)
})

visitorSDK
  .sendMessage({
    text: 'Hello',
    customId: 123423215,
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

weight: 30

Methods

init

Initializes the chat window.

import LivechatVisitorSDK from '@livechat/livechat-visitor-sdk'

const visitorSDK = LivechatVisitorSDK.init({
  license: 123,
  group: 0,
})

Parameters:

paramtypedescription
licensenumberLiveChat license number
groupnumberGroup number (default: 0)

sendMessage

Sends a message.

visitorSDK
  .sendMessage({
    text: 'Hello',
    customId: '123423215',
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

paramtypedescription
textstringVisitor message text
customIdstringMessage custom id

Errors:

typereason
connection"Request failed"
missing argument"Missing text or customId parameter"
state"Chat is offline"

closeChat

Closes the chat.

visitorSDK
  .closeChat()
  .then(() => {
    console.log('Chat is closed')
  })
  .catch(error => {
    console.log(error)
  })

This method has no parameters.

Response:

paramtypedescription
successbooleanRequest's response status

Errors:

typereason
"state"There is no chat to close
"connection"Request failed

sendFile

Enables file sharing through the chat window.

visitorSDK
  .sendFile({
    file: FileObject,
    customId: '123423215',
  })
  .then(response => {
    console.log(response.status)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

paramtypedescription
fileblobFile to upload
onProgressfunctionCallback function. It will receive a progress value (a number between 0 and 1)

Errors:

typereason
connection"Request failed"
missing argument"Missing file"
wrong argument"Cannot upload a file over 10MB"

Response:

paramtypedescription
idstringFile id
timestampstringFile timestamp
urlstringFile URL address
contentTypestringFile content type
sizenumberFile size in bytes
widthnumberImage width (for image content types) - optional
heightnumberImage height (for image content types) - optional

rateChat

Enables chat ratings.

visitorSDK
  .rateChat({
    rate: 'good',
    comment: 'Agent helped me a lot!',
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

paramtypedescription
rate"good" \ "bad" \ "none"Rate type
commentstringRate comment text (optional)

Response:

paramtypedescription
successbooleanRequest's response status

Errors:

typereason
"missing argument"Missing rate parameter
"wrong argument"Rate argument should be equal "good", "bad" or "none"
"connection"Request failed
"connection"Rate Comment request failed

markMessageAsSeen

Marks a message as Seen.

Learn more about LiveChat delivery statuses here.

visitorSDK.markMessageAsSeen('123123123')

Parameters:

paramtypedescription
messageIdstringId of message to be marked as seen

setSneakPeek

Enables sneak peeks to see what the visitor is typing in before they actually send the message.

visitorSDK.setSneakPeek({
  text: 'Hello, I woul',
})

Parameters:

paramtypedescription
textstringCurrent message input text

Note: Sneak peek won't be sent every time you call a function. It will be throttled (i.e. sent not earlier than 300ms after the last sneak peek request).

forwardChatTranscript

Sends chat transcripts to the specified email address when the chat is ended.

visitorSDK
  .forwardChatTranscript({
    email: 'test@livechatinc.com',
  })
  .then(response => {
    console.log(response)
  })
  .catch(error => {
    console.log(error)
  })

Parameters:

paramtypedescription
emailstringEmail that will automatically receive a transcript when a chat is finished

Response:

paramtypedescription
successbooleanRequest's response status

Errors:

typereason
"state"There is no chat to forward transcript
"missing argument"Missing email parameter
"connection"Request failed

getPostchatForm

Get post-chat survey form fields configured in chat window settings section in agent app.

visitorSDK
  .getPostchatForm()
  .then(data => {
    console.log('Post-Chat form data', data)
  })
  .catch(error => {
    console.log('error')
  })

This method has no parameters.

Response:

paramtypedescription
fieldsformField[]Array with form fields details - see field's description below

formField object description

paramtypedescription
type"text" / "select" / "checkbox" / "radio" / "information"Type of the field
requiredbooleanIs field required?
namestringfield's name
labelstringField's label
valuestringOptional - field's value
optionsfieldOption[]Array with fields options - only for fields of type: radio, checkbox, select, group_select. see option's description below

fieldOption object description

paramtypedescription
labelstringinput's label
checkedbooleaninput's checked flag
valuestringinput's value

Errors:

typereason
"connection"Request failed
"state"Post-chat survey is turned off

getPrechatForm

Get pre-chat survey form fields configured in chat window settings section in agent app.

visitorSDK
  .getPrechatForm()
  .then(data => {
    console.log('Pre-Chat form data', data)
  })
  .catch(error => {
    console.log('error')
  })

This method has no parameters.

Response:

paramtypedescription
fieldsformField[]Array with form fields details - see field's description below

formField object description

paramtypedescription
type"name" / "text" / "email" / "select" / "checkbox" / "radio" / "group_select" / "information"Type of the field
requiredbooleanIs field required?
namestringfield's name
labelstringField's label
valuestringOptional - field's value
optionsfieldOption[]Array with fields options - only for fields of type: radio, checkbox, select, group_select. see option's description below

fieldOption object description

paramtypedescription
labelstringinput's label
checkedbooleaninput's checked flag
valuestringinput's value

Errors:

typereason
"connection"Request failed
"state"Pre-chat survey is turned off

sendPrechatForm

Collects the pre-chat survey form information (it will be visible during the chat and in the archives). Pre-chat form should be rendered using fields fetched by getPrechatForm method.

const formAnswers = {
  '151913066848701614': 'Sidney Bechet', // "151913066848701614" is field's name, and "Sidney Bechet" is value provided by the visitor
  '151913066848701615': 's.brechet@example.org',
  '15191306684870388': ['1', '2'], // Fields with "checkbox" type have multiple values.
}

visitorSDK
  .sendPrechatForm(formAnswers)
  .then(() => {
    console.log('Pre-chat sent')
  })
  .catch(error => {
    console.log('error')
  })

Parameters:

paramtypedescription
formAnswersobjectPre-chat forms answers object - field.name: field.value

Response:

paramtypedescription
successbooleanRequest's response status

Errors:

typereasonfields
connection"Request failed"
state"You can't send prechat when chat is running"
wrong argumentsfieldError[]

wrong arguments error object contains additional array "fields" with detailed validations errors.

fieldError object description

paramtypedescription
reasonstringError reason, e.g. "Required field", "Wrong type"
descriptionbooleanOptional. Detailed error description, e.g. "Pease fill in required field"
fieldstringField's name

sendPostchatForm

Collects the post-chat form information (it will be visible in the archives).

const formAnswers = {
  '151913066848701614': 'Good support!', // "151913066848701614" is field's name, and "Good support!" is value provided by the visitor
  '15191306684870388': ['1', '2'], // Fields with "checkbox" type have multiple values.
}

visitorSDK
  .sendPostchatForm(formAnswers)
  .then(() => {
    console.log('Pre-chat sent')
  })
  .catch(error => {
    console.log('error')
  })

Parameters:

paramtypedescription
formAnswersobjectPost-chat forms answers object - field.name: field.value

Response:

paramtypedescription
successbooleanRequest's response status

Errors:

| type | reason | fields | | --------------- | -------------------------=-------------------- | ------------ | | connection | "Request failed" | | | state | "You can't send postchat when chat is running" | | | wrong arguments | | fieldError[] |

getVisitorData

Collects the visitor information.

const visitorData = visitorSDK.getVisitorData().then(visitorData => {
  console.log(visitorData)
})

Returned value:

paramtypedescription
namestringVisitor's name
emailstringVisitor's email address
pageUrlstringVisitor's currently visiting website URL
pageTitlestringVisitor's currently visiting website title
customPropertiesobjectVisitor's additional data object (custom properties)

setVisitorData

Set the visitor information.

visitorSDK.setVisitorData({
  name: 'Wynton Marsalis',
  email: 'test@livechatinc.com',
  pageUrl: 'http://example.org/pricing',
  pageTitle: 'Pricing',
  customProperties: {
    login: 'wyntonmarsalis',
    customerId: '18260556127834',
  },
})

Parameters:

paramtypedescription
namestringVisitor's name
emailstringVisitor's email address
pageUrlstringVisitor's currently visiting website URL
pageTitlestringVisitor's currently visiting website title
customPropertiesobjectVisitor's additional data object (custom properties)

Errors:

typereason
missing argument"Missing name, email, url or customProperties"
connection"Request failed"

getTicketForm

Get ticket form fields configured in chat window settings section in agent app.

visitorSDK
  .getTicketForm()
  .then(data => {
    console.log('Ticket form data', data)
  })
  .catch(error => {
    console.log('error')
  })

This method has no parameters.

Response:

paramtypedescription
fieldsformField[]Array with form fields details - see field's description below

formField object description

paramtypedescription
type"name" / "subject" / "email" / "header"Type of the field
requiredbooleanIs field required?
labelstringField's label
valuestringOptional - field's value

sendTicketForm

Send ticket form filled in by visitor. Ticket form should be rendered using fields fetched by getTicketForm method.

visitorSDK
  .sendTicketForm({
    name: 'John',
    email: 'john@example.org',
    subject: 'App support',
    message: 'I have a problem with your app',
  })
  .then(() => {
    console.log('Ticket sent')
  })
  .catch(error => {
    console.log('error')
  })

Parameters

paramtypedescription
namestringVistior's name
emailstringVisitor's email address
subjectstringTicket subject
messagestringVisitor's message

Response:

paramtypedescription
successbooleanRequest's response status

Errors:

typereason
connection"Request failed"
missing argument"Missing email"
missing argument"Missing message"

disconnect

Disconnect Visitor SDK. A visitor won't be tracked, and you won't be notified about agent's availability status. You will be automatically connected again after using sendMessage or setVisitorData methods.

visitorSDK.disconnect()

Errors:

typereason
state"You can't disconnect during the chat"

destroy

Disconnect Visitor SDK and unsubscribe from all callbacks.

visitorSDK.destroy()

getTranslations

Get translations for current group.

visitorSDK.getTranslations().then(translations => {
  console.log('Translations', translations)
})

Errors:

typereason
connection"Request failed"

getPredictedAgent

Get agent details without starting a chat

Response:

paramtypedescription
namestringAgent's name
idstringAgent's ID
avatarUrlstringAgent's avatar - path to the image on Amazon s3
jobTitlestringAgent's job title

Errors:

typereason
connection"Request failed"

getConfig

Get chat widget configuration

Response:

paramtypedescription
visitorDataobjectVisitor's data
featuresobjectFeature toggles and settings
buttonsarrayButtons configuration
themeobjectTheme settings
domainWhitelistarrayWhitelisted domains
widgetType"embedded" / "popup"Chat widget type
integrationsobjectInstalled chat widget integrations
languagestringChat widget language
groupsobjectGroups details

Errors:

typereason
connection"Request failed"

startChat

Start the chat

visitorSDK.startChat().then(data => {
  console.log('data', data)
})

Response:

paramtypedescription
chatIdstringNew Chat ID

Errors:

typereason
connection"Request failed"
state"You can't start new chat during chat"

weight: 40

Callbacks

Callbacks let you bind a custom JavaScript function to an event. For example, your function can be executed every time agent's message has been received.

visitor_data

Callback function executed when server returns visitor's data.

visitorSDK.on('visitor_data', visitorData => {
  console.log(visitorData)
})

Payload:

paramtypedescription
idstringVisitor ID

new_message

Callback function executed when a new message arrives.

visitorSDK.on('new_message', newMessage => {
  console.log(newMessage)
})

Payload:

paramtypedescription
idstringMessage ID
authorIdstringMessage author ID
timestampnumberTimestamp added by server
textstringMessage text
chatIdstringMessage chat ID
customIdstringMessage custom ID (for visitor's messages only)

visitor_banned - not implemented yet

Callback function executed when a visitor is banned.

visitorSDK.on('visitor_banned', data => {
  console.log(data)
})

chat_started

Callback function executed when a chat is started.

visitorSDK.on('chat_started', chatData => {
  console.log(chatData)
})

Payload:

paramtypedescription
chatIdstringNew chat ID

chat_ended

Callback function executed when a chat is ended. This callback is called without any additional data.

visitorSDK.on('chat_ended', () => {
  console.log('Chat is closed')
})

status_changed

Callback function executed when the chat status is changed.

visitorSDK.on('status_changed', statusData => {
  console.log(statusData)
})

Payload:

paramtypedescription
status"online" | "offline"Current chat availability status

visitor_queued

Callback function executed when a visitor is queued.

visitorSDK.on('visitor_queued', queueData => {
  console.log(queueData)
})

Payload:

paramtypedescription
numberInQueuenumberVisitor's order number in queue
waitingTimenumberEstimated waiting time in seconds

connection_status_changed

Callback function executed when the connection status changes.

visitorSDK.on('connection_status_changed', statusData => {
  console.log(statusData)
})

Payload:

paramtypedescription
status"connected" | "disconnected"Current connection status

new_file

Callback function executed when a file is shared.

visitorSDK.on('new_file', newFile => {
  console.log(newFile)
})

Payload:

paramtypedescription
idstringFile ID
authorIdstringFile author ID
timestampnumberTimestamp added by server
urlstringFile url
contentTypestringFile content type (i.e. 'text/plain')
sizenumberFile size

agent_changed

Callback function executed when an agent takes over the chat.

visitorSDK.on('agent_changed', newAgent => {
  console.log(newAgent)
})

Payload:

paramtypedescription
namestringAgent's name
idstringAgent's ID
avatarUrlstringAgent's avatar - path to the image on Amazon s3
jobTitlestringAgent's job title

typing_indicator

Callback function executed when the typing indicator appears.

visitorSDK.on('typing_indicator', typingData => {
  console.log(typingData)
})

Payload:

paramtypedescription
authorIdstringAuthor ID of the writer
isTypingbooleanAuthor is typing / stopped typing

message_seen

Callback function executed when a message is marked as seen.

Learn more about LiveChat delivery statuses here.

visitorSDK.on('message_seen', data => {
  console.log(data)
})

Payload:

paramtypedescription
idstringSeen message id
customIdstringSeen message custom id
type"agent" / "visitor"Original message author type

chat_rated

Callback function executed when the chat is rated or commented by visitor.

visitorSDK.on('chat_rated', data => {
  console.log(messageData)
})

Payload:

paramtypedescription
rate"good" \ "bad" \ "none"Rate type
commentstringRate comment text

new_invitation

Callback function executed when an invitation was sent to visitor.

visitorSDK.on('new_invitation', invitationData => {
  console.log(invitationData)
})

Payload:

paramtypedescription
idstringMessage ID
authorIdstringMessage author ID
textstringMessage text
receivedFirstTimebooleanWas invitation received for the first time

ready

Callback executed when SDK finished initialization and all chat history was fetched. This callback is called without any additional data.

visitorSDK.on('ready', () => {
  console.log('Visitor SDK is ready')
})

weight: 50

Changelog

Subscribe to LiveChat Developers Newsletter to be notified about changes in Visitor SDK.

[v0.36.0] - 08.08.2019

Fixed
  • Fixed CORS error

[v0.35.2] - 20.06.2018

Fixed
  • Fixed sendTicketForm method

[v0.35.1] - 08.05.2018

Fixes

  • Fixed CORS error

[v0.35.0] - 01.05.2018

Added

  • Added sendPostChatForm method
  • Added getPostChatForm method
  • Added acceptInvitation method

[v0.34.0] - 19.03.2018

Added
  • Added getPredictedAgent method
Fixed
  • Fixed getPrechatForm method documentation - error description

[v0.33.3] - 8.03.2018

Fixed
  • Fix sendTicketForm method - incorrect data passed to request

[v0.33.2] - 6.03.2018

Fixed
  • Fix sendPrechatForm method - incorrect answers bug

[v0.33.1] - 27.02.2018

Fixed
  • Fix sendMessage method - reject promise if chat is offline

[v0.33.0] - 26.02.2018

Added
  • Added getPrechatForm method
  • Added sendPrechatForm method

[v0.32.0] - 16.02.2018

Added
Fixed
  • Fix documentation - npm installation code snippet

[v0.31.3] - 31.01.2018

Fixed
  • Fix fielsharing bug - use correct chat id after starting a new chat again

[v0.31.2] - 30.01.2018

Fixed
  • Fix group init parameter

[v0.31.1] - 25.01.2018

Fixed
  • sendFile method - correct server address
  • fix URL rules - correct visitor's current URL detection

[v0.31.0] - 9.01.2018

Added
  • Added sendFile method

[v0.30.0] - 3.01.2018

Added

[v0.29.2] - 28.12.2017

Fixed
  • Docs fix - correct date in changelog

[v0.29.0] - 28.12.2017

Added
  • Added chat_rated callback
  • Added URL rules support
Fixed
  • sendMessage parameter "customId" now parsed to string by default

[v0.28.4] - 27.11.2017

Fixed
  • Fixed docs

[v0.28.3] - 22.11.2017

Fixed
  • Fixed npm build Safari support

[v0.28.2] - 22.11.2017

Fixed
  • Fixed iOS Safari support
Changed
  • New reject type for setVisitorData method: "connection"

[v0.28.1] - 30.10.2017

Fixed
  • Fixed npm build

[v0.28.0] - 30.10.2017

Added
  • Added destroy method
Changed
  • Added customId parameter to new_message callback's data

[v0.27.1] - 30.10.2017

Fixed

[v0.27.0] - 16.10.2017

Added
  • Added getVisitorData method
Changed
  • setVisitorData method: Added possibility to set customProperties

[v0.0.26] - 13.10.2017

Added
  • Added getTicketForm method
  • Added sendTicketForm method
Fixed
  • Fixed error handling
Changed
  • setVistiorData method renamed to setVisitorData

[v0.0.25] - 03.10.2017

Added
  • Added disconnect method

[v0.0.24] - 12.09.2017

Added
  • Added iOS React Native sample app to Examples

[v0.0.23] - 11.09.2017

Added
  • Added visitor_data callback

[v0.0.22] - 07.09.2017

Added
  • Support for non-browser environments

[v0.0.21] - 06.09.2017

Added
  • Added closeChat method

[v0.0.20] - 05.09.2017

Fixed
  • Fix npm package - add all dependencies

[v0.0.19] - 31.08.2017

Added
  • Added forwardChatTranscript method

[v0.0.18] - 30.08.2017

Added
  • Added setSneakPeek method

[v0.0.17] - 29.08.2017

Added
  • Added rateChat method
  • Added changelog section

[v0.0.16] - 24.08.2017

Fixed
  • Docs fixes - correct method names

[v0.0.15] - 24.08.2017

First public Release

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free