У мессенджеров человек появляется в тот момент, когда написал. До этого его для нас не существует: ни имени, ни адреса доставки. Чат на сайте устроен иначе — посетитель открыл страницу, и он уже виден: что читает, откуда пришёл, сколько раз возвращался. Написать он может и не написать никогда.
Из-за этой разницы у чата на сайте есть методы, которых нет ни у одного мессенджера. Они отвечают на три вопроса: кто сейчас на сайте, кто был раньше и что мы знаем про конкретного человека.
Чем это отличается от списка диалогов
GET /{channel}/chats возвращает тех, кто писал. Посетитель, который третий день читает тарифы и молчит, туда не попадёт никогда — диалога у него нет.
GET /webchat/visitors возвращает всех, включая молчунов. Именно они обычно и интересны: человек, который за десять минут трижды открыл страницу оплаты, — это событие, а не строка в логе.
Методы работают только у канала «Чат на сайте». Тот же запрос с ключом Telegram-бота вернёт
422 channel_unsupported_operation— не пустой список, который вы бы прочитали как «никого нет». У мессенджера нет страниц, по которым можно ходить, и притворяться, что есть, мы не будем.
Кто на сайте прямо сейчас
GET https://etochat.bot/api/v2/webchat/visitors/online{
"online": 5,
"window_seconds": 45,
"data": [
{
"visitor_id": "v_8f31c0a2",
"chat_id": "5827431900215634771",
"name": "Ирина",
"email": "irina@example.com",
"online": true,
"idle_seconds": 4,
"page_views": 12,
"current_url": "https://example.com/pricing",
"current_title": "Тарифы",
"has_dialog": true,
"first_seen": "2026-08-02 11:20:41",
"last_seen": "2026-08-17 16:58:03"
}
]
}Счётчик online всегда полный, даже если вы ограничили выдачу параметром limit.
Что такое «онлайн». Человек считается онлайн, пока его вкладка отмечалась в последние window_seconds секунд. Это договорённость, а не физический факт: закрыть вкладку молча можно, и узнаём мы об этом только по молчанию. Значение приходит в каждом ответе — берите его оттуда, а не зашивайте в код: изменим окно, и ваши цифры разойдутся с теми, что видит оператор в кабинете.
Все посетители
GET https://etochat.bot/api/v2/webchat/visitors?online=1&query=ирина&sort=views&limit=50&offset=0| Параметр | Что делает |
|---|---|
online | Только те, кто на сайте сейчас. По умолчанию — все. |
query | Поиск по имени, почте, адресу и заголовку текущей страницы. |
sort | active — по последней активности (по умолчанию), views — по числу просмотров, email — сначала с почтой. |
limit | От 1 до 100, по умолчанию 50. |
offset | Сколько записей пропустить. |
Кроме data в ответе приходят total, with_email, with_dialog — по ним удобно строить свою сводку, не выкачивая весь список.
Почему здесь
offset, а не курсор, как в остальном API. Список отсортирован по последней активности, и порядок меняется каждые несколько секунд: человек обновил страницу — и уехал наверх. Курсор обещал бы устойчивую страницу, которой в такой сортировке не существует.offsetчестно говорит, что это срез, а не снимок.
Карточка одного человека
GET https://etochat.bot/api/v2/webchat/visitors/v_8f31c0a2К полям из списка добавляются referrer, geo, user_agent и последние 50 открытых страниц — самая свежая первой:
{
"visitor": {
"visitor_id": "v_8f31c0a2",
"referrer": "https://yandex.ru/",
"geo": "Москва, RU",
"pages": [
{ "url": "https://example.com/pricing", "title": "Тарифы", "seen_at": "2026-08-17 16:57:12" },
{ "url": "https://example.com/", "title": "Главная", "seen_at": "2026-08-17 16:55:48" }
]
}
}По этой истории видно намерение. Три захода на страницу тарифов за десять минут говорят больше, чем любая формула скоринга.
IP-адреса в ответе нет. На вопрос «кто сейчас на сайте» он не отвечает, а хранить и передавать его — отдельная ответственность, в том числе юридическая. Если он вам действительно нужен для конкретной задачи — напишите нам, обсудим.
Как написать посетителю
Отдельного метода для чата на сайте нет и не нужно: подойдёт обычная отправка. Возьмите chat_id из карточки и вызовите тот же эндпоинт, что и для мессенджеров:
POST https://etochat.bot/api/v2/webchat/messages{ "chat_id": "5827431900215634771", "text": "Подсказать по тарифам?" }Посетитель увидит сообщение сразу, если он на сайте, и когда вернётся — если ушёл.
Писать можно не каждому. Пока у человека
has_dialog = false, отправлять некуда: контакта не существует, ровно как в мессенджере до первого сообщения. Проверяйте это поле перед отправкой — так вы отличите «не дошло» от «отправлять было некуда».
chat_id — всегда строка
Он длиной до 19 цифр. В JavaScript число такой длины теряет младшие разряды молча:
Number("5827431900215634771"); // 5827431900215634800 ← последние цифры потеряныОшибки не будет — будет «почти тот» идентификатор и сообщение не тому человеку. Держите chat_id строкой на всём пути: в JSON, в базе, в шаблонах.
Что из этого обычно собирают
- Свой виджет «кто онлайн» во внутренней панели — опрос
visitors/onlineраз в 15–30 секунд. - Оповещение менеджеру, когда на страницу оплаты зашёл человек с известной почтой: список с
online=1, сверкаemailсо своей базой. - Обогащение CRM: раз в час забираем
visitors, сопоставляем по почте, дописываем в карточку клиента, что он смотрел на сайте. - Проактивное сообщение тем, кто долго висит на одной странице:
idle_secondsиcurrent_urlдают повод,chat_id— адрес.
Частота запросов общая для всего API — смотрите статью «Ошибки, ограничения и частые вопросы». Опрашивать visitors/online чаще раза в 15 секунд смысла нет: окно присутствия всё равно 45 секунд.