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.
Shopify Storefronts
Shopify merchants should deploy the Shopify Agent from the Zeiko app inside Shopify admin instead of manually adding the hosted script.
The Shopify flow prepares the storefront widget channel automatically, installs or updates the Shopify theme app embed, and keeps customization inside the Shopify app. After deployment, enable the Zeiko app embed in the Shopify theme editor if it is not already active, then use Widget settings in the Shopify app to update the title, greeting, theme, position, and Home tab questions.
The storefront still uses Zeiko's website-widget runtime behind the scenes, but Shopify users do not need to choose or manage it as a separate deployment channel.
The current widget behavior also includes:
- persisted conversation continuity across refreshes for the same visitor/session
- stable conversation continuity per
agentId + parentOrigin - a mobile-first fullscreen shell on phones, with keyboard-aware viewport sizing
- live human handoff thread sync when a support operator joins the conversation
- local offline queueing and automatic replay when the browser reconnects
- snapshot sync that waits briefly for the canonical turn order so messages do not jump around
- long-thread windowing so older messages can be revealed incrementally instead of rendering the entire transcript at once
- markdown/rich-text rendering for agent and human replies
- Shopify storefront product cards render inside the chat transcript so commerce results scroll with the conversation
- Shopify storefront starter prompts send immediately when selected
- response guardrails that keep very large streamed replies responsive by falling back to a static render when needed
- 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" |
Supported positions are bottom-right, bottom-left, top-right, top-left, middle-right, middle-left, top-center, and bottom-center.
Closing the widget docks it back to the configured edge launcher instead of hiding the launcher. Mobile browsers that support the Web Vibration API receive subtle haptic feedback for opening, docking, and switching widget tabs; unsupported browsers ignore it automatically.
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
- the customer's queued message remains visible if connectivity drops, then replays automatically when the browser reconnects
- the thread keeps its current order while the widget waits for a canonical snapshot, which reduces message jumping during fast multi-turn chats
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.