Event listeners

Once the embed script is on your page it exposes a global, window.bookbag, that emits real-time chat events. Register listeners to drive analytics, route leads, sync your UI, or react when the agent calls a tool. For reliable server-side awareness (a lead was captured even if the tab closed), use webhooks.

Registering listeners

window.bookbag.addEventListener(eventName, callback);
window.bookbag.removeEventListener(eventName, callback);

Each callback receives an event object of the shape { type, data }.

Available events

Example

function onUserMessage(e) {
  console.log("User said:", e.data.content);
  window.analytics?.track("chat_user_message", { text: e.data.content });
}
function onAssistantMessage(e) {
  console.log("Agent replied:", e.data.content);
}

window.bookbag.addEventListener("user-message", onUserMessage);
window.bookbag.addEventListener("assistant-message", onAssistantMessage);

// Later (e.g. on SPA route change):
window.bookbag.removeEventListener("user-message", onUserMessage);

Reacting to tool calls

tool-call and tool-result let you observe what the agent is doing. On Shopify, the storefront cart bridge uses tool-call to add items to the live cart — you can hook the same event to fire analytics when the agent recommends or adds a product.

Controlling the widget

The same global opens, closes, and resets the widget — see JavaScript embed for window.bookbag('open'), ('close'), ('toggle'), and ('resetChat').

Server: webhooks for reliable events

Browser events live only as long as the tab is open. For anything you must act on — a lead was captured, a conversation ended — use webhooks: server-to-server, signed, and delivered regardless of the browser.