Боти та інтерактивні повідомлення

Акаунт бота — це користувач, створений для програми. Він має власну назву, фото та токени, а поруч із назвою відображається мітка BOT. На цій сторінці також описано інтерактивні елементи повідомлень: кнопки, меню та діалоги, які може використовувати будь-яка інтеграція.

Навіщо акаунт бота

Їхні повідомлення надходять від чітко визначеної особи з позначкою БОТ, а не від облікового запису колеги.
Його токени продовжують працювати, навіть якщо особа, яка його налаштувала, змінює роль або покидає робоче середовище (якщо на сервері не вимкнено ботів деактивованих власників, див. нижче).
Боти не можуть увійти за допомогою пароля та ніколи не бачать веб-додатку.

Додатки створюють власних ботів, наприклад ботів Todo або Playbooks, через API плагінів (EnsureBotUser).

Увімкніть акаунти ботів

Системний адміністратор увімкнути Увімкнути створення облікового запису бота у Системна консоль › Інтеграції › Акаунти ботів (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, який за замовчуванням мають лише системні адміністратори. Інтеграції зазвичай надсилають тимчасові повідомлення як відповіді на команди зі скісною рискою та кнопки.

Інтерактивні повідомлення: кнопки та меню

Будь-яке повідомлення з вкладеннями може містити дії: кнопки та меню для вибору. Вони працюють у повідомленнях, надісланих через API, вебхуки та відповіді на команди зі скісною рискою. Коли хтось використовує одну з них, 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 секунд). Адреси інтеграцій у приватних мережах мають бути дозволеними системним адміністратором, як і вебхуки.

Діалоги

Діалог — це форма, що відкривається поверх чату. Відкрити його можна лише у відповідь на щось, що щойно зробила людина: команду зі скісною рискою або кнопку, оскільки для цього потрібен trigger_id того запиту. trigger_id дійсний протягом часу, визначеного таймаутом запиту інтеграції.

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`	Дата, або дата й час.

Кожен елемент приймає display_name, name, help_text, placeholder, default та optional.

Коли людина надсилає форму, 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 плагіна приймає той самий запит.