Ботове и интерактивни съобщения

Акаунтът на бот е потребител, създаден за програма. Той има собствено име, снимка и токени и показва етикет BOT до името си. Тази страница обхваща и AI агенти, които управлявате сами, както и интерактивните части на съобщенията: бутони, менюта и диалогови прозорци, които всяка интеграция може да използва.

Защо ботов акаунт

Съобщенията му идват от ясна идентичност, с етикет БОТ, а не от акаунта на колега.
Токените му продължават да действат, когато лицето, което го е настроило, смени роля или напусне (освен ако сървърът не деактивира ботовете на деактивирани собственици, вижте по-долу).
Ботовете не могат да влизат с парола и никога не виждат уеб приложението.

Приложенията създават свои собствени ботове, като например ботовете на Задачи или Наръчници, чрез API на плъгините (EnsureBotUser). AI агентите също са акаунти на ботове, от собствен вид, показани с етикет AGENT: вижте Агенти.

Активиране на ботови акаунти

Системен администратор активира Разреши създаването на бот акаунти в Системна конзола › Интеграции › Акаунти на ботове (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). По подразбиране е изключено. Само системни администратори могат да създават ботове, освен ако не предоставят това право на други роли в настройките за разрешения.

На същата страница Деактивирай бот профили, когато собственикът е деактивиран (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, активно по подразбиране) изключва бота, когато акаунтът на собственика му е деактивиран.

Създаване на бот

Отворете менюто на екипа, след това Настройки на екипа, кликнете върху Интеграции в края на неговите табове, след това върху Акаунти на ботове и Добавете бот профил.
Въведете Потребителско име (малки букви, цифри, точки, тирета и долни черти) и по желание Икона на бот, Показвано на име и Описание.
Изберете Роля: Член или Системен администратор за бот, който управлява сървъра. Давайте на бота само това, от което има нужда.
Отбележете публикувай:канали, за да може да публикува във всеки публичен канал, или публикувай:всички за всеки канал, включително частните и директните съобщения, без да е член.
Задайте кога изтича срокът на валидност на токена по подразбиране, след което изберете Създайте бот профил.
Копирайте показания токен за достъп. Той няма да се покаже отново.

По-късно, Създаване на нов токен в реда на бота добавя токен, и всеки токен може да бъде деактивиран или изтрит. Токените на ботовете работят, дори когато личните достъпни токени са изключени за хората.

Ботът може да носи атрибути на сървъра (тези, които са зададени в Системна конзола › Системни атрибути), зададени от формуляра за добавяне/редактиране на бот или от Редактиране на атрибути… в менюто ⋯ на бота. Те се задават от този, който управлява бота: неговият собственик (с разрешение за управление на ботове) или всеки, който има разрешение за управление на чужди ботове; атрибут, управляван от администратор, все още изисква системен администратор. Ботът на агент с изкуствен интелект няма собственик, затова само някой с разрешение за управление на чужди ботове или системен администратор може да зададе неговите атрибути.

Чрез API:

# create the bot (you become its owner)
curl -X POST https://chat.example.com/api/v4/bots \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"username": "deploy-bot", "display_name": "Deploy", "description": "Posts deployments"}'

# give it a token
curl -X POST https://chat.example.com/api/v4/users/$BOT_USER_ID/tokens \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"description": "deploy pipeline"}'

От командния ред, след като сте влезли като администратор (не в локален режим): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Други крайни точки: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable и /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} за смяна на собственика.

Добавете бота в общности и канали

Новият бот не е в нито една общност. Добавете го като обикновен член, чрез управлението на членовете на общността или чрез API:

curl -X POST https://chat.example.com/api/v4/teams/$TEAM_ID/members \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"team_id": "'$TEAM_ID'", "user_id": "'$BOT_USER_ID'"}'

curl -X POST https://chat.example.com/api/v4/channels/$CHANNEL_ID/members \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"user_id": "'$BOT_USER_ID'"}'

Бот с публикувай:канали или публикувай:всички може да публикува, без да е член, но получава WebSocket събития само за каналите, в които присъства.

Публикуване от името на бота

Използвайте токена на бота в всеки API извикване; POST /api/v4/posts е най-честото (вижте Основни ресурси). За да пишете директно на някого, първо отворете канала за директно съобщение:

# returns the channel; use its "id" as channel_id
curl -X POST https://chat.example.com/api/v4/channels/direct \
  -H "Authorization: Bearer $BOT_TOKEN" -H 'Content-Type: application/json' \
  -d '["'$BOT_USER_ID'", "'$USER_ID'"]'

За да реагирате на това, което хората казват, следвайте WebSocket с токена на бота и отговаряйте на събитията posted, които ви интересуват. Игнорирайте собствените съобщения на бота, за да избегнете цикли.

Съобщение, което може да види само един човек (ефемерно съобщение), се изпраща с POST /api/v4/posts/ephemeral и {"user_id", "post": {"channel_id", "message"}}. Изисква се разрешение create_post_ephemeral, което по подразбиране имат само системните администратори. Интеграциите обикновено изпращат ефемерни съобщения като отговор на команди с наклонена черта и бутони.

Агенти

Агентът е акаунт на бот от вида agent: потребителите имат "is_agent": true, ботовете имат "kind": "agent", а интерфейса показва етикет АГЕНТ вместо БОТ. Агентите се създават само от системни администратори (агенти за целия сървър) в Системна конзола › Изкуствен интелект › Връзки с модели и от администратори на общност (за тяхната общност) в раздела Изкуствен интелект на настройките на общността или чрез /api/v4/ai/agents (вижте API). Бот, създаден чрез POST /bots или от приложение, винаги е обикновен бот.

На вграден агент отговаря сървъра, чрез връзка с модел. Външен агент е ваш за управление: програма на друго място (например агент за кодиране в проект), която влиза като агент и отговаря както човек. Antimatter не отговаря вместо него.

Статусът на вграден агент се задава от сървъра: На линия, докато връзката с модела му отговаря; Отсъстващ, когато не отговаря (спаднал е, има изчакване за таймаут или отказан ключ); и Извън линия, когато е изключен или няма използема връзка или модел. Той се проверява при промяна на агента или неговата връзка, при тестване на връзка, при всяко извикване на модела на агента и на всеки 10 минути. Никой не може да зададе статуса на вграден агент: крайните точки PUT /users/{id}/status и за персонализиран статус връщат 403 (api.status.agent.app_error), дори за системни администратори, а UpdateUserStatus, SetUserStatusTimedDND, UpdateUserCustomStatus и RemoveUserCustomStatus от API на приставките отказват същото. Статусът на външен агент следва собствената му връзка и само неговият собствен токен може да го промени.

Управление на външен агент

Администраторът добавя агента в Системна конзола › Изкуствен интелект › Връзки с модели (или в раздела Изкуствен интелект на общност) с вид Външен агент и избира кой може да разговаря с него. Страницата след това показва как да го свържете.
Дайте му токен: системният администратор отваря Интеграции › Акаунти на ботове, намира акаунта на агента и избира Създаване на нов токен, или извиква API за токени с ID-то на потребителя на агента:
```
curl -X POST https://chat.example.com/api/v4/users/$AGENT_USER_ID/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"description": "agent"}'
```
Програмата извиква API и отваря WebSocket с Authorization: Bearer <token>, чете споменаванията и директните съобщения от събитията posted и отговаря с POST /posts, в нишката на съобщението.

Той показва на хората какво прави, като задава дейността си:

curl -X PUT https://chat.example.com/api/v4/ai/agents/$AGENT_USER_ID/activity \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"state": "working", "text": "Running the tests", "thread_post_id": "'$ROOT_ID'"}'

ID-то на агента в тези пътища е неговото потребителско ID. Пазете токена в тайна: всеки, който го има, може да публикува като агента.

Дейност

state: idle, thinking, working, waiting (за някого), blocked или offline. Заетите състояния (thinking, working, waiting, blocked) се връщат към idle след expires_in_seconds: по подразбиране 10 минути, максимум 24 часа.
text: кратко описание на задачата, един ред с най-много 200 знака. Интерфейсът го показва в списъка с членове и в профила на потребителя.
thread_post_id: идентификаторът на нишката, в която работи агента; програмата трябва да има право за четене на тази нишка. Той се предоставя само на тези, които имат право да я четат.

Кой може да види агента може да прочете неговата активност (GET /ai/agents/{agent_id}/activity или POST /ai/agents/activity/ids със списък с идентификатори) и получава събитието agent_activity_changed чрез WebSocket, без данните за нишката. Вградените агенти задават активността си самостоятелно.

Докато вграден агент пише отговора си, сървърът изпраща нарастващия текст в събития agent_post_stream към канала: post_id, channel_id, root_id, user_id, message (текста до момента) и control (start, text, end, error или cancel). Събитието post_edited доставя финалното съобщение. Клиентите, които игнорират потока, виждат отговора, когато той е запазен.

Интерактивни съобщения: бутони и менюта

Всяко съобщение с прикачени файлове може да съдържа действия: бутони и менюта за избор. Те работят в съобщения, публикувани чрез API, Webhook и отговори на команди с наклонена черта. Когато някой използва действие, Antimatter извиква URL-а на вашата интеграция.

{
  "channel_id": "…",
  "message": "Deploy **api 2.4.0** to production?",
  "props": {
    "attachments": [{
      "actions": [
        {
          "id": "approve",
          "type": "button",
          "name": "Approve",
          "style": "primary",
          "integration": {"url": "https://deploy.example.com/actions", "context": {"release": "2.4.0", "action": "approve"}}
        },
        {
          "id": "env",
          "type": "select",
          "name": "Pick an environment",
          "options": [{"text": "Staging", "value": "staging"}, {"text": "Production", "value": "production"}],
          "integration": {"url": "https://deploy.example.com/actions", "context": {"release": "2.4.0", "action": "env"}}
        }
      ]
    }]
  }
}

type: button или select.
id: букви, цифри, тирета и долни черти, различни за всяко действие в съобщението. Генерира се, ако го оставите празен.
style (за бутони): default, primary, success, good, warning, danger или шестнадесичен цвят.
options (за менюта) или data_source: users или channels за избор на човек или канал. default_option предварително избира стойност.
integration.url: адресът, към който се изпраща щракването. Приложението (плъгинът) може да използва собствен маршрут, например /plugins/com.example.deploy/actions. integration.context е ваш: връща се заедно с щракването и клиентите никога не го виждат.

Заявката, която интеграцията ви получава

{
  "user_id": "…",
  "user_name": "priya",
  "channel_id": "…",
  "channel_name": "releases",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "post_id": "…",
  "trigger_id": "…",
  "type": "button",
  "context": {"release": "2.4.0", "action": "approve"}
}

За меню type е select, а context.selected_option съдържа избраната стойност.

Вашият отговор

{
  "update": {"message": "Deploy of **api 2.4.0** approved by @priya", "props": {}},
  "ephemeral_text": "Done. The deploy starts in a minute."
}

update: замества текста и свойствата на съобщението, например за да премахне бутоните след използването им (празно props).
ephemeral_text: съобщение, което вижда само лицето, което е щракнало.
goto_location: URL за отваряне.
Празно тяло не променя нищо.

Сървърът изчака докато Време за изчакване на заявката за интегриране позволява (30 секунди по подразбиране). Адресите на интеграции в частни мрежи трябва да бъдат разрешени от системен администратор, както и за webhook-ове.

Диалози

Диалогът е формуляр, който се отваря върху чата. Може да се отвори само в отговор на нещо, което лицето току-що е направило — команда с наклонена черта или бутон, защото е необходим trigger_id на тази заявка. trigger_id е валиден за времето на Integration request timeout.

curl -X POST https://chat.example.com/api/v4/actions/dialogs/open \
  -H 'Content-Type: application/json' \
  -d '{
    "trigger_id": "'$TRIGGER_ID'",
    "url": "https://deploy.example.com/dialog",
    "dialog": {
      "callback_id": "new-release",
      "title": "New release",
      "introduction_text": "Fill in the release details.",
      "submit_label": "Create",
      "notify_on_cancel": false,
      "state": "anything you want back",
      "elements": [
        {"display_name": "Version", "name": "version", "type": "text", "placeholder": "2.4.0"},
        {"display_name": "Notes", "name": "notes", "type": "textarea", "optional": true},
        {"display_name": "Environment", "name": "env", "type": "select",
         "options": [{"text": "Staging", "value": "staging"}, {"text": "Production", "value": "production"}]},
        {"display_name": "Owner", "name": "owner", "type": "select", "data_source": "users"},
        {"display_name": "Notify the channel", "name": "notify", "type": "bool", "default": "true"}
      ]
    }
  }'

Тип на елемента	Какво показва
`text`	Едноредово поле. `subtype`: `text`, `email`, `number`, `password`, `tel` или `url`. `min_length` и `max_length` го ограничават.
`textarea`	Многоредово поле.
`select`	Списък: `options`, или `data_source` `users`, `channels`, или `dynamic` с `data_source_url`. `multiselect` позволява няколко стойности.
`bool`	Квадратче за отметка.
`radio`	Един избор сред `options`.
`date`, `datetime`	Дата или дата и час.
`action_button`	Бутон, който самостоятелно извиква `action_button_url`, отделно от изпращането на диалога. Неговият `help_text` се показва под него.
`collapsible`	Свиваема група от елементи. С `sub_type: "grid"`, неговите дочерни контейнери се подреждат като таблица, вместо да се натрупват: всеки един е ред, а собствените му елементи са клетките на този ред.

Всеки елемент приема display_name, name, help_text, placeholder, default и optional.

submit_buttons в диалога указва статичен елемент select: неговите опции стават бутоните за изпращане на диалога, по един за всяка опция, вместо един бутон Изпрати, като самият select не се показва. size ("small", "medium" или "large"; "small", ако е пропуснато) задава по-широк диалог. refresh_on_return (изисква source_url) повторно извлича диалога от source_url, когато диалог, отворен отгоре, се затвори, за да покаже промените. Неразпознат size или sub_type не пречи на отварянето на диалога: той се връща към стойността по подразбиране и сървърът само записва това в журнала.

Когато лицето изпрати, Antimatter изпраща POST към url на диалога:

{
  "type": "dialog_submission",
  "callback_id": "new-release",
  "state": "anything you want back",
  "user_id": "…",
  "channel_id": "…",
  "team_id": "…",
  "submission": {"version": "2.4.0", "notes": "", "env": "staging", "owner": "…", "notify": true},
  "cancelled": false
}

Отговорете с празно тяло, за да затворите диалога, или го оставете отворен и покажете какво е грешно:

{"errors": {"version": "This version already exists."}}

{"error": "…"} показва съобщение за цялата форма. С notify_on_cancel, затварянето на диалога изпраща "cancelled": true. Диалозите работят по същия начин в приложенията: OpenInteractiveDialog от API на плъгините приема същата заявка.