Widget parameters

Script tag

Every option works two ways: as a query parameter on the widget.js URL, or as a data-<name> attribute on the script tag. Query parameters win when both are present, and they survive tag managers that strip attributes.

Option	Values	Does
`agent`	embed name	Required. Which agent answers. Any name the agent has ever had resolves to it, so renaming never breaks a live tag.
`position`	`left`, `right`	Which corner the launcher sits in. Overrides the agent setting.
`lang`	language code	Pins the interface language instead of following the visitor.
`offset-bottom`	pixels	Moves the launcher up, clear of something else.
`offset-side`	pixels	Moves the launcher in from its edge.
`q`	text	Pre-fills the input. Never sent automatically.
`page`	URL	The page to attribute the conversation to. For iframes.
`mode`	`embed`, `fullpage`	Set by the hosted chat page; not normally used by hand.
`api`	origin	Overrides where API calls go. Defaults to wherever `widget.js` was served from.

<script src="https://engadin.ai/widget.js?agent=acme&position=left&offset-bottom=90" defer></script>

CSS custom properties

Read live from the page, so they can change with your own state and the launcher animates between positions:

Property	Does
`--eng-offset-bottom`	Distance from the bottom edge.
`--eng-offset-side`	Distance from the left or right edge.

body:has(.to-top-button.is-visible) { --eng-offset-bottom: 96px; }

Opening the chat from the page

Attribute	Does
`data-engadin-open`	Clicking the element opens the chat.
`data-engadin-open="<question>"`	Opens it with that question pre-filled.

A ?engadin_q=<question> parameter on any page URL does the same thing, which lets a plain link from elsewhere on your site open the chat with a question ready.

JavaScript API

Call	Does
`window.engadin.open()`	Opens the chat.
`window.engadin.open('<question>')`	Opens it and types that question into the input.
`window.engadin.open({ prefill: '<question>' })`	The same, object form.
`window.engadin.close()`	Closes the panel. No effect on the full-page chat.

Pre-filled text is never sent: the visitor still presses send. Input is whitespace-collapsed and capped at 600 characters. Calls made before the widget has finished booting are queued rather than dropped.

For an iframe embed, the host page reaches the same behaviour with a message to the frame:

frame.contentWindow.postMessage(
  { type: 'engadin-prefill', prefill: 'Do you ship to Switzerland?' },
  'https://engadin.ai'
);

See suggesting a question from JavaScript for worked examples.

Hosted chat page

https://engadin.ai/chat

Parameter	Does
`agent`	Which agent. Required on the platform’s domain; a workspace’s own domain falls back to its first agent.
`embed`	`1` renders the compact variant, without the sidebar. For iframes.
`lang`	Pins the language.
`page`	The real page an iframe sits on, for attribution.
`q`	Pre-fills the input.

<iframe src="https://engadin.ai/chat?agent=acme&embed=1&page=https%3A%2F%2Fexample.com%2Fpricing"
        style="width:100%;height:640px;border:none"
        allow="microphone"></iframe>

Events

Every event goes out three ways at once: pushed to window.dataLayer as engadin_<name>, dispatched on window as an engadin CustomEvent, and posted to the parent window from inside an iframe.

window.addEventListener('engadin', (e) => {
  e.detail; // { event: 'message_rated', agent: 'your-agent', rating: 'up' }
});

Every payload has event and agent. Some carry one extra field:

Event	Extra	When
`widget_loaded`		The script booted and the launcher exists.
`chat_opened`	`via`: `launcher`, `teaser`, `auto`, `deeplink`, `api`	The panel opened. Fires on every open.
`chat_closed`		The panel closed.
`chat_restored`		A returning visitor’s conversation was reloaded.
`conversation_started`		The first message of a new conversation.
`conversation_started_suggested`		That first message came from a suggested question, and fires alongside the previous one.
`suggested_question_clicked`		A suggestion chip was clicked.
`message_sent`		Any message the visitor sent.
`voice_message_sent`		That message came from voice, and fires alongside `message_sent`.
`message_rated`	`rating`: `up`, `down`	Thumb pressed on an answer.
`rating_reason`	`reason`: `wrong`, `incomplete`, `outdated`	A reason chosen after a thumb down.
`lead_created`		A conversation produced a new lead.
`lead_updated`		An existing lead gained details.
`link_clicked`	`url`	A link inside the conversation was clicked.
`attachment_uploaded`		A visitor attached a file.
`ticket_offer_shown`		The assistant offered to open a ticket.
`ticket_created`		The visitor took it.
`chat_downloaded`		The visitor saved the conversation as a text file.
`chat_emailed`		The visitor had the conversation mailed to an address they typed.
`action_run`	`action`: slug	A custom action started mid-reply.
`action_ok`	`action`: slug	It succeeded.
`action_failed`	`action`: slug	It failed or timed out.
`teaser_shown`		A proactive teaser bubble appeared.
`teaser_dismissed`		The visitor dismissed it.
`voice_chat_opened`		Voice mode was opened.
`error_shown`		The visitor saw an error message.

Never any message content, and nothing a visitor typed. link_clicked carries the destination URL only.

For iframe embeds, add the bridge script next to the frame so the same events reach the host page:

<script src="https://engadin.ai/widget-events.js" defer></script>

On a custom domain, widget.js, widget-events.js, /chat and the API all answer on your own hostname as well. Use it in all of them, so every request stays first-party.

See analytics events for the Google Tag Manager setup.

Other public URLs

URL	What
`/api/health`	Liveness plus the active model provider.
`/help/microphone`	Visitor-facing help for a blocked microphone. `?lang=de` for German.