РазделБоты

Боты

Что такое бот в Syncra, кто может его создать, как получить ключ и что бот умеет через API.

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

Что такое бот

  • Бот — настоящий участник. Он виден в списке участников и в каналах, пишет под своим именем и аватаром, рядом с именем стоит пометка BOT.
  • Бот принадлежит одному рабочему пространству. Поставить одного бота в несколько пространств нельзя: для каждого пространства создайте отдельного бота.
  • Бот видит сообщения и пишет только в тех каналах, куда вступил.
  • Программа управляет ботом по ключу. Ключ начинается с skb_ и передаётся в заголовке каждого запроса.

Остальные участники видят список ботов, но ключей и других секретов не видят. На вкладке «Боты» у них написано: «Управлять ботами могут только владелец и администраторы воркспейса.»

Как создать бота

  1. Откройте настройки рабочего пространства: значок шестерёнки «Настройки воркспейса» рядом с названием пространства в левой панели.
  2. Перейдите на вкладку «Боты». Её прямой адрес: https://ai-syncra.ru/w/<адрес-пространства>/settings/bots.
  3. Нажмите «Новый бот».
  4. Заполните «Имя». Поля «Описание (необязательно)», «Ссылка на аватар (необязательно)» и «Системный промпт (необязательно)» можно оставить пустыми.
  5. Нажмите «Создать бота». Сразу откроется страница нового бота.

Переключатель «Ответы ИИ» разрешает боту отвечать самому, силами ИИ Syncra: когда его упоминают через @ и когда ему пишут в личные сообщения. Если сообщения за бота пишет ваша программа через API, этот переключатель не нужен.

Что есть на странице бота

Раздел Для чего
«Профиль» Имя, описание, аватар, переключатель «Бот включён», кнопка «Удалить бота»
«API-токены» Ключи для API ботов
«Входящие вебхуки» Адрес, на который можно отправить текст одним запросом: входящие вебхуки
«Каналы» Каналы, в которых состоит бот
«Слеш-команды» Команды, которые участники вызывают в поле ввода: слеш-команды
«Исполнитель задач» Встроенный демо-агент. Вашей программе он не нужен
«Подписки на события» Запросы на ваш адрес, когда в пространстве что-то происходит: подписки на события

Как получить ключ

В интерфейсе ключ называется «API-токен».

  1. На странице бота найдите раздел «API-токены» и нажмите «Создать токен».
  2. В окне «Новый API-токен» заполните «Название токена». Назовите токен по сервису, который будет им пользоваться.
  3. Откроется окно «Токен создан» с ключом вида skb_.... Скопируйте его сразу: «Скопируйте его сейчас — больше он не покажется.»
  4. Нажмите «Готово».

Что важно знать о ключе:

  • Полный ключ показывается один раз. Потом в списке видны только его первые 12 символов. Потерянный ключ восстановить нельзя, выпустите новый.
  • Ключ привязан к одному боту и одному рабочему пространству. Запрос с ним видит только это пространство.
  • У бота может быть несколько ключей, например по одному на каждый ваш сервис.
  • Кнопка «Отозвать» в строке ключа выключает его сразу. Запросы с отозванным ключом получают ответ 401. Отменить отзыв нельзя.
  • Срока действия у ключа нет. Он работает, пока его не отозвали и пока бот включён.

Храните ключ как пароль: в секретах сервиса, а не в коде и не в репозитории.

Как добавить бота в канал

В разделе «Каналы» выберите канал в поле «Добавить в канал» и нажмите «Добавить». После этого бот читает канал и может в него писать.

В открытый канал бот может вступить сам, запросом POST /channels/:channelId/join. В закрытый канал бота добавляет человек в разделе «Каналы» на странице бота.

Проверьте ключ

Запрос GET /me возвращает бота, которому принадлежит ключ.

curl "https://ai-syncra.ru/api/bot/v1/me" \
  -H "Authorization: Bearer skb_..."

Ответ 200:

{
  "botId": "5f0c2a7e9b1d4c3a8e6f1a2b3c4d5e6f",
  "userId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Deploy bot",
  "workspaceId": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "workspaceSlug": "acme"
}

Если пришёл ответ 401 с телом {"error":"Unauthorized"}, ключ скопирован не целиком, отозван или бот выключен.

Что бот умеет через API

Что Где описано
Узнать список каналов и вступить в открытый канал Сообщения и каналы
Написать сообщение, ответить в ветке, изменить или удалить своё сообщение Сообщения и каналы
Прочитать историю канала, в котором он состоит Сообщения и каналы
Открыть личный чат с участником и написать в него Сообщения и каналы
Приложить файл к сообщению Сообщения и каналы
Прочитать задачи и проекты, оставить комментарий, сменить исполнителя, срок, приоритет и статус, завершить задачу Задачи и проекты

Чего в API ботов нет: создания задач и страниц базы знаний, реакций, закрепления сообщений, поиска, списка участников, созвонов и скачивания файлов. Полный список ограничений собран на странице «Что есть и чего нет».

Как выключить или удалить бота

  • Переключатель «Бот включён» в разделе «Профиль» останавливает бота и сохраняет его настройки. Выключенный бот не отвечает, не отправляет события, а запросы с его ключами получают 401.
  • Кнопка «Удалить бота» убирает бота вместе с ключами, вебхуками, подписками и командами. Сообщения, которые он отправил, остаются.

Что дальше