Widget Script Reference

Every script attribute, iframe parameter, and query-string override for the embed widget.

Script embed

HTML

<script
  src="https://your-mozo-domain.com/embed/widget.js"
  data-agent-id="YOUR_AGENT_ID"
  data-position="right"
  async
></script>

The script is served from /embed/widget.js. On load, it injects a fixed-position <iframe> pointing at /widget/{agentId} into document.body.

Script attributes

Attribute	Required	Description
`data-agent-id`	Yes, unless `data-embed-url` is set	The agent to load
`data-embed-url`	No	Full iframe URL override, replacing the default `/widget/{agentId}` URL
`data-position`	No	`"left"` or `"right"` (default `"right"`) — which corner the widget docks to

The injected iframe is fixed at 360×600px, bottom: 16px, with z-index: 2147483647 so it stays above your page's other content. It's sandboxed with allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-same-origin.

Iframe embed

If you'd rather control placement yourself instead of a floating widget, embed the iframe directly:

HTML

<iframe
  src="https://your-mozo-domain.com/widget/YOUR_AGENT_ID"
  style="width:360px;height:600px;border:none;"
></iframe>

Query parameter overrides

Both the default widget iframe and a manually embedded iframe accept query parameters that override the agent's saved widget configuration for that specific embed:

Parameter	Description
`primary`	Primary color (hex, URL-encoded, e.g. `%236366F1`)
`accent`	Accent color
`background`	Background color
`text`	Text color
`brand`	Brand name override
`logo`	Logo URL override
`profilePicture`	Profile picture URL override
`welcome`	Welcome message override
`alignment`	Chat bubble alignment: `left` or `right`
`embed`	Set to `floating` for the floating widget layout

Example:

Code

https://your-mozo-domain.com/widget/YOUR_AGENT_ID?primary=%236366F1&alignment=right&embed=floating

Anything not overridden by a query parameter falls back to the agent's saved configuration from the Embed Widget settings page.

Security

Widget and hosted-page chat requests are authenticated with a short-lived signed session token (header x-widget-session) and checked against the agent's origin allowlist. See Security & Access Control for how to configure allowed origins, since embeds on domains not in the allowlist will be blocked.

PreviousIntegration Overview NextCustom Actions Reference