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](https://docs.cloud.google.com/contact-center/ccai-platform/docs/web-sdk)
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](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-web-api).
A list of available events can be found on the
[Events page](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-web-events).

> [!NOTE]
> **Note:** Google only supports the latest three minor versions of the headless web SDK. To receive support, your website must be using one of these versions of the headless web SDK.

## Install the headless web SDK

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

You can install the package with npm:

    npm install @ujet/websdk-headless --save

Or, you can use the script hosted by UJET:

    <script src="https://websdk.ujet.co/v3/headless.js"></script>

    <script>
      // The hosted script exposes the client as the global `UJETClient`.
      // const client = new UJETClient(...)
    </script>

## Use the headless web SDK

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

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

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;
      version?: string;
      cobrowse?: {
        enabled?: boolean;
        messages?: CobrowseMessages;
        api?: string;
        license?: string;
        trustedOrigins?: string[];
        capabilities?: string[];
        registration?: boolean;
        redactedViews?: string[];
        unredactedViews?: string[];
        template?: 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)

## Configure Screen Share

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
      // Widget-only - the following template + root options have no effect in the Headless SDK:
      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[]
      // Headless consent callbacks
      confirmSession?: () => Promise<boolean>
      confirmRemoteControl?: () => Promise<boolean>
      confirmFullDevice?: () => Promise<boolean>

      // Headless session-control callbacks
      showSessionControls?: () => void
      hideSessionControls?: () => void

      // Existing CobrowseIO instance
      instance?: any
    }

### 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](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-web-guide#custom-template):

- `$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"
    }

## Headless client API

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

> [!NOTE]
> **Note:** Error handling - Most `Client` methods propagate HTTP errors as thrown exceptions. Wrap calls in `try/catch` unless the method's documentation notes otherwise.

## Events

For a list of all emitted events, refer to the [Events](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-web-events#all-available-events) page.

## Properties

| Name | Description |
|---|---|
| `deviceId` | The device's id, determined by the headless SDK on initialization. |
| `lang` | The current Client's language configuration. If lang is passed in configuration, it becomes read-only. |
| `chat` | Only has a value when there is an ongoing chat. |
| `cobrowse` | The underlying CobrowseIO client, available after cobrowse has been initialized |

## Events

For a list of all emitted events, refer to the [All available events](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-web-events) page.

| Name | Description |
|---|---|
| `destroy` | Destroys the communicator and all event listeners. |
| `on` | Adds event handler for provided event. |
| `off` | Removes event handler for provided event. |

Use the `.destroy` method to remove iframe and all event listeners:

    client.destroy()

Use the `.on` method to track the events:

    client.on('chat.updated', someFunc)

Remove the event handler with `.off`:

    client.off('chat.updated', someFunc)

## Reference implementation

For a reference implementation of the web SDK, see
[ccaas-web-headless-sdk-sample](https://github.com/ayushbisaria/ccaas-web-headless-sdk-sample.git)
on GitHub.

This repository contains a demonstration of a chat application built using a
CCAI Platform Web Headless SDK. It showcases a basic client-server
architecture where the Node.js backend handles secure authentication and
configuration delivery, while the pure JavaScript frontend provides the chat
user interface.