# Widget API — Telybot docs

- URL: https://telybot.com/docs/reference-widget
- Last updated: 2026-10-12

## Widget API

For developers, or anyone who wants the chat to open from their own button.

### Installing

```html
<script src="https://telybot.com/widget.js"
        data-key="kb_live_your_key_here" async></script>
```

The script tag needs only `src` and `data-key`. Everything else — colours, position, greeting, language — comes from your dashboard so you never have to redeploy your site to change them.

The widget is drawn in the language set on **Install → Language your bot speaks**: its button, placeholders and notices, and the direction of the layout (Arabic and Urdu are right-to-left). The strings arrive with the widget's configuration, so there is no second request and nothing to translate on your side.

### Modes

**Floating (default).** A launcher button in the corner, opening a chat panel.

**Inline.** Put an empty container on the page and the chat fills it instead:

```html
<div data-keyda-bot style="height:520px"></div>
```

The container needs a height. In inline mode the chat is always visible, so there is nothing to open or close.

### JavaScript API

Available on `window.KeydaBot` once the script has loaded:

| Call | What it does |
| --- | --- |
| `KeydaBot.open()` | Opens the chat panel |
| `KeydaBot.close()` | Closes it |
| `KeydaBot.toggle()` | Opens or closes |
| `KeydaBot.expand()` | Makes the panel as tall as the window and up to 760px wide |
| `KeydaBot.shrink()` | Back to the standard card |
| `KeydaBot.isOpen` | `true` when the chat is visible |
| `KeydaBot.isExpanded` | `true` while the panel is expanded |
| `KeydaBot.clientId` | The client id this page is using |

Example — open the chat from your own "Chat with us" button:

```html
<button onclick="KeydaBot.open()">Chat with us</button>
```

> The script loads asynchronously, so `window.KeydaBot` may not exist for a moment after page load. Attach handlers to a click rather than calling it as the page parses.

### How it behaves on your page

- The panel opens **above** the launcher button, which stays where it is and becomes the close control. Tapping it again, the ✕ in the header, or pressing Escape closes the chat.
- A visitor can **expand** the panel from the header — it grows to the height of the window and up to 760px wide — and the choice is remembered in their browser. On phones the panel is already the whole screen, so the control is not shown there.
- Your **logo size** setting changes the logo, not the button: the launcher keeps its size and the logo grows inside it. **Button size** (Install → Appearance) is what resizes the button itself — small, medium or large — whatever shape it is.
- Four button shapes: a pill with your label, a round bubble, a rounded square, and a chat bubble with a tail. The tail sits on the side facing your page.
- Everything renders inside a **shadow root**, so your CSS cannot break the widget and the widget's CSS cannot touch your site.
- The panel loads only when a visitor opens it, so it does not slow your page down.
- The chat opens on your welcome and up to four **suggested questions** as buttons — write your own under **Install → Suggested questions**, or leave them to the defaults. Nothing else is said until the visitor taps one or types, and your catalog's cards appear when they ask about prices or items, not before.
- With **Say it is an AI assistant** on, the header says “AI assistant” under your bot's name on every screen.
- A chat lasts as long as the visitor's browser tab. Moving between your pages keeps it, and reopening the panel restores the thread — files included, and a welcome-flow question that was still waiting for an answer. Closing the tab ends it, and their next visit opens a fresh chat. A reply from your team still reaches a visitor who asked for a person, in their next chat, for two weeks.
- Chats from the same browser are linked in **Chats** (“Visitor · 3 chats”), so you can read one visitor's conversations side by side. The link is a random id kept in the visitor's browser; it is not created when their browser asks not to be tracked.
- The **paperclip** in the composer lets a visitor attach up to three photos or documents to a message (sizes and types in [Limits and security](https://telybot.com/docs/reference-limits)). Photos are downscaled in the browser before upload, so a 12-megapixel snapshot leaves the page at a few hundred kilobytes. Switch files off under **Install** and the button goes.
- A **welcome flow** runs as ordinary bubbles: choices become buttons under the bubble, a Skip button appears when a step is optional, and the composer's placeholder becomes the question. A completed flow is remembered in the visitor's browser for 30 days.
- If the assistant cannot be reached, the widget shows a short message and never throws an error into your page.

### Inside the app SDKs

The same chat runs in every SDK, so attachments and welcome flows reach your app with no release — with one exception. Opening a file picker from a web view is the host's job. The iOS, React Native and Ionic packages already do it; **Android and Flutter need SDK 0.1.4 or later**. On older versions the widget recognises the shell and hides the paperclip rather than showing a button that does nothing.

> On iOS the system sheet offers Take Photo whenever images are accepted, and choosing it crashes an app that has no `NSCameraUsageDescription` in its Info.plist. Add the key before you ship a build with the chat in it.