Headless web SDK guide

The headless web SDK gives you the flexibility to extend and customize your company's support experience according to your needs. It contains all our familiar web SDK features and provides the ability to build out the UI and UX to support them.

Installing and using the headless web SDK requires the support of your organization's web development team. To perform a successful integration and achieve optimal performance, Google recommends involving your qualified personnel.

In the context of software development, "headless" refers to a decoupled architecture where the frontend presentation layer (the "head") is separated from the backend logic and capabilities. In a headless architecture the backend, also known as the "headless" part, provides APIs that let you use its features and services.

An example is custom workflow automation. When an end-user initiates a chat, the on("chat.message") event is triggered. You can define custom automation triggers based on specific chat messages you've received. For example, if an end-user types "Escalate" in the chat, the event handler can automatically escalate the chat session to a higher-level support team, providing prompt attention to critical issues.

This guide walks you through the SDK's installation process, integration capabilities, and usage. For details about using the API, see the Headless web SDK API documentation. A list of available events can be found on the events page.

Install the headless web SDK

To install the headless web SDK, use the following code snippet in your project:

npm install @ujet/websdk-headless --save

Use the headless web SDK

To use the headless Web SDK, you can follow the example code provided:

import { Client } from "@ujet/websdk-headless"
const client = new Client({ ... })

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

The Client class accepts several options (you can customize according to your requirements):

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[];
  };
}

Enable logging

During implementation and testing it might be necessary to gather additional information in the console log. To enable logging for the headless SDK, import Logger and consoleLoggerHandler by adding the following code to your web application:

import {Logger, consoleLoggerHandler } from '@ujet/websdk-headless'
Logger.addHandler(consoleLoggerHandler)

You can enable and configure Screen Share using the headless web SDK.

The following code sample shows you how to enable Screen Share:

new Client({
  // ...
  cobrowse: {
    enabled: true,
    license: 'YOUR_SCREEN_SHARE_LICENSE'
  }
})

The following code sample show the options for Screen Share:

interface CobrowseOption {
  enabled: boolean
  template?: string
  confirmSessionTemplate?: string
  confirmRemoteControlTemplate?: string
  confirmFullDeviceTemplate?: string
  sessionControlsTemplate?: string
  root?: Element
  messages?: {
    confirmSessionTitle: string;
    confirmSessionContent: string;
    confirmRemoteControlTitle: string;
    confirmRemoteControlContent: string;
    confirmFullDeviceTitle: string;
    confirmFullDeviceContent: string;
    allowText: string;
    denyText: string;
    endSessionText: string;
  }
  api?: string
  license?: string
  trustedOrigins?: string[]
  capabilities?: string[]
  registration?: boolean
  redactedViews?: string[]
  unredactedViews?: string[]
}

Custom template

You can customize the Screen Share dialog template using the template option from the preceding code sample.

The following example shows the default template:

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

You can use this template to configure a dialog that requests approval from the end-user for the following:

Start a Screen Share session
Start a remote control Screen Share session
Start a full device Screen Share session

Here are the template options:

confirmSessionTemplate: For confirming a Screen Share session.
confirmRemoteControlTemplate: For confirming a remote control Screen Share session.
confirmFullDeviceTemplate. For confirming a full device Screen Share session.
sessionControlsTemplate: For the session controls button. Here's the default template: <button class="cobrowse-end js-cobrowse-end">$end</button>

Messages

The following message variables are used in Custom templates:

$title
$content
$allow
$deny

The following example shows how these variables are applied:

{
  confirmSessionTitle: string;  // $title
  confirmSessionContent: string;  // $content
  confirmRemoteControlTitle: string;  // $title
  confirmRemoteControlContent: string;  // $content
  confirmFullDeviceTitle: string;  // $title
  confirmFullDeviceContent: string;  // $content
  allowText: string;  // $allow
  denyText: string;  // $deny
  endSessionText: string;  // $end
}

The following example shows the default English variable values:

{
  "confirmSessionTitle": "Screen Share Session Request",
  "confirmSessionContent": "Do you want to share your current screen with the agent?",
  "endSessionText": "End Screen Share 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"
}

Custom data configuration

The custom_data option lets you pass arbitrary key/value data to the web SDK.

Usage

You can provide custom data as either an object (unsigned) or a string (signed) when creating a chat:

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

See the following example:

const custom_data = {
  unsigned: {
    version: {
      label: 'Version',
      value: '1.0.0'
    }
  },
  signed: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' // JWT or other signed payload
}

try {
  const chat: Chat = await client.createChat(123, { custom_data })
} catch (error) {
  // handle error
}

External chatbot transfer

There are some cases where you might want to maintain history and interactions from other chat providers. You can do this by using the custom_data object.