> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zephlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Add the Zephlo widget to a page with tools, forms, and page context in under 5 minutes

## 1. Install and initialize

Add the script tag, call `Zephlo.initialize()` with your API key and agent ID, and drop in a `<zephlo-fab>` element where the floating button should appear.

```html theme={null}
<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>
```

Or install from npm:

```bash theme={null}
npm install zephlo
```

```javascript theme={null}
import Zephlo from "zephlo";

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

The widget renders, fetches its settings, and opens a WebSocket to your agent. Prefer an embedded chat instead of a floating button? Use `<zephlo-chat>`. [Full integration docs →](/widget/integration)

***

## 2. Register a tool

Give the agent an action it can take on your site with `registerTool()`.

```javascript theme={null}
zephlo.registerTool({
  name: "navigate_to_page",
  description: "Navigate the visitor to a page on the site",
  inputSchema: {
    type: "object",
    properties: {
      url: { type: "string", description: "The URL to navigate to" },
    },
    required: ["url"],
  },
  execute({ url }) {
    window.location.href = url;
    return `Navigating to ${url}`;
  },
});
```

Now when a visitor asks "take me to the pricing page", the agent calls your function. [Full tools docs →](/widget/tools)

***

## 3. Add a form tool

Add `zephlo-tool-name` and `zephlo-tool-description` to any existing form — no JavaScript needed.

```html theme={null}
<form zephlo-tool-name="contact_sales"
      zephlo-tool-description="Fill out the contact form for the visitor">
  <input name="name" placeholder="Your name" required />
  <input name="email" type="email" placeholder="Work email" required />
  <button type="submit">Contact sales</button>
</form>
```

The widget detects the form automatically and registers it as a tool the agent can fill out. [Full form docs →](/widget/forms)

***

## 4. Send page context

Tell the agent where the visitor is so it can give relevant answers.

```javascript theme={null}
zephlo.sendContextUpdate({
  page_type: "pricing",
  highlighted_plan: "Pro",
}, true); // true = also include URL, title, and meta description
```

Now if a visitor asks "what's included?", the agent already knows they're looking at the Pro plan. [Full context docs →](/widget/page-context)

***

## Next steps

<CardGroup cols={2}>
  <Card title="Widget integration" icon="puzzle-piece" href="/widget/integration">
    Script tag vs npm SDK, configuration, and customization.
  </Card>

  <Card title="Register tools" icon="wrench" href="/widget/tools">
    Full tool API reference with more examples.
  </Card>

  <Card title="Form tools" icon="rectangle-list" href="/widget/forms">
    Form attributes, auto-submit, and dynamic detection.
  </Card>

  <Card title="Page context" icon="map-pin" href="/widget/page-context">
    Context API, auto page details, and SPA examples.
  </Card>

  <Card title="Proactive triggers" icon="bell" href="/widget/triggers">
    Have the agent reach out to visitors first, with cooldowns.
  </Card>

  <Card title="Theming" icon="palette" href="/widget/theming">
    Control colors and light/dark mode from the SDK.
  </Card>
</CardGroup>