{"openapi":"3.1.0","info":{"title":"API ЭТОЧАТБОТ","version":"2.0.0","description":"Публичное API для владельцев ботов. Возможности зависят от канала — см. GET /api/v2/channels."},"servers":[{"url":"https://etochat.bot"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Problem":{"type":"object","description":"Ошибка в формате RFC 9457 с машинным кодом в поле code.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}}}}},"paths":{"/api/v2/channels":{"get":{"operationId":"get_channels","summary":"Список каналов и что они умеют","description":"Ключ не нужен. Все каналы, их ограничения и что в каждом работает.","tags":["Бот"],"parameters":[],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"channels":[{"channel":"telegram","label":"Telegram","limits":{"text_length":4096,"caption_length":1024,"edit_window_hours":48,"buttons_max":100,"photo_max_mb":10,"file_max_mb":50}}],"matrix":[{"operation":"typing","title":"Показать «печатает…»","channels":{"telegram":{"support":"yes","note":""}}}]}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[]}},"/api/v2/{channel}/capabilities":{"get":{"operationId":"get_capabilities","summary":"Что умеет канал","description":"Ограничения канала и что в нём работает, в JSON.","tags":["Бот"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"channel":"telegram","label":"Telegram","limits":{"text_length":4096,"edit_window_hours":48,"buttons_max":100},"operations":{"typing":{"title":"Показать «печатает…»","support":"yes","note":""}}}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/me":{"get":{"operationId":"get_me","summary":"Проверить ключ","description":"Какому боту принадлежит ключ. Ничего не меняет — с него удобно начать. Если can_send = false, у бота не оплачен тариф и отправка вернёт 402.","tags":["Бот"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"bot":{"id":42,"name":"Поддержка","channel":"telegram","username":"my_bot"},"can_send":true,"rate_limit":{"per_minute":120}}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/chats":{"get":{"operationId":"get_chats","summary":"Список диалогов","description":"Люди, которые писали боту, сверху — с последней активностью. Ответ приходит страницами: передавайте next_cursor в следующий запрос, пока has_more = true.","tags":["Диалоги"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"limit","in":"query","required":false,"description":"Сколько вернуть, от 1 до 100. По умолчанию 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor из прошлого ответа.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Поиск по имени и username.","schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"chat_id":"9995735656","name":"Иван","username":"ivan","status":"open","unread":0,"blocked_bot":false,"external_ids":["user-42"],"created_at":"2026-10-14 10:02:11","updated_at":"2026-10-23 18:44:31","business":false,"tags":["заявка"],"automation":{"mode":"bot","until":null}}],"has_more":true,"next_cursor":"MjAyNi0xMC0yMyAxODo0NDozMXwxNzc"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/chats/{chat_id}":{"get":{"operationId":"get_chat","summary":"Один диалог","description":"Всё про одного человека: имя, теги, ваши external_id, кто сейчас ведёт диалог (automation) и переменные, которые сохранили сценарии, — ответы на вопросы, телефон, номер бонуса. business = true — переписка идёт через Telegram Business от имени вашего аккаунта. Метка ссылки, по которой человек пришёл, — в переменной start_param (Telegram, ВКонтакте, МАКС). У Instagram есть reply_until — до какого времени можно ответить.","tags":["Диалоги"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"chat_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"chat":{"chat_id":"9995735656","name":"Иван","username":"ivan","status":"open","unread":0,"blocked_bot":false,"external_ids":["user-42"],"created_at":"2026-10-14 10:02:11","updated_at":"2026-10-23 18:44:31","business":false,"tags":["заявка"],"automation":{"mode":"bot","until":null},"variables":{"phone":"+79000000000"}}}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/chats/{chat_id}/messages":{"get":{"operationId":"get_messages","summary":"Переписка","description":"Переписка, новые сообщения сверху, страницами — то же, что в «Сообщениях» кабинета. Кто отправил — в sent_by, файлы — в attachments со ссылкой на скачивание. file_name и file_size — если они известны.","tags":["Диалоги"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"chat_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Сколько вернуть, от 1 до 100. По умолчанию 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"next_cursor из прошлого ответа.","schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":16672,"direction":"out","type":"text","text":"Добрый день! Сейчас подберу.","attachments":[],"sent_by":"automation","sent_at":"2026-10-23 18:44:40","edited":false},{"id":16671,"direction":"in","type":"voice","text":"","attachments":[{"type":"voice","mime_type":"audio/ogg","duration":7,"url":"https://etochat.bot/api/v2/telegram/files/16671"}],"sent_by":"person","sent_at":"2026-10-23 18:44:31","edited":false}],"has_more":true,"next_cursor":"MjAyNi0xMC0yMyAxODo0NDozMXwxNjY3MQ","source":"cabinet"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/chats/{chat_id}/status":{"post":{"operationId":"post_chat_status","summary":"Открыть или закрыть диалог","description":"Закрывает или открывает диалог в кабинете — как кнопка «Закрыть» у оператора. Человек ничего не заметит, а если напишет — диалог откроется снова. Пригодится, если ваша система сама пишет человеку и ответ не нужен: диалог не будет висеть «без ответа».","tags":["Диалоги"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"chat_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","chat_id":"9995735656","chat_status":"closed","closed_at":"2026-10-23 19:32:32","changed":true}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"open или closed. Обязательно."}}}}}}}},"/api/v2/{channel}/chats/{chat_id}/automation":{"post":{"operationId":"post_chat_automation","summary":"Кто отвечает: бот или человек","description":"Передаёт диалог вашему сотруднику или вашему ИИ и обратно. mode = human — наши сценарии и ИИ-агент в этом диалоге молчат, сообщения человека по-прежнему приходят вам, отвечаете вы через «Отправить сообщение». По умолчанию на сутки, срок можно задать в minutes. mode = bot — вернуть диалог боту. Если человек нажмёт кнопку под старым сообщением бота, бот ответит.","tags":["Диалоги"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"chat_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","chat_id":"9995735656","mode":"human","until":"2026-10-23 21:32:32"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","description":"human — отвечает человек, бот молчит; bot — вернуть боту. Обязательно."},"minutes":{"type":"integer","description":"Для human: на сколько минут, от 1 до 43200 (30 дней). По умолчанию 1440 — сутки."}}}}}}}},"/api/v2/{channel}/messages":{"post":{"operationId":"post_messages","summary":"Отправить сообщение","description":"Отправляет человеку текст или файл. Файл — ссылкой в attachment или загрузкой (multipart/form-data). Ответ 200 — мессенджер принял сообщение, иначе придёт 502 с причиной.","tags":["Сообщения"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Уникальная строка запроса. Повтор с тем же ключом и телом вернёт сохранённый результат.","schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","message_id":16672,"chat_id":"9995735656","channel":"telegram","type":"text"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chat_id":{"type":"string","description":"Кому. Нужен chat_id или external_id."},"external_id":{"type":"string","description":"Ваш идентификатор человека, если вы связали его через «Связать с вашим пользователем»."},"text":{"type":"string","description":"Текст. Обязателен, если нет файла; с файлом — подпись. В Telegram и МАКС можно размечать HTML: <b>, <i>, <a href=\"…\">. В остальных каналах разметка снимается. Перенос строки — \\n."},"attachment":{"type":"object","description":"Файл ссылкой: {\"type\":\"photo\",\"url\":\"https://…\"}. type: photo, document, video, audio, voice, video_note. Ссылка прямая, без авторизации и редиректов. file_name — как файл назовётся у человека."},"file":{"type":"string","description":"Файл загрузкой вместо ссылки: multipart/form-data с полями file, type, chat_id и, если нужно, text."},"buttons":{"type":"array","description":"Кнопки-ссылки: [{\"text\":\"…\",\"url\":\"https://…\"}]. Кнопки с ответами делаются в сценарии — запустите его методом «Запустить сценарий».","items":{"type":"object"}}}}}}}}},"/api/v2/{channel}/messages/{id}/edit":{"post":{"operationId":"post_edit","summary":"Изменить сообщение","description":"Меняет текст сообщения, которое отправил этот бот. id — message_id из ответа «Отправить сообщение» или id из переписки. Сколько времени есть на правку, зависит от канала: Telegram — около 48 часов, ВКонтакте — 24 часа, МАКС — 7 суток, чат на сайте — без ограничения. Позже придёт 422 edit_window_expired.","tags":["Сообщения"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","message_id":16672}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Новый текст. Обязательно."}}}}}}}},"/api/v2/{channel}/messages/{id}/delete":{"post":{"operationId":"post_delete","summary":"Удалить сообщение","description":"Удаляет сообщение бота у человека и в кабинете. Сроки те же, что у изменения. Если мессенджер откажет, придёт 502 channel_delete_failed, а в кабинете сообщение останется.","tags":["Сообщения"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","message_id":16672}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/typing":{"post":{"operationId":"post_typing","summary":"Показать «печатает…»","description":"Показывает человеку «печатает…». Пропадёт сам через несколько секунд или когда придёт сообщение.","tags":["Сообщения"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chat_id":{"type":"string","description":"Кому. Нужен chat_id или external_id."},"external_id":{"type":"string","description":"Ваш идентификатор человека."}}}}}}}},"/api/v2/{channel}/files/{message_id}":{"get":{"operationId":"get_file","summary":"Скачать файл из сообщения","description":"Отдаёт файл из сообщения: голосовое, фото, документ, видео — и присланные человеком, и отправленные ему. Ссылка на него приходит в attachments[].url — в вебхуке и в переписке. Скачивайте с вашим ключом в заголовке Authorization.","tags":["Сообщения"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"message_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Сам файл. Тип — в заголовке Content-Type.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/trigger":{"post":{"operationId":"post_trigger","summary":"Запустить сценарий","description":"Запускает сценарий из конструктора для одного человека. Удобно для уведомлений: данные передаёте переменными, а текст, кнопки и логика живут в конструкторе — их можно менять без правки вашего кода. Нужен включённый сценарий с триггером «Из другой автоматизации», иначе придёт 404 no_flow. В сценарии переменные доступны как {{var.имя}}. В ответе outcome: handled — сценарий отработал, operator — сценарий передал диалог оператору.","tags":["Сценарии"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Уникальная строка запроса. Повтор с тем же ключом и телом вернёт сохранённый результат.","schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","outcome":"handled","chat_id":"9995735656"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chat_id":{"type":"string","description":"Для кого. Нужен chat_id или external_id."},"external_id":{"type":"string","description":"Ваш идентификатор человека."},"vars":{"type":"object","description":"Данные для сценария. Имена — латиница, цифры и подчёркивание; до 20 переменных, значение до 500 символов."}}}}}}}},"/api/v2/{channel}/contacts/link":{"post":{"operationId":"post_link","summary":"Связать с вашим пользователем","description":"Связывает человека с идентификатором в вашей системе, например с номером клиента в CRM. Дальше вместо chat_id можно передавать external_id. Повторный вызов с тем же external_id перевесит связку на другой диалог.","tags":["Контакты"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"linked":true,"external_id":"user-42","chat_id":"9995735656"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chat_id":{"type":"string","description":"Наш идентификатор диалога. Обязательно."},"external_id":{"type":"string","description":"Ваш идентификатор, до 190 символов. Большие и маленькие буквы различаются. Обязательно."}}}}}}}},"/api/v2/{channel}/events":{"get":{"operationId":"get_events","summary":"Журнал событий","description":"Те же события, что уходят вебхуком, списком от старых к новым. Храним 14 дней. Пригодится, если ваш сервер был недоступен, или если вебхук поднимать не хочется и проще забирать события раз в минуту. Запомните cursor последнего обработанного события и в следующий раз передайте его в after — придёт всё, что было после.","tags":["События и вебхуки"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"after","in":"query","required":false,"description":"cursor последнего события, которое вы уже обработали. Без него — с самого старого.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Сколько вернуть, от 1 до 100. По умолчанию 100.","schema":{"type":"integer"}},{"name":"types","in":"query","required":false,"description":"Только эти события, через запятую, например message.received,message.sent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"cursor":"88214","id":"0b6f3c1e-8d2a-4f57-9a41-2c7e5d9b8f10","type":"message.received","created_at":"2026-10-23T18:44:32+03:00","bot_id":42,"channel":"telegram","data":{"chat":{"chat_id":"9995735656","name":"Иван","username":"ivan","business":false},"message":{"id":16671,"direction":"in","type":"voice","text":"","attachments":[{"type":"voice","mime_type":"audio/ogg","duration":7,"url":"https://etochat.bot/api/v2/telegram/files/16671"}],"sent_by":"person","sent_at":"2026-10-23 18:44:31"}}}],"next_after":"88214","has_more":false}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/{channel}/webhooks":{"get":{"operationId":"get_webhooks","summary":"Ваши вебхуки","description":"Адреса, на которые мы отправляем события этого бота, и когда туда последний раз удалось доставить. Секрет не показываем.","tags":["События и вебхуки"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":7,"url":"https://crm.example.com/hooks/etochat","events":[],"active":true,"last_ok_at":"2026-10-23 18:40:12","last_error":null,"created_at":"2026-10-20 12:00:00"}]}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"post_webhooks","summary":"Подключить вебхук","description":"Добавляет адрес, на который мы будем отправлять события. Адрес должен быть доступен из интернета, лучше https. До 5 адресов на бота. Без events придут все события. В ответе secret для проверки подписи — показываем его один раз, сохраните.","tags":["События и вебхуки"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok","id":7,"secret":"whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw","events":["*"]}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Куда отправлять события. Обязательно."},"events":{"type":"array","description":"Только эти события, например [\"message.received\",\"message.sent\"]. Пусто — все.","items":{"type":"object"}}}}}}}}},"/api/v2/{channel}/webhooks/{id}/delete":{"post":{"operationId":"post_webhooks_delete","summary":"Отключить вебхук","description":"Удаляет адрес. Что не успели доставить, туда уже не уйдёт — заберите из журнала событий.","tags":["События и вебхуки"],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["telegram","vk","max","webchat","instagram"]}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"status":"ok"}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/webchat/visitors":{"get":{"operationId":"get_visitors","summary":"Посетители сайта","description":"Все, кто открывал сайт, в том числе те, кто ничего не написал. Сверху — с последней активностью. Написать можно тем, у кого has_dialog = true.","tags":["Посетители сайта"],"parameters":[{"name":"online","in":"query","required":false,"description":"Только те, кто на сайте сейчас.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Поиск по имени, почте, адресу и заголовку страницы.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"active — по последней активности (по умолчанию), views — по числу просмотров, email — сначала с почтой.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Сколько вернуть, от 1 до 100. По умолчанию 50.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Сколько пропустить. Список меняется каждые несколько секунд, поэтому страницы могут немного сдвигаться.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"visitor_id":"v_8f31c0a2","chat_id":"5827431900215634771","name":"Ирина","email":"irina@example.com","verified":true,"online":true,"idle_seconds":4,"page_views":12,"current_url":"https://example.com/pricing","current_title":"Тарифы","has_dialog":true,"first_seen":"2026-10-02 11:20:41","last_seen":"2026-10-23 16:58:03"}],"total":37,"with_email":12,"with_dialog":9,"has_more":true,"next_offset":1}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/webchat/visitors/online":{"get":{"operationId":"get_visitors_online","summary":"Кто на сайте сейчас","description":"Сколько людей на сайте прямо сейчас и кто они. Считаем как «Сейчас на сайте» в кабинете: посетитель онлайн, если его вкладка отмечалась в последние window_seconds секунд.","tags":["Посетители сайта"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Сколько записей вернуть, от 1 до 100. По умолчанию 50. Число online всегда полное.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"online":3,"window_seconds":45,"data":[{"visitor_id":"v_8f31c0a2","chat_id":"5827431900215634771","name":"Ирина","email":"irina@example.com","verified":true,"online":true,"idle_seconds":4,"page_views":12,"current_url":"https://example.com/pricing","current_title":"Тарифы","has_dialog":true,"first_seen":"2026-10-02 11:20:41","last_seen":"2026-10-23 16:58:03"}]}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v2/webchat/visitors/{visitor_id}":{"get":{"operationId":"get_visitor","summary":"Карточка посетителя","description":"Всё про одного посетителя и последние 50 страниц, которые он открывал, — свежая первой. IP-адрес не отдаём. Чтобы написать посетителю, возьмите chat_id и вызовите «Отправить сообщение».","tags":["Посетители сайта"],"parameters":[{"name":"visitor_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"visitor":{"visitor_id":"v_8f31c0a2","chat_id":"5827431900215634771","name":"Ирина","email":"irina@example.com","verified":true,"online":true,"idle_seconds":4,"page_views":12,"current_url":"https://example.com/pricing","current_title":"Тарифы","has_dialog":true,"first_seen":"2026-10-02 11:20:41","last_seen":"2026-10-23 16:58:03","referrer":"https://yandex.ru/","geo":"Москва, RU","user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X)…","pages":[{"url":"https://example.com/pricing","title":"Тарифы","seen_at":"2026-10-23 16:57:12"},{"url":"https://example.com/","title":"Главная","seen_at":"2026-10-23 16:55:48"}]}}}}},"422":{"description":"Операция не поддерживается каналом или нарушены его ограничения","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}