Website widget

The website widget is a floating chat button that appears on your site. Customers click it to start a conversation with your AI bot. Responses stream in real time, token by token.

Setting up

In the dashboard → Chatbot → Channels → Add channel → Website widget.

Enter the domain where you'll embed the widget (e.g., mysite.com). A unique widget token is generated.

Embedding

Copy the embed snippet and paste it before </body> on every page you want the widget to appear:

<script
  src="https://widget.vlozi.app/loader.js"
  data-token="wt_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
></script>

That's it. The widget loads asynchronously — it doesn't block page render.

Visitor opens your page — the loader script fetches the widget UI
Visitor clicks the chat button and types a message
The widget sends the message to /chat/widget/message with the widget token
The Chat Engine validates the token, checks credits, and starts streaming the response
Tokens appear in the chat UI in real time (Server-Sent Events)
The session ID is stored in the visitor's browser session storage — refreshing the page resumes the same session

Session continuity

Sessions persist across page navigation within the same browser tab session. If the visitor closes the tab and comes back, a new session starts.

The session ID is passed back on the first SSE event:

event: session
data: {"session_id": "sess_01j..."}

Store this and pass it on subsequent messages to maintain conversation context.

SSE event reference

Event	Payload	When
`session`	`{ session_id }`	First event — use this to store the session ID
`token`	`{ text }`	Each token of the AI response (streaming)
`usage`	`{ inputTokens, outputTokens, modelTier, fallback }`	After the last token
`done`	`{ session_id, message_id, latency_ms }`	Response complete
`error`	`{ code, message }`	Error (insufficient credits, timeout, etc.)

Non-streaming fallback

If SSE isn't available in your environment, use the non-streaming endpoint:

POST /chatbot/chat/widget/send
Content-Type: application/json
 
{
  "widget_token": "wt_XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "What are your opening hours?",
  "session_id": "sess_01j..."
}

Response:

{
  "response": "We're open Monday–Friday, 9 AM–6 PM IST.",
  "session_id": "sess_01j..."
}

You can pause a channel without deleting it:

Dashboard: Chatbot → Channels → [channel] → Pause

Or via the API:

PATCH /chatbot/channels/:channelId/status
Content-Type: application/json
 
{ "status": "paused" }

When paused, the widget token still validates but messages return the fallback message instead of an AI response.

Customisation

The widget appearance (colors, position, button icon) is configured in Chatbot → Settings → Widget Appearance. Changes apply to all website widget channels under the same account.

The welcome message shown when the chat is first opened is set in Chatbot → Configuration → Welcome message.