Control Widget With Code

How to open the bot programmatically

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

---

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

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.