quiq-chat

quiq-chat

Library to handle the communication with Quiq Messaging APIs to build a web chat app

Installation

Install quiq-chat with

npm install --save quiq-chat

or

yarn add quiq-chat

Usage

The default export of quiq-chat is the QuiqChatClient singleton class which will fetch information about the current webchat, initialize a websocket connection, and allow you to register callbacks so that you can keep your app's UI in sync with the webchat state.

All the functions to register callbacks return the QuiqChatClient object so that you can chain them together. You also need to call start() to connect to Quiq Messaging. You will need to call the initialize(host, contactPoint) function before calling start. The start method returns a promise that resolves to the QuiqChatClient, so you can add a callback that will be executed after the connection is opened;

  import QuiqChatClient from 'quiq-chat';

  QuiqChatClient.onNewMessages(messages => {
    // Update your app with the new array of messages
  })
  QuiqChatClient.onAgentTyping(typing => {
    // Show or hide the typing indicator
  })
  QuiqChatClient.onRegistration(() => {
    // Hide form, or show main app
  })
  QuiqChatClient.onConnectionStatusChange(connected => {
    // Show the connection status of the app
  })
  QuiqChatClient.onError(error => {
    // Show some error message
  })
  QuiqChatClient.onRetryableError(error => {
    // Show some error message
  }).
  QuiqChatClient.onErrorResolved(() => {
    // Remove the error message
  })
  QuiqChatClient.start()
  .then(client => {
    // Run some code after the webchat app is connected
  });

Documentation

Supported Browsers

QuiqChat works with any browser that supports Local Storage, standard AJAX CORS requests. The standard implementation of the Chat client supports a subset of these browsers, and we recommend any custom implementations support the same browsers. The isSupportedBrowser utility function can be used to determine if the end-user is using a browser supported by Quiq. The following browsers with versions greater than or equal to the following are supported.

• Chrome 43
• Firefox 48.0
• Safari 6.1
• Internet Explorer 10
• Internet Explorer 11
• Microsoft Edge 12
• Mobile devices

QuiqChatClient

onNewMessages(messages: Array<ConversationMessage>) => QuiqChatClient

Called whenever new messages are received. messages is an array containing full transcript of the current chat

onNewEvents(events: Array<Event>) => QuiqChatClient

Called whenever new messages are received. messages is an array containing full transcript of the current chat

onAgentTyping(typing: boolean) => QuiqChatClient

Called whenever the support agent starts or stops typing

onError(error: ?ApiError) => QuiqChatClient

Called whenever there is a non-retryable error or an error that has exceeded the maximum number of retries from the API.

onRetryableError(error: ?ApiError) => QuiqChatClient

Called whenever there is a retryable error from the API

onErrorResolved() => QuiqChatClient

Called whenever any error from the API has been resolved

onRegistration() => QuiqChatClient

Called when Register event is received through a websocket message

onNewSession() => QuiqChatClient

Called when the end users previous session has expired and has begun a new session. This is a good spot to have the UI reset itself to an initial state

onAgentAssigned(agentAssigned: boolean) => QuiqChatClient

Called when the isAgentAssigned value changes.

onEstimatedWaitTimeChanged(estimatedWaitTime: ?number) => QuiqChatClient

Called when the estimate wait time calculation changes.

onConnectionStatusChanged(connected: boolean) => QuiqChatClient

Called when a connection is established or terminated

onBurn() => QuiqChatClient

Called when quiq-chat gets in a fatal state and page holding webchat needs to be refreshed

onClientInactiveTimeout() => QuiqChatClient

Called when quiq-chat disconnects the websocket due to the chat client being inactive for a set amount of time

getMessages(cache?: boolean = true) => Promise<Array<ConversationMessage>>

Retrieve all messages for the current chat. If cache is set to true, a hit to the API is not made, and only the messages currently in memory are returned.

getEvents(cache?: boolean = true) => Promise<Array<Event>>

Retrieve all events for the current chat. If cache is set to true, a hit to the API is not made, and only the events currently in memory are returned.

emailTranscript(data: EmailTranscriptPayload) => void

Email a transcript of the current conversation to the specified e-mail. If an agent has not yet responded to the conversation, a 400 will be returned.

sendTextMessage(text: string) => void

Send a text message from the customer. Can be used to initiate a conversation if no messages have been sent.

sendAttachmentMessage(file: File, progressCallback: (progress: number) => void) => string

Send an attachment message containing a File from the customer. Th type of this file must conform to the allowed file types set in your configuration. The method also accepts a progressCallback function which will be fired during upload of the file with values between 0 and 100, denoting percentage uploaded. Upon completion of upload, this method returns a string containing the id of the new message.

start() => Promise<QuiqChatClient>

Establishes the connection to QuiqMessaging

stop() => void

Disconnects the websocket from Quiq

isStorageEnabled() => boolean

Utility function to tell the client if quiq-chat has the capability to set its required data in a persistent way. If this returns false, quiq-chat will cease to function, and will block all requests.

isSupportedBrowser() => boolean

Utility function to return if the end-user is using a browser supported by Quiq.

hasTakenMeaningfulAction() => boolean

Returns whether the end-user has performed a meaningful action, such as submitting the Welcome Form, or sending a message to the agent.

isChatVisible() => boolean

Returns the last state of chat's visibility. Only includes actions that call the joinChat and leaveChat events. For instance, if your user maximizes chat, but you never call joinChat, isChatVisible won't reflect this change. Can be used to re-open webchat on page turns if the user had chat previously open. Defaults to false if user has taken no actions.

sendRegistration(data: {[string]: string}) => Promise

Submits a map of custom (key, value) pairs to be included in the data for the current chat. Method accepts a single parameter, a JavaScript object with values of type String. key is limited to 80 characters and must be unique; value is limited to 1000 characters.

getHandle() => Promise<handle?: string>

Returns the unique identifier for this session. If the user is not logged in, returns undefined.

login() => Promise<handle: string>

Creates a session for the current user, if one does not already exist. Returns the unique identifier for the new or existing session.

checkForAgents() => Promise<{available: boolean}>

Fetches whether or not there are agents available for the contact point the webchat is connected to. The value of this call is cached for 10 seconds.

updateTypingIndicator(text:string, typing:boolean) => void

Sends a message to Quiq Messaging that the end user is typing and what they've typed in the message field

joinChat() => void

Sends a message to Quiq Messaging that the end user has opened the chat window

leaveChat() => void

Sends a message to Quiq Messaging that the end user has closed the chat window

isRegistered() => boolean

Returns whether the end user has triggered a registration event. This happens when the sendRegistration API is called, and the server has confirmed the registration was valid.

isAgentAssigned() => boolean

Returns whether the end user's chat has been taken up by an agent. This returns true when the agent sends their first message.

getEstimatedWaitTime() => ?number

Returns the estimate wait time in milliseconds. This is the amount of time we estimate it will take for the user's chat to be assigned to an agent. If this is undefined or null, then no ETA is currently available.

Data types

ConversationMessage

TextMessage | AttachmentMessage

TextMessage

{
    authorType: 'Customer' | 'User',
    text: string,
    id: string,
    timestamp: number,
    type: 'Text',
}

AttachmentMessage

{
  id: string,
  timestamp: number,
  type: 'Attachment',
  authorType: 'Customer' | 'User',
  url: string,
  contentType: string,
}

Event

{
  authorType?: 'Customer' | 'User',
  id: string,
  timestamp: number,
  type: 'Join' | 'Leave' | 'Register' | 'SendTranscript' | 'End' | 'Spam',
}

ApiError

{
  code?: number,
  message?: string,
  status?: number,
}

UserEvent

'Join' | 'Leave'

EmailTranscriptPayload

{
  email: string,
  originUrl: string,
  timezone?: string,
};

Event

  {
    id: string,
    timestamp: number,
    type: string,
  };