@ujet/websdk-headless NPM

Headless WebSDK

Install

npm install @ujet/websdk-headless --save

Usage

import { Client } from "@ujet/websdk-headless"

async function authenticate() {
  const resp = await fetch("/your-auth-endpoint")
  const data = await resp.json()
  return { token: data.token }
}

const client = new Client({
  companyId: "YOUR-COMPANY-ID",
  tenant: "YOUR-TENANT-NAME",
  authenticate: authenticate,
})

// const company = await client.getCompany()
// const menus = await client.getMenus()

Available options for Client class:

interface ClientOption {
  companyId: string;
  authenticate: () => Promise<TokenResponse>;
  tenant?: string;
  host?: string;
  lang?: string;
  bridge?: string;
  cobrowse?: {
    enabled: boolean;
    messages?: CobrowseMessages;
    api?: string;
    license?: string;
    trustedOrigins?: string[];
    capabilities?: string[];
    registration?: boolean;
    redactedViews?: string[];
    unredactedViews?: string[];
  };
}

Methods

All methods available for client instance.

`getTrigger`

This method is used to detect current page proactive triggers. It will return current matched trigger or null.

const trigger = await client.getTrigger()

`getCompany`

This method is used to get the company information.

const company = await client.getCompany()

interface CompanyResponse {
  name: string;
  subdomain: string;
  support_email: string;
  languages: LanguageOption[];
  action_tracking: boolean;
  email_transcripts: boolean;
  message_preview: boolean;
  email_enhancement: boolean;
}

`getAfterHourMessage`

This method is used for fetching the message for after hour deflection.

Request parameter:

(lang?: string)

Example:

const message: string = await client.getAfterHourMessage()

`getMenus`

This method is used to list all the menu items available for the tenant.

Request parameter:

(key?: string, lang?: string)

Example:

const data = await client.getMenus("direct_menu_key")
console.log(data.menus)
console.log(data.direct)

Response data:

interface MenuItem {
  id: number;
  name?: string;
  enabled: boolean;
  redirection?: {
    option: string;
    data: string;
  };
  children?: MenuItem[];
  channels: MenuChannel[];
  deflection?: {
    enabled: boolean;
    type: string;
  };
}

interface MenuResponse {
  menus: MenuItem[];
  direct: {
    key: boolean;
    user: boolean;
  };
}

`getTimeSlots`

This method is used to get available time slots for scheduled calls.

Request parameter:

(menuId: number | string, lang?: string)

Example:

const slots = await client.getTimeSlots(123)

Response data example:

[
  "2023-05-31 11:45 +0000",
  "2023-05-31 12:00 +0000",
  "2023-05-31 12:15 +0000",
  "2023-05-31 12:30 +0000",
  "2023-05-31 12:45 +0000",
  "2023-05-31 13:00 +0000",
  "2023-05-31 13:15 +0000",
  "2023-05-31 13:30 +0000",
  "2023-05-31 13:45 +0000",
  "2023-05-31 14:00 +0000"
]

`getWaitTimes`

This method is used to get the waiting time for chat channel and call channel of a menu.

Request parameter:

(menuId: number | string, lang?: string)

Example:

const {chat, voice_call} = await client.getWaitTimes(123)

`createCall`

This method is used to create an instant/scheduled call.

Request parameter:

interface CallRequest {
  phone_number: string;
  lang?: string;
  scheduled_at?: string;
  ticket_id?: string;
  email?: string;
  recording_permission?: boolean;
}

(menuId: number | string, data: CallRequest)

When scheduled_at is set, it will create a scheduled call.

create an instant call:

const call = await client.createCall(123, {
 lang: 'en',
 phone_number: '+12345678',
})

create a scheduled call:

const call = await client.createCall(123, {
 lang: 'en',
 phone_number: '+12345678',
 scheduled_at: '2023-05-31T11:45+0000',
})

`loadCall`

This method is used to get the call information of the given call ID.

Request parameter:

(callId: number | string)

Example:

const call = await client.loadCall(1234)

`cancelCall`

This method is used to cancel a call, usually used for cancelling a scheduled call.

Request parameter:

(callId: number | string)

Example:

client.cancelCall(1234)

`createChat`

This method is used to create a new chat.

Request parameter:

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
}

(menuId: number | string, data: ChatRequest, customData?: string | object)

An example:

client.createChat(123, { lang: 'en' })

`loadChat`

This method is used to get the chat information of the given chat ID.

Request parameter:

(chatId: number | string)

// client.loadChat(1234)

`resumeChat`

This method is used to resume the chat when chat is "dismissed".

Request parameter:

(chatId: number | string)

// client.resumeChat(1234)

`loadOngoingChat`

This method is used to get the ongoing chat information. The client will save current ongoing chat ID in browser's localStorage, this method will try to load the ongoing chat information.

const chat = await client.loadOngoingChat()

`getChatDeflection`

This method is used to fetch the chat deflection configuration.

Example:

// this method can only be used when there is a chat
const deflection = await client.getChatDeflection()

The response is null or:

interface ChatDeflectionResponse {
  enabled: boolean;
  threshold: number;
  keep_waiting: boolean;
}

`escalateChat`

This method will transfer the chat from virtual agent to human agent.

client.escalateChat()

`finishChat`

This method will change the chat status to finished.

client.finishChat()

Some methods are called after finishChat, e.g. sendChatSurvey, sendChatRate.

`destroyChat`

This method will destroy current ongoing chat.

client.destroyChat()

`fetchMessages`

This method is used to get all the previous messages, it is usually used together with loadOngoingChat. You would use this method after chat is connected.

client.on("chat.connected", async () => {
  const messages = await client.fetchMessages()
})

`sendTextMessage`

Send a text message:

client.sendTextMessage("hello world")

`sendFileMessage`

Send a file message:

const input = document.querySelector('input[type="file"]')
const file = input.files[0]
client.sendFileMessage(file)

`startCobrowse`

Request starging cobrowse:

client.startCobrowse()

`createCobrowseCode`

Create cobrowse code digits:

client.createCobrowseCode()

`sendChatTranscripts`

Send current chat transcripts to the given emails.

client.sendChatTranscripts([
  "name1@example.com",
  "name2@example.com",
])

`sendChatRate`

This method will send user feedback for current chat, when chat is finished.

Request parameter:

client.sendChatRate({
  rating: 5,
  feedback: "Very good service",
})

`sendChatSurvey`

This method will also send user feedbacks, but powerful.

Request parameter:

interface {
  [question_id: string]: number | string;
}

you will need to get the survey questions:

const questions = await client.getChatSurvey()
/* response:
{
  sign_off_display_text: "some text",
  questions: [
   {
     id: number,
     type: string,
     display_text: string,
     valid_answers?
   }
  ]
}
*/

answer each questions, and call sendChatSurvey:

client.sendChatSurvey({
 123: "a",
 231: "b",
})

`createEmail`

This method will send an email:

Request parameter:

interface EmailRequest {
  name?: string;
  email: string;
  content: string;
  lang?: string;
  files?: File[];
  recaptcha?: string;
}

(menuId: number | string, data: EmailRequest)

client.createEmail(123, {
  lang: "en",
  name: "User name",
  email: "name@example.com",
  content: "description of the question",
  files: input.files,
})

Events

It is possible to add and remove event listners via .on and .off methods:

const handleReady = () => {
  console.log("**** client is ready")
}

client.on("ready", handleReady)

// client.off("ready", handleReady)

Here lists all the available events:

ready

Emit when client is ready for communication.

client.on("ready", () => {
})

authenticated

Emit when client has authenticated with the user's token.

client.on("authenticated", () => {
})

chat.ongoing

Emit when there is an ongoing chat.

client.on("chat.ongoing", (chat) => {
  console.log(chat)
})

chat.updated

Emit when chat instance has updated.

client.on("chat.updated", (chat) => {
  // the `chat` property on `client` has updated
  console.log(chat)
})

chat.message

Emit when there is a new message.

client.on("chat.message", message => {
  console.log(message)
})

The message type:

interface MessageResponse {
  $index: number;
  $sid: string;
  $timestamp: Date;
  $userType: string;
  $userId: number;
  type: string;
  content?: string;
  event?: string;
  file?: File;

  // extra parameters
  [key: string]: unknown;
}

chat.memberJoined

Emit when a new member joined the conversation.

client.on("chat.memberJoined", (identity) => {
  console.log(identity)
})

chat.memberLeft

Emit when a member left the conversation.

client.on("chat.memberLeft", (identity) => {
  console.log(identity)
})

chat.typingStarted

Emit when a member started typing.

client.on("chat.typingStarted", (identity) => {
  console.log(identity)
})

chat.typingEnded

Emit when a member ended typing.

client.on("chat.typingEnded", (identity) => {
  console.log(identity)
})

chat.connected

Emit when the chat is connected with conversation provider.

client.on("chat.connected", () => {
  console.log("connected")
})

chat.disconnected

Emit when the chat is disconnected with conversation provider.

client.on("chat.disconnected", () => {
  console.log("disconnected")
})

chat.dismissed

Emit when the chat's status is changed to dismissed.

client.on("chat.dismissed", () => {
  console.log("dismissed")
})

chat.timeout

Emit when the chat is ended, and the reason is "timeout".

client.on("chat.timeout", () => {
  console.log("timeout")
})

chat.ended

Emit when the chat is ended.

client.on("chat.ended", () => {
  console.log("ended")
})

chat.destroyed

Emit when destroyChat is called.

client.on("chat.destroyed", () => {
  console.log("destroyed")
})

cobrowse.request

Emit when end user or agent request to start cobrowse.

client.on("cobrowse.request", { from } => {
  console.log("request by", from)
})

cobrowse.loaded

When cobrowse session is loaded.

client.on("cobrowse.loaded", session => {
  console.log("cobrowse session", session)
})

cobrowse.updated

When cobrowse session is updated.

client.on("cobrowse.updated", session => {
  console.log("cobrowse session", session)
})

cobrowse.ended

When cobrowse session is ended.

client.on("cobrowse.ended", session => {
  console.log("cobrowse session", session)
})

Cobrowse

Headless WebSDK has built-in integration with co-browse. It has a simple UI without CSS, developers SHOULD add style for it.

The default template is:

<dialog open class="cobrowse-dialog">
  <h1>$title</h1>
  <div class="cobrowse-dialog_content">$content</div>
  <div class="cobrowse-dialog_footer">
    <button class="cobrowse-dialog_allow js-cobrowse-allow">$allow</button>
    <button class="cobrowse-dialog_deny js-cobrowse-deny">$deny</button>
  </div>
</dialog>

The template will be wrapped by a <div> tag:

<div class="cobrowse-wrapper">${template}</div>

You can add CSS style according to the above template's class names.

Custom template

Developers can also provide a custom template with class="cobrowse-template", e.g.

<script class="cobrowse-template" type="text/template">
  <div class="cobrowse">
    <div class="cobrowse-title">$title</div>
    <div class="cobrowse-content">$content</div>
    <div class="cobrowse-footer">
      <button class="cobrowse-deny js-cobrowse-deny">$deny</button>
      <button class="cobrowse-allow js-cobrowse-allow">$allow</button>
    </div>
  </div>
</script>

Variables $title, $content, $deny, and $allow will be replaced automatically.

Note: js-cobrowse-deny and js-cobrowse-allow class names are required.

Custom messages

We know $title, $content, $deny, and $allow are variables, the default (en) messages for these variables are:

{
  "confirmSessionTitle": "Co-browse Session Request",
  "confirmSessionContent": "Do you want to share your current screen with the agent?",
  "endSessionText": "End Co-browse Session",
  "confirmRemoteControlTitle": "Remote Access Request",
  "confirmRemoteControlContent": "The agent would like to have access to your currently shared screen to further assist you. Do you want to allow this?",
  "confirmFullDeviceTitle": "Screen Share Request",
  "confirmFullDeviceContent": "Do you want to share your full screen with the agent? The agent will not be able to control anything on the screen.",
  "allowText": "Allow",
  "denyText": "Deny"
}

You can customize the message through option cobrowse.messages:

const client = new Client({
  companyId: "YOUR-COMPANY-ID",
  tenant: "YOUR-TENANT-NAME",
  authenticate: authenticate,
  cobrowse: {
    enabled: true,
    messages: {
      confirmSessionTitle: "...",
      confirmSessionContent: "...",
      endSessionText: "...",
      confirmRemoteControlTitle: "...",
      confirmRemoteControlContent: "...",
      confirmFullDeviceTitle: "...",
      confirmFullDeviceContent: "...",
      allowText: "...",
      denyText: "...",
    }
  }
})

@everything-registry/sub-chunk-963

9 months ago

10 months ago

10 months ago

10 months ago