quiq-chat

quiq-chat

A high-level JavaScript Library to handle the communication with Quiq Messaging APIs when building a web chat app

Installation

Install quiq-chat with

npm install --save quiq-chat

or

yarn add quiq-chat

Promise Polyfill

quiq-chat leverages Promises for asynchronous operations, including the relatively new Promise.finally() method. Unless your target browsers support this natively (only Chrome >= 63 and Firefox >= 58) you'll need to include a Promise polyfill on your page. If you aren't already using a polyfill which includes Promise support, we recommend the lightweight https://github.com/taylorhakes/promise-polyfill.

Install with

npm install --save promise-polyfill

or

yarn add promise-polyfill

Then include at the top of your module like so:

import 'promise-polyfill/src/polyfill';

Note that this will add a Promise prototype to the global environment.

Usage

The quiq-chat library exports a QuiqChatClient, which is a singleton. This means that you can import it as many times as you want, in as many modules as you want, and always get back the same instance of the client.

Import it like so:

import QuiqChatClient from 'quiq-chat';

QuiqChatClient exposes a fluent API for client setup, allowing you to chain calls together. First, we call initialize(host, contactPoint). We then register our own handler functions to respond to different chat events. Finally, we call start(). The start method returns a promise that resolves once the client is fully initialized and ready to send and receive messages.

Below we show a simple setup, with handler functions for new message and agent typing events.

QuiqChatClient
    .initialize('tenant.goquiq.com', 'default')
    .onNewMessages(messages => {
        messages.forEach(msg => console.log(msg)
    })
    .onAgentTyping(isTyping => {
        if (isTyping) {
            console.log("The agent started typing!")
        } else {
            console.log("The agent stopped typing!")
        }
    })
    // Connect that chat client
    .start()
    .then(() => {
        console.log("The chat client is connected and ready to send and receive messages");
    });

Starting and stopping the client

start() => Promise<QuiqChatClient>

Begins the chat session, allowing the client to send and receive messages. Should be called immediately after initializing and registering event handlers. The returned Promise is resolved once the session is active and everything is ready to go.

stop() => void

Ends the chat session. The client will no longer receive messages.

Handling events

Register your event handling functions prior calling QuiqChatClient.start(). All of these methods can be chained together.

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.

onErrorResolved() => QuiqChatClient

Called whenever any error from the API has been resolved

onMessageSendFailure = (callback: (messageId: string) => void) => QuiqChatClient

Called when a text or attachment message could not be delivered to the agent.

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 the connection to Quiq is established or terminated. This can be used for showing a "we're trying to reconnect you" message or similar.

onBurn() => QuiqChatClient

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

onPersistentDataChange(callback: (data: PersistentData) => void) => QuiqChatClient

Called whenever Quiq-related data stored in the browser's localStorage changes.

Retrieve messages and conversation events

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.

Sending messages

sendTextMessage(text: string) => void

Send a text message from the customer. The first message sent from the client will initialize (start) a conversation.

sendAttachmentMessage(file: File, prog#ressCallback: (progress: number) => void) => Promise

Send an attachment message containing a File from the customer. The 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.

User Registration

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.

Session

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 (handle) 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

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.

Email the conversation transcript

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.

Utilities

isStorageEnabled() => boolean

Utility function to tell the client if quiq-chat has the capability to set its required data in a persistent way.

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

getPersistentData() => PersistentData

Returns all Quiq-related data stored locally in the browser's localStorage. Includes any custom data set using the setCustomPersistentData() method.

setCustomPersistentData(key: string, value: any) => void

Stores a key/value pair in persistent storage (available between refreshes and browser closes). Can be retrieved using the getPersistentData() method.

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,
  };

PersistentData

    {
      accessToken?: string,
      chatContainerVisible?: boolean,
      subscribed?: boolean,
      hasTakenMeaningfulAction?: boolean,
      [string]: any,
    };

Supported Browsers

QuiqChat works with any browser that supports Local Storage, and CORS requests. The isSupportedBrowser utility function can be used to determine if the end-user is using a browser supported by Quiq. The following browsers and versions are supported:

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