Custom JavaScript

Each web chat configuration can carry its own JavaScript snippet. Open Settings → Advanced → Custom JavaScript, pick the configuration, turn it on and paste the code in. A business with several configurations (different deployments) runs a different snippet on each.

Use it to connect the widget to the rest of your site — analytics and tag managers, your CRM, cart state, or anything the bot and your agents should know about the visitor.

How it runs

The snippet runs once per page load, as soon as the widget has loaded its configuration, in the page's own scope — the same place your other site scripts run. It is served with the public widget configuration, so treat it as public and never put secrets or API keys in it.

A snippet that throws is caught and logged to the console as [octocom] custom script failed — it cannot break the widget or your page. In DevTools the snippet appears as octocom-custom-script.js, so you can set breakpoints in it.

Widget events

Inside the snippet, window.octocom is an event emitter:

octocom.on("message:sent", function (event) {
  window.dataLayer.push({ event: "chat_message_sent", text: event.text });
});

octocom.on("handoff", function (event) {
  myCrm.flagConversation(event.publicId);
});

octocom.on returns an unsubscribe function, and octocom.off(name, handler) does the same job. widget:ready, conversation:started and handoff are replayed to handlers that subscribe after they fired, so a late subscription never misses them.

Every event is also dispatched on document as octocom:<name>, if you would rather listen from your own scripts:

document.addEventListener("octocom:message:received", function (event) {
  console.log(event.detail.text);
});

Attaching data to the conversation

octocom.setCustomData writes key-value pairs onto the visitor's conversation. Each pair becomes chat-widget:<key> conversation metadata — the same place Chat Custom Data query parameters land — so it shows up in the dashboard, in custom system prompt sections, in Python actions, and in analytics. The keys email, name and phone additionally identify the customer.

octocom.on("conversation:started", function (event) {
  octocom.setCustomData({
    plan: window.currentUser.plan,
    cart_value: window.cart.total,
    last_order_id: window.currentUser.lastOrderId,
  });
});

If a conversation is already open, the pairs are pushed to it immediately instead of waiting for the visitor's next message. If none is open yet, they are kept and attached when the visitor starts one.

Timing matters if the bot itself has to see the data. conversation:started fires once the visitor has already sent their first message, so the bot's first turn may be underway before the push lands. Set anything the bot needs from a widget:ready handler — or any time before the visitor writes — and use the conversation:started push for data your agents, Python actions and analytics read afterwards.

Up to 25 pairs per call, keys up to 64 characters, values up to 2000. Setting the same key again overwrites it.

Values are coerced to strings, objects are JSON-encoded, and empty keys are dropped. octocom.getCustomData() returns everything currently stored for the visitor, whether it came from a snippet, a query parameter, or localStorage.

Nothing is written to the visitor's device before they open the chat, matching the widget's own storage behavior. See Browser Storage and Consent.

Opening the chat from your own code

To open the widget — with or without a prefilled message — dispatch the openChatEvent described in Control Widget With Code. That works whether or not custom JavaScript is enabled.