# Telloox

> Telloox is a live-chat widget for websites. Add one script tag and visitors can chat with your team. No cookies, no npm package, no build step. This file tells an AI coding assistant how to install, configure and verify it.

Server: https://telloox.com
The widget key is not in this link. Ask the user for it (panel: Impostazioni / Settings -> Installazione / Installation) and never invent one; the user can also open https://telloox.com/llms.txt?site=THEIR_KEY.

## Install

Add this tag once, in the site-wide layout, just before `</body>`:

```html
<script src="https://telloox.com/widget.js" data-site="YOUR_WIDGET_KEY" async></script>
```

- Keep `data-site` on that element. Do not self-host, bundle, proxy or rename widget.js; do not add type="module".
- Frameworks: plain HTML, WordPress, Next.js, React, Vue/Nuxt, Astro, SvelteKit, Laravel, Shopify and Google Tag Manager recipes are in https://telloox.com/llms-full.txt (Google Tag Manager needs a script-creating variant, because it can drop data-* attributes).
- Single-page apps need nothing else: History API and hash navigation are tracked automatically. Preserve URL fragments (#telloox=...) used by links in emails to visitors.
- If the site sends a Content-Security-Policy, allow https://telloox.com in `script-src` and `frame-src` (or default-src). Nothing else is required. Trusted Types enforcement (`require-trusted-types-for 'script'`) is not supported.
- If the workspace restricts allowed domains (Settings -> Widget), the site's domain, including staging and localhost, must be listed; subdomains of a listed domain are covered.

## JavaScript API (optional)

Use the queue form, valid before and after the script loads:

```js
window.Telloox = window.Telloox || [];
window.Telloox.push(['identify', { name: 'Ada', email: 'ada@example.com', plan: 'pro' }]);
window.Telloox.push(['setLanguage', 'it']);
window.Telloox.push(['open']);
window.Telloox.push(['on', 'message', function (m) { console.log(m.body); }]);
```

- Methods: open(), close(), toggle(), identify(object), setLanguage(code), reset(), on(event, fn), push([name, ...args]). Call reset() when a user logs out: the next person on the same browser starts as a new visitor.
- Events: open, close (no payload), message (agent reply: id, sender, agent_name, body, attachment, created_at).
- identify: name (string), email (an invalid address is ignored with a console warning; the other fields are still saved), other keys are custom fields (max 20, scalar values, key up to 40 and value up to 200 characters). Call it once per page load; values are not verified.
- Languages: it, en, fr, de, es (default: the visitor's browser language, English when unsupported).

## Verify the installation

```bash
curl -s https://telloox.com/api/site/YOUR_WIDGET_KEY/status
```

Returns JSON: `installed` (true after the widget has loaded in a real browser page from an allowed domain; curl-ing the site HTML does not count), `domain` (where it was last seen: check it is the site you changed), `last_seen_at` (UTC, refreshed every 5 minutes at most), `agents_online`. HTTP 404 means unknown key or suspended workspace; 429 means more than 30 calls a minute.

1. Make the site with the snippet reachable over http(s) (localhost is fine, file:// is not).
2. Load a page once in a browser (use a browser tool if you have one, otherwise ask the user to open it).
3. Poll the endpoint every 5 seconds for up to a minute until `installed` is true and `domain` matches.
4. If it does not turn true, check key, allowed domains, CSP and that the tag is really on the loaded page (troubleshooting table in the full guide).
5. Tell the user what you changed, the snippet used, and the verification result.

## Docs

- [Full guide for assistants](https://telloox.com/llms-full.txt): workflow, framework recipes, API reference, CSP, troubleshooting, privacy facts in one file.
- [Agent Skill (zip)](https://telloox.com/skill.zip): the same content as an installable skill folder (telloox/SKILL.md plus reference files).

## Optional

- Privacy: the widget sets no cookies; the visitor token lives in the chat frame's localStorage; IP addresses are not stored (only an approximate location derived from them).