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

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

Field	Type	Required	Description
`type`	string	✅	Must always be `"OPEN_OCTOCOM"`.
`message`	object	❌	Optional object defining the initial customer message.
├─ `content`	string	✅ (if `message` provided)	The text of the customer’s message.
└─ `imageUrl`	string	❌	A URL to a user-uploaded image to include with the message.

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.",
        },
      },
    }),
  );
}

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.