Widget integration

Overview

The Zephlo widget is a drop-in chat experience that connects your website visitors to your AI agent. It runs as a Web Component with full Shadow DOM isolation, so it won’t interfere with your existing styles or scripts. There are two ways to add the widget to your site:

Script tag

Paste one line of HTML. No build tools needed.

SDK (npm)

Full programmatic control with TypeScript support.

Script tag

The fastest way to get started. Add a single <script> tag with your agent’s ID before your closing </body> tag:

index.html

<script
  src="https://unpkg.com/zephlo/dist/zephlo.js"
  data-chatbot-id="YOUR_AGENT_ID"
></script>

That’s it. When the script tag carries a data-chatbot-id, the widget auto-injects a floating chat button into the page, fetches its configuration from the Zephlo API, and opens a chat session for each visitor.

Attributes

Attribute	Required	Description
`data-chatbot-id`	Yes	Your agent’s UUID from the dashboard

You’ll find your agent’s ID and API key in the Dashboard under your agent’s Settings. Always use the agent’s UUID, not a numeric id.

The widget talks to https://app.zephlo.ai by default. To point it at a self-hosted or staging API, set a global before the script loads: <script>window.FLAPI = "https://your-api.example.com";</script>. With the SDK, pass the apiUrl option instead.

SDK (npm)

Install the package from npm for full programmatic control:

npm install zephlo

Then initialize in your application and place a widget element where you want it to render:

app.ts

import Zephlo from "zephlo";

const zephlo = Zephlo.initialize({
  key: "flk_your_api_key",        // required
  chatbotId: "YOUR_AGENT_ID",     // required
});

index.html

<!-- A floating chat button in the corner of the page -->
<zephlo-fab></zephlo-fab>

With the SDK, Zephlo.initialize() only configures the widget — it does not render anything on its own. You must add a <zephlo-fab> or <zephlo-chat> element to your HTML. (The plain script-tag integration above injects the <zephlo-fab> for you.) See Choosing a layout.

You can also use the SDK inline with the script tag (no npm required):

index.html

<script src="https://unpkg.com/zephlo/dist/zephlo.js"></script>
<zephlo-fab></zephlo-fab>
<script>
  const zephlo = Zephlo.initialize({
    key: "flk_your_api_key",
    chatbotId: "YOUR_AGENT_ID",
  });
</script>

Options

Option	Type	Required	Description
`key`	`string`	Yes	Your API key (must start with `flk_`)
`chatbotId`	`string`	Yes	Your agent’s UUID
`apiUrl`	`string`	No	Custom API base URL. Defaults to `https://app.zephlo.ai`
`theme`	`object`	No	Colors and light/dark mode. See Theming

The initialize call returns a handle you can use to send page context, register tools, scan forms, fire proactive triggers, control theming, and listen for events:

// Send page context so the agent knows where the visitor is
zephlo.sendContextUpdate({ page: "pricing", plan: "Pro" }, true);

// Listen for tool results from the agent
const unsubscribe = zephlo.onToolResult((results) => {
  console.log("Agent used tools:", results);
});

Calling Zephlo.initialize() more than once on the same page is a no-op. The widget prevents duplicate instances automatically.

Choosing a layout

Place one of two custom elements to control how the widget appears. Both connect to the same agent and share the same conversation, so you can even use both on one page.

<zephlo-fab>

A floating action button pinned to the corner of the page. Clicking it opens the chat panel. This is the classic chat-bubble experience.

<zephlo-chat>

An inline chat that fills whatever container you place it in — great for a contact page, a help center, or a docs sidebar.

Floating button

<zephlo-fab></zephlo-fab>

Position, colors, and other appearance settings come from the Dashboard (see Customization).

Inline chat

Drop <zephlo-chat> anywhere in your layout. It expands to fill its parent. Use the optional width and height attributes to size it directly — plain numbers are treated as pixels, or pass any CSS value:

<div class="support-panel">
  <zephlo-chat width="100%" height="540"></zephlo-chat>
</div>

These elements only render once Zephlo.initialize() has been called with your key and agent ID. The plain script-tag integration sets this up automatically and injects a <zephlo-fab> for you.

How it works

Once loaded, the widget follows this sequence:

Fetch configuration

The widget calls GET /api/public/agents/{id}/config to retrieve your agent’s appearance settings, welcome message, quick prompts, and feature flags.

Create a session

A chat session is created via POST /api/session. The session ID is stored in localStorage so returning visitors resume their conversation.

Open a WebSocket

A persistent WebSocket connection is established at /ws/chat for real-time messaging between the visitor and your agent.

Ready to chat

The widget renders. Visitors can type messages, use voice input, and interact with any registered tools.

Customization

All visual customization is managed from the Dashboard. The widget automatically picks up your settings at load time, including:

Position — bottom-right, bottom-left, left sidebar, or right sidebar
Colors — header, user bubbles, assistant bubbles, text
Typography — any Google Font, custom font size
Dimensions — panel width and height
Branding — custom logo or emoji icon
Welcome message — greeting text shown on first open
Quick prompts — clickable suggestion chips
Greeting prompts — animated suggestions that appear before the visitor opens the chat
Voice — enable speech-to-text input and text-to-speech responses

On mobile screens narrower than 440px, the widget automatically expands to full screen for a better experience.

If you use the SDK, you can also override colors and light/dark mode at runtime — see Theming.

Call destroy() on the SDK handle to close the connection and tear the widget down. This is useful in single-page apps when unmounting a view:

zephlo.destroy();

TypeScript support

The SDK ships with full type definitions. If you’re using the script tag approach and need types for event handling, you can install the package as a dev dependency:

npm install --save-dev zephlo

Then import the types you need:

import type { ZephloInstance, ToolDefinition, McpToolResult } from "zephlo";

Next steps

Register tools

Give your agent the ability to take actions on your website.

Form tools

Turn any HTML form into an agent-callable tool with zero JavaScript.

Page context

Send page context so the agent gives smarter, more relevant answers.

Proactive triggers

Have the agent reach out to visitors first.

Theming

Match the widget’s colors and mode to your brand.

Getting started

Widget

Widget integration

Overview

Script tag

SDK (npm)

Script tag

Attributes

SDK (npm)

Options

Choosing a layout

<zephlo-fab>

<zephlo-chat>

Floating button

Inline chat

How it works

Customization

Removing the widget

TypeScript support

Next steps

Register tools

Form tools

Page context

Proactive triggers

Theming

​Overview

Script tag

SDK (npm)

​Script tag

​Attributes

​SDK (npm)

​Options

​Choosing a layout

<zephlo-fab>

<zephlo-chat>

​Floating button

​Inline chat

​How it works

​Customization

​Removing the widget

​TypeScript support

​Next steps

Register tools

Form tools

Page context

Proactive triggers

Theming

Overview

Script tag

Attributes

SDK (npm)

Options

Choosing a layout

Floating button

Inline chat

How it works

Customization

Removing the widget

TypeScript support

Next steps