От данных — к диалогу.

Светлая и тёмная темы

Кнопка солнца / луны в верхней панели открывает оформление. Доступны «Светлая», «Тёмная» и «Как в системе». Выбор применяется сразу, сохраняется в этом браузере и синхронизируется между вкладками одного адреса платформы. В автоматическом режиме тема меняется вместе с настройкой операционной системы. Настройка также доступна на странице входа, в руководстве и описании API.

Тёмная тема охватывает панели, формы, таблицы, редакторы, аналитику и диалоги. В чатах используются отдельные цвета входящих и исходящих сообщений. Цвета статусов сопровождаются текстом. При недоступном localStorage переключение работает до перезагрузки страницы. Настройка не переносится между разными браузерами и адресами платформы.

Виджет на сайте следует data-theme="light" / "dark" элемента html, если он задан, иначе системной теме. На script подключения можно явно задать data-theme="light" или data-theme="dark". Без этого атрибута выбор автоматический. Основной цвет виджета берётся из его настроек в проекте.

Куда вставить токен бота

Откройте проект → «Боты и каналы» → «Подключить бота». Кнопка перехода к подключению есть и в шапке проекта. По умолчанию выбран настоящий бот; поле токена видно сразу.

Telegram: выберите Telegram и вставьте «Токен бота от BotFather». В Telegram откройте @BotFather, выберите своего бота и скопируйте API Token. Для создания нового бота используйте /newbot. Укажите название подключения, нажмите «Сохранить и продолжить», затем «Подключить Telegram». Последняя кнопка направляет сообщения бота в BotDock, заменяя прежнюю подписку webhook этого бота.

VK: выберите ВКонтакте и вставьте токен сообщества, ID сообщества и строку подтверждения Callback API. После сохранения откроются URL и секрет, которые нужно указать в настройках Callback API сообщества и включить событие входящих сообщений.

MAX, Одноклассники и Viber: выберите сервис, вставьте выданный им токен и после сохранения завершите подключение. У «Своего сервиса / API» другой порядок: BotDock выдаёт реквизиты для вашего адаптера, внешний токен вводить не требуется.

Токен хранится на сервере в зашифрованном виде и не выводится обратно в интерфейс. Название подключения нужно только для кабинета. Карточки «Тестовый» не связаны с настоящими мессенджерами. Кнопка «Подключить Telegram» или «Подключить ВКонтакте» в тестовой карточке создаёт отдельное реальное подключение, сохраняя симулятор.

Для ответов клиентам нужен опубликованный сценарий и включённый проект. Если проект на паузе, включите его в обзоре. Локальному серверу для приёма сообщений нужен публичный HTTPS-адрес; на botdock.itunity.dev он уже настроен.

Удобство повседневной работы

Кнопка «?» в верхней панели даёт инструкцию именно для открытого раздела и ссылку на полное руководство. Меню проекта остаётся сгруппированным; на телефоне оно открывается кнопкой слева в шапке. У страниц собственные названия вкладок, чтобы различать проекты.

Каталог интеграций ищет по названию, категории и описанию. В таблицах и документах есть поиск источника по названию. В описании открытого API можно искать метод и путь. Пустой результат поиска объясняется отдельно от отсутствия данных в проекте.

Новая строка таблицы и её изменение открываются в форме с полями по колонкам: текст, число, «Да/Нет». Сложная схема колонок и параметры интеграций остаются JSON. Для JSON-полей есть форматирование и сообщение об ошибке. Ошибки отправки формы отображаются рядом с действием, фокус переходит к сообщению; введённые значения сохраняются. Звёздочкой отмечены обязательные поля.

У примеров кода, API и инструкций есть кнопка «Копировать». Она использует буфер обмена браузера; если он недоступен, скопируйте текст вручную. Большие таблицы прокручиваются в своём контейнере, не расширяя всю страницу. Контейнер таблицы доступен клавишей Tab и прокручивается стрелками.

Поля расписания показываются по выбранному типу: интервал, каждый день или дни недели. В блоке запуска процесса настройки расписания и собственного события появляются только для соответствующего источника.

На доске кнопка лупы или F открывает поиск по названию, типу и ID блока. Enter выбирает первый результат; стрелка вниз переводит фокус к результатам. Переход показывает выбранный блок в масштабе не меньше 85%, не изменяя сценарий. Сетка автоматически разрежается при уменьшении, чтобы не сливаться в фон.

Навигация нового кабинета

Рабочий стол показывает проекты, подключённые каналы, число профилей и опубликованных ботов. Поиск учитывает название и описание. Фильтры «Активные», «Черновики» и «На паузе» используют состояние проекта; активный проект может исполнять процессы без опубликованного бота. Переключатель карточек и списка запоминается в этом браузере.

Верхний поиск открывается кнопкой или Ctrl/⌘ K. Начните вводить название проекта или раздела; стрелки выбирают результат, Enter открывает, Escape закрывает. Переключатель над меню показывает проекты и сохраняет текущий раздел при переходе между ними.

В проекте меню разделено на «Бот», «Клиенты и команда», «Автоматизация», «Данные и контроль». Раскройте нужную группу. «Центр поддержки» объединяет рабочее место оператора с выбором проекта. «Согласования» показывает решения команды. На телефоне меню открывается кнопкой в левом верхнем углу.

Полотно ботов и процессов

Конструктор бота занимает всю ширину окна. Меню кабинета открывается кнопкой слева в шапке. При входе показывается весь сценарий; настройки скрыты. Щёлкните блок: он приблизится до читаемого масштаба, справа откроется панель. «Готово», крестик или Escape внутри панели возвращают полотно. На телефоне настройки занимают всю ширину.

Для нового шага нажмите «+» у выхода блока или рядом с переходом в настройках. Каталог показывает действия с описаниями и поиском. «Добавить шаг» в шапке позволяет выбрать место в списке «Добавить после». Новый шаг вставляется между выбранным блоком и его прежним продолжением. У условия обе ветки сначала ведут в прежнее продолжение — выберите разные шаги для «Если да» и «Если нет». Завершающее действие можно вставить перед конечным блоком; оно заменяет завершение только в выбранной ветке.

Условия предлагают сообщение клиента, сохранённые поля и известные колонки результата таблицы. «Другие данные» открывает ручной путь state.поле / event.поле. В блоке таблицы колонки выбираются из схемы, поля записи и случайной выдачи появляются по выбранному действию. Запросы API и сложные записи пока используют JSON.

Конструктор бота и редактор процесса используют общие жесты полотна. Перетаскивайте блок за карточку; координаты привязываются к сетке 8 px. Стрелки перемещают сфокусированный блок на 8 px, Shift + стрелки — на 80 px.

Чтобы соединить блоки, потяните кружок выхода ко входу другого блока. Можно нажать выход, затем вход или карточку назначения. Клавиатурой: Tab до выхода → Enter → Tab до входа → Enter. Выбранную связь можно удалить клавишей Delete; Escape отменяет незавершённое соединение. Обязательные переходы проверяются при сохранении. В свойствах остаются выпадающие списки переходов.

Пустой фон перетаскивает полотно. Режим руки включается кнопкой или H; V возвращает выбор блоков. Пробел + перетаскивание временно включает руку. Колесо/трекпад перемещают полотно, Ctrl/⌘ + колесо меняет масштаб вокруг курсора. Плюс и минус изменяют масштаб, 0 показывает весь сценарий. Есть кнопка 100%, мини-карта, автоматическая расстановка и полноэкранный режим. Полотно поддерживает касание и масштабирование двумя пальцами; точный переход также можно выбрать в свойствах.

Масштаб — 8–300%. Видимая область перемещается свободно; технический предел координаты блока — ±1 000 000. Число блоков осталось прежним: 100 для бота, 80 для процесса. Это полотно сценариев, не совместная многопользовательская доска. Точка обзора и масштаб запоминаются локально в браузере; конструктор бота при новом открытии показывает весь граф.

Отмена: кнопка или Ctrl/⌘ Z. Повтор: кнопка или Ctrl/⌘ Shift Z. История хранит до 70 состояний текущего графа в памяти вкладки. Перезагрузка или повторное открытие редактора начинает новую историю. Отмена не откатывает уже выполненные действия процесса и опубликованные версии. Удаление обычного последовательного шага соединяет предыдущий со следующим. Удаление сложного разветвления требует сначала перенаправить связи; редактор не удаляет оставшиеся ветки автоматически.

Сохранение выполняется кнопкой «Сохранить». «Не сохранено» означает локальные правки. «Готово» закрывает настройки шага, но не сохраняет черновик на сервере. «Опубликовать» сохраняет изменения и создаёт новую исполняемую версию. В конструкторе бота «Проверить» открывает изолированный тест текущего черновика, в том числе несохранённых правок: публикация не нужна, записи и внешние вызовы моделируются. Отдельный раздел «Симулятор» исполняет опубликованный сценарий в среде sandbox. Импорт и экспорт JSON находятся в меню «•••». Перемещение обзора и масштаб не меняют сам сценарий. Конфликт ревизий с другой вкладкой по-прежнему блокирует перезапись.

Текст и кнопки сообщения

В блоке «Сообщение» сначала заполните «Что напишет бот». «Подставить данные клиента» вставляет имя, сообщение, сохранённое поле или известную колонку результата таблицы в позицию курсора. Такие данные доступны после выполнения шага, который их сохраняет. Разделы «Кнопки под сообщением» и «Предпросмотр сообщения» раскрываются по необходимости. Название блока, формат, изображение и JSON находятся в «Дополнительных настройках». B, I, U, S и моноширинный текст вставляют разрешённые HTML-теги; формат меняется на Telegram HTML. В остальных каналах используется поддерживаемое представление из существующих адаптеров. Переменные в предпросмотре видны как шаблоны; подстановка происходит при исполнении.

«Добавить кнопку» создаёт строку с подписью, действием, значением и цветом. Действие — команда боту, HTTPS-ссылка или запрос собственного номера. Для запроса номера используйте отдельное сообщение: Telegram показывает системную кнопку контакта в личном чате, другие каналы предлагают команду /phone с доступным для них способом. Можно задать расположение клавиатуры и число колонок. Максимум 12 кнопок. Для разных каналов используйте «Дополнительные настройки» → «JSON и варианты по каналам»; варианты не подменяют общий формат. Цвет и HTML зависят от возможностей сервиса. Предпросмотр показывает базовое оформление Telegram; нажатие его кнопок не выполняет сценарий.

Диалоги и операторское место

Диалоги показывают список клиентов, поиск по имени/ID и фильтры «Все», «Реальные», «Тестовые». История объединяет подтверждённые аккаунты. Белый пузырь — входящее сообщение, светло-зелёный — исходящее. У каждого сообщения есть автор, канал, время и доступный статус доставки. Один знак отправки не означает прочтение клиентом.

Enter отправляет ответ, Shift + Enter добавляет строку. Кнопка смайла открывает эмодзи. Несохранённые ответы удерживаются в памяти вкладки для выбранного диалога; после обновления страницы черновик теряется. Канал ответа выбирается над полем ввода. Ответ из карточки клиента переводит разговор оператору; для автоматических ответов верните статус «Работает» в профиле.

Карточка клиента открывается справа: аккаунты каналов, метки, сохранённые поля, права, статус и экспорт истории. В центре поддержки боковая карточка содержит внутренние заметки, приоритет и назначение сотрудника. Текущие роли и права продолжают проверяться сервером. Закрытое обращение не даёт отправить операторский ответ.

На телефоне сначала виден список. Выбор клиента или обращения открывает разговор на весь экран под верхней панелью. Стрелка назад возвращает список. Обзор клиента показывает последние 100 сообщений; полная история доступна в экспорте. Операторский API также поддерживает before. Новые входящие в центре поддержки обновляются опросом; в обычных «Диалогах» есть ручное обновление.

Аналитика и данные на графиках

Выберите среду, период 7/30/90 дней и канал, затем «Применить». Карточки, график и таблицы используют один ответ API. График показывает входящие и исходящие сообщения, нулевые дни заполняются нулями. Легенда включает и выключает серии, сохраняя хотя бы одну. Наведите указатель или сфокусируйте день клавишей Tab, чтобы увидеть значения. Тот же набор по дням доступен в раскрывающейся таблице.

Время графиков — UTC. Период начинается в точное время запроса минус число дней, поэтому первый и последний календарные дни могут быть неполными. Круглые даты в истории чата показываются в часовом поясе браузера. Если сообщений нет, отображается пустое состояние. Рост, прогнозы и сравнения с прошлым периодом не выдумываются.

Распределение по каналам использует число записей сообщений, включая технические подтверждения. События конверсий, поддержка, внешние операции, блоки, доставка и игры имеют отдельные таблицы с исходными единицами. p50/p95 и размер выборки поясняются внизу. Экспорт CSV/XLSX сохраняет применённые фильтры.

Принципы оформления и референсы

Bitrix24 — структура рабочего пространства, боковое меню и контекст проекта: https://helpdesk.bitrix24.com/open/25409295/

Telegram — организация чатов, папок и визуальная иерархия сообщения: https://telegram.org/blog/folders и https://core.telegram.org/themes

Miro — инструменты полотна, мини-карта и управление масштабом: https://help.miro.com/hc/en-us/articles/360017730553-Toolbars

Metabase — фильтры и выбор графика по смыслу данных: https://www.metabase.com/docs/latest/dashboards/filters и https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/visualization/chart-guide

Иконки, разметка, стили и фон диалогов реализованы в проекте. Внешние шрифты, библиотеки диаграмм и аналитические трекеры для нового кабинета не загружаются. Визуальные приёмы мессенджера не добавляют звонки, голосовые сообщения, статусы прочтения и другие отсутствующие возможности Telegram.

Быстрый старт и шаблоны

Откройте проект → Данные и контроль → Таблицы и документы. Карточки «Погода», «Контент из документа», «Крокодил» и «Заявки» создают новый проект с тестовыми Telegram/VK. Исходный проект не меняется. Изучите блоки, опубликуйте сценарий и перейдите в Симулятор. Токены для этого не нужны.

Погода: отправьте /start, затем город. В sandbox используются заданные координаты Москвы и 18 °C — это проверка сценария, а не фактическая погода. Для реальных ответов подключите live-канал. Шаблон использует геокодирование и текущую погоду Open-Meteo. Публичный бесплатный API имеет условия использования и ограничения для коммерческого применения: перед коммерческим запуском выберите подходящий тариф и URL провайдера. Атрибуция уже есть в сообщении.

Документ: /start → Овен / Телец / Близнецы. Это демонстрационный развлекательный текст. Замените его своим материалом в документе. Шаблон читает локальный документ среды sandbox. Для live создайте документ в live, укажите его в блоке и опубликуйте новую версию, либо замените блок операцией Google Docs.

Заявки: /start → имя → контакт. Бот сохраняет строку и событие lead.created. Откройте таблицу «Заявки», выберите ту же среду, скачайте XLSX. Шаблон не проверяет достоверность телефона/email; условия проверки можно добавить перед сохранением.

Крокодил: опубликуйте проект → Игры → песочница. Каждый игрок начинает с /game в личном чате. Создатель: /game create Животные; второй игрок: /game join КОД; создатель: /game start. Для группы у всех одинаковый ID группы в песочнице. Полная последовательность ниже.

Проект, каналы, профили и среды

Проект объединяет сценарий, подключения, таблицы, документы, пользователей и историю. Каналы Telegram, VK, MAX, OK, Viber и webchat исполняют опубликованную версию. bridge предназначен для вашего адаптера с подписанными входящими событиями и подтверждением исходящих сообщений.

sandbox — тестовые профили, строки таблиц, документы, комнаты, mock-ответы API. live — реальные данные и отправки. Эти среды не смешиваются автоматически. Схема таблицы общая; строки раздельные. Права service key действуют на весь проект, поэтому интегратору с data:read доступны обе среды через параметр environment.

Состояние профиля — до 100 строковых полей по 4000 символов. Вложенный результат сохраняется JSON-строкой, но шаблоны читают её по пути: {{state.result.text}}, {{state.result.rows.0.name}}. Ноль не заменяется пустой строкой. Права доступа и платёжные права хранятся отдельно от состояния.

Имена и ники не подтверждают личность. В исходном личном чате отправьте /link; во втором — /link КОД; подтвердите запрос командой /confirm КОД в исходном канале. Сохраняется состояние исходного профиля. Во время внешней операции или активной игры сначала дождитесь завершения/выйдите из комнаты. Служебные аккаунты сотрудников с клиентскими не связываются. Групповые сообщения не запускают команды привязки, оплаты, поддержки и личный сценарий.

Конструктор: блоки, переменные, версии

Полотно поддерживает перемещение, масштаб, мини-карту, отмену и автоматическую расстановку. Перетаскивайте блоки и соединяйте кружки выходов со входами. Переходы также доступны в правой панели. Подробные жесты и клавиши описаны в разделе «Полотно ботов и процессов». Черновик сохраняется отдельно от публикации. Публикации неизменяемы. Диалоги, уже ожидающие ответа или интеграции, продолжают свою версию. /cancel сбрасывает ожидание. Сохранение проверяет связность графа; каждый цикл должен проходить через «Ждать ответ». Лимит: 100 блоков, до 20 ответов за обработку события.

Входящее сообщение (trigger): один вход в сценарий. Не является фильтром команды. Для /start, /weather и других команд добавьте условие по text.

Условие (condition): поля text, status, channel, state.поле или event.поле. Сравнения equals, not_equals, contains, starts_with, exists и числовые gt/gte/lt/lte. Строки сравниваются без учёта регистра и крайних пробелов. exists проверяет непустое значение. Вложенное логическое true из JSON отображается в строковом шаблоне как True; его можно сравнить со значением True.

Ответ (reply): текст с переменными, кнопки, раскладка, формат, HTTPS-изображение. Поддержка зависит от канала. Кнопка callback поступает как обычный текст команды; наличие кнопки само по себе не выдаёт прав. Проверяйте доступ отдельным блоком.

Записать поле (set): задаёт значение строкового поля по шаблону. Ждать ответ (wait): сохраняет следующее сообщение в поле и приостанавливает выполнение. Внешнее событие также может заполнить ожидаемое поле, поэтому проектируйте маршрутизацию событий явно. Проверить доступ (access): учитывает включённое право и срок окончания, включая подтверждённую оплату.

Интеграция (integration): выбранная сохранённая операция, JSON input, result_key, next/on_error. Вызов выполняется в очереди. Пока он не завершён, новые сообщения этого профиля ждут. Ответ сохраняется в result_key и по result_map операции. Sandbox никогда не вызывает внешнюю систему.

Данные таблицы (data): lookup возвращает первую строку с точным совпадением; без колонки — первую строку. random выбирает случайную строку, при заданной колонке/значении фильтрует категорию. Без повторов означает без повторов до исчерпания доступных строк в рамках профиля; затем начинается новый цикл. Изменение таблицы сбрасывает историю выдачи. append добавляет одну строку. update требует ровно одно совпадение и меняет указанные колонки. values поддерживает переменные; fields ограничивает колонки результата. Результат содержит _id; lookup также found. Пустые/ошибочные данные направляются в on_error. После ошибки last_error содержит безопасное общее описание. Результат ограничен 4000 символами; уменьшите fields при превышении.

Документ (document): читает документ той же среды целиком или по заголовку. Возвращает title, text, found. Заголовок — строка, начинающаяся с #. Поиск точный, без учёта регистра. Текст ответа обрезается до 3500 символов; длинные материалы разбивайте на разделы. Отсутствие раздела — found=false, а недоступность документа — on_error.

Вычисление (math): add, subtract, multiply, divide над текущим числовым полем (по умолчанию 0) и value. random выбирает целое от текущего поля до value включительно; диапазон не более миллиона. Деление на ноль и нечисловые значения идут в on_error. Python/JS из сценария не исполняются.

Событие аналитики (metric): имя до 60 символов, JSON properties до 4000 байт с переменными. Примеры: lead.created, weather.viewed, game.signup. Событие фиксируется вместе с успешной обработкой транзакции; повтор входящего event_id не создаёт дубль. Для воронки добавьте отдельный блок на каждом важном шаге.

Передать оператору (handoff): создаёт обращение и переводит профиль в поддержку. Бот перестаёт отвечать обычным сценарием до завершения обращения. Завершение (end): заканчивает текущую обработку, сохраняя состояние профиля.

Доступные шаблоны: {{name}}, {{text}}, {{channel}}, {{profile_id}}, {{status}}, {{state.city}}, {{state.result.text}}, {{event.order.id}}, {{access.premium}}. Текстовые шаблоны возвращают строки; целиком заданный шаблон в JSON input/values сохраняет исходный тип значения. Секреты подключений не подставляются в шаблоны.

Excel, CSV и собственные таблицы

Создайте таблицу в «Таблицы и документы». Колонки: key (латиница, цифры, _, начинается с буквы), label (подпись), type (string, number, boolean). Ключи уникальны. Схема после создания неизменна: для другой структуры создайте новую таблицу и перенесите данные. Строки редактируются через «Изменить»; API также позволяет удалять их.

Импорт: .xlsx, .csv, .tsv, до 3 МБ, 5000 строк данных и 30 колонок. XLSX использует первый лист. CSV/TSV — UTF-8; распознаются запятая, точка с запятой и табуляция. Первая строка — заголовки, совпадающие с key или label. Пустые строки пропускаются. Неизвестные колонки, дубли заголовков, формулы и макросы отклоняются. Выгрузите вычисленные значения из исходного Excel перед импортом. .xls, изображения, оформление и формулы не импортируются.

Выберите «Добавить» либо «Заменить все строки выбранной среды». Импорт атомарный: некорректная строка не оставляет частично загруженные данные. Ревизия защищает от перезаписи изменений с другой вкладки: при 409 обновите таблицу. string — до 4000 символов; number — конечное число; boolean — true/false, 1/0, да/нет. Пустое значение становится null.

Экспорт XLSX/CSV сохраняет все строки выбранной среды. XLSX содержит заголовки, фильтр и закреплённую первую строку. Строки, похожие на формулу, записываются как текст; в CSV перед ними добавляется апостроф. Это может менять отображение в последующем импорте CSV; для точного обмена такими строками используйте XLSX.

В шаблоне «Заявки» append записывает name/contact/profile. Для каталога используйте lookup по sku. Для слов/цитат — random с категорией. Для счётчиков профиля используйте math; обновление общей таблицы происходит в транзакции SQLite.

Google Sheets и Google Docs

В Google Cloud включите Google Sheets API и/или Google Docs API. Создайте сервисный аккаунт и JSON-ключ. В самом документе/таблице предоставьте доступ адресу client_email из ключа: чтение для чтения, редактирование для добавления строк. Общедоступная ссылка не заменяет выдачу доступа сервисному аккаунту. Пользовательский OAuth и автоматический выбор файла из Google Drive пока не реализованы.

В BotDock: Интеграции → Google Sheets / Docs → Подключить → вставьте JSON-ключ. Он хранится зашифрованным и не возвращается в списке подключений. Ротация: создайте новое подключение/операцию, обновите блок сценария, опубликуйте, отключите старое. Документ открывается только сервисному аккаунту; делегирование пользователя не используется.

ID берётся из URL между /d/ и следующим /. Операция для чтения таблицы:

{"action":"sheets.read","document_id":"YOUR_DOCUMENT_ID","range":"Sheet1!A1:C100","result_map":{"first_word":"values.1.0"},"mock":{"values":[["word","category","aliases"],["крокодил","Животные","аллигатор"]]}}

Операция записи строк:

{"action":"sheets.append","document_id":"YOUR_DOCUMENT_ID","range":"Sheet1!A:C","values":[["{{input.name}}","{{input.contact}}","{{input.profile}}"]],"result_map":{"written":"updates.updatedRows"},"mock":{"updates":{"updatedRows":1}}}

Вход блока интеграции: {"name":"{{state.name}}","contact":"{{state.contact}}","profile":"{{profile_id}}"}. Запись использует RAW: строка =1+1 останется текстом. Неизвестный результат записи требует сверки перед повтором; повторы могут создать дубли в Sheets. Изменение существующих ячеек и форматирование через этот адаптер пока не реализованы.

Google Docs:

{"action":"docs.read","document_id":"YOUR_DOCUMENT_ID","result_map":{"article":"text"},"mock":{"title":"Прогнозы","found":true,"text":"Пример прогноза"}}

В input можно передать {"section":"{{state.sign}}"}. Заголовки Google Docs уровней HEADING преобразуются в разделы; поддерживается текст вкладок, дочерних вкладок и ячеек таблиц. Рисунки, комментарии, сноски, оформление и предложения правок не извлекаются. Без section возвращается весь текст до 40 000 символов, с section — до 3500. Ответ всей интеграции ограничен 64 КБ, поэтому большой документ/диапазон может потребовать сужения.

Для локального снимка выполните sheets.read или docs.read в интеграциях и скопируйте полный ID успешного запуска. В таблице нажмите «Из Google Sheets», для текста — «Из Google Docs». Среда снимка соответствует запуску; первая строка Sheets является заголовками. Импорт Docs создаёт новый документ. Это снимок, а не фоновая двусторонняя синхронизация. Чтобы читать актуальные данные при каждом обращении, используйте блок «Интеграция» напрямую. Регулярную запись/чтение можно запускать через существующие расписания и внешние события.

Кнопки, ссылки и оформление

В блоке «Ответ» выберите формат, тип клавиатуры, 1–3 кнопки в строке и JSON-массив кнопок. До 12 кнопок. Можно использовать простой массив строк: ["Москва","Минск"]. Подписи — до 40 символов; callback value — до 64 байт UTF-8 (кириллица занимает больше одного байта).

[
  {"text":"Заказать","action":"callback","value":"/order","color":"primary"},
  {"text":"Правила","action":"url","value":"https://example.com/rules"}
]

Telegram: клавиатура под вводом, inline-кнопки, ссылки, цвета primary/positive/negative, HTML b/strong/i/em/u/s/code/pre/a. Переменные в HTML экранируются. callback принимается по webhook и подтверждается answerCallbackQuery. Измените webhook старого бота через «Подключить», чтобы включить callback_query. Если есть ссылка или команда отличается от подписи, клавиатура автоматически становится inline. photo: HTTPS-ссылка, подпись до 1024 символов; при более длинном тексте изображение становится ссылкой в сообщении. Оформление старых сообщений и загрузка файлов с диска не реализованы.

VK: обычная/inline-клавиатура, text payload с командой, open_link, цвета. Пользовательское нажатие обрабатывается как входящее сообщение. Viber: reply и open-url. Виджет: безопасные текстовые кнопки и HTTPS-ссылки. MAX: нативные inline callback/link-кнопки. OK: нативная INLINE_KEYBOARD с CALLBACK/LINK и цветами. HTML преобразуется в обычный текст вне Telegram; изображение передаётся ссылкой. Универсального равенства возможностей мессенджеров нет: матрица адаптеров доступна в Помощи.

Варианты по каналам: поле variants содержит переопределения text/buttons/keyboard/columns/format/image для telegram, vk, max, ok, viber, webchat или bridge. Остальные поля наследуются из общего сообщения. Пример: {"telegram":{"text":"<b>Каталог</b>","format":"html","keyboard":"inline"},"viber":{"text":"Каталог","format":"plain","keyboard":"reply"}}. После подстановки шаблонов сообщение повторно проверяется. Кнопки поддерживают значения {{state.order_id}} в рамках лимита 64 байт. HTML доступен только Telegram; для остальных каналов применяются возможности адаптера. MAX/OK кнопки проверены по контрактам API, без живых аккаунтов пользователя.

Общие возможности не зависят от «Крокодила»: таблицы, документы, вычисления, условия, API и ожидание ответа работают в любом личном сценарии. Шаблон «Викторина из таблицы · общие блоки» собирается только из этих блоков: случайный вопрос без повторов, ответ, условие, счёт, следующий вопрос. Его можно заменить каталогом, опросником или обучающим тестом. «Крокодил» — отдельный готовый игровой модуль, с собственными комнатами и ролями. Универсальный конструктор произвольной многопользовательской игры и группового состояния пока не реализован; общие сценарии обслуживают личные чаты, группы Telegram/VK — игровой модуль.

Крокодил: личные комнаты и группы

Создайте словарь с колонками word, category, aliases. Синонимы разделяются |. В «Игры» выберите таблицу/колонки и правила: длительность 15–3600 секунд, 2–50 игроков, до 200 раундов, очки за ответ, бонус ведущему, штраф за пропуск. Изменения действуют на новые комнаты; существующая комната хранит снимок правил. Слова берутся из текущего словаря среды комнаты, без повторов до исчерпания. Загрузка нового словаря сбрасывает историю выдачи.

Личные чаты: каждый пишет /game боту. Создатель — /game create или /game create Категория. Другие — /game join КОД. После минимум двух игроков создатель пишет /game start. Сообщения о ходе игры идут всем участникам, слово — только ведущему. Комнату можно использовать между Telegram и VK внутри одного проекта и среды. Связанный профиль не может занять два места в одной комнате; при активной игре объединение профилей откладывается до /game leave. Счёт привязан к участию аккаунта в комнате, не является глобальной системой рейтингов.

Группа Telegram/VK: каждый участник сначала открывает личный чат с этим же ботом и отправляет /game. Добавьте бота в группу и разрешите сообщения/получение событий. В группе: /game create, остальные /game join, создатель /game start. Telegram с privacy mode может не доставлять обычные догадки; используйте /game guess ответ, при необходимости /game@botname guess ответ. Для свободного текста настройте privacy mode через BotFather и права группы. В VK включите сообщения сообщества и доступ бота к беседам.

Ведущий выбирается по очереди из активных игроков. /game word повторно отправляет слово только ведущему в личный чат. /game guess ответ либо обычное сообщение — догадка. Сравнение не учитывает регистр, ё/е, крайние пробелы и пунктуацию. Ведущий не может угадывать своё слово. Первый правильный ответ завершает раунд атомарно и начисляет очки. После окончания слово раскрывается участникам.

/game skip доступен ведущему, /game score показывает счёт, /game leave выводит игрока (выход создателя закрывает комнату), /game stop закрывает комнату создателем. Таймер обрабатывается worker; при остановленном worker окончание фиксируется при следующей обработке или после запуска worker. До 100 открытых комнат проекта. Отключение игры закрывает их. Словарь и выбранное слово зашифрованы в базе; владелец проекта может видеть их, как и другие данные своего проекта.

Отчёты и интерпретация

Выберите среду, канал и период 7/30/90 дней. Отчёт содержит входящие/исходящие сообщения, активные личные клиентские профили, динамику по дням UTC, каналы, события конверсии, статусы интеграций, длительность запросов, поддержку, результаты игр и посещения блоков. Экспорт — XLSX/CSV; API — analytics:read.

Активный профиль считается по входящему личному сообщению kind=user. Групповые игровые чаты и аккаунты сотрудников не являются уникальными клиентами этой метрики. В таблице каналов «Профили» включает профили всех видов сообщений; групповой чат представлен техническим профилем. При объединении аккаунтов история сообщений переносится на общий профиль. События аналитики также объединяются для будущего подсчёта уникальных профилей.

simulated — тестовый ответ; queued — ожидает доставки; sent — провайдер подтвердил отправку, это не прочтение человеком; uncertain — результат неизвестен, нужна сверка. callback_ack — техническое подтверждение нажатия, в основных счётчиках сообщений оно исключено. Исходящие данные могут включать служебные сообщения, уведомления и ответы операторов.

Трассировки создаются с версии 0.6, прошлые посещения блоков не восстанавливаются. «Сегмент» — непрерывное исполнение до ожидания/интеграции/завершения. p50/p95 измеряют локальное исполнение сегмента, не время всего диалога. Итоги сообщений и событий считаются по базе за период. Для посещений блоков, статусов сегментов и процентилей берутся последние 10 000 трассировок; при ограничении отчёт показывает предупреждение.

События конверсии показывают срабатывания и уникальные профили по каждому имени. Это ещё не упорядоченная воронка, когортный анализ или атрибуция рекламы. Добавьте metric на этапах lead.started/lead.created; для сложного BI забирайте агрегаты и проектируйте собственное хранилище событий. Свойства событий сохраняются зашифрованно; интерфейс показывает агрегаты, а не произвольный SQL-редактор.

Поддержка: статус обращений, среднее время первого ответа в секундах, просрочка относительно reply_due. Интеграции: время от постановки задания до завершения, включая очередь. Игра: число завершённых раундов и средняя длительность по исходу. Пауза проекта/канала влияет на выполнение и доставку; отчёты продолжают показывать накопленные данные.

Открытый API и SDK

Ключи создаются в Журнал и API и показываются один раз. Передавайте Authorization: Bearer KEY только с сервера. Не вставляйте проектный ключ в сайт, виджет, плагин CMS или общедоступный репозиторий. Все методы привязаны к /api/v1/projects/PROJECT_ID. Новые права: data:read, data:write, analytics:read. Остальные права: profiles:read/write, messages:write, events:write, integrations:read/run, payments:read/write, audit:read.

GET /tables — схемы таблиц. GET /tables/TABLE_ID/rows?environment=live&offset=0&limit=100 — строки, total, offset, table.revision. limit 1–500. По умолчанию чтение public API использует live. Запись требует явного environment для предсказуемости: значение по умолчанию у POST — sandbox.

{"environment":"live","rows":[{"word":"крокодил","category":"Животные","aliases":"аллигатор"}],"replace":false}

POST /tables/TABLE_ID/rows с Idempotency-Key: import-2026-09-19-01. Повтор того же ключа и тела возвращает сохранённый результат. Другое тело с тем же ключом даёт 409. replace=true удаляет строки только выбранной среды и требует revision текущей таблицы. Замену всей таблицы нельзя использовать для небезопасного автоматического retry с новым ключом. Права data:write разрешают и замену.

GET /analytics?environment=live&days=30&channel_id=CHANNEL_ID. days: 1–90, channel_id можно опустить. Ответ включает messages, daily, channels, metrics, integrations, support, games, failures, flows и примечания к расчёту.

POST /messages также принимает buttons, keyboard, columns, format и image по контракту блока «Ответ». Требуются messages:write и Idempotency-Key.

Публичный контракт: /api/v1/openapi.json. Полный контракт панели после авторизации: /api/docs/openapi.json. Все модели запросов, обязательные параметры и пути берутся из FastAPI. 400 — неверные настройки/данные; 401 — авторизация; 403 — недостаточно прав; 404 — ресурс недоступен; 409 — конфликт ревизии/идемпотентности; 422 — неправильная форма запроса; 429 — лимит. Ключи ограничены 120 запросами в минуту; квоты проекта действуют отдельно.

SDK Python (/sdk/botdock.py) и JS (/sdk/botdock.mjs) содержат tables, rows, append_rows/appendRows, analytics вместе с методами профилей, сообщений, событий и операций. Параметры запроса и примеры доступны в /developers. Файлы SDK не управляют секретами за вас — берите их из переменных окружения. Для UI владельца используются cookie-сессия и CSRF; эти методы не подменяют публичный service API.

HTTP, базы, 1С, платежи и собственные методы

HTTP / REST: задайте базовый HTTPS URL, авторизацию none/bearer/basic, заголовки. Операция задаёт метод, путь, query/body, result_map и mock. В input передайте переменные профиля. Секреты остаются в подключении. Ответ ограничен 64 КБ, сетевой ответ — 512 КБ. Публичный HTTP выполняется только к проверенным публичным адресам HTTPS 443, без редиректов и системного proxy. Локальную 1С/БД подключайте исходящим агентом.

PostgreSQL/MySQL/SQLite и внутренняя 1С: установите агент рядом с системой, зарегистрируйте его в проекте, настройте именованные операции и переменные окружения. Облако передаёт alias и параметры, а не произвольный SQL. У агента свой журнал идемпотентности. Примеры конфигурации и точные команды: docs/INTEGRATIONS.md и examples/agent.config.json в поставке.

ЮKassa: операция создаёт платёж, общий доступ выдаётся только после сверки статуса, суммы, магазина и привязки. Тестовый магазин не даёт реального доступа. Полные возвраты поддерживаются; подписки с автосписанием и частичные возвраты пока нет. Другие платёжные провайдеры подключаются через HTTP/агент и требуют отдельной проверки их подтверждений и идемпотентности. Наличие HTTP-коннектора не означает готовый сертифицированный платёжный адаптер.

Конструктор API публикует именованную версию метода поверх сохранённой операции. Задайте поля входа/результата, окружение, отдельный ключ ep_. Вызов создаёт задачу и возвращает status_url; клиент опрашивает её до результата. OpenAPI конкретного метода доступен в интерфейсе. Эти ключи также предназначены для backend.

Оператор, сотрудники, календари и виджет

Сайты: создайте виджет, разрешите точные origin сайтов, настройте название и цвет. Универсальный script вставляется в HTML/Tilda; в поставке есть WordPress-плагин и PHP-заготовка для 1С-Битрикс. Виджет имеет отдельный канал и сессии посетителей, кнопки сценария, вызов оператора и подтверждённую привязку к мессенджеру. Ключ проекта посетителю не передаётся. Инструкции и ограничения: docs/EXPERIENCE.md.

Операторы: обращение создаётся по /operator, кнопке виджета или блоку handoff. Сотрудник берёт его в работу, отвечает, добавляет внутреннюю заметку, возвращает в очередь или закрывает. Раздел «Боты сотрудников» позволяет отвечать из того же или отдельного служебного бота после подтверждённой регистрации сотрудника: /queue, /take, /read, /reply, /note, /release, /close. Случайное знание ID клиента не даёт доступа к переписке.

Календари и триггеры: внутренний календарь, записи, ICS-импорт/подписка, повторения и напоминания, события обращения/календаря, расписания сотрудников и клиентов. Часовой пояс задаётся явно; пропуски во время простоя не создают бесконечную очередь уведомлений. ICS в этой версии читается, запись обратно в Google/Outlook не реализована. Подробный контракт — docs/TEAM_AUTOMATION.md.

Развёртывание и эксплуатация

Платформа Python/FastAPI + HTML/CSS/JS хранит данные в SQLite WAL и обслуживает омниканальные сценарии одним worker. Боты и процессы создаются в конструкторах, внешние системы подключаются через интеграции, открытый API и SDK. Платформа устанавливается напрямую на Python или через Docker Compose.

Развёртывание, env-переменные, HTTPS, worker, резервные копии и операции: README.md и docs/LAUNCH.md. Копируйте базу вместе с secret.key. app.ops verify проверяет расшифровку таблиц, документов, игровых слов и свойств аналитики. Восстановление закрывает игровые комнаты и отключает внешние точки отправки/расписания по существующей процедуре; включайте их после проверки.

Версия 0.8 — расширенный пилот для одного хоста. Не заявляется готовность к неограниченной массовой нагрузке, HA, многоузловым очередям, биллингу арендаторов или полному паритету n8n. Нет произвольного кода в визуальном сценарии, OAuth-мастера Drive, редактирования Google Docs, двусторонней синхронизации всех данных, собственного BI-конструктора и универсального богатого контента всех каналов. Это конкретные границы текущей поставки, а не скрытые заглушки.

Проверка и типовые проблемы

Бот молчит: опубликован ли сценарий; активен ли проект; включён ли канал; запущен ли worker; нет ли ожидающей интеграции или handoff; есть ли токен/webhook для live. Посмотрите статус входящего события, исходящую очередь, журнал интеграций и ошибки аналитики. В sandbox проверьте тот же external_id, которым начинали диалог.

Таблица пуста: проверьте environment. Импорт 409: обновите ревизию. Формулы отклонены: замените их значениями. Нет колонки: сравните заголовок с key/label. Google 403: включите API и предоставьте доступ client_email. Google 404: проверьте ID и доступ сервисного аккаунта. Google append uncertain: найдите строку в Sheets перед повтором.

В игре нет слова: загружен ли словарь нужной среды и категории; правильна ли word_column. В группе бот просит открыть личку: каждый игрок должен самостоятельно начать диалог с ботом. Нет таймера: worker должен работать. Слово доставлено не сразу: проверьте outbox и права на личные сообщения. Игра стартует по транзакции, а не по подтверждению доставки слова; проблемы провайдера видны в очереди, ведущий может запросить /game word повторно.

Кнопки не работают: обновите Telegram webhook с callback_query; проверьте 64 байта команды; обычная reply-кнопка Telegram отправляет свою подпись. Для других каналов сверяйтесь с матрицей. Старая клавиатура: отправьте reply с keyboard=remove. Цвет зависит от приложения и темы клиента.

Проверка релиза: python -m pytest -q. Новые тесты находятся в tests/test_studio.py: шаблоны, Excel/CSV, idempotency, среды, игры, секретность личного слова, Google adapter, кнопки и аналитика. Моделирование запросов Google не заменяет проверку с ключами конкретного заказчика. Личные аккаунты и внешние платёжные операции в автоматических тестах не используются.

Первичные источники

Telegram Bot API: https://core.telegram.org/bots/api

VK keyboard: https://dev.vk.com/ru/api/bots/development/keyboard

Google service accounts: https://developers.google.com/identity/protocols/oauth2/service-account

Google Sheets append: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append

Google Docs get: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get

Open-Meteo: https://open-meteo.com/en/docs

openpyxl: https://openpyxl.readthedocs.io/en/stable/

Автоматизации без ИИ: быстрый старт

Откройте проект → Автоматизация → Процессы → Создать. Выберите тестовый режим и один из пяти шаблонов: переменные, согласование, ожидание события, обработка списка, параллельные задачи. Полотно поддерживает масштаб, перетаскивание, мини-карту, соединение портов и отмену. Нажмите карточку блока, заполните свойства и переходы. «Применить к блоку» меняет черновик; «Сохранить» сохраняет его на сервере; «Опубликовать» создаёт неизменяемую версию и включает запуски. JSON / импорт позволяет переносить описание графа. ID таблиц, операций и подпроцессов относятся к конкретному проекту и требуют перенастройки после переноса.

Процесс работает самостоятельно, в том числе без опубликованного диалога бота. Диалог и процесс используют общие каналы, данные и интеграции, но имеют разные версии и состояние. События, условия и действия настраиваются в конструкторе; нейросети для выполнения не используются.

Первый пример: создайте «Согласование сотрудником», опубликуйте и запустите с {"request_id":"REQ-1"}. Откройте «Согласования», нажмите «Обновить», одобрите заявку. В «Запуски → Обновить → Шаги и данные» появятся решение, автор, время и vars.status. Можно отклонить или дождаться срока: это отдельные переходы графа. Обновление журнала ручное.

Sandbox использует отдельные строки таблиц и профили, не отправляет сообщения реальным клиентам и возвращает mock интеграции. При этом согласования, журнал и настройки действительно сохраняются, поэтому это не сухой расчёт без изменений. Режим закреплён за определением процесса; для live создайте отдельный процесс с проверенными идентификаторами и подключениями. Публикация нового процесса активирует новый проект, но не снимает намеренно установленную паузу проекта.

Блоки процессов и переменные

Начало (trigger): ручной вызов/API, расписание, событие сообщения, обращения, календаря, таблицы, подтверждённой оплаты или custom.имя. Фильтры задаются списком {field, operator, value}; все условия должны выполняться. Поле — путь в данных события, например order.status. Источник custom.order.created должен совпадать целиком.

Переменные (set): объект values сохраняется в vars. Условие (condition): left/operator/right; equals, not_equals, contains, starts_with, exists, gt/gte/lt/lte, in. equals учитывает тип, поэтому 1 и "1" различаются. Для in справа нужен массив. Пауза (delay): seconds от 1 секунды до года, сохраняется в БД, не удерживает поток Python.

Ждать событие (wait_event): source, match_field, match_value, seconds, переходы next/timeout. Всегда задавайте уникальную связь с заявкой, например order_id={{input.order_id}}. Принимаются события того же проекта и среды, поступившие после начала запуска, в том числе до достижения блока ожидания. Одно событие может продолжить несколько подходящих процессов; это широковещательная корреляция, не очередь с одним потребителем. Уникальные номера заявок предотвращают случайное совпадение.

Интеграция / CRM (integration): выберите сохранённую операцию, задайте input и result_key. Процесс ждёт сохранённое задание, затем кладёт результат в vars.RESULT_KEY. Сообщение клиенту (message): text, buttons, keyboard, format, columns и необязательные variants. Получатель — подтверждённый аккаунт выбранного проекта/режима, заданный при старте, в триггере или в данных системного события. Блок не ищет людей по нику и не связывает профили автоматически.

Уведомить сотрудников (staff): отправляет текст в подключённые служебные аккаунты выбранной среды. Согласование (approval): текст, срок, необязательный assigned_to (ID пользователя команды), approved/rejected/timeout. Без назначения решить может владелец или участник команды. При назначении — только этот сотрудник с актуальным доступом. Решение сохраняется с автором и примечанием; API позволяет передать note. Кнопки находятся в панели, а команды /approve ID текст и /reject ID текст доступны в подтверждённом служебном боте. Обычный клиент этих прав не получает.

Таблица (data): lookup, random, append, update, upsert и list. upsert обновляет единственную найденную по column/value строку либо добавляет новую; неоднозначное совпадение вызывает ошибку. list возвращает rows, total, truncated; не более 50 записей, можно выбрать fields и фильтр column/value. Для каждой записи (foreach) принимает массив, например {{vars.catalog.rows}}. В дочерней ветке доступны item и index, родитель получает массив vars дочерних запусков в порядке входных записей.

Документ (document): текст целиком или раздел. Вычисление (math): те же операции, что у бота, результат в переменной процесса. Событие аналитики (metric): именованное событие с properties. Отправить событие (emit): custom.имя и объект data; им можно запускать другие процессы или продолжать ожидания. Служебные ключи, начинающиеся с _, зарезервированы.

Параллельные ветки (parallel): 2–8 входных блоков, каждый заканчивается «Конец»; родитель ждёт все ветки и собирает их vars в указанном порядке. Это независимые сохраняемые ветки: локальные операции SQLite выполняются последовательно, ожидания и внешние задания могут перекрываться. Ветки не должны переходить в продолжение родителя. Подпроцесс (subflow): опубликованный процесс той же среды, входной объект и result_key; его переменные изолированы, версия включается в снимок при публикации родителя. После изменения подпроцесса перепубликуйте родителя.

Завершение (end) заканчивает текущий запуск или дочернюю ветку. Переход on_error перехватывает ошибку действия. Если дочерняя ветка завершилась ошибкой, оставшиеся ветки отменяются; успешные внешние записи и предыдущие завершённые шаги не откатываются автоматически. Для компенсации создайте явную ветку с разрешёнными действиями.

Шаблоны: {{input.name}}, {{event.text}}, {{vars.result.crm_id}}, {{item.sku}}, {{index}}, {{state.city}}, {{access.premium}}, {{run.id}}, {{run.environment}}. Целиком заданный шаблон сохраняет исходный JSON-тип; внутри строки становится текстом. input/event/vars сохраняются у запуска. state/access читаются из актуального профиля при выполнении шага, если указан получатель. Чтение секретов подключения через шаблоны не допускается.

События, расписания и взаимодействие систем

Системные источники: message.received (клиентское личное сообщение), ticket.created / ticket.message / ticket.closed, calendar.created / calendar.updated / calendar.cancelled, table.changed, payment.succeeded. Через внешний API принимается только custom.*: нельзя объявить подтверждённую оплату произвольным JSON. payment.succeeded возникает после проверки реальной оплаты через API ЮKassa; тестовый магазин не создаёт его. Новые заказы сохраняют исходный канал плательщика; для старых заказов получатель может отсутствовать, тогда задайте его явно.

Табличное событие содержит table_id, revision и action. Календарное событие — календарь, запись, время и при наличии получателя identity_id. Отключённые календари не запускают процессы. ICS-импорт/подписки остаются в «Календари и триггеры». Напоминания за N минут по-прежнему настраиваются там; новый граф можно вызвать из внешнего API или своим custom-событием. Полноценная автоматизация групповых сообщений общего назначения пока не реализована.

Расписание: интервал от минуты, ежедневно HH:MM с IANA timezone или выбранные дни недели (0 — понедельник). Пропущенные за время простоя интервалы объединяются в один запуск; сотни пропущенных задач не догоняются. Отключение процесса останавливает новые запуски, уже начатые продолжаются. Пауза всего проекта приостанавливает обработку его очередей и процессов. Сроки при этом идут по календарному времени.

Пример цепочки: сообщение боту → фильтр команды → HTTP к вашей CRM → согласование сотрудником → ожидание custom.order.completed с order_id → запись строки → ответ тому же клиенту. Если нужно продолжать через другой привязанный канал, выбирайте разрешённый identity_id явно: сама автоматизация не подменяет получателя на последний канал. Служебный бот может отличаться от клиентского, а сотрудник также может согласовать заявку в веб-панели.

API процессов и SDK

В «Операции и API» создайте серверный ключ с workflows:run, workflows:read и/или events:write. Среду задаёт определение процесса, клиент не меняет её в вызове запуска. Доступ ключа ограничен проектом, но не отдельным процессом: workflows:run позволяет выполнять любой включённый процесс этого проекта, в том числе live. Храните такой ключ только на доверенном сервере. Для ограничения одной операцией используйте отдельные ключи конструктора API.

POST /api/v1/projects/PROJECT/workflows/WORKFLOW/run
Authorization: Bearer SERVICE_KEY
Idempotency-Key: request-2026-0001
Content-Type: application/json

{"input":{"order_id":"ORDER-1","name":"Анна"},"identity_id":null}

Ответ содержит id. GET /api/v1/projects/PROJECT/workflow-runs/RUN возвращает статус, контекст, журнал шагов и дочерние запуски. Повтор запуска с тем же ключом и данными возвращает прежний ID; с изменёнными данными отклоняется. Это идемпотентность принятия запуска, а не гарантия exactly-once внешней CRM.

POST /api/v1/projects/PROJECT/automation-events
Authorization: Bearer SERVICE_KEY
Content-Type: application/json

{"event_id":"order-0001-completed","source":"custom.order.completed","environment":"sandbox","data":{"order_id":"ORDER-1"}}

Повтор того же event_id и тела возвращает прежний результат, изменённое тело — 409. Данные ограничены 32 КБ. Дополнительный identity_id должен принадлежать проекту и среде. Создание/редактирование/публикация процесса выполняются через защищённые сессией и CSRF методы панели /api/omni/projects/PROJECT/workflows. GET /api/support/approvals и POST /api/support/approvals/ID с {decision:"approved",note:"..."} используют аккаунт сотрудника; сервисный ключ не заменяет согласующего.

SDK Python: start_workflow(id, inputs, idempotency_key=...), workflow_run(id), automation_event(source, data, event_id=..., environment="sandbox"). SDK JavaScript: startWorkflow(id,input,{idempotencyKey}), workflowRun(id), automationEvent(source,data,{eventId,environment}). Все URL и схемы доступны в актуальном OpenAPI; ключи не помещайте в код виджета.

Сохранение, ошибки и рабочие границы

Каждый запуск сохраняет версию графа и подпроцессов, текущий блок, переменные, ожидание, дочерние задачи и журнал в SQLite. Перезапуск worker продолжает ожидание. Изменение черновика или новая публикация не изменяют текущий запуск. Локальный шаг и его эффекты коммитятся вместе; ошибка откатывает именно этот шаг. Операция интеграции снимается в задание при достижении блока, поэтому изменение или отключение подключения/операции до этого момента может изменить дальнейшее выполнение. Версионирование графа не замораживает внешние системы и учётные данные.

Неопределённый результат записи в CRM/Sheets/HTTP имеет статус uncertain. Процесс удерживается на интеграции. Сверьте внешнюю систему и разберите задание в журнале интеграций; автоматического слепого повтора записи нет. При явном повторе вызывающая сторона должна учитывать возможность дубля. Ошибка с on_error ведёт в указанную ветку, без него процесс завершается failed. Отклонённый триггер из-за квоты записывается в аудит workflow.trigger_rejected; автоматического повторного запуска события нет.

Отмена останавливает дальнейшие шаги, ожидающие согласования, дочерние процессы и ещё не начатые задания интеграций. Она не отзывает отправленные сообщения, выполненные записи или сетевой запрос, уже находящийся в исполнении. Восстановление резервной копии выключает новые запуски и отменяет незавершённые процессы, чтобы старые события не исполнились неожиданно.

Лимиты пилота: 50 определений на проект, 80 блоков на граф, 60 новых запусков и 1000 локальных шагов на проект в минуту, 1000 незавершённых запусков на проект, 250 шагов на запуск, 4 уровня вложенности и 120 дочерних запусков на корень. foreach — до 50 элементов и до 4 активных веток; parallel — до 8. Вход 32 КБ, сохраняемый контекст 160 КБ. Превышение лимита действия является ошибкой, используйте on_error и разумное дробление данных. Обратные переходы запрещены; ограниченный foreach заменяет бесконечный цикл.

Это движок пилота одного хоста. Отказоустойчивость нескольких узлов, распределённая очередь, нагрузочный SLA, многоступенчатое согласование кворумом, BPMN, произвольный Python/JS, визуальный отладчик с пошаговым исполнением и полный паритет n8n не реализованы. Массовый запуск требует отдельной нагрузочной и эксплуатационной проверки. ИИ в этих процессах не используется.

Готовые CRM и кастомные системы

Битрикс24: создайте входящий webhook в кабинете разработчика, разрешите CRM и при необходимости задачи. В «Интеграции → Битрикс24» сохраните полный HTTPS webhook. URL со встроенным секретом шифруется; в списке показывается только хост. Поддерживаются облачные домены bitrix24.ru/by/com/eu/kz. Для коробочного Битрикс24, другого домена или внутренней сети используйте HTTP/локальный агент.

Битрикс24: создать лид/контакт/сделку, обновить лид/сделку/ответственного/стадию, поставить задачу, добавить комментарий, найти контакт, получить поля лида/сделки, воронки, стадии и пользователей. В форме операции выберите действие, заполните стандартные поля или дополнительные UF_CRM_* поля JSON. В PHONE/EMAIL нужен массив объектов API, например [{"VALUE":"{{input.phone}}","VALUE_TYPE":"WORK"}]. ID воронок и стадий берите из справочников своего аккаунта.

amoCRM / Kommo: адрес аккаунта и долгосрочный токен приватной интеграции. Создать контакт/сделку, обновить сделку и её стадию/ответственного, создать задачу, добавить примечание, искать контакты, читать воронки и поля. В amoCRM объект leads — это сделки, отдельную сущность лида Битрикс24 не переносим автоматически. custom_fields_values и _embedded передаются как JSON по контракту API. Для задач задавайте entity_id, entity_type и complete_till (Unix seconds), а не произвольное название клиента.

Пример операции Битрикс24:

{"action":"lead.create","fields":{"TITLE":"Заявка {{input.request_id}}","NAME":"{{input.name}}","PHONE":[{"VALUE":"{{input.phone}}","VALUE_TYPE":"WORK"}]},"result_map":{"crm_id":"result"},"mock":{"result":101}}

Вход блока процесса: {"name":"{{input.name}}","phone":"{{input.phone}}","request_id":"{{input.request_id}}"}. Если result_key=crm, полный ответ доступен как {{vars.crm.result}}, а result_map сохраняет crm_id отдельно в {{vars.crm_id}}. Для amoCRM ID новой сделки извлекается путём _embedded.leads.0.id. Справочники — обычные операции чтения; автоматического выбора ваших воронок и OAuth-авторизации в один клик нет. Срок действия токена отслеживает администратор; для ротации создайте новое подключение/операцию, обновите граф и отключите старое.

Кастомная CRM: сохранённый HTTPS-запрос с JSON body/query, Bearer/Basic/headers, result_map и mock. Внутренняя система/1С/БД: локальный агент с заранее разрешёнными действиями и фиксированными SQL/HTTP-контрактами. Обратное изменение заказа передавайте как custom.order.updated в API автоматизаций. Поля, типы, права и стадийность конкретной CRM настраиваются владельцем; произвольной автоматической синхронизации схем нет.

Официальные контракты: https://apidocs.bitrix24.ru/api-reference/crm/leads/crm-lead-add.html и https://www.amocrm.ru/developers/content/crm_platform/leads-api . Долгосрочные токены: https://www.amocrm.ru/developers/content/oauth/step-by-step . Адаптеры проверены моделированием транспорта; перед live используйте тестовую воронку вашего аккаунта.

Объединение аккаунтов: код и номер

В меню проекта → «Клиенты и команда» → «Профили и привязки» находятся общие карточки, каналы клиента, замаскированные номера и последние 50 запросов. Поиск: имя клиента, полный ID профиля или внешний ID аккаунта. Карточки выводятся по 30 на страницу.

Каждый канал сначала создаёт отдельный профиль. Имя, ник и просто введённый телефон не дают доступ к другому профилю. Во всех способах требуется подтверждение в исходном чате. Сохраняются состояние и ожидающий шаг исходного профиля; доступ и история объединяются. При незавершённой интеграции сначала дождитесь её результата либо отмените ожидание. Аккаунты сотрудников, заблокированные профили, разные проекты и разные среды не объединяются.

Способ 1 — код. В исходном чате отправьте /link, перенесите полученную команду во второй канал, затем вернитесь в исходный чат и нажмите «Да, это мой аккаунт» или отправьте /confirm с полученным кодом. Для отказа — «Отклонить» или /cancel. Срок кода и запроса — 10 минут, повторное использование завершённого запроса запрещено.

Способ 2 — собственный контакт. Отправьте /phone в Telegram и нажмите «Поделиться номером». Поддерживается личный чат: user_id контакта должен совпадать с отправителем. Пересланный, чужой контакт или контакт без user_id не принимается как доказательство. Запрос действует 10 минут. В VK для запроса собственного номера подключите Mini App по следующей инструкции.

Во втором канале можно также передать подтверждённый контакт либо отправить /phone +НОМЕР. Текстовый номер используется только для поиска и сам не получает отметку подтверждения. Ответ не раскрывает, существует ли подходящий профиль. Если он найден, запрос приходит в исходный аккаунт; до подтверждения права не меняются. Если номер соответствует нескольким разным исходным профилям, используйте код: система не выбирает один из них автоматически.

Команда /account показывает состояние и кнопки выбора способа. /unphone удаляет номер текущего аккаунта из индекса связывания и отменяет незавершённые запросы. /cancel отменяет запросы с обеих сторон и ожидание ответа сценария. Уже объединённые каналы сохраняются: разделение выполняется владельцем через «Отвязать канал». Отвязанный канал получает пустой профиль без общего доступа; общая история остаётся в исходном профиле.

В тестовых карточках есть «Тест номера»: одинаковый вымышленный номер у двух аккаунтов создаёт запрос, который подтверждается в исходном чате симулятора. Этот метод не принимает рабочие аккаунты. Все ответы остаются тестовыми.

Настройка запроса номера в VK Mini App

VK запрашивает номер методом VKWebAppGetPhoneNumber внутри Mini App. Обычная клавиатура сообщений сообщества и кнопка request_contact Telegram имеют разные возможности.

1. Поднимите BotDock на публичном HTTPS-домене. Создайте Mini App в кабинете разработчика VK. Укажите https://ВАШ-ДОМЕН/connect/vk как адрес приложения для нужных платформ.

2. Создайте рабочий канал сообщества VK в BotDock. Затем откройте «Профили и привязки» → «Запрос номера в VK» → «Настроить». Введите ID Mini App и его защищённый ключ. Это ключ приложения, а не токен сообщества. Ключ шифруется, в ответе API и в браузерном JavaScript он отсутствует. Пустой ключ при редактировании сохраняет прежний, если ID приложения не изменился.

3. Напишите /phone своему боту VK. Ссылка ведёт в ваше приложение VK и содержит одноразовый запрос на 10 минут. Разрешите передачу номера внутри VK; для объединения подтвердите запрос в исходном канале. Запрос номера добровольный: доступна альтернатива /link.

Сервер сверяет ID приложения, ID пользователя, свежесть vk_ts (до 10 минут), подпись параметров запуска HMAC-SHA256 и SHA256-подпись phone_number. Дубликаты параметров запуска отклоняются. Одноразовый запрос связан с конкретным каналом и аккаунтом; приложение требует is_verified=true в ответе VK Bridge. Проверка подписей не заменяет отдельное подтверждение объединения в исходном чате.

Встроен официальный VK Bridge 3.0.2 под MIT, с проверкой SHA-512 пакета при включении в поставку. Он загружается локально; CDN во время работы не нужен. Только страница /connect/vk допускает встраивание во фреймы доменов VK. Кабинет сохраняет запрет встраивания.

Контракты и проверки подписей покрыты автоматическими тестами. Реальный запрос в вашем Mini App требует зарегистрированного приложения, разрешений VK, публичного HTTPS и проверки на целевых клиентах VK. Эти реквизиты не входят в локальную поставку. Если VK отклоняет запрос или не подтверждает номер, используйте код; система не принимает неподписанный ответ в качестве замены.

Первичные источники: https://github.com/VKCOM/vk-bridge и https://dev.vk.com/ru/bridge/VKWebAppGetPhoneNumber. Подпись номера описана в официальном архивном SDK: https://github.com/VKCOM/vk-mini-apps-api/blob/master/src/index.ts. Пример подписи запуска: https://github.com/VKCOM/vk-apps-launch-params/blob/master/examples/python3.py.

Проверка черновика без публикации

В конструкторе нажмите «Проверить». Откроется тестовый чат текущего черновика, включая ещё не сохранённые изменения. Публикация не нужна. Выберите канал отображения и отправьте сообщение. В правой части появятся шаги, выбранные ветки, изменения полей и моделируемые действия. Нажатие на название шага закрывает тест и открывает его настройки на доске.

Тест сохраняет переменные, ожидаемый ответ, изменения тестовых таблиц и использованные случайные строки только в памяти браузерной сессии. Таблицы и документы читаются из sandbox. Добавление и изменение строк моделируются; исходные таблицы, аналитика, обращения, платежи, профили, очереди и публикации не изменяются. Закрытие окна или «Начать заново» сбрасывает сессию. После передачи оператору начните новый тест.

Для интеграций используется mock из операции. Состояние получает mock и поля result_map, после чего выполняется следующий блок. Сервис, платёжка, CRM или локальный агент не вызываются. В «Тестовые данные и ошибки» можно указать начальные state/access, данные event и блок, в котором нужно смоделировать ошибку. Это позволяет проверить on_error. Нетипичные большие тестовые сессии ограничены размером запроса; уменьшите таблицу или выбранные поля.

Проверка схемы выявляет структурные ошибки, отсутствующие таблицы/документы/операции и выключенные подключения. Для пройденных шагов выводятся изменения переменных; длинные значения в журнале сокращаются. Данные события и моделируемая ошибка применяются к следующему сообщению, начальные state/access — только к новой сессии.

Это тест движка сценариев, а не эмуляция API мессенджера. С 0.11 специальные блоки аккаунтов моделируются здесь через отдельные кнопки исходов; подробности в разделе «Аккаунты на доске». Системные команды /link, /phone, /account, операторские команды, игры и связывание аккаунтов проверяйте в отдельном «Симуляторе» опубликованной версии. Ссылки и запрос контакта в тесте не открывают внешние сервисы. Реальное оформление и ограничения кнопок проверьте в целевом мессенджере.

Пример начального доступа:

{"premium":{"enabled":true}}

Пример начальных переменных:

{"city":"Минск","customer_name":"Анна","score":"0"}

Удобная настройка CRM

Битрикс24 и amoCRM: выберите действие в «Интеграции → Операции». Поля подписаны по-русски. Телефон и email Битрикс24 можно ввести одной строкой: форма соберёт нужный массив API. Несколько значений можно задать JSON-массивом. Значения могут быть обычным текстом, ID, JSON или шаблоном {{input.name}}. Дополнительные поля и настройка результата убраны в раскрывающиеся секции.

«Загрузить справочники из CRM» выполняет чтение справочников подключённого реального аккаунта. Воронки, ответственных и стадии можно выбирать рядом с полями ID. Стадия должна принадлежать выбранной воронке. У Битрикс24 загрузка стадий использует текущий CATEGORY_ID; после его изменения загрузите справочник повторно. Можно сохранить собственный ID или шаблон без загрузки справочников.

В карточке подключения есть «Проверить подключение / справочники»: воронки, стадии, сотрудники и пользовательские поля. Чтение постраничное; «Следующая страница» добавляет результаты. API разрешает только заранее перечисленные GET-операции. Секреты подключения не возвращаются. Успешное чтение одного справочника не доказывает права на все действия: проверьте создание и изменение нужной сущности отдельно на тестовых данных вашего аккаунта.

Проверка черновика использует пример ответа (mock) из операции. Его можно изменить в секции «Результат и тестовый ответ». Заданные примеры не являются результатом реального вызова CRM. Сервисы с нестандартным API по-прежнему подключаются через HTTP или разрешённые операции локального агента.

Готовность проекта к запуску

В группе меню «Бот» откройте «Готовность к запуску». Страница проверяет структуру и зависимости черновика, наличие публикации, зависимости рабочей версии, изменения черновика, состояние проекта, heartbeat обработчика, настройку публичного HTTPS, включённые рабочие каналы и ошибки очередей. Если в черновике есть передача оператору, показывается проверка состава команды.

Канал получает отметку двустороннего теста, когда зарегистрированы входящее событие и отправка через API. Это исторические признаки, а не постоянная проверка доступности. Зелёный HTTPS означает корректно заданную конфигурацию; доступность снаружи проверяется настоящим webhook. Страница не сертифицирует безопасность, отказоустойчивость, SLA и работу под большой нагрузкой.

Локальная поставка остаётся пилотом на одном сервере с SQLite. Для массового запуска нужны реальные проверки провайдеров, нагрузочные испытания, эксплуатационный мониторинг, организация поддержки и дальнейшее развитие архитектуры. Полный список — docs/LAUNCH.md.

Хранение контактов и API новых функций

Номер хранится зашифрованным Fernet, поиск использует HMAC-индекс с серверным ключом и пространством имён проекта/среды. На страницах кабинета номер маскируется. Контакт и команда поиска не попадают в обычное событие message.received; после успешной обработки номер удаляется из payload входящей очереди, сохраняя метаданные для защиты от дублей. Неуспешные входящие события требуют разбора и действующей политики очистки истории.

Подтверждение действует 90 дней; работающий worker удаляет истёкшие контакты и запросы при периодической очистке. /unphone и кнопка удаления номера очищают запись и индекс текущего аккаунта. Резервные копии живут по политике владельца сервера: удаление в рабочей базе не переписывает старые копии. Восстановление копии сбрасывает подтверждённые номера, одноразовые запросы, незавершённые привязки и выключает Mini Apps, чтобы не воскресить позднее отозванное доверие. Перед повторным включением проверьте ключ приложения.

Команды связывания и подтверждения не порождают обычное событие message.received. Обычные клиентские сообщения продолжают его создавать. Объединение и контакты отражаются в журнале без самого номера; начиная с 0.11 события подтверждения, удаления, объединения, отмены и истечения запроса также доступны автоматизациям.

Новые методы кабинета доступны владельцу проекта через сессию и X-CSRF-Token. Это не новые полномочия публичных серверных ключей:

GET    /api/omni/projects/PROJECT/identities?q=&offset=0
DELETE /api/omni/projects/PROJECT/identities/IDENTITY/phone
DELETE /api/omni/projects/PROJECT/identity-requests/REQUEST
PUT    /api/omni/projects/PROJECT/identities/vk/CHANNEL
POST   /api/omni/projects/PROJECT/identities/simulate-phone
POST   /api/omni/projects/PROJECT/flow/preview
GET    /api/omni/projects/PROJECT/readiness
POST   /api/omni/projects/PROJECT/integrations/connections/CONNECTION/metadata

POST /api/identity/vk/complete — специальный публичный endpoint Mini App, защищённый одноразовым запросом, привязкой к аккаунту и подписями VK. Он не принимает кабинетный ключ в качестве замены доказательств. Структуры запросов находятся в полном OpenAPI кабинета: /api/docs/openapi.json.

Кнопка запроса контакта в сообщении задаётся действием contact и keyboard=reply. В Telegram это request_contact, в остальных каналах — команда /phone с дальнейшим подходящим способом. Не смешивайте contact со ссылками/callback в одном сообщении Telegram. В визуальном редакторе выберите «Запросить свой номер» и объясните в тексте сообщения цель передачи контакта. Документация Telegram: https://core.telegram.org/bots/api#keyboardbutton.

Аккаунты на доске: запрос, ожидание и условия

В конструкторе бота нажмите «Добавить шаг» → «Аккаунты». Доступны три общих блока, не привязанных к конкретному шаблону:

- «Связать аккаунты / запросить номер» (`identity_request`) предлагает выбранный способ и сохраняет ожидание результата. Цель — объединение аккаунтов либо подтверждение собственного номера. Для объединения можно предложить код, номер или выбор пользователя. Для подтверждения номера способ автоматически становится «Запрос номера».

- «Ждать подтверждение аккаунта» (`identity_wait`) только ждёт результат: подходит после собственного сообщения с системной кнопкой. Если требуемое состояние уже достигнуто, блок сразу продолжает сценарий. Проверка собственного номера относится к аккаунту, который вошёл в этот блок, а не к любому телефону общего профиля.

- «Проверить аккаунты» (`identity_condition`) ведёт по ветке «Да/Нет»: номер текущего аккаунта подтверждён; в общем профиле есть действующий подтверждённый номер; связано больше одного аккаунта; в профиле есть выбранный канал; есть незавершённый запрос. Проверяются серверные данные, не переменные, переданные пользователем. Наличие канала в профиле не означает, что доставка в нём сейчас включена.

У запроса и ожидания четыре выхода: «Далее» — успех, «Отмена», «Срок истёк», «Ошибка». Назначьте разные продолжения при необходимости: сразу после вставки все ветки сохраняют прежнее продолжение. Интервал — 30–600 секунд. Результат сохраняется в выбранное поле (по умолчанию `identity_result`): `{{state.identity_result.status}}` равно `success`, `cancelled`, `timeout` либо `error`; также доступны `source` и `providers`. Номер телефона и секретные коды в переменные не попадают. Для проверки последнего исхода после продолжения используйте обычный блок «Условие» и поле результата.

Telegram подтверждает собственный контакт в личном чате. VK требует настроенный Mini App. При цели «Подтвердить номер» в неподдерживаемом канале выполняется ветка ошибки. При цели «Объединить аккаунты» остальные каналы могут использовать код или поиск ранее подтверждённого номера с согласием исходного аккаунта. Блок не обходит двустороннее подтверждение.

Пока бот ждёт подтверждение, обычный текст и внешнее API-событие не продолжают эту ветку. `/cancel` ведёт в ветку отмены; обращение к оператору прекращает сценарий и передаёт диалог поддержке. Ожидание, исход и версия сценария хранятся в базе. Изменение публикации не заменяет уже начатую версию. Своевременное подтверждение фиксируется вместе с доказательством и не теряется из-за очереди событий или перезапуска. Отзыв номера до продолжения отменяет ожидающий успех. Рабочий обработчик обязателен для продолжения и таймеров.

Таймер блока ограничивает ожидание сценария. Он не отзывает уже действующий номер и не запрещает пользователю позже выполнить самостоятельную привязку системной командой. У кодов и запросов собственный срок действия; поздний результат не переисполняет завершённую ветку. При паузе проекта продолжение откладывается до включения. Восстановление резервной копии сбрасывает ожидания аккаунта вместе с подтверждениями.

При объединении сохраняются состояние и активный диалог исходного профиля. Если он сам ждёт привязку, продолжится его ветка. Если он свободен, может продолжиться ожидание второго аккаунта, уже с состоянием исходного профиля. Если исходный профиль ждёт другой ответ, его диалог имеет приоритет: два независимых продолжения в одном общем профиле не запускаются. До административной отвязки канала завершите или отмените ожидание аккаунта.

Готовый пример: «Таблицы и документы» → «Готовые сценарии» → «Единый профиль · код и номер». Он создаёт отдельный проект. Цепочка: проверка существующей привязки → выбор способа → подтверждение → проверка наличия VK → ответ; отмена, срок и ошибка имеют отдельные ветки. Файл для импорта: `examples/account-linking.flow.json`.

В «Проверке черновика» доступны начальное состояние номера и привязки, дополнительный тестовый канал и кнопки четырёх исходов ожидания. Реальные аккаунты, контакты и запросы не создаются. Для проверки реального двустороннего обмена используйте опубликованный сценарий в песочнице и затем целевые мессенджеры.

События аккаунтов в автоматизациях

В запуске процесса, блоке «Ждать событие» и календарных правилах появились готовые события:

| Событие | Когда возникает |

| --- | --- |

| `identity.phone_verified` | Принят собственный контакт либо тестовое подтверждение песочницы |

| `identity.phone_removed` | Сохранённый номер явно удалён |

| `identity.linked` | Двусторонняя привязка завершена |

| `identity.link_cancelled` | Запрос привязки либо ожидание аккаунта отменено |

| `identity.link_expired` | Истёк сохранённый запрос объединения по коду/номеру; очистка выполняется обработчиком |

Истечение таймера блока обрабатывается его собственной веткой «Срок истёк». Истечение срока номера не считается ручным удалением. Песочница и рабочие события разделены. Пользовательское событие `custom.…` не может выдать подтверждение аккаунта.

В данных события есть `identity_id`, `profile_id`, `channel` и `name`. Для объединения также передаётся `target_identity_id` и `method`. Код, токен и номер отсутствуют. В «Ждать событие» выбор события аккаунта автоматически подставляет поле связи `identity_id` и значение `{{input.identity_id}}`; передайте ID клиента при запуске процесса. Для объединения/отмены такое ожидание сопоставляется с участниками запроса, поэтому может ожидать исходный или второй аккаунт. На объединение создаётся одно событие; отдельные дубликаты для каждого канала не создаются. Триггер процесса по умолчанию использует исходный аккаунт события.

Пример: подтверждён номер → сохранить отметку в CRM → уведомить сотрудников. Или: процесс клиента ждёт `identity.linked` → продолжает обработку его заявки. Общие процессы не заменяют текущий шаг бота и имеют собственные журналы.

Подключения и операции прямо из блока

В блоке «Вызвать API» бота и «Интеграция / CRM» процесса нажмите «Создать операцию». Выберите существующее подключение либо «Новое подключение». Затем задайте запрос и сохраните: созданная операция автоматически выбирается в текущем блоке. Доска не закрывается, несохранённые правки сохраняются в памяти.

Для Битрикс24/amoCRM доступны обычные формы действий и загрузка справочников. Универсальные HTTP, Google, 1С и локальные операции используют существующий редактор JSON-настроек. Этот мастер не исполняет операцию. «Создать на основе» создаёт копию выбранной операции и переключает только текущий блок; существующая операция и её пользователи не меняются. Для применения схемы по-прежнему нужны «Сохранить» и «Опубликовать».

Подключение и операция сохраняются отдельными действиями. Если закрыть окно после создания подключения, оно останется в «Интеграциях» и может быть использовано позже. Реальный запрос справочников CRM выполняется только по кнопке «Загрузить справочники из CRM». Неподдерживаемая настройка локального агента по-прежнему выполняется на его сервере.

Закрытый коммерческий пилот

Центр запуска в меню платформы показывает реальные технические проверки, ваши проекты, тариф и расход входящих событий. Зелёная проверка означает выполненную настройку или зафиксированное действие. Она не заменяет приёмку с реальными мессенджерами, платёжным магазином и внешней инфраструктурой.

Формат первого запуска — ограниченный пилот с сопровождением и ручным подтверждением оплаты. Открытая регистрация отключена. Тарифы задаёт администратор после согласования условий, автоматических списаний за платформу нет. Платежи клиентов внутри ботов — отдельный механизм ЮKassa.

Начните с одного законченного сценария: поддержка магазина, запись и CRM или доступ к клубу. До подключения реальных пользователей согласуйте ответственного, часы поддержки, границы сценария, лимиты нагрузки, цену и порядок завершения пилота. Число блоков и интеграций не является обещанием промышленной надёжности.

Установка на сервер и HTTPS

Все Python-зависимости образа зафиксированы в requirements.lock. В комплекте compose.production.yaml: API, обработчик и maintenance. Контейнеры работают без root, с ограничением памяти/CPU и ротацией логов. Данные и локальные резервные копии — в разных томах. Нужны Docker Compose, свободное место, домен с DNS на сервер и внешний доступ к 80/443. Публичный адрес этой установки: https://botdock.itunity.dev.

Для существующего Caddy используйте deploy/compose.shared-proxy.yaml и добавьте отдельный блок deploy/botdock.caddy в его конфигурацию. Сначала сохраните прежнюю конфигурацию и проверьте caddy validate. Если admin API включён, примените caddy reload. На текущем сервере Caddy 2.10.2 с admin off: SIGUSR1 не реализован, поэтому требуется короткий перезапуск только контейнера прокси после проверки конфигурации; веб-соединения могут прерваться. ИИ-контейнеры не перезапускаются. На сервере с другим reverse proxy используйте локальный upstream 127.0.0.1:8096 и сохраните HTTPS снаружи.

cp deploy/production.env.example .env
docker compose -f compose.production.yaml -f deploy/compose.shared-proxy.yaml config --quiet
docker compose -f compose.production.yaml -f deploy/compose.shared-proxy.yaml build
docker compose -f compose.production.yaml -f deploy/compose.shared-proxy.yaml up -d

При пустой базе создайте первого владельца локальной командой; публичная страница production не позволяет захватить первый аккаунт. Пароль запрашивается без отображения и не передаётся в аргументах процесса.

docker compose -f compose.production.yaml exec api python -m app.launch_admin create-owner --email owner@example.com --name Владелец

Не публикуйте /data, резервные копии, .env и deploy/secrets. Production откажется стартовать с HTTP, несовпадающим Origin, незащищённой cookie или открытой регистрацией. Экран входа и /health/live доступны снаружи; проекты требуют авторизации.

Приглашения и восстановление доступа

Команда invite выдаёт одноразовую ссылку на 24 часа для конкретного email. Администратор передаёт её клиенту по проверенному каналу. Ссылка сама ничего не отправляет. При принятии создаётся пилот на 30 дней: до 3 проектов, 5 рабочих каналов и 10 000 входящих событий в сутки UTC. Это стартовые технические ограничения; цена согласовывается отдельно.

docker compose -f compose.production.yaml exec api python -m app.launch_admin invite --email client@example.com

«Забыли пароль?» отправляет ссылку на 30 минут при настроенной SMTP-почте. HTTP-ответ одинаков для существующего и неизвестного адреса; ограничение частоты хранится в базе. Ссылка одноразовая, в базе хранится её хеш, письмо в очереди зашифровано. Новый запрос отменяет прежнюю ссылку. Смена пароля завершает все сеансы и отменяет оставшиеся ссылки восстановления. Восстановление базы также удаляет ссылки и почтовую очередь.

Если SMTP ещё не подключён, администратор после проверки личности может выдать ссылку вручную:

docker compose -f compose.production.yaml exec api python -m app.launch_admin recovery --email client@example.com

Настройте BOTDOCK_SMTP_HOST, PORT, TLS (starttls или ssl), USER и FROM в .env. Пароль храните в deploy/secrets/smtp-password, читаемом UID 10001; задайте BOTDOCK_SMTP_PASSWORD_FILE=/run/botdock-secrets/smtp-password. После изменения конфигурации пересоздайте api и maintenance. Письма отправляет maintenance; до фактической успешной отправки центр запуска не покажет почту проверенной. Восстановление следует протестировать настоящим письмом, включая попадание в спам.

Рекомендации для механизма восстановления: https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html.

Тарифы, срок и ограничения

Администратор назначает условия вручную после сверки оплаты. Команда не списывает деньги, не выпускает чек и не является подтверждением оплаты:

docker compose -f compose.production.yaml exec api python -m app.launch_admin plan --email client@example.com --name "Пилот поддержки" --projects 3 --channels 5 --daily-messages 10000 --days 30

Ограничения проверяются сервером в транзакции: новые проекты, новые рабочие каналы (включая виджеты), входящие live-события всех проектов аккаунта. Повтор одного event_id не расходует лимит. Тестовые сообщения не расходуют live-лимит. Сутки считаются по UTC; дневной лимит отдельного проекта действует дополнительно. Входящие события API и расписания, адресованные live-профилю, также учитываются. Ошибка лимита не подтверждает новое принятое событие: повтор провайдера может прийти позже.

Истёкший или suspended-тариф запрещает эти новые действия, но сохраняет вход в кабинет, чтение данных и тестирование. Уже принятые сообщения, процессы, операционные действия и ранее поставленные внешние задачи могут завершаться. Это не общий выключатель всех расходов интеграций: при завершении договора отдельно остановите проекты, расписания и процессы. Понижение тарифа не удаляет данные.

Существующие аккаунты сохраняют режим «Локальный пилот» до назначения условий администратором. Экран не показывает выдуманные цены, оплаченные счета или успешные списания.

Резервные копии и восстановление

Maintenance раз в сутки делает согласованную SQLite-копию вместе с ключом шифрования, проверяет integrity/foreign keys, контрольные суммы и расшифровку данных. Хранит 7 успешных копий. Ошибка новой копии не скрывается прежней успешной. Локальный том защищает от ошибок приложения, но не от потери сервера; обязательно храните копию на другой машине или в зашифрованном внешнем хранилище.

Просмотр имён копий и учебное восстановление (замените имя конкретной копией):

docker compose -f compose.production.yaml exec maintenance ls /backups
docker compose -f compose.production.yaml exec maintenance python -m app.maintenance drill --source /backups/ИМЯ_КОПИИ --record

Drill разворачивает копию в отдельном временном каталоге, проверяет базу и отключение прежних сеансов/доставки, затем удаляет только временную копию. Рабочую базу не меняет; при --record записывает результат в центр запуска. Требуется свободное место в /tmp по размеру базы; для больших копий увеличьте tmpfs maintenance или выполните на отдельной машине.

Для аварийного восстановления остановите api/worker/maintenance, сохраните повреждённую базу отдельно, используйте app.ops restore в новый каталог, затем замените том на восстановленный. Проекты остаются на паузе, внешние задания требуют сверки, ключи интеграторов/операторов и доказательства телефона отзываются. После проверки доставки возобновляйте проекты вручную. Никогда не копируйте работающий .sqlite3 без WAL: используйте app.ops backup.

Мониторинг и действия при сбое

Maintenance раз в минуту проверяет API/worker, задержку inbox, проблемы доставки/интеграций, свободное место, свежесть копий и ошибки почты. Состояние сохраняется для центра запуска. Чтобы получать уведомления, задайте BOTDOCK_ALERT_WEBHOOK_FILE=/run/botdock-secrets/alert-webhook с HTTPS endpoint, принимающим JSON. При изменении состояния отправляется событие degraded/recovered; продолжающийся сбой напоминается раз в час. В payload только коды проверок, время и имя сервиса, без пользователей, сообщений или токенов.

Монитор на той же машине не обнаружит отключение питания/интернета собственного хоста. Настройте внешний опрос https://botdock.itunity.dev/health/ready и уведомления ответственному. Внешний мониторинг и доставка уведомлений требуют отдельного подключения; отсутствие этих настроек видно в центре запуска.

При api_or_worker проверьте compose ps и логи контейнеров; при inbox_delay — время очереди и внешние интеграции; при disk_low — место и хранение копий; при delivery_review/integration_review — журнал и неопределённую доставку. Перед повторной записью во внешнюю систему сверьте результат, чтобы не создать дубль. Никогда не отправляйте токены/ссылки webhook в общий чат поддержки.

Приёмка первого клиента

1. Согласовать один сценарий, ответственного, режим сопровождения и лимиты пилота.

2. Принять приглашение, проверить пароль и восстановление настоящим письмом.

3. Подключить выделенные настоящие боты, получить и отправить сообщение во всех обещанных каналах.

4. Проверить условия, кнопки, документы и ошибки внешнего API на реальных реквизитах клиента.

5. Пройти передачу оператору, назначение, перевод и возврат к боту.

6. Проверить привязку двух аккаунтов: до подтверждения доступа нет, после — общие права и состояние; отмена/истечение/отзыв работают.

7. Если есть оплата — выполнить тестовую оплату, отказ и возврат в магазине клиента; сверить результат с провайдером.

8. Проверить перезапуск, повтор webhook, отказ провайдера, переполнение квоты и восстановление отдельной копии.

9. Подключить внешний монитор и копию вне сервера. Назначить процедуру обработки/удаления данных и согласовать договорные документы для выбранной деятельности.

10. Зафиксировать акт пилотной приёмки: дата, версии, каналы, результат каждой проверки, известные ограничения. Не обещать SLA или число одновременных пользователей без измерений.

Синтетическую проверку можно повторить командой python scripts/launch_load.py --messages 600. Она использует временную базу, четыре параллельных источника, дубликаты и повторное открытие движка перед обработкой. Это тест очереди и простого сценария без сети, а не измерение пропускной способности реальных мессенджеров.

Обновление и откат

Перед обновлением создайте проверенную копию данных и сохраните предыдущий образ/конфигурацию. Сначала прогоните миграцию и приёмку на восстановленной изолированной базе без внешних токенов доставки. Обновляйте только стек intrafica-botdock; не выполняйте docker compose down -v, docker system prune или перезапуск общих ИИ-сервисов.

После обновления проверьте /health/ready, вход, опубликованные сценарии, очередь, резервную копию и тестовое сообщение. При проблеме остановите новый стек; откат образа допустим только при совместимости схемы. Иначе восстановите предрелизную копию в новый том и сверяйте внешние действия за промежуток после копии. Доставка после восстановления не возобновляется автоматически.