@livechat/livechat-visitor-sdk v0.36.2

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 window, check if you can do this with custom CSS.

• 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

• A sample chat widget implementation
• A sample chat widget implementation integrated with BotEngine, built with React Chat UI Kit
• A sample iOS React Native implementation

Resources

• Chat Widget Visitor SDK tutorial - blog post
• npm package

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.35.2/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:

sendMessage

Sends a message.

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

Parameters:

Errors:

closeChat

Closes the chat.

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

This method has no parameters.

Response:

Errors:

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:

Errors:

Response:

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:

Response:

Errors:

markMessageAsSeen

Marks a message as Seen.

Learn more about LiveChat delivery statuses here.

visitorSDK.markMessageAsSeen('123123123')

Parameters:

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:

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:

Response:

Errors:

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:

formField object description

fieldOption object description

Errors:

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:

formField object description

fieldOption object description

Errors:

sendPrechatForm

Collects the pre-chat survey form information (it will be visible during the chat and in the archives). Pre-chat form 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'], // Fieds with "checkbox" type have multiple values.
}

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

Parameters:

Response:

Errors:

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

fieldError object description

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'], // Fieds with "checkbox" type have multiple values.
}

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

Parameters:

Response:

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:

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:

Errors:

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:

formField object description

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

Response:

Errors:

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:

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:

getPredictedAgent

Get agent details without starting a chat

Response:

Errors:

getConfig

Get chat widget configuration

Response:

Errors:

startChat

Start the chat

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

Response:

Errors:

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:

new_message

Callback function executed when a new message arrives.

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

Payload:

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:

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:

visitor_queued

Callback function executed when a visitor is queued.

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

Payload:

connection_status_changed

Callback function executed when the connection status changes.

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

Payload:

new_file

Callback function executed when a file is shared.

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

Payload:

agent_changed

Callback function executed when an agent takes over the chat.

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

Payload:

typing_indicator

Callback function executed when the typing indicator appears.

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

Payload:

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:

chat_rated

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

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

Payload:

new_invitation

Callback function executed when an invitation was sent to visitor.

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

Payload:

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.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

• Added new_invitation callback

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

• Support Data Centers in Europe

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

• Adjust docs according to Docs Changelog Guidelines

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