Перейти к основному содержимому

Бот-аккаунты

Бот-аккаунт — это отдельная учётная запись для интеграции. Он работает с REST API по токену доступа и не привязан к конкретному сотруднику: если автор интеграции уйдёт из команды, интеграция продолжит работать.

Чем боты отличаются от обычных пользователей:

  • не могут войти в Loop через интерфейс — только работать через API;
  • не могут создавать других ботов;
  • не учитываются в количестве пользователей лицензии;
  • всегда отмечены меткой БОТ — в сообщениях, списках пользователей и в заголовке личной переписки.

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

Включение​

По умолчанию создавать ботов через интерфейс и REST API нельзя (плагины могут всегда). Системный администратор включает эту возможность в Системная консоль > Интеграции > Учетные записи ботов > Включить создание учетной записи бота.

Создавать ботов и управлять ими по умолчанию могут только системные администраторы.

Создание бота​

В интерфейсе​

  1. Откройте Главное меню > Интеграции > Учетные записи ботов и нажмите Добавить учетную запись бота.
  2. Укажите Имя пользователя: 3–22 символа, начинается со строчной буквы, может содержать строчные буквы, цифры, точки, дефисы и подчёркивания, не заканчивается точкой.
  3. (Необязательно) Загрузите Значок бота, задайте Отображаемое имя и Описание.
  4. Выберите Роль: Участник (по умолчанию) или Администратор системы. Бот с ролью администратора получает все права системного администратора — назначайте её только при необходимости.
  5. (Необязательно) Включите дополнительные разрешения:
    • сообщения:всем — писать во все каналы, включая личные сообщения;
    • сообщения:каналы — писать во все публичные каналы.
  6. Нажмите Создать аккаунт бота и скопируйте токен доступа. После закрытия экрана посмотреть токен снова нельзя, но можно выпустить новый — кнопкой Создать новый токен в списке ботов.
  7. Добавьте бота в нужные команды и каналы так же, как обычного пользователя.

Через REST API​

Создайте бота методом POST /api/v4/bots, затем выпустите ему токен методом POST /api/v4/users/{user_id}/tokens. Нужно разрешение на создание ботов.

Через mmctl​

Существующего пользователя можно превратить в бота:

mmctl user convert ivan@example.ru --bot

Вместо email можно указать имя пользователя или ID. У пользователей, входивших по email и паролю, данные для входа удаляются. У пользователей из AD/LDAP и SAML они сохраняются, чтобы не нарушить синхронизацию.

Из плагина​

Плагины создают ботов вспомогательной функцией EnsureBot. Владельцем такого бота считается плагин.

Работа через API​

Передавайте токен бота в заголовке Authorization:

curl -i -H 'Authorization: Bearer <токен-бота>' https://your-loop-server.ru/api/v4/users/me

Опубликовать сообщение от имени бота:

curl -i -X POST -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <токен-бота>' \
  -d '{"channel_id": "<id-канала>", "message": "Сообщение от бота"}' \
  https://your-loop-server.ru/api/v4/posts

Бот должен быть участником канала (или иметь разрешение сообщения:каналы / сообщения:всем).

Частые вопросы​

Нужно ли переводить существующие интеграции на ботов?​

Интеграции через REST API и плагины — желательно: создайте бота или преобразуйте существующую учётную запись и используйте его токен. Вебхуки и slash-команды всегда создаются от имени пользователя, перевести их на бота нельзя.

Что будет, если плагин хочет создать бота с именем существующего пользователя?​

Допустим, плагин GitHub использует бота github, а на сервере уже есть обычный пользователь github. Тогда плагин будет публиковать сообщения от этого пользователя без метки БОТ, а в журнал сервера попадёт ошибка. Чтобы исправить, либо преобразуйте пользователя в бота (mmctl user convert github --bot), либо переименуйте пользователя и перезапустите плагин — он создаст бота заново.

Истекает ли токен бота?​

Нет. Чтобы регулярно менять токен, автоматизируйте ротацию через REST API:

  1. Создайте новый токен.
  2. Обновите токен во всех сервисах.
  3. Отзовите старый токен.

Подробнее — в разделе Персональные токены доступа.

Может ли бот выдать себя за другого человека?​

Бот может иметь любое отображаемое имя и изображение, но метка БОТ показывается везде, где он появляется: в сообщениях, списках пользователей и заголовке личной переписки.

Что происходит с ботами, если их владелец деактивирован?​

По умолчанию боты деактивированного пользователя отключаются. Пользователи с правом управления ботами могут включить их снова в Главное меню > Интеграции > Учетные записи ботов. После этого рекомендуется выпустить новые токены.

Чтобы боты оставались включёнными, выключите Системная консоль > Интеграции > Учетные записи ботов > Отключить учетные записи ботов когда их владелец деактивирован (ServiceSettings.DisableBotsWhenOwnerIsDeactivated).

Может ли бот редактировать сообщения через API?​

Свои сообщения — да. Если редактирование не работает, проверьте, не запрещено ли оно для роли участника в схеме разрешений. Бот с ролью Администратор системы может редактировать любые сообщения.

Нужен ли боту email при синхронизации с AD/LDAP или SAML?​

Нет. Боты, созданные в Loop, не требуют адреса электронной почты и не зависят от синхронизации.