Боты
Что такое бот в Syncra, кто может его создать, как получить ключ и что бот умеет через API.
Бот — это участник рабочего пространства, за которого действует ваша программа. Он нужен, чтобы ваши сервисы сами писали команде о сборках, заказах и ошибках, отвечали на сообщения и работали с задачами. Создать бота и выпустить его ключ может владелец или администратор рабочего пространства: в настройках пространства, на вкладке «Боты».
Что такое бот
- Бот — настоящий участник. Он виден в списке участников и в каналах, пишет под своим именем и аватаром, рядом с именем стоит пометка
BOT. - Бот принадлежит одному рабочему пространству. Поставить одного бота в несколько пространств нельзя: для каждого пространства создайте отдельного бота.
- Бот видит сообщения и пишет только в тех каналах, куда вступил.
- Программа управляет ботом по ключу. Ключ начинается с
skb_и передаётся в заголовке каждого запроса.
Остальные участники видят список ботов, но ключей и других секретов не видят. На вкладке «Боты» у них написано: «Управлять ботами могут только владелец и администраторы воркспейса.»
Как создать бота
- Откройте настройки рабочего пространства: значок шестерёнки «Настройки воркспейса» рядом с названием пространства в левой панели.
- Перейдите на вкладку «Боты». Её прямой адрес:
https://ai-syncra.ru/w/<адрес-пространства>/settings/bots. - Нажмите «Новый бот».
- Заполните «Имя». Поля «Описание (необязательно)», «Ссылка на аватар (необязательно)» и «Системный промпт (необязательно)» можно оставить пустыми.
- Нажмите «Создать бота». Сразу откроется страница нового бота.
Переключатель «Ответы ИИ» разрешает боту отвечать самому, силами ИИ Syncra: когда его упоминают через @ и когда ему пишут в личные сообщения. Если сообщения за бота пишет ваша программа через API, этот переключатель не нужен.
Что есть на странице бота
| Раздел | Для чего |
|---|---|
| «Профиль» | Имя, описание, аватар, переключатель «Бот включён», кнопка «Удалить бота» |
| «API-токены» | Ключи для API ботов |
| «Входящие вебхуки» | Адрес, на который можно отправить текст одним запросом: входящие вебхуки |
| «Каналы» | Каналы, в которых состоит бот |
| «Слеш-команды» | Команды, которые участники вызывают в поле ввода: слеш-команды |
| «Исполнитель задач» | Встроенный демо-агент. Вашей программе он не нужен |
| «Подписки на события» | Запросы на ваш адрес, когда в пространстве что-то происходит: подписки на события |
Как получить ключ
В интерфейсе ключ называется «API-токен».
- На странице бота найдите раздел «API-токены» и нажмите «Создать токен».
- В окне «Новый API-токен» заполните «Название токена». Назовите токен по сервису, который будет им пользоваться.
- Откроется окно «Токен создан» с ключом вида
skb_.... Скопируйте его сразу: «Скопируйте его сейчас — больше он не покажется.» - Нажмите «Готово».
Что важно знать о ключе:
- Полный ключ показывается один раз. Потом в списке видны только его первые 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. - Кнопка «Удалить бота» убирает бота вместе с ключами, вебхуками, подписками и командами. Сообщения, которые он отправил, остаются.