Customisation

Script Tag Embed

Full reference for the Bounds widget script tag. The minimal one-liner gets you a working widget; the attributes below let you customise its behaviour and appearance without touching any JavaScript.

Minimal embed

<script
  src="https://cdn.bounds.ai/widget.js"
  data-agent-id="agt_your_key_here"
  defer
></script>

All attributes

Attribute	Required	Description
`data-agent-id`	Yes	Your agent's public key (`agt_` prefix). Safe to expose in HTML.
`data-session-token`	No	A signed session token from your server. Enables user-scoped actions. Omit for anonymous sessions.
`data-placeholder`	No	Placeholder text in the message input. Defaults to the value set in agent settings.
`data-primary-color`	No	Hex colour for the widget launcher button and accent elements. Example: `#0f766e`. Overrides the colour set in agent settings.
`data-open`	No	Set to `true` to start the widget in the open state on page load.

JavaScript API

After the script loads, window.Bounds exposes a small API:

Method	Description
`window.Bounds.open()`	Programmatically open the chat panel.
`window.Bounds.close()`	Programmatically close the chat panel.
`window.Bounds.reset()`	End the current session and clear local state. Call before a user logs out to prevent session bleed between accounts.

DOM events

The widget dispatches custom events on window so you can integrate with your own analytics or state management:

Event	Fires when
`bounds:open`	User opens the chat panel.
`bounds:close`	User closes the chat panel.
`bounds:escalate`	User requests to speak to a human. Event detail includes the session ID.
`bounds:message`	A message is sent or received. Event detail includes role and content.

window.addEventListener('bounds:escalate', (e) => {
  analytics.track('support_escalated', { sessionId: e.detail.sessionId });
});