Боты и сценарии автоматизации

Актуально для: SimpleTwo 0.9.x · Проверено: 20.09.2026

Бот в SimpleTwo — не «интеграция сбоку», а участник разговора: у него есть учётная запись в каталоге, отображаемое имя, @-обращение и членство в беседах. Отсюда следует главное для администратора: на вопрос «кто может здесь писать» отвечает список участников, а чтобы забрать доступ, бота достаточно убрать из беседы.

1. Что такое бот

Свойство	Как устроено
Учётная запись	заводит координатор; видна в каталоге, пароля нет — интерактивный вход ботом отклоняется
Токен	выдаёт служба переписки; показывается один раз при создании или обновлении
Права	области доступа токена + членство в беседах, а не роль в консоли
@-обращение	задаёт администратор (человек меняет себе сам, бот — не может)
Знак организации	«системный» бот помечается как принадлежащий организации, чтобы его нельзя было подделать чужим ботом с похожим именем

У бота нет роли в админ-консоли, и это не упущение

Роль консоли читается только при интерактивном входе, а войти ботом нельзя. Раньше поле роли у бота было — оно сохранялось, показывалось в таблице и не проверялось нигде: человек видел «администратор» и думал, что что-то выдал. Поле убрано, попытка передать роль отклоняется с ошибкой, а управляет ботом то, что действительно проверяется: области доступа, список бесед и членство.

2. Области доступа

Область	Что разрешает
read	читать сообщения бесед, куда бот допущен
send	отправлять сообщения
react	ставить реакции
manage-conv	управлять составом беседы

Пустой набор — это полный доступ, наследие первых ботов. Выдавайте явный набор: бот, которому нужно только уведомлять, получает send и ничего больше.

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

3. Вебхуки: как бот узнаёт о событиях

Если у бота указан адрес вебхука, служба переписки отправляет туда события. Доставка подписывается, если задан секрет:

X-S2-Signature: t=<unix-время>,v1=<hex>

Подпись — HMAC-SHA256 по строке <t>.<тело запроса>. Время входит в подпись, поэтому получателю достаточно проверить свежесть (рекомендуемое окно — 5 минут), чтобы отсечь повтор, и не хранить состояние.

Проверяйте подпись, а не адрес источника

До появления подписи единственным доказательством происхождения было «пришло из нашей сети». Приёмник, который верит IP-адресу, поверит и всему, что попадёт в ту же сеть.

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

4. Жизненный цикл

• Создать — AI & automation → Bots: имя, отображаемое имя, @-обращение, области, беседы, адрес и секрет вебхука. Токен показывается один раз.
• Обновить токен — тем же действием; пустые поля сохраняют текущие значения.
• Выключить — переключатель «отключён». Бот остаётся на месте, но перестаёт аутентифицироваться: это то, что нужно при разборе инцидента.
• Удалить — убирает учётную запись и токен.

5. Сценарии автоматизации

Сценарий — это триггер → линейная цепочка шагов, с необязательным согласованием человеком. Намеренно маленький механизм: ветвлений нет и не будет, две аудитории — это два сценария.

Триггеры:

Вид	Срабатывает
mention	бота упомянули в беседе
keyword	в сообщении встретилось слово
schedule	по расписанию, раз в N минут
webhook	пришёл внешний вызов
появление, блокировка, удаление человека	изменения в каталоге

Триггер можно сузить условием по контексту: например, только для гостей или только для одного подразделения. Это не ветвление — это отбор запусков.

Шаги: отправить сообщение, вызвать вебхук, добавить участника, убрать участника. В тексте сообщения подставляются значения из контекста запуска ({{body}}, {{sender}}, {{conv}}, а для событий каталога — поля появившегося человека).

Согласование. Любой шаг можно закрыть воротами: user:<имя> или role:<роль>. Сценарий останавливается и ждёт, пока разрешённый человек не ответит реакцией — ✅ или 👍 разрешают, ❌ или 👎 отказывают. Возможность отказать обязательна: без неё очередь навсегда зависших запусков растёт молча.

Сценарий всегда говорит от имени бота

Указать бота обязательно. Раньше движок писал в беседы от имени, которому не соответствовала ни одна учётная запись: в списке участников такой «автор» не появлялся, и комната не могла показать, что в неё вообще кто-то пишет. Теперь автор — настоящий участник, и отозвать доступ можно, убрав его из беседы.

Запуски и аудит. В консоли есть журнал запусков (что сработало, на каком шаге стоит, чего ждёт) и кнопка запуска вручную — ею удобно проверять сценарий, не дожидаясь события. Действия агентов и ботов собираются в отдельный след аудита.

Шаг «написать в личный чат» (post_direct) отправляет сообщение от имени бота в его личный чат с человеком. Если чата ещё нет, шаг его создаёт. Так бот поддержки приветствует новых пользователей (см. ниже).

6. Первый день: приветствие и бот поддержки

Новичка встречают два сообщения. Оба собираются кнопками в консоли, и оба остаются обычными сценариями — тексты можно править в карточке сценариев.

Канал приветствия — Настройки → Welcome flow → Provision. Кнопка создаёт бота приветствия, канал «Welcome» и сценарий, который добавляет каждого нового человека в канал и пишет ему приветствие. Для гостей можно включить отдельный канал. Текст приветствия — ваш: подстановки {{mention}} (человек как упоминание), {{display_name}}, {{user}}. По умолчанию это одно приветствие от компании, без инструкций про ошибки — их рассказывает бот поддержки.

Если вы не меняли текст приветствия, при обновлении координатор сам заменит прежний текст по умолчанию (с абзацем про ошибки и пожелания) на новый. Отредактированный текст не меняется.

Канал заполняется только приглашениями: те, кто пришёл до включения, в нём отсутствуют. Кнопка Who is missing? считает их, Fill the room now добавляет.

Приветствие бота поддержки — Настройки → Кейс поддержки, блок «Приветствие бота новым пользователям». Бот поддержки пишет каждому новому человеку в личный чат: как сообщить об ошибке или пожелании прямо в этом чате, где в приложении пункт «Сообщить о проблеме» и ссылка simpletwo://report, которая открывает форму. Сотрудникам и гостям — разные тексты.

• Правила создаются при развёртывании кейса поддержки и кнопкой Save greeting — без повторного развёртывания, которое меняет токены. В карточке сценариев это support-greet и support-greet-guests.
• Основной кейс приветствует по умолчанию. Дополнительные кейсы — только если включить Greet new users: три бота, приветствующие одного новичка, — это три ответа на один вопрос.
• Выключенные правила остаются в карточке сценариев, но не срабатывают.
• Back to the default text возвращает текст по умолчанию. Если текст не меняли, новые версии текста по умолчанию приходят сами.
• Тем, кто пришёл раньше, приветствие отправляется только по кнопке. Who has not been greeted? считает людей без чата с ботом, Greet them now отправляет им приветствие. Тех, у кого чат с ботом уже есть, кнопка не трогает.

Через API: POST /admin/api/support/greeting (instance, enabled, greeting, guest_greeting, reset) и POST /admin/api/support/greeting/backfill (instance, dry_run).

Дальше

• ИИ-помощники и агенты — вторая сторона ботов: модели, бюджеты, делегирование
• Обзор API — аутентификация и формат ошибок
• Помощники и боты — то же глазами пользователя