Widget Embed
How to embed a Zeiko website-widget channel for customer-facing agents.
You can embed any Zeiko agent as a chat widget on your website, allowing visitors to interact with a scoped support, sales, or commerce specialist 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 Zeiko Ecommerce storefront specialist 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
- subtle reply sounds when a new agent or human message arrives while the visitor is in another tab or the app window is unfocused
- subtle interaction feedback for opening, docking, sending, and switching tabs
- a larger image-based Shopify storefront launcher so the collapsed Chat entry point is easier for shoppers to notice
- 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" |
data-launcher-image | Optional collapsed launcher image URL | data-launcher-image="/chat.png" |
data-launcher-image-alt | Accessible label for a custom launcher image | data-launcher-image-alt="Open chat" |
data-launcher-image-width | Custom launcher image width in pixels | data-launcher-image-width="121" |
data-launcher-image-height | Custom launcher image height in pixels | data-launcher-image-height="65" |
data-home-actions | Shopify storefront Home tab question JSON string | data-home-actions='["Returns?"]' |
Supported positions are bottom-right, bottom-left, top-right, top-left, middle-right, middle-left, top-center, and bottom-center.
Shopify storefront widgets use Zeiko's built-in black Chat image launcher by default. Manual embeds can override the launcher image with the data-launcher-image* attributes above; the host iframe reserves enough collapsed space for the configured image so the launcher is not clipped. If a visitor docks the launcher to middle-left or middle-right, the widget uses the compact side tab instead of the image pill.
Visitors can drag the collapsed launcher to any supported dock position. The selected dock is stored locally per agentId + parentOrigin, so the launcher returns to that edge on the same customer site without changing the merchant's default embed setting.
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. Reply sounds use the browser's normal audio permission model, so they are only eligible after the visitor has interacted with the page or widget and they stay silent while the tab is active and focused.
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
- closed human handoffs show that the live support chat is closed and the visitor can continue with the AI assistant
- 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.