AI Chatbot Widget — Integration Guide

How it works

The widget is a self-contained JavaScript module (widget.js). It renders a floating action button (FAB) and a chat panel inside a sandboxed <iframe>, so it never conflicts with the host page's styles or scripts.

The partner page loads widget.js as a type="module" script (required by the current build).
The widget reads configuration from data-* attributes on that script tag.
On first open, it calls POST /welcome on the backend to create a conversation and fetch the welcome message.
Each user message is sent via POST /chat using the thread_id returned by /welcome.
If the backend transfers the conversation to another agent, the widget follows the new agent route automatically.

Quick start

Paste this snippet before </body> on any page. Replace the placeholder values with your own.

<script
    id="ai-chatbot-script"
    type="module"
    src="https://<your-static-web-app>.azurestaticapps.net/widget.js"
    data-tenant-id="your_tenant_id"
    data-agent-id="your_agent_id"
    data-design='{"position":"bottom-right","brand-primary":"#1e293b","brand-accent":"#ef4444"}'>
</script>

Required IDs Use the tenant slug and agent slug provided by your platform team. These are the values for data-tenant-id and data-agent-id.

Configuration attributes

Attribute	Required	Default	Description
`data-tenant-id`	required	—	Your tenant slug from the Agent Studio.
`data-agent-id`	required	—	Agent slug to start the conversation with.
`data-design`	optional	`{"position":"bottom-right","brand-primary":"#1e293b","brand-accent":"#ef4444"}`	Single JSON object for widget styling. Supports `position`, `brand-primary`, and `brand-accent`.
`data-vehicle`	optional	—	Vehicle name shown in the chat header and passed to the agent as `vehicle_id`.
`data-vehicle-price`	optional	—	Passed to the agent as `vehicle_price` in `page_context`.
`data-vehicle-reg`	optional	—	Passed to the agent as `vehicle_reg` in `page_context`.

Branding example

<script
    id="ai-chatbot-script"
    type="module"
    src="https://<your-static-web-app>.azurestaticapps.net/widget.js"
    data-tenant-id="hpl_motors"
    data-agent-id="dealer_assistant"
    data-design='{"position":"bottom-right","brand-primary":"#003087","brand-accent":"#e4002b"}'>
</script>

Vehicle detail page example

Pass structured page data so the agent can answer questions about the specific vehicle being viewed.

<script
    id="ai-chatbot-script"
    type="module"
    src="https://<your-static-web-app>.azurestaticapps.net/widget.js"
    data-tenant-id="hpl_motors"
    data-agent-id="dealer_assistant"
    data-vehicle="2023 Nissan Qashqai"
    data-vehicle-price="24995"
    data-vehicle-reg="EX23 ABC">
</script>

API endpoints used

Method	Path	Purpose
`POST`	`/v1/tenants/{tenant_id}/agents/{agent_id}/welcome`	Creates a conversation and returns the welcome message and `thread_id`.
`POST`	`/v1/tenants/{tenant_id}/agents/{agent_id}/chat`	Sends a user message and returns the agent reply.

Both endpoints require the Azure Functions key as ?code=<key>. The chat endpoint also requires an X-User-Token header — the widget automatically sends a session-scoped UUID if no explicit token is provided.

Implementation checklist

Get your embed URL — the hosted widget.js URL.
Get your tenant and agent IDs — values for data-tenant-id and data-agent-id.
Add the script tag — include the snippet on pages where chat should appear.
Optionally brand and position it — using a single data-design JSON object.
Verify in browser — open the page, start chat, and confirm replies are returned.

Browser support

Any browser that supports ES modules and crypto.randomUUID(): Chrome 92+, Edge 92+, Firefox 95+, Safari 15.4+.