Control Widget With Code

You can programmatically open the Octocom chat widget from anywhere in your site. This allows you to connect the chat experience to your own buttons, menus, or custom logic.

When triggered, the widget will appear in the corner of the page as usual.

Example use cases include:

• Connect website search bar to the bot
• Open the bot in a web app
• Advanced workflows including
  • Age detection workflows
  • Skincare suggestions
  • Recommending furniture for a given room

Showing a hidden widget

In Settings → Channels → Web Chat → Deployment, enable Hidden by default for the configuration. This is an advanced setting: the launcher and chat stay hidden until your JavaScript shows or opens the widget. The question mark next to the setting explains the behavior and links to this guide.

Dispatch showWidgetEvent with type SHOW_OCTOCOM to reveal the widget without opening the chat panel:

document.dispatchEvent(
  new CustomEvent("showWidgetEvent", {
    detail: { type: "SHOW_OCTOCOM" },
  }),
);

• The launcher becomes visible; the visitor can click it to start chatting.
• This does not send a message, record a chat open, or write interaction storage.
• Repeating the event is safe. An already open chat stays open.
• The event applies to all widget instances on the page. Visibility is kept in memory for this page load; a fresh page load starts hidden again.
• Deployment rules and support hours still apply.

Run this after the widget has loaded its configuration. The simplest option is Settings → Advanced → Custom JavaScript, which runs even while the widget is hidden. For example, reveal it after your own asynchronous eligibility check:

octocom.on("widget:ready", async function () {
  try {
    // Your site's endpoint: return { eligible: true } to show the widget.
    const response = await fetch("/api/chat-eligibility");
    if (!response.ok) return;
    const result = await response.json();
    if (result.eligible === true) {
      document.dispatchEvent(
        new CustomEvent("showWidgetEvent", {
          detail: { type: "SHOW_OCTOCOM" },
        }),
      );
    }
  } catch (error) {
    // Leave the widget hidden when eligibility cannot be checked.
    console.error("Could not check chat eligibility", error);
  }
});

The endpoint above is an example to implement on your website, not a built-in Octocom endpoint. You can replace it with your own logic. Events dispatched before the widget initializes are not queued. Page scripts can listen for octocom:widget:ready when Custom JavaScript is enabled; snippets can use octocom.on("widget:ready", ...), which also works after readiness has fired.

Hidden by default disables automatic opening on configured paths, timed automatic opening, and restoring an open chat from a previous visit. Explicit opening still works: openChatEvent, open-widget links, data-open-window="true", and embedded or hosted chat pages can open the chat directly. This setting controls visibility; it is not an access restriction. Use showWidgetEvent when you want only the launcher to appear, or openChatEvent below when you want to open the panel.

Triggering the widget

To open the chat, dispatch a CustomEvent named openChatEvent:

const event = new CustomEvent("openChatEvent", {
  detail: {
    type: "OPEN_OCTOCOM",
    message: {
      content: "some text",
      imageUrl: "some URL",
    },
  },
});

document.dispatchEvent(event);

Example: Open chat on button click

<button
  onClick={() => {
    const event = new CustomEvent("openChatEvent", {
      detail: {
        type: "OPEN_OCTOCOM",
        message: {
          content: "Hello, I need help with my order.",
        },
      },
    });
    document.dispatchEvent(event);
  }}
>
  Open Assistant
</button>

Clicking the button opens the chat widget and sends a pre-filled customer message.

Behavior

• Without a message object The widget simply opens without sending any message.
• With a message object A customer message is created inside the chat when it opens.

Parameters

Connecting your own logic

You can dispatch the openChatEvent from anywhere in your application:

• Buttons or links
• Menu actions
• Custom triggers (timeouts, API responses, etc.)

For example, automatically opening the chat after an error:

if (hasCheckoutError) {
  document.dispatchEvent(
    new CustomEvent("openChatEvent", {
      detail: {
        type: "OPEN_OCTOCOM",
        message: {
          content: "I ran into an issue during checkout.",
        },
      },
    }),
  );
}

Running your own JavaScript

Beyond opening the chat, a configuration can carry its own JavaScript snippet that subscribes to widget events (opened, message sent, handed off, ...) and attaches data to the conversation. See Custom JavaScript.

Important note

If all you need is to open the widget by clicking a link/button, it might be simpler to use a link instead. See the relevant guide here.

✅ That’s all you need to wire your site’s logic to the Octocom chat widget.