# Telloox: full integration guide

This document concatenates the Telloox skill: SKILL.md followed by the reference files. Links such as reference/api.md point to the sections below, introduced by an HTML comment with the file name.

<!-- SKILL.md -->

# Telloox widget

Telloox is a hosted live-chat widget. One `<script>` tag adds a launcher button and a chat panel. It sets no cookies and needs no build step or npm package.

Placeholders in these docs: `https://telloox.com` is the Telloox server URL (no trailing slash), `YOUR_WIDGET_KEY` is the widget key.

## 1. Get the two values

Ask the user for:

- the **widget key** (about 20 letters/digits)
- the **Telloox base URL**

Both are shown in the Telloox panel under Impostazioni / Settings -> Installazione / Installation. Only workspace admins see that page: an assistant must ask an admin. If the user cannot provide them, stop and ask. Never invent or guess a key: a wrong key makes the widget silently invisible.

## 2. Install the snippet once, site-wide

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

1. Detect the stack (look for `package.json`, `next.config.*`, `nuxt.config.*`, `astro.config.*`, `svelte.config.*`, `composer.json`, `style.css` + `functions.php`, `theme.liquid`, plain `.html`).
2. Put the tag in the shared layout/template, just before `</body>` (recipes: [reference/frameworks.md](reference/frameworks.md)). Add it exactly once: a second copy is ignored, but it wastes a request.
3. Keep `data-site` on the script element itself. The loader reads the key from that attribute. Do not rename `widget.js` or wrap the file in a bundle.
4. Do not add `type="module"`, do not self-host or proxy `widget.js`: the script must load from `https://telloox.com`, because the chat frame is served from the same origin.
5. Do not strip URL fragments (`#telloox=...`) in routers or redirects. Reply emails to visitors link to the page of the site where they chatted plus `#telloox=<token>`; the loader reads the token, removes the fragment and reopens the conversation. When that page is not known to be on the site, the link opens the hosted chat page `https://telloox.com/c/YOUR_WIDGET_KEY` instead.

## 3. Optional configuration

Full API: [reference/api.md](reference/api.md). Queue pattern, safe before the script has loaded:

```html
<script>
  window.Telloox = window.Telloox || [];
  Telloox.push(['identify', { name: 'Ada Lovelace', email: 'ada@example.com', plan: 'pro' }]);
  Telloox.push(['setLanguage', 'it']);
</script>
```

- Identify logged-in users with `identify` (name, email, up to 20 scalar custom fields). Call it once per page load, not on every render. On logout call `Telloox.push(['reset'])`, so the next person on the same browser starts as a new visitor.
- Language: by default the visitor's browser language. Supported: `it`, `en`, `fr`, `de`, `es` (anything else falls back to English). Force one with `setLanguage('fr')`.
- Open from your own button: `window.Telloox.open()` (use the queue form if the script may not be loaded yet).
- Single-page apps need nothing extra: route changes made with the History API or hash changes are reported automatically.

## 4. Content-Security-Policy

If the site sends a CSP (response header or `<meta http-equiv>`), add `https://telloox.com` to `script-src` and `frame-src` (or `default-src`). Nothing else is needed. Details, nonce/`strict-dynamic` setups, Trusted Types: [reference/csp.md](reference/csp.md).

Also check the workspace's **allowed domains** list (Settings -> Widget). When non-empty, the site's domain (and every staging/preview/localhost domain used for testing) must be in it. A listed domain also covers its subdomains.

## 5. Verify (do not skip)

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

```json
{"installed": false, "domain": null, "last_seen_at": null, "agents_online": false}
```

- `installed`: `true` once the widget has loaded in a real browser page and reached Telloox from an allowed domain. `curl`-ing the site's HTML does NOT count: the script must run in a browser.
- `domain`: host (with `:port` if not default) of the page where the widget was last seen. Check it is the site you just changed; `installed` can already be true from an earlier install elsewhere.
- `last_seen_at`: UTC ISO-8601, refreshed at most every 5 minutes per domain.
- `agents_online`: whether any agent is currently available (informational).
- HTTP 404 `{"error":...,"code":"404"}` means the key is unknown or the workspace is suspended. HTTP 429: more than 30 calls per minute from your IP.

Procedure:

1. Deploy or serve the site with the snippet (a `file://` page never registers; use `http://localhost:PORT` or a real URL).
2. Load a page of the site once in a browser. If you have a browser tool, open the page yourself; otherwise ask the user to open it and tell you when done.
3. Poll the status endpoint every ~5 s for up to a minute until `installed` is `true` and `domain` matches. Optionally also check in the browser that the round launcher button is at the bottom-right.
4. If it stays `false`: go through [reference/troubleshooting.md](reference/troubleshooting.md). The most common causes are a wrong key, a domain missing from the allowed list, a CSP block, and the script not being on the page that was loaded.

## 6. Report to the user

State concisely: which files you changed, the exact snippet placed, any identify/language/CSP changes, the verification result (`installed`, `domain`), and what remains for them (for example "answer the first chat from the panel at https://telloox.com"). Mention anything you could not verify.

## Reference files

- [reference/frameworks.md](reference/frameworks.md): copy-paste recipes per stack.
- [reference/api.md](reference/api.md): `window.Telloox` methods, events, limits, identify examples.
- [reference/csp.md](reference/csp.md): CSP directives, allowed domains.
- [reference/troubleshooting.md](reference/troubleshooting.md): symptom, cause, fix. Also privacy facts (cookies, storage, IP).

---

<!-- reference/frameworks.md -->

# Framework recipes

All recipes add the same tag once, site-wide. `https://telloox.com` and `YOUR_WIDGET_KEY` are the Telloox server URL and the widget key.

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

How the loader finds its key: it reads `data-site` from `document.currentScript`, and falls back to the first `script[data-site][src*="widget.js"]` in the document. So the tag can be static HTML or created with `document.createElement('script')` as long as `data-site` is set (with `setAttribute`) and the `src` contains `widget.js`. A tag with no `data-site` logs `Telloox: missing data-site...` to the console and does nothing.

Single-page apps: no extra code. The loader wraps `history.pushState`/`replaceState` and listens to `popstate` and `hashchange`; when the URL changes it reports the new URL and `document.title` (after 300 ms, so the router can update the title first). Install the tag once in the root layout, never per route/component.

Identify examples for each stack use the queue form, which works whether or not the script has loaded:
`window.Telloox = window.Telloox || []; window.Telloox.push(['identify', {...}]);`

## Plain HTML

Before `</body>` of every page (or of the shared include/partial/layout):

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

## WordPress

Add to the active theme's `functions.php` (use a child theme) or to a small must-use plugin. Simplest, no script API needed:

```php
add_action('wp_footer', function () {
    ?>
    <script src="<?php echo esc_url('https://telloox.com/widget.js'); ?>" data-site="<?php echo esc_attr('YOUR_WIDGET_KEY'); ?>" async></script>
    <?php
}, 100);
```

Equivalent with the enqueue API. WordPress does not let `wp_enqueue_script` set arbitrary attributes, so add `data-site` through the `script_loader_tag` filter:

```php
add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script('telloox', 'https://telloox.com/widget.js', [], null, ['in_footer' => true, 'strategy' => 'async']);
});
add_filter('script_loader_tag', function ($tag, $handle) {
    return $handle === 'telloox' ? str_replace('<script ', '<script data-site="YOUR_WIDGET_KEY" ', $tag) : $tag;
}, 10, 2);
```

(The array form of the fifth argument needs WordPress 6.3 or newer; on older versions pass `true` and drop `strategy`.) Passing `null` as the version avoids a `?ver=` suffix.

Identify the logged-in WordPress user (put it in the same `wp_footer` hook). Skip it on cached pages shared between users: full-page caches usually bypass logged-in users, but check.

```php
add_action('wp_footer', function () {
    $user = wp_get_current_user();
    if (!$user->exists()) {
        return;
    }
    $data = wp_json_encode(
        ['name' => $user->display_name, 'email' => $user->user_email],
        JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT
    );
    echo '<script>window.Telloox=window.Telloox||[];window.Telloox.push(["identify",' . $data . ']);</script>';
}, 99);
```

If a performance plugin delays or combines JavaScript, exclude `widget.js` from it.

## Next.js, App Router

`app/layout.tsx`:

```tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src={`${process.env.NEXT_PUBLIC_TELLOOX_URL}/widget.js`}
          data-site={process.env.NEXT_PUBLIC_TELLOOX_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}
```

`.env.local`: `NEXT_PUBLIC_TELLOOX_URL=https://telloox.com` and `NEXT_PUBLIC_TELLOOX_KEY=YOUR_WIDGET_KEY`. Extra props such as `data-site` are copied to the script element.

Identify after login, in a client component rendered inside the layout:

```tsx
'use client';
import { useEffect } from 'react';

declare global {
  interface Window { Telloox?: any }
}

export function TellooxIdentify({ user }: { user: { name: string; email: string; plan?: string } | null }) {
  useEffect(() => {
    if (!user) return;
    window.Telloox = window.Telloox || [];
    window.Telloox.push(['identify', { name: user.name, email: user.email, plan: user.plan }]);
  }, [user?.email]);
  return null;
}
```

## Next.js, Pages Router

Put the `<Script>` in `pages/_app.tsx` (not in `_document`):

```tsx
import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src={`${process.env.NEXT_PUBLIC_TELLOOX_URL}/widget.js`}
        data-site={process.env.NEXT_PUBLIC_TELLOOX_KEY}
        strategy="afterInteractive"
      />
    </>
  );
}
```

## React SPA (Vite or Create React App)

Edit `index.html` (project root for Vite, `public/index.html` for CRA), before `</body>`. Do not import the script from JavaScript.

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

To keep the key out of source, Vite replaces `%VITE_TELLOOX_KEY%` in `index.html` from `.env` (CRA: `%REACT_APP_TELLOOX_KEY%`):
`data-site="%VITE_TELLOOX_KEY%"`.

Identify after login (and when the user changes):

```jsx
import { useEffect } from 'react';

export function useTellooxIdentify(user) {
  useEffect(() => {
    if (!user) return;
    window.Telloox = window.Telloox || [];
    window.Telloox.push(['identify', { name: user.name, email: user.email, plan: user.plan }]);
  }, [user?.email]);
}
```

## Vue 3 (Vite SPA)

Same as React: tag in `index.html` before `</body>`. Identify in the code that handles login:

```js
window.Telloox = window.Telloox || [];
window.Telloox.push(['identify', { name: user.name, email: user.email }]);
```

## Nuxt 3

`nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { src: 'https://telloox.com/widget.js', 'data-site': 'YOUR_WIDGET_KEY', async: true, tagPosition: 'bodyClose' },
      ],
    },
  },
});
```

Identify with a client-only plugin, `plugins/telloox.client.ts`:

```ts
export default defineNuxtPlugin(() => {
  const user = useState<{ name: string; email: string } | null>('user'); // adapt to your auth store
  watch(user, (u) => {
    if (!u) return;
    const w = window as any;
    w.Telloox = w.Telloox || [];
    w.Telloox.push(['identify', { name: u.name, email: u.email }]);
  }, { immediate: true });
});
```

## Astro

In the shared layout (for example `src/layouts/Layout.astro`), before `</body>`. `is:inline` stops Astro from processing or bundling the tag:

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

It works with the View Transitions client router: the script runs once and URL changes are tracked through the History API.

## SvelteKit

`src/app.html`:

```html
<body data-sveltekit-preload-data="hover">
  <div style="display: contents">%sveltekit.body%</div>
  <script src="https://telloox.com/widget.js" data-site="YOUR_WIDGET_KEY" async></script>
</body>
```

Identify in `src/routes/+layout.svelte`:

```svelte
<script lang="ts">
  import { browser } from '$app/environment';
  export let data; // data.user from your +layout.server.ts

  $: if (browser && data.user) {
    (window as any).Telloox = (window as any).Telloox || [];
    (window as any).Telloox.push(['identify', { name: data.user.name, email: data.user.email }]);
  }
</script>
<slot />
```

## Laravel (Blade)

`config/services.php`:

```php
'telloox' => ['url' => env('TELLOOX_URL'), 'key' => env('TELLOOX_KEY')],
```

`.env`: `TELLOOX_URL=https://telloox.com` and `TELLOOX_KEY=YOUR_WIDGET_KEY`. In the main layout (`resources/views/layouts/app.blade.php`), before `</body>`:

```blade
@if (config('services.telloox.key'))
    @auth
        <script>
            window.Telloox = window.Telloox || [];
            window.Telloox.push(['identify', @json(['name' => auth()->user()->name, 'email' => auth()->user()->email])]);
        </script>
    @endauth
    <script src="{{ rtrim(config('services.telloox.url'), '/') }}/widget.js" data-site="{{ config('services.telloox.key') }}" async></script>
@endif
```

`@json` escapes `<`, `>`, `&` and quotes, so it is safe inside `<script>`. With a CSP nonce package, add the nonce attribute to both tags.

## Shopify (Online Store theme)

Edit `layout/theme.liquid`, before `</body>`:

```liquid
<script src="https://telloox.com/widget.js" data-site="YOUR_WIDGET_KEY" async></script>
{%- if customer -%}
  <script>
    window.Telloox = window.Telloox || [];
    window.Telloox.push(['identify', { name: {{ customer.name | json }}, email: {{ customer.email | json }}, orders: {{ customer.orders_count | json }} }]);
  </script>
{%- endif -%}
```

`theme.liquid` covers storefront pages. Checkout pages use their own template, so the widget does not appear there unless the plan lets you customize checkout.

## Google Tag Manager

Create a **Custom HTML** tag, trigger **All Pages**, "Once per page" firing. Use the script-creating form, not a literal `<script src data-site>` tag, because GTM re-creates script tags in Custom HTML and does not guarantee that custom `data-*` attributes survive:

```html
<script>
(function () {
  if (document.querySelector('script[data-site][src*="widget.js"]')) return;
  var s = document.createElement('script');
  s.src = 'https://telloox.com/widget.js';
  s.async = true;
  s.setAttribute('data-site', 'YOUR_WIDGET_KEY');
  document.head.appendChild(s);
})();
</script>
```

This works because the loader reads `document.currentScript` (set for dynamically inserted classic scripts) and otherwise finds the element by `script[data-site][src*="widget.js"]`. Set `data-site` before appending. GTM's own script must be allowed by the site CSP, and so must `https://telloox.com` (see csp.md); with a nonce + `'strict-dynamic'` CSP, scripts inserted by trusted GTM code inherit trust.

To identify a user from GTM, push values to `dataLayer` and read them in the tag, or call the queue from site code. Never interpolate GTM variables directly into JavaScript strings without JSON-encoding them.

---

<!-- reference/api.md -->

# JavaScript API

The loader (`https://telloox.com/widget.js`) defines `window.Telloox`. Every method is wrapped so that an error never reaches the host page (it is logged with `console.warn('Telloox:', ...)`).

## Calling it before the script has loaded (queue)

`async` scripts load at an unknown time. Use the queue form for calls made from page code or other scripts:

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

- Each entry is `[methodName, ...args]`. When the loader starts it replays the queue in order, then replaces `window.Telloox` with the real API object.
- After loading, the same `push([name, ...args])` form keeps working, so one calling convention is safe everywhere. Unknown method names and nested `'push'` are ignored.
- Always read `window.Telloox` when you call; do not keep a reference to the array you created earlier, because after load it is a different object.
- Direct calls (`window.Telloox.open()`) only work after the script has run; before that `window.Telloox` is undefined or a plain array without `open`.
- Commands issued before the chat frame is ready (`open`, `identify`, `setLanguage`) are buffered and applied when it is.

## Methods

| Call | Effect |
|---|---|
| `Telloox.open()` | Open the chat panel. |
| `Telloox.close()` | Close it. |
| `Telloox.toggle()` | Open if closed, close if open. |
| `Telloox.identify(data)` | Attach visitor details. `data` must be a plain object (see below). |
| `Telloox.setLanguage(code)` | Force the widget language. `code` is a string such as `'fr'` or `'pt-BR'`. |
| `Telloox.reset()` | Forget the current visitor in this browser and start over as a new one (call it on logout, see below). |
| `Telloox.on(event, fn)` | Subscribe to `'open'`, `'close'` or `'message'`. |
| `Telloox.push([name, ...args])` | Queue-style call of any method above. |

There is no `off`/unsubscribe, no `destroy`/`hide`, and no getter. The launcher cannot be moved or hidden from the API.

### identify(data)

```js
Telloox.identify({ name: 'Ada Lovelace', email: 'ada@example.com', userId: 'u_123', plan: 'pro', trial: false, seats: 5 });
```

- `name` (string, trimmed, stored up to 120 characters). An empty string clears the name.
- `email` (string, up to 190 characters). An invalid address is ignored (the previous email, if any, is kept) and the warning `Telloox: identify() ignored an invalid email` appears in the browser console; the name and custom fields of the same call are still saved. An empty string is ignored (the email cannot be cleared from the API; use `reset()` on logout).
- Every other key is a custom field shown to agents next to the conversation. Limits: at most 20 fields in total (newly sent keys are kept first, older ones are dropped beyond 20), key up to 40 characters, values must be strings (up to 200 characters), numbers, booleans or `null`. Objects and arrays are skipped. `null` clears a previously sent field. New values are merged over earlier ones.
- `data` must survive `JSON.stringify` (no circular structures, no functions); otherwise the call is dropped with a console warning.
- Rate limit: 20 identify calls per visitor per 10 minutes. Call it once per page load or on login, not inside a render loop.
- Values are supplied by the browser, so agents see them but they are not verified. Do not use them for authorization and do not send secrets or more personal data than agents need.
- Giving an email also lets Telloox continue the conversation by email when the visitor is offline.

### setLanguage(code)

Widget languages: `it`, `en`, `fr`, `de`, `es`. Only the first two letters of `code` matter (`'fr-CA'` is French); anything else falls back to English. Without a call, the widget uses the visitor's browser language (`navigator.language`) on the host page. The setting is per page load: call it on every page (or in the queue snippet in the shared layout). Calling it again with a different value switches the open widget. It translates the widget interface only, not agent messages.

### Events

```js
Telloox.on('open', function () { /* panel opened (button, open(), toggle()) */ });
Telloox.on('close', function () { /* panel closed (button, Escape, close(), toggle()) */ });
Telloox.on('message', function (message) { /* an agent reply arrived */ });
```

`open` and `close` have no payload and fire only when the state actually changes. `message` fires for each new agent message received while the page is open (history loaded at startup does not trigger it), also when the panel is closed. Payload:

```js
{
  id: 1234,                    // message id
  sender: 'agent',
  agent_name: 'Marta',         // may be null
  body: 'Hi! How can I help?', // text ('' for an attachment-only message)
  attachment: { name: 'invoice.pdf', mime: 'application/pdf', size: 48213 }, // or null/undefined
  created_at: '2026-01-31 10:15:00' // UTC, 'YYYY-MM-DD HH:MM:SS'
}
```

Unknown event names are ignored. An exception in your handler is caught and logged. Polling pauses while the browser tab is hidden, so `message` events can arrive late when the tab is in the background.

The unread badge on the launcher is automatic.

## Open the chat from your own button

```html
<button onclick="(window.Telloox = window.Telloox || []).push(['open'])">Talk to us</button>
```

The queue form works before and after `widget.js` has loaded, and a click made too early is not lost: the chat opens as soon as it is ready.

## Identify a logged-in user: server-rendered page

Render the data as JSON from the server and push it before or after the loader tag. Always encode on the server (never concatenate strings), and escape `<`, `>`, `&` for HTML.

PHP:

```php
<?php if ($user): ?>
<script>
  window.Telloox = window.Telloox || [];
  window.Telloox.push(['identify', <?= json_encode(['name' => $user->name, 'email' => $user->email, 'plan' => $user->plan],
      JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT) ?>]);
</script>
<?php endif ?>
```

Jinja2 / Flask (`|tojson` escapes `<`, `>`, `&` and quotes):

```html
{% if current_user.is_authenticated %}
<script>
  window.Telloox = window.Telloox || [];
  window.Telloox.push(['identify', {{ {'name': current_user.name, 'email': current_user.email} | tojson }}]);
</script>
{% endif %}
```

Other stacks: see the Laravel, WordPress and Shopify examples in frameworks.md.

## Identify in a SPA after login

```js
async function onLogin(user) {
  window.Telloox = window.Telloox || [];
  window.Telloox.push(['identify', { name: user.name, email: user.email, plan: user.plan }]);
}
```

Call it again when the details change (for example a plan upgrade); merging means you only need to send what changed.

## Logout

Call `reset()` when a user logs out of your site, so that the next person on the same browser does not see the previous conversation:

```js
function onLogout() {
  window.Telloox = window.Telloox || [];
  window.Telloox.push(['reset']);
}
```

- The visitor is recognised by a token the chat frame keeps in its own localStorage (key `telloox:<widget key>` on the Telloox origin), which the host page cannot read or delete. `reset()` drops that token, empties the chat window and starts a brand-new visitor without name, email, custom fields or history. The launcher badge goes back to zero; the panel stays open or closed as it was.
- The previous visitor and their conversations stay in the Telloox panel (agents see that visitor leave). Nothing is deleted.
- Calls queued after `reset` (for example `identify` for the next user) apply to the new visitor.
- If logout navigates to another page right away, the call can be lost with the old page. Then push `reset` on the page the logout lands on instead, once (for example when your server flags a fresh logout), not on every page load: each call starts another new visitor.

## Navigation and SPA tracking

The loader reports the page URL and title on load and again after every `history.pushState`, `history.replaceState`, `popstate` and `hashchange` that changes `location.href`. No API call is needed.

## Not supported

Positioning, theming and welcome text are set in the panel (Settings -> Widget: accent colour, welcome message, privacy link, allowed domains), not in code. There are no `data-*` options on the script tag other than `data-site`.

---

<!-- reference/csp.md -->

# Content-Security-Policy and allowed domains

## What the host site must allow

The loader is a classic script that creates a closed shadow root on the host page and one `<iframe>` pointing to `https://telloox.com/w/YOUR_WIDGET_KEY`. All chat network traffic (API calls, polling, uploads, images) happens inside that iframe under the iframe's own CSP, so the host's `connect-src` and `img-src` are not involved.

Add exactly these two sources to the site's policy (header or `<meta http-equiv="Content-Security-Policy">`):

| Directive | Value | Why |
|---|---|---|
| `script-src` | `https://telloox.com` | loads `/widget.js` |
| `frame-src` | `https://telloox.com` | embeds the chat frame (falls back to `child-src`, then `default-src`, when `frame-src` is absent) |

Example:

```
Content-Security-Policy: default-src 'self'; script-src 'self' https://telloox.com; frame-src https://telloox.com
```

If the policy has only `default-src`, adding the origin there is enough. Use the origin only (scheme, host, port), without a path.

### Nonce or `'strict-dynamic'` policies

Host allowlists are ignored when `script-src` contains `'strict-dynamic'`. Give the tag the page's nonce instead:

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

A script inserted by an already trusted script (for example Google Tag Manager, see frameworks.md) is trusted under `'strict-dynamic'` and needs no nonce.

### Not needed

- `connect-src`, `img-src`, `font-src`, `media-src`, `worker-src`: the loader uses none of them on the host page (the launcher icon is inline SVG, styles are in the shadow root).
- `style-src`: the loader uses a constructed stylesheet (`adoptedStyleSheets`), which CSP `style-src` does not block. Only browsers without that API (for example Safari before 16.4) fall back to a `<style>` element in the shadow root, and a strict `style-src` without `'unsafe-inline'` blocks it: the launcher then appears unstyled. Everything else works.
- Nothing on the host needs to be relaxed for the chat frame's own policy; the frame sends its own CSP.

### Known incompatibilities

- **Trusted Types** (`require-trusted-types-for 'script'`): the loader builds its shadow root with `innerHTML` (`public/widget.js`, in `mount()`), which Trusted Types rejects. The error is caught and logged as `Telloox: ...` and the widget does not appear. Fix: remove that directive from the site policy; there is no loader option for a Trusted Types policy.
- **`Cross-Origin-Embedder-Policy: require-corp` or `credentialless`** on the host page: the chat frame response carries no `Cross-Origin-Embedder-Policy`/`Cross-Origin-Resource-Policy` headers, so such pages are not supported.

## Allowed domains (workspace setting)

Panel: Impostazioni / Settings -> Widget -> allowed domains. One host per line (commas also work). When the list is empty, the widget works on any site. When it has entries, Telloox refuses everything else: the chat frame answers 404 (the widget simply never appears), API calls get 403, and the install check never registers the site.

Matching rules (case-insensitive):

- `example.com` allows `example.com` and every subdomain (`www.example.com`, `shop.eu.example.com`).
- `www.example.com` allows only that host and its subdomains, not `example.com`. Prefer listing the registrable domain.
- Scheme, path and a leading `*.` are ignored: `https://*.example.com/shop` equals `example.com`. http and https are both accepted.
- An entry with a port (`localhost:3000`, `staging.example.com:8443`) must match host and port exactly and does not cover subdomains. An entry without a port matches any port, so `localhost` covers `http://localhost:3000` and `http://localhost:5173`. The default ports 80/443 are never part of the match: do not write `example.com:443`.
- Up to 50 entries.

The check uses the origin of the embedding page (reported by the browser through `postMessage`), the request `Origin`, the `Referer` of the frame request, and the same list becomes the frame's `Content-Security-Policy: frame-ancestors` (each host and its subdomains, over http and https), so the chat cannot be embedded on other sites.

Remember to add staging, preview (list each exact host, for example `my-app-git-main.vercel.app`), and local development hosts, or the widget will not show there. `file://` pages have no host and are always refused when the list is non-empty.

---

<!-- reference/troubleshooting.md -->

# Troubleshooting

First look at the status endpoint and the browser console:

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

The loader never throws into the page; its problems appear as `Telloox: ...` warnings in the console. When the chat frame is refused, nothing is shown at all: the launcher stays hidden until the frame reports ready.

## Symptom, cause, fix

| Symptom | Likely cause | Fix |
|---|---|---|
| No launcher button, no console message, no request to `/w/...` | `widget.js` not on the page that was loaded (template not deployed, cached page, wrong layout, tag after an early `return`) | View the page source or the Network tab and confirm the `widget.js` request. Fix the template and redeploy or purge caches. |
| Console: `Telloox: missing data-site on the widget script tag` | `data-site` attribute missing or on another element; tag injected by a tool that drops `data-*` attributes (some tag managers, bundlers, optimizer plugins) | Put `data-site="YOUR_WIDGET_KEY"` on the same `<script>` element. In GTM use the script-creating variant from frameworks.md. |
| `widget.js` loads (200) but nothing shows, and the request to `https://telloox.com/w/YOUR_WIDGET_KEY` returns 404 | Wrong or truncated widget key, workspace suspended, or the site's domain is not in the allowed domains list | Compare the key with Settings -> Installation. `curl .../api/site/KEY/status`: a 404 JSON there means unknown or suspended. If the status works, add the site's domain (and staging/localhost) to Settings -> Widget -> allowed domains. |
| API calls in the Network tab return 403 | Origin not in allowed domains (a mismatching subdomain, `www` entry without the apex, a port in the entry that does not match) | See the matching rules in csp.md; list the registrable domain without scheme or port. |
| Console: `Refused to load the script` or `Refused to frame` | The site CSP blocks `https://telloox.com` | Add it to `script-src` and `frame-src`, see csp.md. |
| Console: `This document requires 'TrustedHTML' assignment` | Trusted Types enforced by the site | Remove `require-trusted-types-for 'script'` from the policy; the loader has no workaround. |
| `status` returns `installed: false` | Nobody has loaded a page with the snippet in a browser yet, or the visit came from `file://`, a non-allowed domain, an ad-blocker/privacy extension blocked `widget.js`, or the key is wrong | Load a page in a real browser (not `curl`), wait a few seconds (the frame starts after the page `load` event), poll again. Test with extensions disabled. |
| `installed: true` but `domain` is not the site you changed | The widget was seen earlier on a different domain, and your page does not load it | Check `domain` and `last_seen_at`; `last_seen_at` refreshes only every 5 minutes for the same domain, but a new domain updates at once. Confirm the snippet is on this site. |
| Status endpoint returns 429 | More than 30 requests per minute from your IP | Poll every 5 seconds or slower. |
| Widget shows in the wrong language | Language is taken from the visitor's browser (`navigator.language`) unless forced; unsupported languages fall back to English | Supported: it, en, fr, de, es. Force with `Telloox.push(['setLanguage', 'fr'])` on every page. The call must use a string; `fr-CA` works as `fr`. |
| `Telloox.open is not a function` / `Telloox is not defined` | Direct call before `widget.js` has run | Use the queue form: `(window.Telloox = window.Telloox \|\| []).push(['open'])`. |
| `identify` seems to do nothing | Rate limit (20 per 10 minutes), widget not allowed on this domain, circular data; an invalid email alone is ignored (console warning `identify() ignored an invalid email`), the other fields are saved | Call identify once per page load, check the console. Verify in the panel: the visitor card shows name, email and custom fields. |
| Custom fields missing | Only scalar values are kept, max 20 fields, 40-character keys, 200-character values | Flatten objects (`planName`, `planSeats`), shorten values. |
| Visitor attachments rejected | Allowed types: zip, pdf, jpg/jpeg, png. Maximum 10 MB per file. The file extension and the real content type must match | Send an allowed type under 10 MB. On the server, `upload_max_filesize` and `post_max_size` must be at least 10M and 12M (see README); otherwise large files fail with the same size message. Visitors are limited to 10 uploads per 10 minutes. |
| Launcher hidden behind a site element | The launcher uses `z-index: 2147483000`, `position: fixed`; something with a higher z-index, or an ancestor stacking context, or `transform`/`filter` on `<body>`/`<html>` changes how fixed positioning works | Lower the z-index of the offending element (a cookie banner or sticky bar), and avoid `transform`/`filter`/`perspective` on `html`/`body`. The loader appends its element to `<body>` and cannot be moved with options. |
| Launcher covers a button or the cookie banner | Fixed position, bottom-right, 20px offset; no position option | Add bottom padding to the site's element, or move the site element; the API cannot reposition the launcher. |
| Widget appears twice or conflicts with another chat | Two snippets (a theme and a plugin, or GTM plus the template) | Keep a single install. The loader ignores a second copy, but the extra request remains; remove one. Other chat widgets use their own launchers: remove them. |
| A returning visitor does not see their previous conversation | The visitor token lives in the chat frame's `localStorage`; if the browser blocks it for third-party frames, it is kept in memory for that page only | Nothing to fix on the site. If the visitor left an email, the conversation continues by email. |
| Replies reach the visitor by email, but the link does not reopen the chat | The `#telloox=...` fragment was removed by a redirect or router | Preserve URL fragments across redirects and in client routing. |

## Privacy facts for integrators

Verified in the code:

- **No cookies.** The widget sets no cookies on the host site or on the Telloox origin. The frame and the API never start a session, and the browser calls are made with `credentials: 'omit'`. No cookie banner is needed for the widget itself (that is a legal decision for the site owner).
- **Visitor token in `localStorage`.** A random token is stored in the chat iframe's `localStorage` (key `telloox:<widget key>`, on the Telloox origin, not readable by the host page). If the browser blocks storage in third-party frames, the token is kept in memory only for that page. The server stores only its SHA-256 hash.
- **IP address is not stored.** The IP is used for an approximate geolocation lookup (country, city, coordinates from a local IP database; no external call) and, as a SHA-256 hash inside a key, for rate limiting. Web-server access logs of the Telloox host are outside the application.
- **What is collected:** page URL, page title, referrer, browser language, time zone, user agent, geolocation as above, chat messages and attachments, and whatever the site passes to `identify`.
- **Retention:** conversations and visitors older than the workspace's retention setting (default 30 days, configurable in Settings -> Privacy) are deleted daily. Agents can delete a visitor and their data from the visitor card.
- **Privacy link:** Settings -> Widget accepts a privacy policy URL that the widget shows to visitors.