Embedding the assistant
Two installs — a script tag for any HTML page, or the React package — both rendering the same interface.
The assistant ships in two forms. A script tag drops into any page that can serve HTML, with no build step. The React package suits applications that already have one and want to render their own components for server-described cards. Both mount the same view from the same source, so they cannot behave differently.
The script tag
<script src="https://console.flozentai.com/embed/v1.js"
data-gateway-url="https://gateway.flozentai.com"
data-deployment-id="YOUR_DEPLOYMENT_ID"
data-token-url="/flozentai/token"
defer></script>| Attribute | Required | What it does |
|---|---|---|
| data-gateway-url | Yes | The gateway origin the runtime is reachable at. |
| data-deployment-id | Yes | The approved deployment this assistant runs. |
| data-token-url | Yes | An endpoint on your own origin that returns a gateway token. |
| data-target | No | CSS selector to mount into. Omit for a floating launcher. |
| data-title | No | Heading shown in the assistant panel. |
| data-welcome | No | The line shown before the first message. |
| data-suggestions | No | Up to four starter prompts, separated by a vertical bar. |
| data-theme | No | light or dark. Defaults to light. |
| data-accent | No | indigo or teal. Defaults to indigo. |
| data-placement | No | inline or floating. Inferred from data-target. |
The token endpoint
The widget calls the URL in data-token-url with same-origin credentials, so the session cookie you already set authenticates the request. Your endpoint performs the token exchange and returns the result. Tokens are held in memory and refreshed thirty seconds before they expire.
{
"accessToken": "…",
"expiresIn": 300
}Snake case is accepted too, so an endpoint already returning access_token and expires_in works without changes.
Style isolation
The widget renders inside a shadow root. Your page cannot restyle the assistant by accident, and the assistant cannot leak styles into your page — which matters because a script tag lands in markup neither side fully controls. Theming happens through the documented attributes rather than by overriding selectors.
Controlling it from JavaScript
The script defines window.FlozentAi. Use it to mount manually, to pass page context the agent may read, or to register components for server-described cards.
// Give the agent context from the current screen.
window.FlozentAi.setContext('page', {
screen: 'invoice',
invoiceId: currentInvoice.id,
});
// Render a server-described card without a component framework.
window.FlozentAi.registerComponent({
name: 'invoice-summary',
version: '1',
schemaId: 'invoice-summary@1',
render(container, props) {
container.textContent = `Invoice ${props.number}`;
},
});The React package
import { FlozentAiProvider, FlozentAiAssistant } from '@flozentai/react';
import '@flozentai/widget/styles.css';
<FlozentAiProvider
identityKey={sessionKey}
options={{ gatewayUrl, deploymentId, getAccessToken }}
>
<FlozentAiAssistant placement="floating" />
</FlozentAiProvider>Change identityKey whenever the signed-in user, tenant, application or environment changes — it resets the session rather than letting one person continue another person’s conversation. React consumers render in the light DOM and style the assistant with the shared stylesheet, because a React application controls its own page.