# Tolkly

> AI support chat for online businesses. It answers from the site's own pages with a source in every answer, and hands what it cannot answer to operators in Telegram or a web inbox. The widget is one script tag; its settings come from the server.

The widget endpoint is https://api.tolkly.io. These docs describe the version served at https://tolkly.io. Every page has a Markdown twin: add .md to its address, or send Accept: text/markdown.

## Product

- [Tolkly home page](https://tolkly.io/): what Tolkly is, the price compared with Jivo and Intercom, a live demo on your own site
- [Questions and answers](https://tolkly.io/faq): price, what counts as an AI conversation, how answers are checked, handoff, Jivo and Intercom
- [Articles (in Russian)](https://tolkly.io/blog): Tolkly compared with Jivo, Intercom and other chats, and what an AI support chat changes
- [Articles (in Russian)](https://tolkly.io/ru/blog): Tolkly compared with Jivo, Intercom and other chats, and what an AI support chat changes
- [Tolkly vs Intercom Fin: a Fin alternative without per-outcome fees](https://tolkly.io/vs/intercom): Tolkly vs Intercom Fin: seats from $29 plus $0.99 per Fin outcome against Tolkly's $49 a month for everything. Costs for 3 and 8 operators, with sources.
- [Tolkly или Intercom Fin: альтернатива Fin с ценой без оплаты за исходы](https://tolkly.io/ru/vs/intercom): Tolkly и Intercom Fin: место от $29 плюс $0,99 за исход Fin против $49 в месяц за всё у Tolkly. Расчёт на 3 и 8 операторов, источники, русский интерфейс.
- [Tolkly или Jivo: чат с ИИ для сайта без платы за каждого оператора](https://tolkly.io/ru/vs/jivo): Tolkly и Jivo: цены на 2026 год, ИИ-оператор Jivo за 12 990 ₽ против ИИ в тарифе Tolkly от $49, ответы с цитатой из источника, расчёт на 3 и 8 операторов.
- [Tolkly, Verbox, Carrot quest или Talk-Me: какой онлайн-чат с ИИ выбрать в 2026](https://tolkly.io/ru/vs/verbox-carrot-quest-talk-me): Сравнение Tolkly с Verbox, Carrot quest и Talk-Me: цены на 2026 год, как устроен ИИ, где отвечают операторы, расчёт на 3 и 8 операторов.
- [How AI support chats read your site: Intercom, Zendesk, Chatwoot, Crisp and Tolkly](https://tolkly.io/blog/ai-chat-reads-your-site): Which AI chats read a site by sitemap and links, how often they read it again, what they do with menus, robots.txt and JavaScript, and what to check before launch.
- [How an AI support chat affects conversion and the load on operators](https://tolkly.io/blog/ai-chat-conversion): What research says about response time, questions after hours and the share of conversations AI closes, and how to measure it on your own site.
- [How to answer website chats from Telegram](https://tolkly.io/blog/operators-in-telegram): How operators answer site visitors from the company's Telegram group in Tolkly: a topic per conversation, shifts, files, and why it beats a separate app.
- [What an AI support chat costs and how a hard cap on the bill works](https://tolkly.io/blog/ai-chat-cost-cap): Why paying per seat and per AI outcome grows the bill, how Tolkly's hard cap works, and a worked example for 3,000 conversations a month.
- [Why support bots make up prices and deadlines, and how to prevent it](https://tolkly.io/blog/ai-hallucinations-support): Real cases of support chatbots inventing rules, why it happens, and how a quoted answer, a check in code and an honest refusal prevent it.
- [Альтернативы Jivo в 2026: 6 онлайн-чатов с ИИ для сайта](https://tolkly.io/ru/blog/jivo-alternatives): Чем заменить Jivo в 2026: Tolkly, Carrot quest, Verbox, Talk-Me, Intercom Fin и Chatwoot. Цены с датами и источниками, сильные стороны каждого, расчёт на 3 и 8 операторов.
- [Как ИИ-чат поддержки влияет на конверсию и нагрузку на операторов](https://tolkly.io/ru/blog/ai-chat-conversion): Что говорят исследования о скорости ответа, вопросах в нерабочее время и доле разговоров, которые закрывает ИИ, и как это измерить на своём сайте.
- [Как ИИ-чаты поддержки читают ваш сайт: Intercom, Zendesk, Chatwoot, Crisp, Jivo и Tolkly](https://tolkly.io/ru/blog/ai-chat-reads-your-site): Кто из ИИ-чатов читает сайт по sitemap и ссылкам, как часто перечитывает, что делает с меню, robots.txt и JavaScript, и что проверить до запуска.
- [Как отвечать на чаты с сайта из Telegram](https://tolkly.io/ru/blog/operators-in-telegram): Как операторы отвечают посетителям сайта из Telegram-группы компании в Tolkly: тема на разговор, смены, файлы, и почему это удобнее приложения.
- [Почему бот поддержки выдумывает цены и сроки и как это предотвратить](https://tolkly.io/ru/blog/ai-hallucinations-support): Реальные случаи, когда чат-бот поддержки выдумал правила, почему так происходит и как ответ с цитатой, проверкой кодом и честным отказом это предотвращает.
- [Сколько стоит ИИ-чат поддержки и как работает жёсткий потолок счёта](https://tolkly.io/ru/blog/ai-chat-cost-cap): Почему оплата за операторов и за исходы ИИ растит счёт, как работает жёсткий потолок в Tolkly и пример расчёта для 3 000 разговоров в месяц.

Plans: Start $49 a month (up to 10 operators, 1,000 AI conversations), Business $149 (operators without limit, 5,000 AI conversations); the first month is free. At the limit the bot hands conversations to operators and never charges extra.

---

# Install on a site

> Where the two lines go and how to check that the chat is live.

The chat is a web component. You add two lines to the layout all your pages share. Everything
else comes from the Tolkly server.

## The two lines
```html
<script type="module" src="https://api.tolkly.io/widget.js"></script>
<tolkly-chat project="your-project"></tolkly-chat>
```

Replace `your-project` with the project's id. In the app, open the project's «Install» section,
block «Install on your site». The lines are there with the id filled in, next to a «Copy the code»
button.

- `widget.js` is about a kilobyte: it loads the chat from `https://api.tolkly.io`, and if the chat has not
  come up within 2.5 s, from our next address ([visitors in Russia](#russia)).
- The tag needs no `endpoint`: the chat talks to the address its script came from.
- Load the script from `https://api.tolkly.io`. Do not copy it into your repository or bundle. This way new
  releases reach your site on their own.
- Add no other attributes. The chat's name, greeting, colours and who answers (the AI or only
  people) come from the server. The element reads them from
  `GET https://api.tolkly.io/v1/projects/<project>/widget` when it connects. Attributes are only for the
  rare site that wants its own values ([attributes](https://tolkly.io/docs/en/widget-attributes.md)).

## Where they go

Add both lines once, just before `</body>`, in the template every page uses: the root layout, the
base template or the theme's footer. Do not add them page by page. For your stack, see
[Frameworks](https://tolkly.io/docs/en/frameworks.md).

### Single-page apps

In React, Vue, Angular, Next.js or Nuxt, the chat must stay on the page when the route changes:

- Render `<tolkly-chat>` once, outside the router outlet: in `index.html` or the root layout.
  Inside a page component, the element is removed and created again on every navigation.
- Load the script once, not on every page.
- In TypeScript JSX, declare the element instead of casting it to `any`
  ([TypeScript and JSX](https://tolkly.io/docs/en/frameworks.md#typescript-and-jsx)).

## What loads on every page

Most visitors never open the chat. So most page views load only the launcher:

| Request | When | Caching |
|---|---|---|
| `https://api.tolkly.io/widget.js` | every page | `no-cache` with an ETag: a repeat view gets a `304` with no body |
| `GET …/v1/projects/<project>/widget` | every page | the browser keeps it for `WIDGET_SETTINGS_MAX_AGE_SECONDS` (60 s by default) |
| `POST …/v1/projects/<project>/identify` | every page with `data-identity`, and on `identify()` | a `POST`, never cached ([identity](https://tolkly.io/docs/en/identity.md)) |
| `https://api.tolkly.io/widget/chat-<hash>.js` | when the visitor first reaches for the chat | named by its content, kept for a year |

The chat window loads in three cases:

- the visitor reaches for it: hovers, focuses or taps the launcher;
- the page opens it;
- the visitor already has a conversation going (then it loads at once).

Scripts are sent compressed, with brotli or gzip, whichever the browser accepts. The window's code
comes from the same place as `widget.js`, under `/widget/`.

## Visitors in Russia
Since June 2025 Russian providers cut connections to Cloudflare after the first ~16 KB, so for a
visitor in Russia without a VPN the chat from `https://api.tolkly.io` may never finish loading.
`widget.js` is small enough to arrive whole; it waits for the chat itself, not for a script's
`load` event (a stalled download fires neither `load` nor `error`), and then loads the chat from
our address in Russia. The
address that worked is remembered in the site's `localStorage` for a day, so the next page starts
with it; a browser that refuses storage only loses that memory. The chat then sends every request
to the address it was loaded from: `https://api.tolkly.io https://ru.tolkly.io` all serve the same chat and the same
conversations.

## Check that it works
1. Open two different pages of the site. The chat button shows in the bottom right corner of
   both.
2. In the browser's network panel, `GET https://api.tolkly.io/v1/projects/<project>/widget` answers `200`.
   Its JSON has no `refused` field. Check this in the browser on your site, not with `curl`. The
   server decides by the page's `Origin` header, and it never refuses a request without one.
3. Within a few minutes of the deploy, the project's «Install» section in the app says «The chat
   is live on example.com · 2 min ago». Until then it says «Not installed yet».

How the site gets recorded:

- The server takes the site from the `Origin` header of the settings request.
- It updates the last-seen time at most once per `WIDGET_ORIGIN_TOUCH_SECONDS` (300 s by default).
- A page on the same host as `https://api.tolkly.io` sends no `Origin`, so it is not recorded.
- A site the owner blocked is never shown there.

## If the chat does not show
| What you see | Why, and what to do |
|---|---|
| No request to `https://api.tolkly.io` in the network panel | The browser got a page without the lines. Check the page source, the layout the site really uses and any page cache. |
| `/widget` answers `{"refused": "origin_blocked"}` | The owner blocked this domain. They can unblock it in the project's «Install» section, block «Domains» ([Domains](https://tolkly.io/docs/en/domains.md)). |
| `/widget` answers `{"refused": "origin_not_allowed"}` | The project is in strict mode and this domain is not on its list. The owner can allow it ([Domains](https://tolkly.io/docs/en/domains.md)). |
| `/widget` answers `404` | The `project` attribute does not match any project on this server. |
| The console reports a Content-Security-Policy violation | The site's policy blocks the widget. See [Content-Security-Policy](https://tolkly.io/docs/en/csp.md). |
| The console says `tolkly: the identity token was refused (…)` | The chat works, but anonymously. See [Signed visitor identity](https://tolkly.io/docs/en/identity.md#rejected). |

A refused site gets `200`, not `403`. So the page's console stays clean, and the widget simply
draws nothing.

To hand the install to a coding agent, see [AI agents](https://tolkly.io/docs/en/agents.md).

Source: https://tolkly.io/docs/en/install.md

---

# Frameworks

> Where the two lines go in Next.js, Nuxt, React, Vue, Angular, WordPress, Tilda and Bitrix.

Every stack uses the same two lines ([Install on a site](https://tolkly.io/docs/en/install.md)). Add the script once and
the element once, in the layout all pages share. Replace `your-project` with the project's id.

## Plain HTML

Add the lines before `</body>` on every page, or in the template that builds them:

```html
  <script type="module" src="https://api.tolkly.io/widget.js"></script>
  <tolkly-chat endpoint="https://api.tolkly.io" project="your-project"></tolkly-chat>
</body>
```

Other server templates work the same way: Laravel's Blade layout, Django's `base.html`, Rails'
`application.html.erb`. Put the lines before `</body>` of the base layout.

## Next.js (App Router)
The root layout stays mounted when the visitor navigates. Put the chat there:

```tsx
// app/layout.tsx
import Script from 'next/script'
import type { ReactNode } from 'react'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <tolkly-chat endpoint="https://api.tolkly.io" project="your-project"></tolkly-chat>
        <Script type="module" src="https://api.tolkly.io/widget.js" strategy="afterInteractive" />
      </body>
    </html>
  )
}
```

- `next/script` passes `type="module"` on to the script it adds.
- With `afterInteractive`, the widget runs after React hydrates the page.
- React 19 renders the custom element with its attributes as written.
- Add the [type declaration](#typescript-and-jsx) below, or TypeScript rejects `<tolkly-chat>`.

## Next.js (Pages Router)
`_app` wraps every page and stays mounted on navigation:

```tsx
// pages/_app.tsx
import type { AppProps } from 'next/app'
import Script from 'next/script'

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <tolkly-chat endpoint="https://api.tolkly.io" project="your-project"></tolkly-chat>
      <Script type="module" src="https://api.tolkly.io/widget.js" strategy="afterInteractive" />
    </>
  )
}
```

## TypeScript and JSX
React 19 types read intrinsic elements from `React.JSX`. Declare the tag once in any `.d.ts` file
that your `tsconfig.json` includes, for example `tolkly.d.ts`:

```ts
import type { DetailedHTMLProps, HTMLAttributes } from 'react'

type TolklyChatProps = DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & {
  endpoint?: string
  project?: string
  name?: string
  greeting?: string
  handoff?: string
  teaser?: string
  position?: 'left' | 'right'
  theme?: 'site' | 'system' | 'light' | 'dark'
  'send-icon'?: 'arrow' | 'plane' | 'forward'
  collapse?: string
  'data-identity'?: string
}

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'tolkly-chat': TolklyChatProps
    }
  }
}
```

The `import` makes the file a module. Thanks to it, `declare module 'react'` adds to React's
types instead of replacing them. `HTMLAttributes` already covers `lang`, `nonce`, `style` and
`className`.

Do not pass `open` and `inline` in JSX. If the element has a DOM property with the same name,
React 19 sets the prop as that property. `<tolkly-chat>` has an `open()` method and a read-only
`inline` property. Write these attributes in `index.html` instead, or call `open({ focus: false })`
on the element from an effect.

## Nuxt 3
Load the script from `nuxt.config.ts` and tell Vue the tag is a custom element:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [{ src: 'https://api.tolkly.io/widget.js', type: 'module' }],
    },
  },
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('tolkly-'),
    },
  },
})
```

Then put the element in `app.vue`, outside `<NuxtPage>`:

```vue
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
  <tolkly-chat endpoint="https://api.tolkly.io" project="your-project"></tolkly-chat>
</template>
```

## React with Vite
Put both lines in `index.html`, before `</body>`, outside the `#root` element that React renders
into. You do not need to change the React code. If you prefer to render `<tolkly-chat>` from JSX,
render it once in the root component and add the [type declaration](#typescript-and-jsx).

## Vue 3 with Vite
Put both lines in `index.html`, before `</body>`, outside the `#app` element. If you prefer to use
the tag in a Vue template, tell the compiler it is a custom element:

```ts
// vite.config.ts
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: { isCustomElement: (tag) => tag.startsWith('tolkly-') },
      },
    }),
  ],
})
```

## Angular

Put both lines in `src/index.html`, before `</body>`, outside the app's root element. Do not add
the script to `scripts` in `angular.json`. That bundles it as a classic script, and it will not
run.

If you prefer to use the tag in a component template, allow custom elements there:

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppComponent {}
```

## WordPress

Add the lines just before `</body>` in your theme's `footer.php`. Use a child theme, so a theme
update does not remove them. Or add them from the theme's `functions.php`:

```php
add_action('wp_footer', function () {
    echo '<script type="module" src="https://api.tolkly.io/widget.js"></script>';
    echo '<tolkly-chat endpoint="https://api.tolkly.io" project="your-project"></tolkly-chat>';
});
```

No access to theme files? Any plugin that adds custom code before `</body>` on every page will
do. Then clear the page cache, if the site has one.

## Tilda

Add both lines to an HTML code block (T123). Put the block in a footer that every page uses, or on
each page where the chat should show. Then publish the pages again.

## 1C-Bitrix
Add the lines just before `</body>` in the site template's `footer.php`. It is at
`/local/templates/<template>/footer.php` or `/bitrix/templates/<template>/footer.php`. If the
template is cached, clear the site cache afterwards.

Source: https://tolkly.io/docs/en/frameworks.md

---

# Content-Security-Policy

> What to allow for the chat when a site sends a Content-Security-Policy.

If your site sends a Content-Security-Policy, it must let the widget load its script and talk to its server. If your site has no policy, skip this page.

## What the widget needs
Add these sources to the directives in your policy. Keep your own sources as they are:

| Directive | Add | What for |
|---|---|---|
| `script-src` | `https://api.tolkly.io https://ru.tolkly.io` | `/widget.js` and the parts it imports from `/widget/` |
| `connect-src` | `https://api.tolkly.io https://ru.tolkly.io` | project settings; questions and streamed answers; the live conversation stream (server-sent events); file uploads and downloads |
| `img-src` | `https://api.tolkly.io https://ru.tolkly.io blob:` | pictures in the conversation, by signed links (`/v1/files/…`); `blob:` previews a picture before it is sent |

You do not need to change `style-src`, and you do not need `'unsafe-inline'`. The widget styles its shadow root with constructed stylesheets (`adoptedStyleSheets`). A policy does not block them. They work in Chrome 73+, Edge 79+, Firefox 101+ and Safari 16.4+. For older Safari, see [nonces](#nonces).

`https://api.tolkly.io https://ru.tolkly.io` above are every address the widget may load from: `widget.js` loads the chat from
the next one when the first does not answer in time ([visitors in Russia](https://tolkly.io/docs/en/install.md#russia)).
An install code copied before November 10, 2026 may start with an inline `<script>`, a loader. It
keeps working, with your nonce or its hash in `script-src` as before; the plain line from
[install](https://tolkly.io/docs/en/install.md#the-two-lines) needs neither.

Nothing else is needed:

- No `'unsafe-eval'`.
- No `font-src`. The chat uses the site's own font by name (`--tolkly-font`) and loads no font files.
- No `frame-src`. The widget uses no frames.
- No `media-src`. Its sounds are made in the browser.

## A full header

```http
Content-Security-Policy: default-src 'self'; script-src 'self' https://api.tolkly.io https://ru.tolkly.io; connect-src 'self' https://api.tolkly.io https://ru.tolkly.io; img-src 'self' https://api.tolkly.io https://ru.tolkly.io blob:
```

The same policy as a meta tag, in `<head>` before any script:

```html
<meta http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self' https://api.tolkly.io https://ru.tolkly.io; connect-src 'self' https://api.tolkly.io https://ru.tolkly.io; img-src 'self' https://api.tolkly.io https://ru.tolkly.io blob:">
```

## Nonces and strict-dynamic
Safari before 16.4 has no constructed stylesheets. There the widget adds its styles as a `<style>` element in its shadow root, and `style-src` applies to it. If your policy uses a nonce for styles, put the same nonce on the tag. Then the chat is styled in those browsers too:

```html
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project" nonce="SERVER_NONCE"></tolkly-chat>
```

`SERVER_NONCE` is the nonce your server makes for each response.

- If the tag has no `nonce` attribute, the widget takes the nonce of the page's first `<script nonce>`.
- If there is no nonce at all, older Safari shows the chat unstyled, unless `style-src` has `'unsafe-inline'`. Current browsers are not affected.

Two more cases:

- **`script-src` with `'strict-dynamic'`:** host sources such as `https://api.tolkly.io` are ignored. Put your nonce on the widget's `<script>` tag. `'strict-dynamic'` then lets in the parts it imports.
- **Only `default-src`:** it stands in for every directive above that your policy does not name. Add the sources to `default-src`, or add the directives separately.

## nginx

```nginx
add_header Content-Security-Policy "default-src 'self'; script-src 'self' https://api.tolkly.io https://ru.tolkly.io; connect-src 'self' https://api.tolkly.io https://ru.tolkly.io; img-src 'self' https://api.tolkly.io https://ru.tolkly.io blob:" always;
```

An `add_header` inside a `location` replaces all `add_header` lines of the `server` block. Repeat the policy in that `location`, or set it in one place only.

## Next.js

```js
// next.config.mjs
const csp = [
  "default-src 'self'",
  "script-src 'self' https://api.tolkly.io https://ru.tolkly.io",
  "connect-src 'self' https://api.tolkly.io https://ru.tolkly.io",
  "img-src 'self' https://api.tolkly.io https://ru.tolkly.io blob:",
].join('; ')

export default {
  async headers() {
    return [{ source: '/:path*', headers: [{ key: 'Content-Security-Policy', value: csp }] }]
  },
}
```

Add these sources to what your app already allows. Next.js also needs sources of its own, which this example leaves out: its inline scripts and styles, or a nonce from middleware.

## If the policy cannot allow this
If the policy blocks the chat, the chat does not work on those pages. The browser refuses the script or the requests and reports it in the console. Do not loosen the policy on your own. Tell the site's owner what the chat needs and let them decide.

Source: https://tolkly.io/docs/en/csp.md

---

# Widget attributes

> Every attribute of <tolkly-chat>, the --tolkly-* colour properties, and <tolkly-search>.

`<tolkly-chat>` needs only two attributes: `endpoint` and `project`. Everything else comes from the
server (`GET /v1/projects/<project>/widget`): the project's name, greeting, theme and who answers.
The project's owner sets these in the app, in the project's **Widget** section, with a live
preview. Use the attributes below when a site wants its own.

## Attributes

| Attribute | What it does |
|---|---|
| `endpoint` | The Tolkly server's origin, `https://api.tolkly.io`. Without it, the origin `widget.js` was loaded from. |
| `project` | The project's id. Required. |
| `name` | Sets the chat's title and the site's name in its lines. Without it, the project's name. |
| `greeting` | Replaces the chat's opening line with the site's own. |
| `handoff` | The site's own support link. The chat offers it when the project has no operators in Tolkly. Only `https:`, `http:`, `tg:` and `mailto:` links work; others are ignored. A `t.me` link gets the order number from the question as its `start` parameter. |
| `teaser` | A one-line hint over the closed chat, in place of the one set in «Widget». Shown once per browser session. It goes away when the visitor hides it or opens the chat. |
| `open` | The chat starts open, without taking the page's focus. |
| `position` | `left` or `right`: the corner of the button and the window, in place of the one set in «Widget» ([Placement](#placement)). |
| `inline` | Puts the open chat into the page, sized by its container: no button, no close. Give the container a height. |
| `launcher` | `none`: no button and no hint in the corner. The chat still opens there, from your own control with `open()`; show unread replies from [`tolkly:unread`](https://tolkly.io/docs/en/widget-api.md#tolkly-unread). |
| `lang` | The chat's language, instead of `<html lang>` ([Language](https://tolkly.io/docs/en/widget-api.md#language)). |
| `theme` | Light or dark ([Light and dark](#light-dark)): `site` follows the page, `system` the visitor's system, `light` and `dark` fix one. Without it, the choice in «Widget», `site` by default. |
| `send-icon` | The send button's icon: `arrow` (up), `plane` or `forward` (right), in place of the one picked in «Widget». Any other value draws the arrow. |
| `collapse` | How many statements of an answer show before the rest folds. `3` by default; `0` never folds. |
| `data-identity` | A token your site's server signed for the visitor ([Signed visitor identity](https://tolkly.io/docs/en/identity.md)). |
| `nonce` | The style nonce from your Content-Security-Policy. Needed for browsers without constructed stylesheets (Safari before 16.4). Without it, the widget takes the nonce of the page's first `<script nonce>` ([CSP](https://tolkly.io/docs/en/csp.md#nonces)). |
| `preview` | Draws the chat as visitors see it, but sends nothing and restores no saved conversation. The app's widget preview uses it. Not for a live site. |

For `name`, `greeting`, `teaser`, `theme`, `send-icon` and `position`, the attribute on the tag
wins over the server. Whether the AI answers or only people do can't be set on the tag. Only the
project's switch decides that.

The element reacts at once when `lang`, `name`, `data-identity` or `theme` change. Put the other
attributes in the markup.

How the chat gets the visitor to a person:

- `handoff` is set and the project has no operators in Tolkly: through the link.
- The project has operators: the chat hands the conversation to them.
- Neither: the chat asks the visitor for a contact (of the kinds the project allows), so your
  team can write back.

## Colours and font
The theme is a set of CSS custom properties on the element. The server sends the ones it read from
the site, with the owner's corrections from the app. Set your own in the tag's `style` attribute:

```html
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project"
  style="--tolkly-accent: #0b7a53; --tolkly-radius: 8px"></tolkly-chat>
```

The server's colours sit inside the widget, below anything your page sets: a value in the tag's
`style` and a rule in your stylesheet (`tolkly-chat { --tolkly-accent: … }`) both win, with no
`!important`.

| Property | Default (light) | Used for |
|---|---|---|
| `--tolkly-accent` | `#4f46e5` | the button, the visitor's messages, pressed controls |
| `--tolkly-accent-fg` | `#ffffff` | text on the accent |
| `--tolkly-accent-text` | the accent | accent-coloured text and outlines on the background: source marks, focus |
| `--tolkly-bg` | `#ffffff` | the window's background |
| `--tolkly-fg` | `#16181d` | text |
| `--tolkly-muted` | `#667085` | secondary text |
| `--tolkly-border` | `#e4e7ec` | borders |
| `--tolkly-surface` | `#f6f7f9` | cards, code, quoted sources |
| `--tolkly-radius` | `12px` | the window's corners (in the app: «Corners»). Small controls take it, up to 12px. The reply field wraps its buttons with 5px more. |
| `--tolkly-font` | `system-ui, …` | the text font; a family the page already loads |
| `--tolkly-mono` | `ui-monospace, …` | code |

A value you set applies in both schemes. To set one for a scheme only, select it by
`data-scheme` ([Light and dark](#light-dark)).

## Light and dark
The chat has a light and a dark palette. The server sends both: the colours read from your site,
and its dark (or light) mode when the site has one, read from `prefers-color-scheme` rules and
`.dark`-style classes. When the site has none, the other palette is made from your colours: the
brand keeps its hue and stays readable on the new background.

Which one shows is the `theme` attribute, else the choice in «Widget» («Light or dark»):

| Value | The chat |
|---|---|
| `site` (default) | looks like the page under it: its background colour, then a `dark` or `light` class or `data-theme`, `data-bs-theme`, `data-color-mode` on `<html>` or `<body>`, then the page's `color-scheme`. It follows your site's own switch as it happens. |
| `system` | follows the visitor's system setting. |
| `light`, `dark` | always that palette. |

The chat puts the palette it shows on the tag as `data-scheme="light"` or `data-scheme="dark"`.
Your own switch can drive the chat by setting the attribute:

```js
document.querySelector('tolkly-chat').setAttribute('theme', isDark ? 'dark' : 'light')
```

To give a scheme colours of your own, select it in your stylesheet:

```css
tolkly-chat[data-scheme="dark"] { --tolkly-bg: #0f172a; --tolkly-accent: #60a5fa; }
```


## Placement
The chat sits in the bottom right corner, 20 px from the page's edges. The project's owner can
move it in the app: **Widget** → «Position» sets the corner and the gaps from the side and the
bottom, 0 to 400 px. Every page gets this setting from the server. A page can set its own on the
tag:

```html
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project" position="left"
  style="--tolkly-offset-x: 24px; --tolkly-offset-y: 96px"></tolkly-chat>
```

| Property | Default | What it moves |
|---|---|---|
| `--tolkly-offset-x` | `20px` | the button and the window from the page's side (the right one, or the left with `position="left"`) |
| `--tolkly-offset-y` | `20px` | the button from the page's bottom; the window and the hint stay 68 px above it |

Unlike the colours, the offsets work from your stylesheet too. There they win over the owner's
setting without `!important`. For example, if your phone layout has a tab bar at the bottom, you
can lift the chat on phones only:

```css
@media (max-width: 600px) {
  tolkly-chat { --tolkly-offset-y: 80px; }
}
```

Any CSS length works, `calc(env(safe-area-inset-bottom) + 64px)` included. On a screen narrower
than 600 px, the open chat fills the whole screen, so the offsets move only the button there.

Until the project's settings arrive (at most 1.5 s), the button is not drawn. Otherwise it would
appear in the default corner and then jump to the owner's.

## `<tolkly-search>`
The same script adds a search box over a project's pages, for docs sites:

```html
<tolkly-search endpoint="https://api.tolkly.io" project="your-project"></tolkly-search>
```

The element draws a «Search docs ⌘K» button where it stands.

- It opens on that button or on Cmd+K (Ctrl+K) anywhere on the page. Escape closes it.
- Pages are listed as you type. Enter asks for an answer with its sources.
- It takes `endpoint`, `project`, `lang`, `theme` and the `--tolkly-*` properties. It reads no
  settings from the server: without `theme` it follows the page, in the widget's own colours.
- `open(question?)` opens it; with a question, it asks it at once. `close()` closes it.
- Its code loads only on a page that has the element.

Source: https://tolkly.io/docs/en/widget-attributes.md

---

# JS API and events

> Open the chat, ask a question for the visitor, say who they are, and learn when a conversation goes to people.

Your page can control `<tolkly-chat>` with methods on the element and listen to three events. A
plain install needs none of this.

## Getting the element

The methods appear once the script defines the element. Wait for that:

```js
await customElements.whenDefined('tolkly-chat')
const chat = document.querySelector('tolkly-chat')
chat.open()
```

## Methods

| Method | What it does |
|---|---|
| `open({ focus })` | Opens the chat. Loads its window first if needed. By default, focus moves into the chat; `focus: false` leaves it where it is. |
| `close()` | Minimizes the chat. Does nothing on an `inline` chat. |
| `ask(text)` | Opens the chat if it is closed and sends `text` as the visitor's message. Returns a promise. Does nothing if `text` is empty or an answer is still coming. The server accepts up to 1000 characters. |
| `identify(token)` | Tells the chat who the visitor is, with a token your server signed. Call it after the visitor signs in on your site ([identity](https://tolkly.io/docs/en/identity.md#pass-the-token)). |
| `identify({ id, name, email, phone, fields })` | Tells the chat who the visitor is, without a signature. Operators see the visitor marked «not verified». Such a visitor never gets a history shared across devices. Only `id` is required. |
| `reset()` | Call it on sign-out. Forgets the visitor and the conversation stored in this browser, and the chat starts over. Also stop rendering `data-identity`. |

## Suggested questions
`suggestions` is a property, not an attribute. It holds questions the chat offers before the first
message. Set on a page, they replace the questions from «Widget» on that page, for example a
question about one exchange direction on its own page.

```js
chat.suggestions = ['How long does a withdrawal take?', 'Which documents do you need?']
chat.suggestions = null // the questions from «Widget» again
```

The chat keeps up to 6 and drops empty ones. They show only until the visitor's first message.
Questions set by a page are not counted in the report; the ones from «Widget» are
([Frequent questions](https://tolkly.io/docs/en/widget.md#suggestions)).

## Events

All three events bubble and cross the shadow root (`composed`). So you can listen on `document`:

```js
document.addEventListener('tolkly:handoff', (event) => {
  const { reason, tokens } = event.detail
  console.log('handed to people:', reason, tokens)
})

document.addEventListener('tolkly:resolved', (event) => {
  console.log('the visitor says this answer helped:', event.detail.answerId)
})
```

### `tolkly:handoff`
The conversation goes to people. The event fires in this tab when:

- the bot hands the conversation over while answering a message;
- a message goes straight to people: in operators-only mode, after the AI limit is spent (the
  company's month or the project's daily guard), or when the visitor sends a file on its own;
- the visitor presses the button that calls a person.

It does not fire when:

- the bot refuses to answer;
- the bot only offers a person;
- the visitor follows the `handoff` link;
- an operator joins;
- a conversation is restored on page load.

`detail.tokens` lists order numbers and transaction hashes found in the question:
`{ kind: 'order' | 'tx', value: string }[]`. `detail.reason` is one of:

| `reason` | Why |
|---|---|
| `requested` | The visitor asked for a person. |
| `personal_case` | The question is about the visitor's own order, payment or account. Only staff can check it. |
| `topic` | The message is about one of the topics the project sends to a person. |
| `operators_only` | The project runs without the AI: every message goes to people. |
| `cap_reached` | The AI limit is spent: the company's month of AI conversations ([Plan, payment and limit](https://tolkly.io/docs/en/billing.md#cap)) or the project's daily guard ([How Tolkly answers](https://tolkly.io/docs/en/overview.md#daily-cap)). People answer instead of the bot. |
| `attachment` | The visitor sent a file, which the bot does not read. |
| `scenario` | The project's order system did not answer for the bot (an error, a timeout, an unknown status), so people take it. |

### `tolkly:resolved`
The visitor pressed «It helped» under a bot answer. `detail.answerId` is the answer's id, or
`null` if the chat does not know it. The event fires once per answer. It does not fire for the
rating the visitor gives after an operator closes a conversation.

### `tolkly:unread`
The replies the visitor has not read changed. `detail.unread` is their count, `detail.ask` is
`true` when the chat asks for a contact the visitor has not seen yet. It fires only on a change.
With `launcher="none"` this is how your page shows the mark the button would have shown:

```js
document.addEventListener('tolkly:unread', (event) => {
  const { unread, ask } = event.detail
  helpButton.classList.toggle('has-news', unread > 0 || ask)
})
```

## Language
The chat uses the language of its `lang` attribute. Without it, the chat uses `<html lang>`.

The chat watches both. If your site switches language without a reload, or sets
`chat.lang = 'ru'`, the chat redraws itself in the new language and loads the conversation from
the server again.

The chat has texts in 15 languages: `en`, `ru`, `hy`, `kk`, `uz`, `az`, `ka`, `ky`, `tg`, `uk`,
`tr`, `de`, `es`, `fr` and `pt`. Any other language gets the project's primary language
([How the chat looks](https://tolkly.io/docs/en/widget.md#language)), or English when none is set, but operators' names
still follow the page's language.

Source: https://tolkly.io/docs/en/widget-api.md

---

# Signed visitor identity

> Your server signs a token, and the chat knows which signed-in visitor is writing.

If visitors sign in on your site, your server can tell the chat who is writing. Then:

- operators see the account and the fields you send;
- the visitor finds their conversation on any device and on any of the project's domains.

Without a signature, the browser keeps a conversation per site. On a new device or mirror, the
visitor starts afresh.

## How it works

1. Your server signs a token for the signed-in user with the project's identity secret.
2. The page passes it to the chat: `data-identity` on the tag, or `identify(token)`.
3. The widget sends it to `POST https://api.tolkly.io/v1/projects/<project>/identify`. The server checks
   it and says which conversation is this visitor's: the one in this browser or, if this browser
   has none, their latest open one.

The widget checks nothing itself. If the server refuses a token, no part of it is trusted: the
chat goes on as an anonymous one.

## The token

An HS256 JWT. The server always reads the algorithm as HS256, whatever the header says. A header
naming any other algorithm, `none` included, is refused.

| Claim | Required | What it is |
|---|---|---|
| `sub` | yes | Your user id, a string (a number is taken as one), up to 200 characters. A longer one refuses the token. |
| `name` | no | The name operators see, up to 120 characters. |
| `email` | no | Dropped if it doesn't look like an email. |
| `phone` | no | Dropped if it doesn't look like a phone number. |
| `fields` | no | An object of the fields the project declared ([below](#fields)). |
| `exp` | no | Expiry, in seconds since the epoch. Without it, a token works as long as the secret does. |

`exp` is checked with 60 seconds of slack, so a slightly slow clock doesn't refuse a fresh token.
A token longer than 8192 characters is refused unread.

The payload is signed, not encrypted: the visitor can read it in the page. Send only what the
visitor may see.

## Fields
Fields are the project's own: an account number, a KYC status, a VIP level, a link to the user in
your admin. The project declares each field with a key and a type. Anything else in `fields` is
dropped, and so is a value of the wrong type. Owners and admins of the company declare them.

| Type | Takes |
|---|---|
| `text` | a string up to 500 characters (a number is taken as text) |
| `number` | a number, or a string that is one |
| `date` | `YYYY-MM-DD` or a full ISO 8601 time |
| `list` | an array of strings or numbers, up to 100 characters each; the first 20 are kept. A single value counts as one item. If any item is empty, too long or of another type, the whole list is dropped. |
| `link` | an `http:` or `https:` URL, up to 2000 characters |
| `boolean` | `true` or `false` (also `"true"`, `"false"`, `1`, `0`) |

Fields are declared in the project's «Install» section, under «Advanced settings», in the block
«Visitor fields»: a title operators see, the key your server writes, the type, and whether
operators see the value. A key stays once made: your server already sends it, so a new key is a
new field. Turn «Show to operators» off for a value kept for rules only, such as a risk score.

## The secret

Owners and admins of the company find it in the project's «Install» section: «Advanced settings» › block
«Visitor identity» › «Show the secret».

Keep it on your site's server, in an environment variable such as `TOLKLY_IDENTITY_SECRET`. Never
put it in browser code or a page: whoever has it can sign in as any of your customers.

## Sign on your server
Node.js:

```js
// npm install jsonwebtoken
import jwt from 'jsonwebtoken'

const token = jwt.sign(
  {
    sub: String(user.id),
    name: user.name,
    email: user.email,
  },
  process.env.TOLKLY_IDENTITY_SECRET,
  { algorithm: 'HS256', expiresIn: '12h' },
)
```

PHP:

```php
// composer require firebase/php-jwt
use Firebase\JWT\JWT;

$token = JWT::encode([
  'sub' => (string) $user->id,
  'name' => $user->name,
  'email' => $user->email,
  'exp' => time() + 12 * 3600,
], getenv('TOLKLY_IDENTITY_SECRET'), 'HS256');
```

Python:

```python
# pip install pyjwt
import os, time, jwt

token = jwt.encode({
    "sub": str(user.id),
    "name": user.name,
    "email": user.email,
    "exp": int(time.time()) + 12 * 3600,
}, os.environ["TOLKLY_IDENTITY_SECRET"], algorithm="HS256")
```

Add `fields` next to the other claims, for example `fields: { vip: user.vip }`.

## Pass the token to the chat
If the page is rendered for a signed-in user, put the token on the tag:

```html
<tolkly-chat endpoint="https://api.tolkly.io" project="your-project"
  data-identity="<token>"></tolkly-chat>
```

If the user signs in without a page reload, pass the token from a script:

```js
await customElements.whenDefined('tolkly-chat')
document.querySelector('tolkly-chat').identify(token)
```

The element also watches `data-identity`: change the attribute and the chat names the visitor
again.

On sign-out, call `reset()` and stop rendering `data-identity`. The chat forgets the visitor and
the conversation kept in this browser, so the next person at this computer starts afresh. If the
browser holds another signed visitor's conversation, the server gives it a fresh one too.

## Hand it to an AI agent
Owners and admins get «Hand it to an AI agent» in the project's «Install» › «Advanced settings», block
«Visitor identity». It gives the prompt below, with the project filled in, for the coding agent
that edits the site (Claude Code, Cursor). With it, the agent:

- signs on the server with the secret from `TOLKLY_IDENTITY_SECRET`;
- passes the token by `data-identity` or `identify(token)`;
- calls `reset()` on sign-out;
- checks the result in the inbox's visitor card.

The prompt names the environment variable, never the secret. Here it has `your-project` in place
of the project's id. «Open in…» → «Prompt for an AI agent» copies it.

```text
Add signed visitor identity to the Tolkly support chat on this website, so operators see which customer writes.

Project: your-project
Widget endpoint: https://api.tolkly.io
Secret: the environment variable TOLKLY_IDENTITY_SECRET on the site’s server. The owner copies it from Tolkly: «Install» › «Advanced settings» › «Visitor identity» › «Show the secret».

1. Read https://tolkly.io/docs/en/identity.md. If it does not load, this prompt is enough.
2. Find where the site’s server knows the signed-in user (the session, the auth middleware) and the layout that renders the <tolkly-chat> tag. If the site has no <tolkly-chat> tag yet, stop and tell me: the chat is installed first.
3. On the server, sign an HS256 JWT for the signed-in user with the secret from TOLKLY_IDENTITY_SECRET, using the platform’s usual JWT library. Never sign in browser code and never send the secret to the page. If the variable is not set, stop and ask me to set it; never write the secret into the repository.
4. Claims: "sub" is the user’s id as a string (required, up to 200 characters); "name" is the name operators see (up to 120); "email" and "phone" when the site has them; "exp" is the expiry in seconds since the epoch, for example 12 hours ahead. Extra data goes in "fields": {…}, only the keys the project declared (listed under «Fields your site may send» in the same block); anything else is dropped. The payload is readable in the page: send only what the visitor may see.
5. Hand the token to the chat. When the page is rendered for a signed-in visitor, put it on the tag: data-identity="<token>". After a sign-in without a page reload, call identify(token) on the element: await customElements.whenDefined('tolkly-chat'); document.querySelector('tolkly-chat').identify(token). An anonymous visitor gets no data-identity.
6. On sign-out, call document.querySelector('tolkly-chat').reset() and stop rendering data-identity, so the next person at this computer starts afresh.
7. Check it in a browser: sign in on the site, open the chat and write a message. In Tolkly’s inbox, under «All», the conversation’s visitor card «Account on the site» shows the user id, marked «Verified». The browser console has no line "tolkly: the identity token was refused (…)"; if it has one, the word in brackets says why (malformed, algorithm, signature, expired). Then sign out and open the chat again: it is anonymous, with a new conversation. Then list the files you changed.
```

## Without a signature
`identify({ id, name, email, phone, fields })` names the visitor without a token. Operators see it
marked «not verified». It stays on that conversation only. It never joins a history across
devices and never takes over a signed visitor's conversation.

## A refused token
The chat goes on as an anonymous one and logs the reason in the browser console:

```text
tolkly: the identity token was refused (signature)
```

| Code | Why |
|---|---|
| `malformed` | Not three base64url parts of JSON, no `sub` or one over 200 characters, an `exp` that is not a number, or longer than 8192 characters. |
| `algorithm` | The header names an algorithm other than HS256. |
| `signature` | Signed with another secret: an old one, or another project's. |
| `expired` | `exp` has passed, beyond the allowed clock skew. |

## Rotate the secret
Press «Issue a new secret» in the app (owners and admins only). The old secret stops working at once. Tokens
signed with it are refused with `signature` until your server signs with the new one. So rotate
the secret together with your deploy.

Source: https://tolkly.io/docs/en/identity.md

---

# For AI agents

> llms.txt, a Markdown twin of every page, and the prompt that installs the chat with Claude Code or Cursor.

These docs are written for coding agents as much as for people. Everything below is plain HTTP, with no account and no key.

## Where to start

| Address | What it is |
|---|---|
| [`https://tolkly.io/llms.txt`](https://tolkly.io/llms.txt) | A short map of the docs ([llmstxt.org](https://llmstxt.org)): a summary, instructions for agents, links to every page's Markdown |
| [`https://tolkly.io/llms-full.txt`](https://tolkly.io/llms-full.txt) | Every English page in one file |
| [`https://tolkly.io/docs/ru/llms.txt`](https://tolkly.io/docs/ru/llms.txt) | The same in Russian; untranslated pages are given in English |

English is the source of these docs and is always complete. Russian pages are translations of it.

## Markdown for every page
Every page has a Markdown twin, built from the same source as the HTML. Links in it are absolute and point at other twins. An agent can follow them without parsing HTML.

- Add `.md` to the page's address: `https://tolkly.io/docs/en/install.md`.
- Or ask for Markdown at the page's own address: the server reads the `Accept` header.

```sh
curl -H 'Accept: text/markdown' https://tolkly.io/docs/en/install
```

A page served as HTML sends `Vary: Accept` and names its twin and llms.txt:

```http
Link: </docs/en/install.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"; type="text/plain"
```

The HTML has the same `<link rel="alternate" type="text/markdown">` in its `<head>`. On each page, «Copy as Markdown» puts the twin on the clipboard, and «Open in…» opens it in Claude or ChatGPT with a question about it.

## The install prompt
In the app, owners see «Hand it to an AI agent» under the install code in the project's «Install» section. It is the prompt below, with the project and the endpoint filled in. Here it has `your-project` in place of the project's id. On the install pages, «Open in…» → «Prompt for an AI agent» copies it.

```text
Install the Tolkly support chat on this website.

Project: your-project
Widget endpoint: https://api.tolkly.io

1. Read https://tolkly.io/llms.txt, then https://tolkly.io/docs/en/install.md and the section for this site's stack in https://tolkly.io/docs/en/frameworks.md. If they do not load, this prompt is enough.
2. Work out how the site is built: static HTML, a server-rendered framework (Next.js, Nuxt, Laravel, Django…), a single-page app (React with Vite, Vue, Angular) or a CMS (WordPress, Tilda, Bitrix).
3. Add these two lines exactly once, in the layout every page shares, just before </body>:

   <script type="module" src="https://api.tolkly.io/widget.js"></script>
   <tolkly-chat project="your-project"></tolkly-chat>

   Add no other attributes: the chat's name, greeting, colours and who answers come from the server. Load the script from https://api.tolkly.io; do not copy or bundle it.
4. In a single-page app the chat must survive route changes: put the tag outside the router outlet (index.html or the root layout) and load the script once, never per page. In TypeScript JSX, declare tolkly-chat as an intrinsic element instead of casting to any.
5. If the site sends a Content-Security-Policy, allow https://api.tolkly.io, https://ru.tolkly.io in script-src, connect-src and img-src, and add blob: to img-src (file previews). style-src needs nothing: the widget uses constructed stylesheets (Chrome 73+, Firefox 101+, Safari 16.4+). If the policy uses a nonce, put the same nonce attribute on the <tolkly-chat> tag so older Safari gets styles too. If script-src has 'strict-dynamic', host sources are ignored: put the nonce on the widget's <script> tag as well. If the policy cannot allow this, stop and tell me.
6. Do not add a domain allowlist: the chat works on any of my domains by default.
7. If visitors sign in on this site, ask me before adding signed identity (https://tolkly.io/docs/en/identity.md). The secret stays on the server in an environment variable, never in browser code.
8. Check it in a browser: run the site, open two different pages, and confirm the chat button shows on both and, in the network panel, the request to https://api.tolkly.io/v1/projects/your-project/widget answers 200 without a "refused" field. A request from curl proves nothing: without the page's Origin it is always allowed. Then list the files you changed. Within a few minutes of the deploy, the «Install» section of the project in Tolkly says the chat is live on this site.
```

What the prompt leaves out on purpose:

- **No secret.** The identity secret stays with the owner. The owner puts it on the site's server by hand, through an environment variable ([Signed visitor identity](https://tolkly.io/docs/en/identity.md)).
- **No forged requests.** The check is a real page in a browser. A request with a made-up `Origin` would add a stranger's site to the project's domains.
- **No chat settings.** The owner changes the name, colours and greeting, not the site's code.

## Rules agents get wrong
- The tag goes once into the layout every page shares. Not into a page component, and not twice.
- The tag gets `endpoint` and `project` only. Theme, greeting and who answers come from the server ([attributes](https://tolkly.io/docs/en/widget-attributes.md)).
- The script is loaded from the endpoint as a module. Never copy it into the repository or bundle it.
- With a Content-Security-Policy, `style-src` needs nothing added, not even `'unsafe-inline'`. If the policy has a style nonce, put the same `nonce` on the tag ([CSP](https://tolkly.io/docs/en/csp.md)).
- No domain allowlist unless the owner asks for one: by default the chat runs on any domain ([domains](https://tolkly.io/docs/en/domains.md)).

Source: https://tolkly.io/docs/en/agents.md

---

# How Tolkly answers

> A source in every answer, an honest refusal, the AI mark, handoff to a person, what counts as resolved, and the AI limit.

The AI in your chat answers only from your own site's pages and shows where each answer comes from. When the bot cannot or should not answer, the conversation goes to your operators, in Telegram or the inbox in the app.

## Every answer has a source
- The AI looks for the answer in your knowledge base. That is the pages of your site we read ([Knowledge base](https://tolkly.io/docs/en/knowledge.md)).
- The answer is made of short sentences. Each sentence names its source and quotes it word for word. The visitor sees the quote under the sentence and a link to the page.
- Code, not the AI, checks each quote. If the quote is not on the page it names, the sentence is removed before the visitor sees it.
- A second check removes a sentence that adds a detail its sources lack.
- Under the answer, the visitor sees how many sentences were checked against the rules and how many were removed.

## When your pages do not cover it
The bot does not guess. If your pages have no answer, or no sentence passes the check, the bot says so: «I did not find this in the help pages and rules of the site.» Then it offers «Hand over to an operator».

## The visitor knows it is AI
- The chat's standard greeting says an AI assistant answers.
- The chat's header says «AI assistant».
- Each AI reply carries an «AI» mark.

When only people answer (the «Operators only» mode, [Who answers](https://tolkly.io/docs/en/handoff.md#who)), there is no AI mark, because no AI writes there.

## When a person takes over
The bot reads each message before it answers and understands it by meaning, not by keywords. The conversation goes to your operators, in Telegram or the inbox, when the visitor:

- asks for a person;
- asks about their own order or payment;
- writes about one of your topics for an operator.

When nobody can answer, the chat asks the visitor for a contact. What goes over when, who answers, in which hours, and how to set it up: [Handoff to people](https://tolkly.io/docs/en/handoff.md).

## What counts as resolved
Only the visitor decides:

- they press «It helped» under an AI answer;
- they answer «Yes» to «Did we solve your question?». The chat asks this after an operator closes the conversation.

Silence never counts. If the visitor read the answer and left, or the conversation went quiet and closed by itself, it is not resolved.

## When the AI limit is spent
Two limits stop the AI:

- **The company's month.** Your plan gives the company a number of AI conversations a month, for all its projects together. When they are spent, people answer until the next month starts ([When the limit is reached](https://tolkly.io/docs/en/billing.md#cap)).
- **A daily guard per project:** 300 answers with a checked source a day. The day starts at 00:00 UTC. Only answers that kept at least one checked sentence count; refusals and messages handed straight to people do not. A second daily guard counts all of the AI's work, refusals included, and works the same way.

Past either limit, people answer. The visitor reads «The AI assistant has reached its limit, so an operator will answer. Bringing one in.» The conversation goes to your operators marked «AI limit spent» in the app and «The AI limit is spent» in Telegram. Nothing extra is charged.

Source: https://tolkly.io/docs/en/overview.md

---

# Quickstart: from sign-up to the first conversation

> Six steps from creating your company to a test conversation on your own site.

This page takes you from sign-up to the first real conversation on your site. You do all of it yourself, in the app. If you want help with any step, write to us.

## 1. Sign up and create your company
1. Open [https://app.tolkly.io/start](https://app.tolkly.io/start) and sign in in one of these ways: a code to your email («Get a code»), «Continue with Google» or «Continue with Telegram». There is no separate sign-up: the account is created when you first sign in.
2. On the «Create your company» screen, enter the company's name, accept the terms of service and the privacy policy, and press «Create company». You are its owner.

The free month starts at once: 30 days, up to 250 AI conversations, 3 sites and 300 pages. Operators, the inbox and Telegram work from day one. When the month ends, the AI turns off and operators answer; nothing is charged by itself ([Plan, payment and limit](https://tolkly.io/docs/en/billing.md#trial)).

> [!TIP]
> If you will answer in Telegram yourself, sign in with Telegram. Or connect it later on the account page, under «Ways to sign in».

## 2. Add your site
Right after the company is created, the app opens «New project». Give the site's address and say what the business does. The app reads the site's colours, then its pages, and shows how far it got. You can leave the page: the site is read in the background. The question about the business picks an AI model allowed to serve your industry and visitors; it changes nothing else. A project's industry can be changed later in «Project».

If you tried the chat on your site from our landing page, that demo becomes the company's first project, with its pages and colours.

Your company's projects are under «Projects». A project opens on «Overview». Its sections are in the panel beside it: «Install», «Widget», «Knowledge», «Q&A», «Handoff to people» and «Project». «Install» holds the code, the sites where the chat runs, and domains. Under «Advanced settings» there you find strict mode, the mirror script key and visitor identity. «Project» holds the name, the industry, the [spam guard](https://tolkly.io/docs/en/spam.md) and deleting the project.

The Telegram group and the team belong to the whole company. They are under «Team and plan» › «Telegram» and «Team».

Operators see every section read-only, marked «View only». Only owners and admins get the buttons; operators only lift visitor blocks in «Project».

Another site of the company (a mirror with its own brand, a second product) is a project of its own: an owner or admin adds it the same way, with «New project» under «Projects».

An owner or admin deletes a project at the bottom of «Project», typing its name to confirm. From that minute the chat shows nothing on the site, open conversations and their Telegram topics close, and the site is not read again. For 30 days an owner or admin brings it back under «Projects» → «Deleted» (closed conversations stay closed); then it is deleted for good with its conversations and files. A deletion never resets the company's month of AI conversations.

Until the chat is launched, «Overview» shows «Launch the chat» and a «N of 7» count. These are the seven steps on this page. The server checks each step by itself. Under the steps, «Not working?» has the open step's guide and a task to copy for a developer or an AI agent. Once every step is done, «Overview» shows the day's numbers instead. Every state, the help with a step and what comes after launch are in [Launch and overview](https://tolkly.io/docs/en/launch.md).

### Check the answers and the look
In «The AI answers by your rules», ask what your visitors ask. Every answer shows its quote and the page it is from. These questions are not counted as visitors' conversations in «Reports».

If the answers are right, press «The AI answers right». If not, the answer is missing from «Knowledge» ([Knowledge base](https://tolkly.io/docs/en/knowledge.md)). If a new reading of your site waits for your decision, decide it in «Knowledge» first: the answers may change with it.

«The chat in your site’s colours» says whether the colours and font come from your site, and leads to «Widget». There, the real chat beside the fields shows your changes before you save them ([How the chat looks](https://tolkly.io/docs/en/widget.md)). The «AI answers» mark is always shown and cannot be turned off. If it all fits, press «Looks good».

## 3. Install the chat
The «Install» section has two lines of code and two buttons: «Copy the code» and «Send to a developer». The second copies the code with the links a developer needs. The code goes just before `</body>` on every page where the chat should appear.

- **A developer:** send them the code and [Install on a site](https://tolkly.io/docs/en/install.md).
- **An AI coding agent:** under the code, «Hand it to an AI agent» gives a prompt for Claude Code, Cursor or another agent. Press «Copy the prompt» and paste it into the agent.
- **A site builder** works too, if it takes custom HTML (Tilda, WordPress, Bitrix).

If your site sends a Content-Security-Policy, your developer adds the chat to it: [Content-Security-Policy](https://tolkly.io/docs/en/csp.md).

Until the chat loads on your site, the block says «Not installed yet». A few minutes after it loads, it says «Works on example.com · 2 min ago». If the chat is not seen on the site for 7 days, it says «Not seen on example.com for 7 days» in red.

## 4. Link your Telegram group
Under «Team and plan» › «Telegram», press «Get a link for the group» and follow the steps. You need a group with Topics on, and you open the link in Telegram. From then on, every handed-off conversation becomes a topic in that group. Details: [Operators in Telegram](https://tolkly.io/docs/en/telegram.md).

Link the group before the chat goes live. Then the group hears about your site the first time the chat loads there ([Domains and mirrors](https://tolkly.io/docs/en/domains.md)).

## 5. Invite your operators
On the team page, press «Invite», choose the role, and press «Create link». The roles:

- **Operator** answers visitors in the inbox of every project and sees the settings read-only.
- **Admin** runs the support: projects and their settings, reports, the team. An admin invites and removes operators and admins, but not owners. Like everyone, an admin sees how much of the plan is used, but not the plans and payments, and does not pay.
- **Owner** can do everything, the plan and payment included.

An owner or admin who also answers visitors is «Owner and operator» or «Admin and operator»: choose that role, or just start a shift or take a conversation, and the operator's part is added by itself. The person who makes the company starts as «Owner and operator».

 Copy the link at once: it is shown only once. It works once, for 7 days. The email field is just a note for you. Send the link yourself, in Telegram or by email.

Each operator then:

- signs in, with Telegram if they will answer there;
- sets a work name on the account page, under «Work name» (or with `/name Anna` in Telegram). By default, replies without a work name do not reach visitors; the company's rule is «Work names» on the team page;
- starts a shift when they start work.

An invited operator lands in the inbox. Above the list they see the «You are on the team» card with items: «Start shift» and «Sign in with Telegram» (when a group is linked). The items tick themselves.

If you answer yourself, press «I answer myself» in the «Invite operators» step.

### Who answers and when
Once someone can answer, turn on «The project has operators» in «Handoff to people». Until then nobody is handed a conversation: when the bot cannot answer, the chat asks the visitor for a contact, or offers your own support link if the install code has one ([Without operators](https://tolkly.io/docs/en/handoff.md#no-operators)). Nobody waits for nothing.

The same section holds:

- the working hours;
- the contact a visitor leaves when nobody can answer;
- topics for an operator;
- reply templates;
- the order number.

Details: [Handoff to people](https://tolkly.io/docs/en/handoff.md).

## 6. Test it on your own site
1. Start a shift: in the app, open your account menu and press «Start shift». Or send `/shift on` in the group.
2. Open the chat on your site and ask a question your rules answer. The answer comes with a quote and a link to the page.
3. Write «I want to talk to a person». The chat says it is bringing in an operator.
4. In the group, a new topic opens with the conversation's card. In the app, the conversation is under «Waiting for a reply».
5. Press «Take» and reply, in the topic or in the inbox. The reply shows in the chat on your site.
6. Press «Close». The chat asks the visitor «Did we solve your question?».

The «A test conversation» step on «Overview» is done as soon as an operator first answers a handed-off conversation. A visitor's real conversation counts too.

If the chat asks for a contact instead of waiting, nobody was on shift and nobody had the inbox open. Details: [A contact when nobody answers](https://tolkly.io/docs/en/handoff.md#contact).

Source: https://tolkly.io/docs/en/quickstart.md

---

# Launch and overview

> The project's «Overview» — the launch steps and their states, help with a step, the day's numbers, what is worth setting up, «Reports» and the start page.

A project opens on «Overview». Until the chat is launched, it shows «Launch the chat», a list of steps. After the last step, it shows how the chat does today. The [quickstart](https://tolkly.io/docs/en/quickstart.md) walks the steps in order. This page says what each state means.

The server checks every step by itself, from what really happened: a page view on your site, a linked group, an operator's reply. You tick a step by hand only where only a person can tell: that the answers are right, that the look fits, that you answer yourself. Operators see the same steps and colours, without the buttons.

## The launch steps
«Launch the chat» has a bar with a segment per step and its «N of 7» count. On a server without a Telegram bot, the «Telegram for operators» step is left out, and it is «of 6».

Two steps belong to the whole company and are marked «for the whole company». Done once, they are done in each of its projects.

A step's dot:

- green — done;
- orange — waits for you;
- grey — under way;
- red — broke.

The step to do now is open: the first that broke, or else the first not done.

| Step | What it says |
|---|---|
| «The AI answers by your rules» | «The site is not read yet»; «Reading the site…» (grey); «12 pages · check the answers»; «Checked 1 Nov · 12 pages» after you press «The AI answers right»; «A new reading waits for your decision» (orange); «Reading failed …» or «robots.txt closes the home page» (red) |
| «The chat in your site’s colours» | «Look and confirm»; «Confirmed …» after you press «Looks good» or save a colour or the greeting in «Widget» |
| «Install on your site» | «Waiting for the first load»; «Works on example.com»; «Not seen on example.com for 7 days» (red) when the chat has not loaded there for 7 days |
| «Telegram for operators», for the whole company | «No group yet»; «Linked …»; «Unlinked …» when an owner unlinked it; «The bot was removed …» (red) |
| «Invite operators», for the whole company | «Only you so far»; «1 invite not yet taken» (grey); «Done …» once a second person joins or you press «I answer myself» |
| «Who answers and when» | «Only the AI answers» until «The project has operators» is on. Then «AI first, then people» or «Operators only» ([Handoff to people](https://tolkly.io/docs/en/handoff.md#who)) |
| «A test conversation» | «Not yet»; «Waits for an answer» (grey) while a handed-off conversation waits; «Answered …» after an operator's first reply. A visitor's real conversation counts too |

### Inside a step
An open step shows its state, one action and a link to its section, where the rest is set. Only two things are done right in a step:

- «The AI answers by your rules» has a chat for your questions. Each answer shows its quote and page. These questions never count as visitors' conversations.
- «Install on your site» has the code with «Copy the code».

The other steps lead to their own page: «Widget», «Telegram», «Team», «Handoff to people» or the inbox.

### «Not working?»
Under the steps, for owners and admins, help with the open step:

- **«Guide»** — the page of these docs for the step.
- **«Copy the task»** — what to do and how to check it, in plain words for a developer or an AI agent. For the install it is the whole install prompt ([For AI agents](https://tolkly.io/docs/en/agents.md#prompt)).
- **«Contact us»** copies our contact with the project and the step named.

## After launch
Once every step has been done, the list folds into one line, «Chat launched» with its date. «Show steps» opens it again. The line's dot shows the worst of today's steps: if any step is red, it is never green.

A step can stop working after launch: the chat not seen on the site for 7 days, the bot removed from the group, a reading of the site failed. Then:

- the step moves up under «Needs attention»;
- «Projects» gets a red dot for owners and admins;
- a strip shows above the inbox of owners and admins.

A step that waits for you (such as a new reading held for your decision) is listed under «Needs attention» too, without the dot.

The company's Telegram group hears of a lost chat or a failed reading. Owners and admins get an email when the bot is removed from the group.

### Today
The day's numbers since midnight in the project's time zone. They refresh every minute.

| Tile | What it counts |
|---|---|
| «Conversations» | Conversations started today, and how many of them the AI answered with a checked source |
| «Handed to people» | Conversations handed over today, and how many wait for an operator now |
| «That helped» | Conversations where the visitor pressed «It helped». Only the visitor's own button counts, never silence or an operator's close |
| «First reply» | How long, on average, from the handoff to an operator's first reply, counted within the working hours |

### Worth setting up
For owners and admins: things the launch steps do not count but that make the chat better. Each row links to its block:

- **«Domains»** — block sites that are not yours, or let the chat run only on your domains ([Domains and mirrors](https://tolkly.io/docs/en/domains.md)).
- **«Topics for an operator»** — questions that always go to people. Once you have topics, the row shows how many ([Topics](https://tolkly.io/docs/en/handoff.md#topics)).
- **«Q&A»** — operators' answers written down for the knowledge base, and your own ([Knowledge base](https://tolkly.io/docs/en/knowledge.md#drafts)).
- **«Visitor identity»** — your site signs the visitor, so operators see who writes ([Signed visitor identity](https://tolkly.io/docs/en/identity.md)).

## Reports
Owners and admins have «Reports» in the main menu: the numbers of every project together, or of one, over 7, 30 or 90 days. After launch, «Reports» next to «Chat launched» opens them for this project. Days are counted in the company's time zone, set on the «Team» page.

- **Tiles:** conversations; the share of AI conversations the visitor confirmed with «That helped»; how many were handed to people, after the AI or straight away; the operator's first reply, timed from the handoff and in working hours where the project has them. Each tile also shows the period before, when it had conversations.
- **By day:** every conversation in one part: «That helped», «The AI refused», «Handed to people», «No reply». Hover over or focus a day to see its numbers. Until there are 7 days of conversations, the days are a table instead of a chart.
- **Why handed to people,** **Operators** (first replies and ratings) and **Missing from the knowledge base:** the visitors' questions the AI could not answer from your sources, the most asked first. «×3» means in three conversations. «Answer» opens [the answer form](https://tolkly.io/docs/en/knowledge.md#drafts); a question with an answer is marked «answered» and moves down.

With fewer than 10 AI conversations, a share is written as «5 of 9», not as a percentage. Silence is its own part and never counts as solved. Only the visitor decides what is resolved ([How Tolkly answers](https://tolkly.io/docs/en/overview.md#resolved)). Your own test questions in the launch step are never counted. Operators do not see «Reports».

## Start page
What opens when you sign in is set on the account page, under «Start page», for each company. «Auto» suits most people: an owner or admin sets the company up on the project's overview until the first launch, then lands on «Reports»; an operator lands in the inbox. Instead of «Auto» you can pick «Reports» (owners and admins), «Inbox» or «Projects». It saves at once. A direct link always opens where it leads.

## On a phone
On a phone, the overview is also the project's list of sections. Before launch it is plain navigation, «Project sections», since the steps above carry every state. After launch it is «Status»: each section with its dot and one line, the same the panel shows on a desktop. For example: «Live on example.com», «12 pages», «AI first, then people» or «Colours from your site · sound off».

Source: https://tolkly.io/docs/en/launch.md

---

# How the chat looks

> The chat's colours and font from your site, the live preview, languages, greeting, hint and sounds.

In the project's «Widget» section you set how the chat looks and sounds to your visitors: colours and font, languages, the greeting, the hint and the sounds. Beside the fields is the preview: the real chat with your changes. On a phone, the preview comes right after the colours. Owners and admins change everything here; operators see the same values as text.

You don't touch your site's code. The chat takes its settings from the server, so the two lines of the install stay as they are ([Install on a site](https://tolkly.io/docs/en/install.md)). Visitors see a change within two minutes, on the next page they open.

## Colours and font
When you create the project, we read the colours and font from your site's home page, so the chat looks like part of the site. The block «Colours and font» shows the accent, «Light or dark» and the font; the background, text, corners and send button are under «Advanced settings»:

- **Accent**: the chat button, the visitor's messages, links to sources.
- **Background** and **Text**: the colours of the chat window itself.
- **Font**: font names separated by commas, as in CSS (`Inter, sans-serif`). If empty, the chat uses the visitor's system font.
- **Corners**: the window's corner radius, 0 to 24 px. If empty, the radius is taken from your site's buttons, and you see it in the field. Buttons and fields inside the window follow it, so their corners stay nested. It saves on its own when you stop typing.
- **Send button**: the icon on it, an arrow up (the default), a plane or an arrow right. Pick what suits your site. It saves at once.

Each colour has a picker and a field for its value (`#ffd828`). A colour saves on its own as soon as you pick it. The font saves when you leave its field. An empty colour field shows «Auto»: the chat picks that colour to match the background.

Whatever you set, the chat keeps text readable:

- if the text colour is too close to the background, the chat replaces it;
- if the accent is too light to read as text (a yellow, say), it stays on the buttons and links take the text colour.

Two more buttons in this block:

- **«Read from the site again»** reads your main site's home page again, for example after a redesign. If the home page gives nothing to read, the colours don't change.
- **«Use the widget’s own colours»** clears the colours and font, both those set here and those read from the site. The chat goes back to its own neutral colours. «Read from the site again» brings the site's colours back.

The main site is the first site in «Knowledge» ([Knowledge base](https://tolkly.io/docs/en/knowledge.md#sites)).

> [!NOTE]
> When you save a colour or the greeting here, the launch step «The chat in your site’s colours» is marked done. «Looks good» on the overview does the same ([Launch and overview](https://tolkly.io/docs/en/launch.md#steps)).

## The preview
The preview is the real chat: the same `widget.js` your site loads. It runs on a page our server signs for the values in the fields, saved or not.

Nothing is sent from the preview. A message typed there reaches nobody, starts no conversation and never counts in «Reports».

The «AI answers» mark always shows, here and on your site. You can't turn it off: a visitor always knows an AI is answering ([How Tolkly answers](https://tolkly.io/docs/en/overview.md#ai-mark)).

The preview reloads a moment after you stop typing. If «Language» has more than one language, a switch appears above the preview. It shows the chat as a page in each language sees it.

## Language
In the block «Language» you say which languages your site is in. The chat speaks the page's language (its `<html lang>`) if it has an interface in that language. It has 15: English, Russian, Armenian, Kazakh, Uzbek, Azerbaijani, Georgian, Kyrgyz, Tajik, Ukrainian, Turkish, German, Spanish, French and Portuguese. Otherwise the chat speaks the primary language: a Polish page of a Russian site gets the chat in Russian, not English.

- **«Primary language»**: the language of most of your pages. If it is not set, the chat follows the page and speaks English in other languages. There is then one greeting for every page.
- **«Other languages of the site»**: the other languages, added with «Add». Each one gets its own greeting and hint below. If you remove a language, its texts are removed too, after you confirm.
- **«Chat’s words»** (under «Advanced settings»): «By the page’s language» or «Always in the primary language». You need the second one when your pages name the wrong language. For example, a template puts `lang="en"` on Russian pages.

The bot's answers don't depend on this block: the bot answers in the language of the question. The quotes under an answer stay word for word, in the language of the page they come from. If a conversation's language differs from the primary one, it shows in the inbox and in the Telegram topic ([Inbox](https://tolkly.io/docs/en/inbox.md)).

## The greeting
The greeting and the hint over the chat share one block, «Chat texts». Each field saves when you leave it.

The greeting is the chat's first line, in your words. Say what visitors can ask about, for example «Hello! Ask about exchange rates, limits and how long a transfer takes.» Up to 400 characters.

With other languages set, you write the greeting on a separate row for each language. If a row is empty, the chat shows its own line in the page's language, saying that an AI assistant answers. A page in a language not on the list gets the primary language's greeting.

## The hint
«Hint over the chat» is a short line beside the closed chat. It shows once per visit. Like the greeting, you write it separately for each language. An empty row means no hint in that language. A page in a language not on the list gets the primary language's hint. The `teaser` attribute on the tag wins over this setting ([Attributes](https://tolkly.io/docs/en/widget-attributes.md)).

## Frequent questions
«Frequent questions» are buttons the visitor sees when the chat opens, on their side at the bottom, next to the reply field. A press sends the question as the visitor's own message, and the bot answers it as any other: from your sources, with a link, or it hands the conversation to people. A page shows 4 at most, up to 60 characters each; the project keeps up to 12. They go away after the visitor's first message. The block shows the questions as the chat does; drag one by the dots at its left to set the order (or focus the dots and press ↑ ↓). Press a question to edit it: a tab per language, where it shows, «Remove».

Under «On every page» you can keep a question to some pages: «Only on pages» takes the start of a page's address after the domain, as `/exchange/`, and `*` stands for any characters (`/exchange/btc-*`). A page shows its own questions first, then the ones for every page.

Each question saves when you leave its field, and is then tried through the bot. Its row says what the bot does with it: «Answers with a quote», «Goes to people» (a person asked for, one of your topics, the order status), or «The bot has no answer». The last one is worth fixing: the chat would offer a question and then refuse it. Add the answer to Knowledge and press «Check again». A check is one paid answer per text, and it starts no conversation.

With other languages set, each question has a row per language. A page in a language without its own text gets no button for that question: a button in the primary language would start the conversation in it. A page may set its own questions instead ([Suggested questions](https://tolkly.io/docs/en/widget-api.md#suggestions)).

Under the list, «Asked in conversations» offers the approved [knowledge drafts](https://tolkly.io/docs/en/knowledge.md#drafts) the most asked first: their answers are sources already, so the bot answers them. A press adds the question.

Each press is kept with its conversation. «Reports» lists every question with its presses and how those conversations ended; a question nobody presses is worth replacing.

## Position
«Position» (at the foot of the page, under «Advanced: position») puts the chat in the bottom right or bottom left corner. It also sets the gaps from the side and the bottom of the page: 0 to 400 px, 20 by default. Lift the chat if a tab bar or a cookie banner covers the button. The preview shows the open window, so you only see the corner on your site. A page can set its own position, including for phones only ([Placement](https://tolkly.io/docs/en/widget-attributes.md#placement)).

## Sounds
The chat plays a short signal when a reply comes and the visitor isn't looking at the chat: it is minimized, or the tab is in the background. A visitor can turn sounds off for themselves right in the chat, and their choice wins over yours.

«Play sounds» turns sounds on and off for everyone. If you turn them off, the settings below are kept until you turn them on again. Every change saves at once.

Under «Advanced: which replies, signal and volume»:

| Setting | What it does |
|---|---|
| «An AI answer» | Once, when the answer is complete |
| «An operator’s message» | Each message an operator sends |
| «An operator joins» | A softer signal of its own. Off by default: the operator's first message rings anyway |
| «Signal» | «Soft», «Bright» or «Short»; «Listen» plays it |
| «Volume» | «Quiet», «Medium» or «Loud» |

At most one signal every 3 seconds, across all of a visitor's tabs.

Source: https://tolkly.io/docs/en/widget.md

---

# Knowledge base and reindexing

> What the bot reads, how often it reads your sites again, how it picks up mirrors and learns from operators' answers.

The bot answers only from your knowledge base. It holds the pages of your sites we have read and the questions and answers you have approved or written. This page covers what we read, when we read it again, and how to keep your rules where the bot can see them.

## What we read
- **The sitemap first.** We take the pages from your site's sitemap: the one named in `robots.txt`, or the one at the usual address. A gzipped sitemap works too.
- **No sitemap, then links.** A site with no sitemap is read from its home page, following links.
- **Only pages under the site's address.** If the site's address is `example.com/help/`, we read only pages under `/help/`.
- **`robots.txt` is respected.** We don't read pages it closes. For your own site you can lift it for some addresses: «Advanced settings» › «Read despite robots.txt». The app asks you to confirm the site is yours and keeps your name and the date.
- **HTML pages only.** We don't read PDF files or documents the site links to: upload them as files ([Files](#files)).
- **No JavaScript.** We read the HTML the server sends. We don't see text a script draws after the page loads.
- **Your menu and footer once.** What repeats on every page is kept once, so it doesn't crowd out the rules.

If a page isn't in your sitemap, add it to «Extra pages». We read up to 2,000 pages from each site.

## Sites
The project's «Knowledge» section opens with «The AI knows: 2 sites, 12 files…» and «Read all again». Each count links to its part: «Sites», «Files» or the «Q&A» section. Below are [what the AI knows about the project](#card), the sites, the files and one line on what can be connected soon. Whether the chat's new domains are read is set in «Install» › «Domains» ([The domain rule](#domain-rule)).

«Sites» lists your sites and the sites found on your domains, one row each. A row shows how many pages were read and when. The common schedule is said once in the part's note; a site on another one names its own. A dot opens the grey line only when a site needs you, with what is wrong in a few words, such as «no links seen». For all such sites, one «Hand it to an AI agent» row at the end of the part holds a prompt for the developer.

An owner or admin presses «Add a site». A site needs only its address. The rest is under «Advanced settings», a line per setting: what it is now and «Edit». Its editor opens under the line, one at a time; the whole form saves at once.

- **Sitemap:** we find it, you give its address, or there is none and we follow links.
- **Which pages:** all, only the sections you list, or all but them.
- **Extra pages:** addresses the sitemap does not list.
- **Read despite robots.txt:** sections robots.txt closes to reading.
- **Name:** the site's address by default.
- **Read again:** as every site (every day), every week, or only when asked.

A section is the start of a page's address after the domain: `/ru/faq/` is every page whose address starts so. A star stands for any characters, slashes too: `/blog/*/2024/` or `*/archive/`. Nothing needs escaping, and a whole address pasted in loses its domain by itself. «Own expression» stays for those who write regular expressions.

A project has up to 20 sites. The first site is the main one: the site card and the widget's colours come from it. If another source already holds a page's text, it is kept once.

«…» on a row edits or removes the site. A removed site's pages leave the knowledge base at once. A project always keeps at least one site of its own. Operators see the list without the buttons.

## Files
Rules, terms of service, an AML policy or a price list that are not on your site go in as files: drop them on «Files» or press «Upload files». Files show as a grid of cards: a mark with the extension, the name, the size and the number of fragments. Past 12 files a search and an order appear, and the grid folds after two rows. The box in a card's corner selects it, to remove several files at once.

- **Formats.** PDF, DOCX, Markdown, TXT and HTML, up to 10 MB each. We tell the format by the file itself. Open an old `.doc` in Word and save it as `.docx`.
- **Headings.** The bot splits a file into sections by its headings. In a PDF a heading is a line set larger than the text; in Word it is a heading style or a short paragraph that is bold all through. Page numbers and running headers are left out.
- **The link in an answer.** A file has no address on your site, so the bot links to a page with its text, exactly what it answers from, scrolled to the right section. The file's name in its source row opens that page.
- **Scans.** A scan holds pictures of pages, no text. Such a file is not read, and its row says why. Save the document with a text layer.
- **Long files.** We read up to a million characters of a file. If it is longer, the row says only its start was read.
- **A new version.** Drop the new file on the old one's card, or choose «…» › «Replace the file». A dialog shows both files, «Now» and «New», and asks to confirm. A file uploaded under a name that is a source already gets «Replace the file» or «Add as new». The bot reads the new version at once; links in earlier answers open the new text. A file is never read again by itself: it changes only when you upload a new one. The same file is not uploaded twice.

A project holds up to 100 files; they do not count toward the 20 sources.

## The domain rule
Mirrors change faster than anyone edits settings. In «Install» › «Domains», the «Read new domains» row turns the domain rule on: it reads your new domains by itself. Above it in the same block are the domains the chat loaded on and what the AI does with each; a domain that waits for you has «Allow».

- **The mask.** The rule looks only at domains that match its mask: «Advanced: the mask and a new domain» › «Domain mask». The syntax is the same as in the [domains list](https://tolkly.io/docs/en/domains.md#strict). By default it is the subdomains of your main site, for example `*.brand.com`. For numbered mirrors write `brand*.com`: a star stands for any letters and digits. The mask saves when you leave the field. There, too, «Add a domain» puts your domain on the allowed list ahead of time: the AI reads it once the chat loads there.
- **«Which domains»: «Only allowed» or «All but blocked».** Only allowed by default: a domain counts only once you allow it, in «Install» › «Domains», in Telegram or with your mirror script. Without this, a copy of your site with one changed detail, such as a wallet address, could get into answers by itself. A blocked domain is never read.
- **A copy is a mirror.** We compare a new domain with your main site: up to 20 pages, starting with the home page, text against text, and the home page's `rel=canonical`. We don't read a copy again: answers to a visitor there already link to that domain.
- **New text is a site.** A domain with text of its own becomes a site of the project and is read every day. The company's Telegram group gets a message about each one: «a mirror of …» or «a new site … is indexed».
- **When it runs.** When you allow a domain, and once a day. The list shows the domains the chat has been on and what the rule does with each. If you take a domain off your list or block it, its site and its pages go on the next check.

## Runs that wait for you
If one run would change or remove more than 45% of a site's pages, nothing is written. The bot keeps answering from the pages it had. That is what a bot wall, a parked domain or a broken site looks like.

The row's dot turns orange and the row says what changed: «11 changed, 1 gone of 12 pages». The company's Telegram group gets a message too, with a link to the sources.

- If the site really changed, press «Accept changes»: the site is read again and written.
- «Reject» keeps the old pages. The next run checks again.

Sites under 10 pages are never held.

## Make your rules readable
- Put rules, limits and terms on an ordinary HTML page, not on an image or in a pop-up drawn by a script. Rules that exist only as a PDF go in as a [file](#files).
- List that page in your sitemap.
- Don't close it in `robots.txt`.
- Keep it under the site's address.
- When you change a rule, change the page too: the bot quotes what the page says.

### Hand it to your site's AI agent
If a site's last reading went badly, owners and admins see a «Hand it to an AI agent» row in «Sites». It appears when:

- `robots.txt` closes the home page;
- fewer than 5 pages were read;
- pages came with no text: scripts draw them, or they are behind a sign-in.

The prompt asks the coding agent that edits your site to:

- list the help pages in the sitemap;
- render them on the server;
- let us in through `robots.txt`;
- keep the FAQ outside a sign-in;
- check everything with `curl`.

Below is the prompt with a sample site. «Open in…» → «Prompt for an AI agent» copies it.

```text
Make this website readable for the Tolkly support chat: it answers visitors only from the site’s own pages, and its crawler reads them badly now.

Site: https://your-site.example
Crawler: the user agent "TolklyBot/0.1 (+https://github.com/tolkly/tolkly)"; in robots.txt it reads the groups for TolklyBot and for *

1. Read https://tolkly.io/docs/en/knowledge.md. If it does not load, this prompt is enough.
2. Find the pages with the answers visitors need: help, FAQ, rules and terms, prices and limits, contacts.
3. Serve a sitemap.xml that lists every one of them, at https://your-site.example/sitemap.xml or named by a "Sitemap:" line in robots.txt. When a sitemap exists the crawler reads only the pages it lists and follows no links, so a page missing from it is never read.
4. Render those pages on the server: their text must be in the HTML the server sends, with no JavaScript run. In a single-page app use the framework’s server rendering or prerender these routes; an empty shell that scripts fill in reads as a page with no text. Leave no <meta name="robots" content="noindex"> on them.
5. In robots.txt, let the crawler in: no Disallow line in the group for TolklyBot or for * may cover the home page or these pages. An Allow line does not reopen what a Disallow closes for this crawler, so remove or narrow the Disallow instead. Do not turn the user agent away at a firewall, CDN or bot protection either.
6. Keep the FAQ and the rules outside a sign-in: a page that asks the crawler to log in reads as a page with no text.
7. Check it: curl -A "TolklyBot/0.1 (+https://github.com/tolkly/tolkly)" <a help page’s address> prints the answer’s text in the HTML, https://your-site.example/robots.txt closes none of these pages, and the sitemap lists them. Then list the files you changed, and tell me to press «Read again» on the site in Tolkly’s «Knowledge» section.
```

## The daily reindex
Each site is read again on its own schedule, at 04:00 Moscow time: every day (the default) or every week. A site set to «Only when asked» is never read again on its own. The site's form shows that time in your project's time zone, as in «Read again every day at 04:00 (Moscow Standard Time)».

- Changed pages are read again; the rest are kept as they are.
- Pages gone from your sitemap leave the knowledge base. A site read by following links loses no pages because one request failed.

## Reindex by hand
If a change must count today, an owner or admin presses «Read again» (the arrow on the site's row) or «Read all again» above the list. What a row may say:

| Words | What they mean |
|---|---|
| «Not read yet» | Added, not read yet (orange dot) |
| «Waiting for its turn…» | Another site or project is being read first |
| «Reading the site now…» | The run is going |
| «Read … · Every day · next …» | Done |
| «Not read …: the site did not answer» | The run failed (red dot). It may also say «the site turned us away (a bot wall or a login)», «the site answered with an error», «the server restarted mid-run» |
| «… changed, … gone of … pages» | The run waits for your decision (orange dot) |
| «robots.txt closes the home page to us» | Your `robots.txt` closes the home page itself to the bot (red dot) |

## When a run fails
A failed run is not retried until the next scheduled time. Once your site answers again, press «Read again». Until then the bot keeps answering from the pages it read before. If it keeps failing, tell us.

## What the AI knows about the project
With every question, the AI is told what your project is, whatever domain the chat is on. By default that is the title and description of your main site's home page. It is the block «What the AI knows about the project» at the top of «Knowledge». An owner or admin presses «Edit», writes it in their own words (up to 1,500 characters) and presses «Save». The main site is then read again to take it in. «Use the home page's» goes back to the default.

## Q&A
When a conversation an operator answered is closed, the AI saves the operator's answer as a draft: a question and an answer, in the operator's words only. Drafts wait in the project's «Q&A» section, under «New». The most asked come first («Asked 3 times»).

You can also write an answer yourself, without changing the site or uploading a file: «Write an answer» in «Q&A», «Answer» beside a question in «Reports» › «Missing from the knowledge base», or «Write the answer» beside a frequent question the bot would refuse. «Save and approve» puts it in the knowledge base at once; «Save to New» leaves it for another look.

- If a close question is there already, its answer is shown first: edit that one, or «Save anyway».
- The question becomes the title of the answer's page, so it cannot hold an order or transaction number, an email or a phone.
- For something passing (withdrawals delayed today), set «Answer until» under «Advanced»: after that day the bot stops answering from it and its page closes.

- **«Approve»**: from now on the bot answers that question itself. In the chat it cites «Support answer» («Ответ поддержки» in a project set up in Russian). The answer has its own page.
- **«Edit»**, then «Save and approve»: fix the words first.
- **«Dismiss»**: if the question is asked again, no new draft appears. «Approve after all» brings it back.
- **«Withdraw»** on an approved answer: the bot stops answering from it at once, the answer's page closes, and the answer moves to «Dismissed».

Only owners and admins can write, approve, edit and dismiss. Operators see what became of their answers.

Source: https://tolkly.io/docs/en/knowledge.md

---

# Handoff to people

> When the bot hands a conversation to a person, who answers and when, the visitor's contact, topics for an operator, reply templates and the order number.

If the bot cannot or should not answer, the conversation goes to your operators: to the company's Telegram group and to the app's inbox. In the project's «Handoff to people» section you set who answers and when, what a visitor can leave when nobody is there, and which subjects always go to a person. Owners and admins change these settings; operators see them as text.

## When the bot hands over
The bot reads each message before it answers. It goes by meaning, not by keywords, so it recognizes a request in any wording and any language.

| What happens | What the bot does |
|---|---|
| The visitor asks for a person | Says nothing and hands over at once |
| A question about the visitor's own order, payment or account | Answers the general part from your rules, then hands over |
| One of your [topics for an operator](#topics) | As you choose: says nothing and hands over at once, or answers and offers a person |
| The visitor sends a file | The bot never reads files. A file alone goes to people at once. If the file comes with text, the text gets its answer first |
| «Operators only» | Every message goes to people ([Who answers](#who)) |
| The AI limit is spent: the company's month of AI conversations, or a project's daily guard | Every message goes to people ([When the limit is reached](https://tolkly.io/docs/en/billing.md#cap), [the daily guard](https://tolkly.io/docs/en/overview.md#daily-cap)) |

If the bot is unsure whether a person is needed, it still answers, and offers a person beside the answer. Under every answer there is also a «Talk to an operator» button. If the message holds an order number, the operator sees it on the conversation ([Order number](#order)).

## Who answers
The «Who answers» block shows one of three states. The words are the same as on the overview and in the phone's list of sections.

| State | What it means |
|---|---|
| «Only the AI answers» (orange dot) | Nobody is handed a conversation; when the bot cannot answer, the chat asks the visitor for a contact ([Without operators](#no-operators)) |
| «AI first, then people» | The bot answers from your sources and hands over when needed |
| «Operators only» | Every message goes straight to people; the bot stays silent |

The state comes from two settings. Each one saves at once.

- **«The project has operators»**: turn it on once someone can answer. When it is off, nobody is handed a conversation ([Without operators](#no-operators)).
- **«Who answers first»**: «AI first, then people» or «Operators only». «Operators only» is also the pilot's emergency switch: the bot stops answering at once.

With operators on, the launch step «Who answers and when» is done ([Launch and overview](https://tolkly.io/docs/en/launch.md#steps)).

## Working hours
Working hours are when your operators answer. The AI answers round the clock either way.

- Outside the hours, a handed-off visitor is asked to leave a contact. The exception is when someone is on shift: they answer at any time.
- With no hours set, whoever is on shift or has the inbox open answers.

«Add hours» adds a range: days, a start time and an end time. A project can have up to 14 ranges. A range that ends before it starts runs past midnight, and the form marks it «past midnight». For example, «Fri 22:00–02:00» is Friday night into Saturday. «Save hours» saves the ranges. If you leave the page without saving them, it asks first.

Pick the time zone under «Advanced: time zone», below the save button. The hours are counted in it. A new project starts on Moscow time. Pick your zone, then save the hours above to put it to use.

## A contact when nobody answers
After a handoff the visitor waits for an operator. But the chat asks them to leave a contact instead when:

- it is outside the working hours and nobody is on shift;
- nobody is on shift and nobody has the inbox open;
- nobody took the conversation in time.

The contact lands in the conversation, so an operator can write back later. In «The visitor may leave», pick the ways: Telegram, email, phone. At least one must stay on.

«Advanced: wait for an operator» sets how many minutes a handed-off conversation waits for an operator before the contact form shows. The default is 3 minutes; it can be anything from 1 minute to a day.

## Topics for an operator
These are subjects your business always wants a person for: payment details, a working mirror, a refund. «Add a topic» opens the form:

- **Topic**: its title, which operators see on the conversation.
- **What it covers**: in your own words, what the visitor asks for. The bot reads it by meaning, so write a description, not a list of keywords.
- **What the bot does**: «To a person at once» (the bot says nothing), or «Answer, offer a person».
- **Examples**, under «Advanced: examples»: a few messages on the topic, one per line, up to 12. They help the bot recognize the topic.

A project can have up to 20 topics. If you remove a topic, the bot answers such messages again, unless they need a person for another reason. There is nothing to tune: the thresholds are the same for every project and topic, so a new topic works at once.

### Check the topic
The «Check the topic» button in the form shows how the bot will read your messages. Write up to 8 messages, one per line. If the box is empty, it checks the examples.

Each message shows what the chat would do («To a person», «Offers a person», «The bot answers») and how sure the bot is. The result is a line such as «3 of 4 go to a person». Check a general question on the same subject too: «Is a card accepted at all?» should stay with the bot.

Checking each message costs money. If topic checking is not set up on the server, the check says it is unavailable.

## Reply templates
Templates are ready-made answers. An operator inserts one by typing `/` and its code in the reply box: `/refund`, `/limits`. A template has a code (lowercase Latin letters, digits, `-` and `_`), a title and its text. On insert, `{name}`, `{operator}` and `{order}` are filled in ([Inbox](https://tolkly.io/docs/en/inbox.md#templates)).

Owners and admins add, edit and remove templates here. You can also turn an AI answer into a template in the inbox: «Save as a template». Operators see the list and use the templates.

## Order number
Under «Advanced: order number», in «Number format», describe how your business writes an order number. The operator then sees the number found in a message and copies it in one click. The number also goes into the Telegram topic's card and into a `t.me` support link as its start parameter.

The number is written as a mask: `#` is one digit, `*` any letters and digits, the rest is written as it is, in any case. For example: `#####` is five digits (48213), `INV-#####` is INV- and five digits, `ZK-*` is ZK- and any letters and digits. The number is looked for as a word of its own: never inside a longer number or word. As you type, «Try it on a message» tests the mask on a sample and shows «Found: 48213» or «Nothing found in this message». The format saves when you leave the field or press Enter. If the box is empty, order numbers are not looked for.

Those who write regular expressions keep «Own expression»: one group in brackets holds the number, `(?:…)` for any other brackets, up to 120 characters, no repeat inside a repeat such as `(\d+)+`.

## Telegram and the team
The group and the team are shared by every project of the company. So this block shows only their state, and each one links to its own page:

- **Telegram**: the linked group's title, «No group linked», or what broke, such as «The bot was removed …» in red, as on the overview. Without a group, handed-off conversations wait in the inbox only ([Operators in Telegram](https://tolkly.io/docs/en/telegram.md)).
- **Team**: how many people are in the company and who is on shift now. A grey dot means nobody is on shift.

## Without operators
With «The project has operators» off, the bot answers from your sources and hands nobody a conversation. When the bot cannot answer, the chat asks the visitor for a contact. The contact lands in the conversation, where your team sees it. If your developer gave the tag your own support link (the `handoff` attribute, [Widget attributes](https://tolkly.io/docs/en/widget-attributes.md)), the chat offers that link instead. Files cannot be sent: there is no paperclip.

Turn operators on only when someone will really answer. A visitor promised a person who never comes is worse off than one sent straight to your support link.

Source: https://tolkly.io/docs/en/handoff.md

---

# Spam guard

> Limits per network, the spam filter, a harder check in a surge, blocked visitors and the «Possible spam» folder.

Someone may flood your chat: write from a hundred incognito tabs, paste ads, or try to spend the company's monthly limit of AI conversations. The «Spam guard» block in the project's «Project» section sets what the chat does about it. Owners and admins of the company change these settings; operators open «Project» read-only, block visitors from the inbox and lift blocks. Nothing is ever deleted: a conversation the guard holds back waits in the inbox under «Possible spam».

Our cloud has its own guards in front of every project, the same for everyone: a challenge at the network's edge during a flood, a short proof of work before every new conversation, and limits on how fast one address may write. The settings below are yours, on top of them.

## The settings
| Setting | Default | What it does |
|---|---|---|
| Hide spam | On | A message the classifier is sure is spam (ads, gibberish, an attempt to make the bot ignore its rules) gets a short «nothing in the rules answers this». No person is called, no model writes an answer, nothing is charged. The conversation goes to «Possible spam». A rude or angry customer is not spam: they still get an answer |
| Harder check in a surge | On | When new conversations come ten times faster than in the project's busiest hour of the week (and at least 30 an hour), the visitor's browser does 3–4 seconds of extra work before the first message, while they type. Nobody is refused, so a newsletter that brings a crowd costs no answers |
| Trust visitors your site signed | On | A customer your site signs in the chat ([Visitor identity](https://tolkly.io/docs/en/identity.md)) skips the per-network limits and the spam filter: their account on your site already exists |

## Limits
Under «Advanced: limits». A network is a block of addresses one home, office or hosting customer usually holds (IPv4 /24, IPv6 /48), so a hundred incognito tabs are one network. 0 turns a limit off.

| Limit | Default | Past it |
|---|---|---|
| AI conversations an hour from one network | 20 | People answer, as when the monthly limit is spent. Nothing is charged |
| Conversations for people an hour from one network | 5 | The conversation still reaches the inbox, under «Possible spam», without a Telegram topic. The group gets one summary an hour instead of a topic per conversation |
| AI conversations a day | A tenth of the company's monthly limit (100 of 1 000) | People answer until the day's count drops. A flood spread over many networks spends a tenth of the month a day, not the whole month in an hour. Leave it empty for automatic |
| Block the address for | 24 hours | See [Blocking](#block) |

A conversation the bot answered with a source counts; a refusal or spam does not.

## «Possible spam»
The inbox lists the folder under the other views while it holds anything. A conversation lands there when it went past «Conversations for people», when the classifier was sure it is spam, or when its visitor is blocked. It is in no other view, gets no Telegram topic and plays no sound. Open it and press «Not spam» to bring it back: if it waits for a person, its topic opens in Telegram then.

## Blocking
In a conversation's menu, «Block the visitor». From then on the chat refuses the visitor's messages and files and tells them it no longer takes their messages, so a person blocked by mistake knows to reach you another way. Their conversations go to «Possible spam».

A block holds the visitor's chat on that browser and, if your site signed them, their account, until someone unblocks them. It holds their address only for the hours set in «Block the address for», since a mobile operator puts thousands of people behind one address. A new incognito tab from the same address is blocked for those hours too.

Every block is listed in «Project», in the «Blocked visitors» block, with who blocked and when. Any member of the team unblocks, there or in the conversation's menu.

Source: https://tolkly.io/docs/en/spam.md

---

# Operators in Telegram

> Link your company's group, then answer handed-off conversations in its topics, with shifts, work names and files.

Every conversation handed to a person becomes a topic in your company's own Telegram group. Operators answer right there, and the visitor reads the reply where they wrote from: the chat on your site or your own Telegram bot.

This page is about the group for operators. To let customers write to your own Telegram bot: [A Telegram bot for your customers](https://tolkly.io/docs/en/telegram-bot.md).

## Link the group
Only an owner or admin links the group, in the app under «Team and plan» › «Telegram».

1. In Telegram, create a group and turn on Topics (group settings → Topics).
2. Press «Get a link for the group». The link works once and only for a short time. «Get a new link» gives another.
3. Press «Open in Telegram» and choose that group. Our bot becomes an admin there that manages topics and deletes those of closed conversations.

The page updates by itself and shows «Linked to «…»». If the link does not open, add the bot to the group by hand, as an admin with «Manage topics» and «Delete messages». Then send the `/link` command the page shows into the group.

One group serves every project of the company. The bot writes in the group in the language your app was set to when you got the link.

## Each operator, once
1. **Sign in to the app with Telegram**, or connect Telegram on the account page. The bot knows operators by their Telegram account and their membership in your company, not by name. If anyone else writes in a topic, their message goes nowhere, and the bot asks them to sign in.
2. **Set a work name**: `/name Anna` (or on the account page, under «Work name»). That is the name visitors see. For pages in another language, add its form, as in `/name ru Анна`. By default, replies without a work name do not reach visitors. An owner or admin can change this on the team page, under «Work names»: one name for everyone, no name, or the account's own name.
3. **Start a shift**: `/shift on` ([Shifts](https://tolkly.io/docs/en/telegram.md#shift)).

`/name` and `/shift` work in the group and in a private chat with the bot. In a private chat they apply to every company you are a member of.

## A topic per conversation
When a conversation goes to people, the bot opens a topic and names it after the visitor's question. A card at the top of the topic shows:

- why it was handed over («Asked for a person», a topic of yours, «Sent a file the AI cannot see»…);
- the order number or transaction, if the visitor gave one;
- the question, what the AI answered and its sources;
- the whole conversation, folded;
- if your site said who the visitor is: their name, ID and fields, each marked verified or not. For a verified visitor, also links to their earlier topics ([Visitor identity](https://tolkly.io/docs/en/identity.md)).

The visitor's new messages arrive in the same topic. If the conversation goes to people again, its topic opens again with a new card.

## Closed topics
So the group keeps only live conversations, the bot deletes a closed conversation's topic 3 days after the close. The conversation stays in the [inbox](https://tolkly.io/docs/en/inbox.md). If the visitor writes again later, that is a new conversation with a new topic: its card links the earlier conversation and shows its last messages.

An owner or admin changes the delay on the company's «Telegram» page, under «Closed topics»: a day, 3, 7 or 30 days, or keep topics in the group. The bot needs the admin right «Delete messages» for this. Without it, the group's general topic and the page say so once.

## Answering
Write in the topic, and the visitor sees your reply in the chat. The card's buttons:

| Button | What it does |
|---|---|
| «Take» | The conversation is yours, and only you answer it. Replying in a waiting conversation takes it too |
| «Take over» | Takes a conversation a colleague holds |
| «Back to the bot» | The AI answers the visitor again; the topic closes |
| «Snooze» | For an answer that takes days. Pick a day, 3 days or a week: until then the conversation does not close by itself after a quiet day. When the time is up, the bot mentions whoever holds it in the topic. Press again to stop snoozing. The visitor sees nothing |
| «Close» | Ends the conversation. The topic closes, and the visitor is asked «Did we solve your question?» |

In the app, the same «Snooze» is in the conversation's «More actions» menu.

One person holds a conversation at a time, in the group and in the app alike. If you write in a conversation a colleague holds, your message does not reach the visitor, and the bot tells you so.

## Shifts
Tolkly cannot see who is online in Telegram, so it relies on shifts.

- If someone in your company is on shift, a handed-off visitor waits for an operator, even outside your working hours.
- If nobody is on shift, the chat asks the visitor to leave a contact. Outside your working hours it always does; within them, only if nobody has the inbox open in the app.

Send `/shift on` when you start and `/shift off` when you finish.

## Files
- A visitor's file comes into the topic as a photo or a document.
- A picture (PNG, JPEG, WebP, GIF, HEIC) or a PDF up to 10 MB that you post in the topic reaches the visitor as a file. Other files do not, and the bot says why.

## New domains
When the chat appears on a site for the first time, the bot posts about it in the group's general topic, not in a conversation's topic: «the chat appeared on brand38.shop», with a «Block» button. Only an owner or admin of the company can press it. More in [Domains and mirrors](https://tolkly.io/docs/en/domains.md).

The general topic also gets a message about each breakage, once per breakage:

- the chat has not been seen on your site for 7 days;
- the knowledge base could not be read again;
- `robots.txt` or your exclusions closed the home page.

From [Knowledge](https://tolkly.io/docs/en/knowledge.md), the same topic gets a mirror or a new site the domain rule found, and a run that waits for you.

## Unlink
The «Unlink» button on the company's «Telegram» page stops sending handed-off conversations to the group. Operators keep answering in the [inbox](https://tolkly.io/docs/en/inbox.md). You can link a group again at any time.

If someone removes the bot from the group, the page says «The bot was removed from the group on …» in red. Handed-off conversations wait in the inbox, and the owners and admins get an email. Link the group again on the same page.

Source: https://tolkly.io/docs/en/telegram.md

---

# A Telegram bot for your customers

> Customers write to your own Telegram bot, the same AI answers, and handoffs come to the same inbox and support group.

Besides the chat on your site, customers can write to your bot in Telegram. It is your bot, with its own name and picture, not Tolkly's. The same AI answers it from the same knowledge and rules as the chat on the site. When a person is needed, the conversation goes to the inbox and to a topic of the [support group](https://tolkly.io/docs/en/telegram.md), like a conversation from the site. The operator answers where they always do, and the customer gets the reply in Telegram.

Do not mix up the two bots:

- **Tolkly's bot** works in your company's support group and serves operators ([Operators in Telegram](https://tolkly.io/docs/en/telegram.md)).
- **Your bot** talks to customers in private chats. It is connected in each project on its own.

## Connect the bot
An owner or admin of the company connects it, in the project's «Install» section, block «Telegram bot».

1. In Telegram open [@BotFather](https://t.me/BotFather), send `/newbot`, give the bot a name and an address. BotFather sends a token: digits, a colon, then letters.
2. Paste the token into «Bot token from BotFather» and press «Connect».
3. Write to the bot yourself. The block shows «Connected, no messages yet», and after the first message «Working». The AI answers in a few seconds.

The token is kept encrypted and is never shown again. One bot serves one project. If the bot already answers somewhere else, it stops there: Telegram sends a bot's messages to one place only. Tolkly's bot for operators cannot be connected as yours.

For people to answer conversations from the bot, the project needs operators («Handoff to people» › «The project has operators»), and someone to answer: operators answer in the app's inbox or in the company's [support group](https://tolkly.io/docs/en/telegram.md#link).

## How the bot talks
- Before the first AI answer the bot says an AI answers, as the chat on the site does.
- The bot answers in the customer's language: by the letters of their message, and for `/start` by the language of their Telegram app.
- The customer is not asked for a contact: the Telegram chat is the contact. Outside working hours the bot says an operator will answer right there.
- A customer can send up to 10 messages a minute. The bot drops the rest and says so once a minute.
- A new question after a closed conversation, or after two hours of quiet, starts a new conversation with a new topic in the group. The operator sees this customer's earlier conversations on the card.

## From the chat on the site to Telegram
When the bot works and the project has operators, the contact form in the chat on the site offers «Continue in Telegram». The customer presses it, the bot opens with the same conversation, and the operator's reply comes in Telegram: the tab with the site can be closed. Replies reach both Telegram and the chat on the site.

## The support group through your bot
By default Tolkly's bot posts conversation cards into the support group. It serves many companies, and at peak times cards can lag. To keep the group yours alone, add your bot to it as an admin with «Manage topics» and «Delete messages» and press «Switch to @your_bot» in the «Telegram bot» block, row «Support group». With no group yet, you can link one through your bot right there. «Back to @…» returns the group to Tolkly's bot.

## Disconnecting
«Disconnect» in the «Telegram bot» block. People who write to the bot stop getting answers, and operators' replies in its conversations do not reach them. The conversations stay in the inbox.

If the block says «Telegram does not take the token», the token was revoked or the bot deleted in BotFather: get a new token and connect the bot again.

Source: https://tolkly.io/docs/en/telegram-bot.md

---

# The inbox in the app

> Views, search, taking and assigning conversations, reply templates, the visitor card, closing and shifts.

The inbox holds the conversations of every project in your company. Each person works in it under their own account. These are the same conversations as in your [Telegram group](https://tolkly.io/docs/en/telegram.md), with the same rules: one person holds a conversation at a time, wherever they answer from.

## Views
| View | What is in it |
|---|---|
| «Waiting for a reply» | Handed to people, nobody has taken it yet. The longest wait is on top, as in «Waiting · 5 min» |
| «Mine» | Assigned to you or held by you, not closed |
| «AI is answering» | The AI is talking to the visitor now |
| «All» | Every conversation |

The «Left a contact» filter narrows any view to visitors who left an email, phone or Telegram.

## Search
The search box, «Order number, tx or text», finds a conversation:

- by an order number or transaction;
- by words in the visitor's or the AI's messages;
- by a contact the visitor left;
- by the ID, name, email or phone your site sent.

## Take, take over, assign
- **«Take»** makes a conversation yours. It works on a waiting conversation and on one the AI is answering. Simply replying takes it too.
- **«Take over»**, in «More actions», takes a conversation a colleague holds. Until you take it over, only they can answer it.
- **«Assignee»** is who should see the conversation through. Anyone can assign a conversation to themselves («Assign to me»); only owners and admins can assign it to someone else. If a conversation has no assignee, taking it makes you the assignee. Taking one over moves the colleague's assignment to you, but not an assignment an owner gave to someone else.

## Reply and templates
- Type `/` in the reply box and pick one of the project's templates. Keep typing to narrow the list. On insert, `{name}`, `{operator}` and `{order}` are filled in. Blanks left empty are highlighted, and the reply is not sent until you fill them.
- Owners and admins add, edit and remove templates in the project's section «Handoff to people» › «Reply templates». An AI answer can become a template too: «Save as a template» under the answer.
- Attach a picture or a PDF with the paperclip. You can also just paste a screenshot.
- Beside your message's time: a clock while it is sending, one tick once sent, two ticks once the visitor has read it.
- To reply, you need a work name, set on the account page under «Work name». An owner or admin can change the company's rule («Work names» on the team page).

## Reading a conversation
- **«Brief for the operator»** at the top: what the visitor asked, which sources the AI answered from, and why the conversation was handed over.
- **«How the AI answered»**, a chip on the AI answer's author line: how the AI understood the question, how many passages from your sources it found, and how many quotes passed the check.
- **The action bar** under an AI answer: «Copy», «Save as a template» (owners and admins) and «AI was wrong». It shows on hover and focus; on the newest answer and on touch screens it is always there.
- **«AI was wrong»**: mark the reason — «Not by the rules», «Wrong item», «Out of date» or «Should have handed over». Colleagues see how many people marked the answer.

## The visitor card
«Visitor card» opens beside the conversation:

- **«Account on the site»**, when your site tells the chat who the visitor is: user ID, name, email, phone and the fields you send. «Verified» means your site's server signed the data. «Not verified» means the page sent it without a signature, so anyone could have typed it. A verified visitor also has «Earlier conversations». Setup for your developer: [Visitor identity](https://tolkly.io/docs/en/identity.md).
- **«Order»**: the order number and transaction with copy buttons, and why the conversation was handed over.
- **«Visitor»**: the project; the conversation's language, if it is not the project's main one (the same badge, such as `EN`, marks it in the list); the page it started on; when it started; the contact left; the assignee. There is no translation: you answer in the language you choose ([Language](https://tolkly.io/docs/en/widget.md#language)).

## Close or give back
- **«Close»** ends the conversation. The visitor sees that the operator closed it and is asked «Did we solve your question?».
- **«Give back to the AI»**, in «More actions», returns the conversation to the bot. The visitor sees that the AI assistant answers again.

If a conversation people hold stays quiet for a day and nobody is waiting for a reply, it closes by itself. That never counts as resolved.

## On shift
Open your account menu (your name in the side rail) and press «Start shift» or «End shift». In Telegram, `/shift on` and `/shift off` do the same.

While someone is on shift, a handed-off visitor waits for an operator. Within your working hours, an open inbox also counts as someone being there. With neither, the chat asks the visitor to leave a contact.

When you open the inbox after more than 4 hours off shift, a card in the bottom right corner asks «Start your shift?». «Not now» puts the question off for another 4 hours. An owner or admin also sees «I do not answer chats»: it removes the operator's part of their role, and the card no longer shows.

The sound is a short signal when a conversation is handed to people while the inbox tab is in the background. It is on by default; the browser plays it after your first click on the page. Turn it off in the account menu: «Turn off the inbox sound». The choice is kept on that device.

Source: https://tolkly.io/docs/en/inbox.md

---

# Domains and mirrors

> The chat works on any of your domains, tells you of each new site, and lets you block one that is not yours or keep the chat to a list.

Mirrors change more often than anyone opens the settings. So by default the chat works on any
domain. When it appears on a new site, you get a notice. You can block a site that is not yours
with one button.

## A notice for each new site
The first time the chat loads on a site, the bot posts in your company's Telegram group, in its
general topic: «the chat appeared on brand38.shop». The notice has a «Block» button.

- Only an owner or admin of the company can press it; anyone else is told so. After a press, the notice
  shows who blocked the site and offers «Unblock».
- The bot announces each site only once.
- It never announces a developer's machine or a private network (`localhost`, `*.local`,
  `192.168.*` and the like).
- If the chat loaded on a site before the group was linked, the site is listed in the app but
  never announced.

## The domains list
The app lists every site the chat loaded on: the project's «Install» section, block «Domains».
For each site you see:

- when the chat was first and last seen there;
- how many conversations started there;
- «New» for the first 7 days.

| State | What it means |
|---|---|
| «Works» | The chat runs there. The site is not on your list. |
| «Allowed» | The site is on your list. The chat runs there, in strict mode too. |
| «Not allowed» | Strict mode is on and turns the site away. |
| «Blocked» | You blocked the site. No chat there. |
| «Not seen for N days» | The chat was last seen on this site, and it has not shown there for over 7 days. The code may have been removed (red dot). |

Owners and admins can press «Block», «Unblock» and «Allow». «Allow» adds the site's domain to the list and
unblocks it.

Without strict mode, «Allow» changes nothing for the chat. It only confirms the domain is yours.
That matters for the [domain rule](https://tolkly.io/docs/en/knowledge.md#domain-rule): the rule then reads the domain as a
mirror or as a site of its own. The «Read new domains» row at the end of the block turns the rule
on. With the rule on, the Telegram notice of a new site offers «Allow» too.

Operators see the list without the buttons. A project keeps up to 50 sites. Past that, new sites
are neither recorded nor announced.

## What a blocked site gets
Nothing is drawn: no chat button, no hint, nothing in the browser console. If a page had the chat
open before the block, it can't send anything more. So a blocked site spends none of your limit.
A block from the app or from Telegram applies at once.

## Strict mode
Use it when the chat must show only on your own domains. Open «Install» › «Advanced settings»,
block «Strict mode». Turn on «Only allowed domains» and fill in «Allowed domains and masks»,
one per line. A mask covers the whole domain, never a part of it:

| Entry | Matches | Does not match |
|---|---|---|
| `brand.com` | `brand.com` | `www.brand.com`, `brand.com.evil.io` |
| `*.brand.com` | `www.brand.com`, `pay.brand.com` | `brand.com` |
| `brand*.shop` | `brand.shop`, `brand38.shop` | `brand38.evil.shop` |

In strict mode, a site off the list gets no chat. The group gets «a try from an unknown site» with
«Allow» and «Block».

Leave strict mode off while your mirrors change often. If strict mode is on and the list is empty,
the chat works nowhere.

## The mirror script's key
If a script moves your site to a new mirror, it can add the new domain to the list itself. It
needs a key: in «Install» › «Advanced settings», block «Key for your mirror script», press «Issue
a key». The key is shown once. «Issue a new key» stops the old one at once. Give the key to your
developer to keep on the server, never in a page.

An example for your developer. The address is in the block, under «Example: add a mirror to the
list»:

```sh
KEY=tk_domains_…
API=https://api.tolkly.io/v1/projects/<project>/origins

# What is on the list now
curl -H "Authorization: Bearer $KEY" $API

# Add the new mirror, drop the old one; the rest stays
curl -X POST $API -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"add": ["brand39.shop"], "remove": ["brand38.shop"]}'

# Replace the whole list; "strict" is optional and switches the mode
curl -X PUT $API -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"patterns": ["brand.com", "*.brand.com", "brand\\d+\\.shop"], "strict": true}'
```
The list matters even with strict mode off: it tells the chat which domains are yours for source
links (below).

### Hand it to an AI agent
Under the key, owners and admins get «Hand it to an AI agent». It gives a prompt, with the project filled in,
for the coding agent that edits your mirror script (Claude Code, Cursor). With it, the agent:

- adds the new domain before visitors are sent there;
- keeps the key in the server's `TOLKLY_DOMAINS_KEY` environment variable, never in the
  repository or a page;
- checks that the domain shows as «Allowed».

Here the prompt has `your-project` in place of the project's id. «Open in…» → «Prompt for an AI
agent» copies it.

```text
Make this site’s mirror switch add the new domain to the Tolkly chat’s list of allowed domains, so the chat keeps working in strict mode.

Project: your-project
Domains API: https://api.tolkly.io/v1/projects/your-project/origins
Key: the environment variable TOLKLY_DOMAINS_KEY on the server that runs the switch. The owner issues it in Tolkly: «Install» › «Advanced settings» › «Key for your mirror script».

1. Read https://tolkly.io/docs/en/domains.md, the sections on strict mode and the mirror script’s key. If it does not load, this prompt is enough.
2. Find the script or job that moves the site to a new mirror domain: a deploy step, a DNS or CDN change, a scheduled job that registers domains. If there is none, stop and tell me.
3. In it, before DNS or a redirect sends visitors to the new domain, add the domain to the list: POST https://api.tolkly.io/v1/projects/your-project/origins with the headers "Authorization: Bearer $TOLKLY_DOMAINS_KEY" and "Content-Type: application/json" and the body {"add": ["<new domain>"]}. A domain is a host only (brand39.casino), with no scheme or path. With strict mode on, a domain off the list gets no chat, so this call comes first.
4. Optionally drop the old mirror in the same call: {"add": ["<new domain>"], "remove": ["<old domain>"]}. Do not use PUT unless I ask: it replaces the whole list.
5. Treat a failed call as a failed step of the switch: retry on 429 and 5xx; stop and report on 401 (no key, or a key the owner replaced) and on 400 (the answer names the entry it refused). Log the status, never the key.
6. Read the key from TOLKLY_DOMAINS_KEY only: never put it in the repository, a page, browser code or a log. The API sends no CORS headers, so it is never called from a browser. If the variable is not set where the script runs, stop and ask me to set it.
7. Check it: GET https://api.tolkly.io/v1/projects/your-project/origins with the same Authorization header answers {"strict": …, "patterns": […]} with the new domain among the patterns. Once the chat loads on that domain, «Install» › «Domains» in Tolkly shows it as «Allowed». Then list the files you changed.
```

## A visitor on a new mirror
- **Source links follow the visitor.** If a link in an answer points at another domain of yours,
  it opens on the site the visitor writes from. On `brand38.shop`, `https://brand.com/rules`
  becomes `https://brand38.shop/rules`, because the main domain may be blocked for the visitor.
  Your domains are the indexed site, the domains your list matches, and the sites the chat ran on
  that nobody blocked.
- **A signed-in visitor keeps their conversation.** The browser keeps a conversation per site, so
  on a new mirror an anonymous visitor starts a new one. If your site signs the visitor in, they
  get their latest open conversation back on any mirror. Setup for your developer:
  [Visitor identity](https://tolkly.io/docs/en/identity.md).

Source: https://tolkly.io/docs/en/domains.md

---

# Plan, payment and limit

> The free month, the plans, paying by card or in crypto, what counts as an AI conversation and what happens when the limit is reached.

You pay for AI conversations: conversations where a source confirms the bot’s answer. Operators, sites, mirrors and brands do not change the plan. The plan, what is left of the limit and the payments are in «Team and plan» › «Plan and limit». Every member sees what the company has and how much of the limit is used; only owners see the plans and payments and pay.

## The free month
A new company works free for 30 days. In that time it has:

- 250 AI conversations for the whole month (not per calendar month);
- up to 3 projects;
- up to 300 indexed pages across all projects.

You can pay for a plan during the free month too: the free days left are kept, and the paid period starts after them. When the free month ends unpaid, the AI stops answering and every conversation goes to operators. Nothing is deleted.

## Plans
| Plan | Price | AI conversations a month | Operators |
|---|---|---|---|
| Start | $49 a month | 1,000 | up to 10 |
| Business | $149 a month | 5,000 | no limit |
| Enterprise | by agreement | 20,000 | no limit |

On Start, operators means everyone in the company: members and open invites together. The 11th invite is refused; revoke an invite or move to Business. The free month has no such limit.

A year costs 10 months: two months free. Enterprise (roles and reports per brand, SLA) is set up after a call: write to us.

## Payment
You pay by card or in crypto. In «Plan and limit», pick a plan and a term (a month or a year), then the payment method.

### By card
Visa, Mastercard and more, through Polar. Press «Go to payment» and pay on Polar's page. The plan turns on once the card is charged.

A card subscription renews by itself at the end of each period. A company has one renewing subscription: a period paid any other way stops the card's renewal.

To stop it, press «Stop renewal» beside the dates in «Plan and limit». The plan works until the paid period ends and the card is not charged again; after that the AI stops answering and every conversation goes to operators, with nothing deleted. Until that date, «Resume renewal» takes it back.

### In crypto
USDT, BTC, ETH, TON and more, through NowPayments.

1. Press «Pay» and pick a coin. USDT on TRON costs the least to send.
2. The page shows the amount, the network and the address. Send exactly that amount on that network. An exchange keeps its withdrawal fee from the transfer: add it on top. On another network the money is lost.
3. You can close the page: the plan turns on when the transfer arrives and is confirmed, usually in a few minutes.

If less arrived, the page says how much to add to the same address. Up to $1 short is forgiven. With no transfer, the invoice expires; a new one costs the same. Sent after it expired? Write to us with the order number.

Crypto is never charged by itself, so a period paid in crypto does not renew on its own. 3 days before the paid period ends and on its last day, owners get a letter and a message in the company's Telegram group. You can renew any time ahead: the new period starts where the current one ends.

### Changing the plan
- **A higher plan** starts at once. The paid days not used are credited against its price.
- **A lower plan** starts when the paid period ends.

## What counts as an AI conversation
| | |
|---|---|
| Counted | The bot's first answer in a conversation that kept a link to a source |
| Counted again | When the bot answers 24 hours after the last counted answer, and for every further 10 answers in one conversation |
| Not counted | Silence, an honest refusal («the rules do not say»), a conversation handed to a person at once, «Operators only» mode, a file on its own |

The month is counted by the UTC calendar.

## When the limit is reached
At 80% of the limit and when it is reached, owners are told in the company's Telegram group, and the app shows a strip above the page. Once the limit is reached, the bot hands every new conversation to operators until the next month starts. Nothing is charged past the limit: the bill never grows without your decision.

To have the AI answer again sooner, buy more AI conversations for this month or move to a higher plan: either starts at once.

### More AI conversations
On a paid plan, an owner can add AI conversations to this month: «Plan and limit», «Buy more». A pack of 1,000 costs $10; one order holds up to 20 packs. They count on top of the plan from the moment the payment arrives until the calendar month ends; what is unused does not carry over.

Pay by card or in crypto, as for a plan. A crypto payment is never under $15, the smallest one the provider takes: one pack in crypto costs $15 and brings 1,500 conversations. Nothing is bought by itself: only when an owner presses «Buy more».

## If the bot stopped answering
Open «Plan and limit». The reason is usually there:

- the month's limit is reached: every conversation goes to operators until the date under «Starts again on»;
- the free month or the paid period ended: the AI is back as soon as the payment arrives.

If all is fine there, open the project's «Handoff to people» section: with «Operators only» picked in «Who answers first», the bot never answers ([Handoff to people](https://tolkly.io/docs/en/handoff.md)).

Source: https://tolkly.io/docs/en/billing.md