Widget Embed
How to embed a Zeiko AI agent chat widget on your website.
You can embed any Zeiko agent as a chat widget on your website, allowing visitors to interact with your AI agent directly.
The Website Widget is the customer-facing chat surface. It is different from Zeiko's internal In-app Chat, which is meant for workspace operators and testing.
Recommended Embed Method
Use the hosted Zeiko widget script on your site:
<script src="https://zeiko.io/widget.js" data-agent-id="YOUR_AGENT_ID" data-title="Support" data-greeting="Hi! How can I help you today?" data-theme="light" ></script>
Replace YOUR_AGENT_ID with the agent ID from your workspace.
The script handles the widget iframe, conversation continuity, and boot configuration for you. This is the best option for most websites.
The current widget behavior also includes:
- persisted conversation continuity across refreshes for the same visitor/session
- live human handoff thread sync when a support operator joins the conversation
- markdown/rich-text rendering for agent and human replies
- a footer badge that reads Powered by Zeiko and links back to zeiko.io
Configuration Options
Customize the widget with script attributes:
| Parameter | Description | Example |
|---|---|---|
data-agent-id | Required agent ID | data-agent-id="YOUR_AGENT_ID" |
data-title | Widget header title | data-title="Support" |
data-greeting | Initial greeting message | data-greeting="Hi! How can I help?" |
data-theme | Color theme (light or dark) | data-theme="dark" |
data-token | Optional channel token | data-token="your-token" |
data-position | Widget position | data-position="bottom-right" |
Advanced Option: Direct Widget URL
If you need to embed the widget manually, the hosted widget page is available at:
https://zeiko.io/widget/{agentId}
You can pass query parameters such as title, greeting, theme, parentOrigin, and token. For most customers, the script method above is simpler and more reliable.
Security
- Restrict allowed origins in your agent's Website Widget channel settings
- Use a channel token if your widget is configured to require one
- The widget communicates with Zeiko over HTTPS
Channel Requirements
To use the widget, ensure:
- The agent is active (not paused)
- The Website Widget channel is enabled for that agent
- Any allowed-origin or token settings match the site where you are embedding the widget
- The agent has instructions and knowledge appropriate for website visitors
Live Support Behavior
If a conversation is escalated to a human:
- the widget stays on the same conversation thread
- operator replies appear back in the widget conversation
- active human-owned handoffs suppress normal bot follow-up replies
- the widget no longer pretends the bot is typing when the thread is already in a live human handoff state
If no live support target is configured for the widget handoff flow, the widget will still capture the request and show that follow-up is pending rather than presenting it as an active live-chat thread.
Webflow Integration
For Webflow sites, connect Webflow from Integrations in your workspace, then enable the Website Widget channel on the agent you want to embed.