MENU

-

Introduction

LiveChat Visitor JS 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 LiveChat Visitor JS SDK is one of the options to do this.

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

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

About LiveChat Visitor JS SDK

LiveChat Visitor JS 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.

Examples

How to start

Install Visitor JS SDK

You can use LiveChat Visitor JS API in two different ways:

Using npm

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

Now, you can import SDK in your code:

import 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.0.24/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)
    })

Methods

init

Initializes the chat window.

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

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

Parameters:

param type description
license number LiveChat license number
group number Group number (default: 0)

sendMessage

Sends a message.

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

Parameters:

param type description
text string Visitor message text
customId string Message custom id

Errors:

type reason
connection "Request failed"
missing argument "Missing text or customId parameter"

closeChat

Closes the chat.

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

This method has no parameters.

Response:

param type description
success boolean Request's response status

Errors:

type reason
"state" There is no chat to close
"connection" Request failed

sendFile - not implemented yet

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:

param type description
file file File to upload
customId string custom file id

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:

param type description
rate "good" \ "bad" \
comment string Rate comment text (optional)

Response:

param type description
success boolean Request's response status

Errors:

type reason
"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 - not implemented yet

Marks a message as Seen.

Learn more about LiveChat delivery statuses here.

visitorSDK.markMessageAsSeen({
    messageId: "123123123",
})

Parameters:

param type description
messageId string Id 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:

param type description
message string Current 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:

param type description
email string Email that will automatically receive a transcript when a chat is finished

Response:

param type description
success boolean Request's response status

Errors:

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

sendTicketForm - not implemented yet

Gathers the data collected from a customer.

visitorSDK.sendTicketForm(form)

sendPrechatForm - not implemented yet

Collects the pre-chat form information (it will be visible during the chat and in the archives).

visitorSDK.sendPrechatForm(form)

sendPostchatForm - not implemented yet

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

visitorSDK.sendPostchatForm(form)

getVisitorData - not implemented yet

Collects the visitor information.


const visitorData = visitorSDK.getVisitorData()

Returned value:

param type description
name string Visitor's name
email string Visitor's email address
pageUrl string Visitor's currently visiting website URL
pageTitle string Visitor's currently visiting website title
customProperties object Visitor's additional data object (custom properties)

setVisitorData

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

Parameters:

param type description
name string Visitor's name
email string Visitor's email address
url string Visitor's currently visiting website URL
customProperties object Not implemented yet: Visitor's additional data object (custom properties)

Errors:

type reason
missing argument "Missing name, email, url or customProperties"

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:

param type description
id string Vistior ID

new_message

Callback function executed when a new message arrives.

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

Payload:

param type description
id string Message ID
authorId string Message author ID
timestamp number Timestamp added by server
text string Message text
chatId string Message chat ID

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:

param type description
chatId string New chat ID

chat_ended

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

visitorSDK.on('chat_ended', (chatData) => {
    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:

param type description
status "online" \ "offline"

visitor_queued

Callback function executed when a visitor is queued.

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

Payload:

param type description
numberInQueue number Visitor's order number in queue
waitingTime number Estimated 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:

param type description
status "connected" \ "disconnected"

new_file

Callback function executed when a file is shared.

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

Payload:

param type description
id string File ID
authorId string File author ID
timestamp number Timestamp added by server
url string File url
contentType string File content type (i.e. 'text/plain')
size number File size

agent_changed

Callback function executed when an agent takes over the chat.

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

Payload:

param type description
name string Agent's name
id string Agent's ID
avatarUrl string Agent's avatar - path to the image on Amazon s3
jobTitle string Agent's job title

typing_indicator

Callback function executed when the typing indicator appears.

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

Payload:

param type description
authorId string Author ID of the writer
isTyping boolean Author is typing / stopped typing

message_seen - not implemented yet

Callback function executed when a message is marked as Seen.

Learn more about LiveChat delivery statuses here.

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

Changelog