Skip to main content
Use this page when your goal is simple: get the AI Chat Widget live on a website and confirm visitors can start a conversation.
Need the widget to recognize signed-in customers? Open Authentication after installation.

​
Before You Start

You need a from your OpenCX dashboard. This token tells the widget which organization it belongs to. Choose the install path that matches your site:

HTML

Best when you want the fastest website embed.

React

Best when your site already uses React.

Headless

Best when you want your own UI or storage model.

​
Implementation Steps

1

Confirm this is the right path

Choose HTML when you want the default widget on a standard website and do not need to build custom UI from scratch.
2

Add the widget script

Put the widget script in your page head.
index.html
<script defer src="https://unpkg.com/@opencx/widget@latest/dist-embed/script.js"></script>
3

Initialize the widget after the page loads

Call after DOMContentLoaded and pass your widget token.
index.html
<script>
  window.addEventListener('DOMContentLoaded', () => {
    initOpenScript({
      token: '<WIDGET_TOKEN>',
    });
  });
</script>
4

Reload the page and verify the widget

By default, the widget appears as a floating launcher. Open it and send a test message.
Widget does not appear after page load: keep the DOMContentLoaded wrapper unless your site guarantees the widget initializes only after the DOM is ready.

​
Choose How The Widget Appears

These options control what visitors see on the page before they even start chatting.
This is the standard widget behavior. Visitors see a launcher button, click it to open the widget, and close it when they are done.Use this when the widget should be available site-wide without taking up permanent page space.
const options = {
  token: '<WIDGET_TOKEN>',
};
Use this when the widget should live inside a page section, such as a help page, pricing page, portal, or account screen.When is true, the widget stays open inside its parent container and the floating launcher is hidden. In practice, this means the widget becomes part of the page layout instead of hovering over it.
const options = {
  token: '<WIDGET_TOKEN>',
  inline: true,
};
Use this when the widget should already be open on first render, such as inside a webview or a dedicated support page.This changes the initial state only. The visitor can still continue using the widget normally after it opens.
const options = {
  token: '<WIDGET_TOKEN>',
  isOpen: true,
};
Use this when you want the widget to open after the visitor has already spent time on the page.This is best for proactive support moments. It is usually a poor fit for every page on your site because it can feel intrusive if the visitor was not trying to chat.
const options = {
  token: '<WIDGET_TOKEN>',
  openAfterNSeconds: 10,
};

​
Test Your First Conversation

1. Confirm the widget appears

Load the page and verify the launcher or inline widget shows where you expect.

2. Confirm the opening behavior

Check that the widget opens the way you configured it: floating, inline, already open, or delayed.

3. Send a real message

Start a conversation and verify the message reaches your inbox.

4. Reload and return

Refresh the page and confirm the same visitor can continue the conversation on the same device.

​
Good To Know

If browser storage is not the right fit, use from @opencx/widget-core.This matters most in mobile apps, embedded environments, or custom shells where your app already controls how tokens and session data are stored.

​
Where To Go Next

Authentication

Identify signed-in visitors and protect conversation history.

Configuration

Control branding, prompts, behavior, and advanced options.

Conversation Sessions

Understand history, handoff, and returning-visitor behavior.

Custom Components

Replace plain text action replies with richer UI.