Bot dan pesan interaktif

Akun bot adalah pengguna yang dibuat untuk sebuah program. Akun ini memiliki nama, gambar, dan token sendiri, serta menampilkan tag BOT di samping namanya. Halaman ini juga membahas bagian interaktif dari pesan: tombol, menu, dan dialog, yang dapat digunakan oleh integrasi apa pun.

Mengapa menggunakan akun bot

• Pesan dari akun bot berasal dari identitas yang jelas, dengan tag BOT, bukan dari akun rekan kerja.
• Token bot tetap berfungsi ketika orang yang mengaturnya mengubah peran atau keluar (kecuali server menonaktifkan bot milik pemilik yang dinonaktifkan, lihat di bawah).
• Bot tidak dapat masuk menggunakan kata sandi, dan tidak pernah melihat aplikasi web.

Aplikasi membuat bot-nya sendiri, seperti bot Todo atau Playbooks, melalui API plugin (EnsureBotUser).

Aktifkan akun bot

Admin sistem mengaktifkan Aktifkan Pembuatan Akun Bot di Konsol Sistem › Integrasi › Akun bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Pengaturan ini nonaktif secara bawaan. Hanya admin sistem yang dapat membuat bot, kecuali mereka memberikan hak tersebut ke peran lain di pengaturan izin.

Di halaman yang sama, Nonaktifkan akun bot saat pemilik dinonaktifkan (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, aktif secara bawaan) menonaktifkan bot saat akun pemiliknya dinonaktifkan.

Membuat bot

1. Buka avatar Anda di kanan atas, lalu Integrasi › Akun bot, lalu Tambahkan Akun Bot.
2. Masukkan Nama Pengguna (huruf kecil, angka, titik, tanda hubung, dan garis bawah), serta secara opsional Ikon Bot, Nama Tampilan, dan Deskripsi.
3. Pilih Peran: Anggota, atau Admin Sistem untuk bot yang mengelola server. Berikan bot izin seminimal mungkin.
4. Centang post:channels untuk mengizinkan bot memposting di setiap kanal publik, atau post:all untuk semua kanal, termasuk kanal privat dan pesan langsung, tanpa harus menjadi anggota.
5. Atur kapan token default-nya kedaluwarsa, lalu pilih Buat Akun Bot.
6. Salin token akses yang ditampilkan. Token ini tidak akan ditampilkan lagi.

Nanti, Buat Token Baru di baris bot akan menambahkan token, dan setiap token dapat dinonaktifkan atau dihapus. Token bot berfungsi bahkan ketika token akses pribadi dinonaktifkan untuk pengguna manusia.

Dengan 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"}'

Dari baris perintah, masuk sebagai admin (bukan dalam mode lokal): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Endpoint lainnya: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable dan /enable, serta POST /api/v4/bots/{bot_user_id}/assign/{user_id} untuk mengubah pemiliknya.

Tambahkan bot ke komunitas dan kanal

Bot baru tidak berada di komunitas mana pun. Tambahkan seperti orang biasa, melalui manajemen anggota komunitas atau dengan 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'"}'

Bot dengan post:channels atau post:all dapat memposting tanpa menjadi anggota, tetapi hanya menerima peristiwa WebSocket untuk kanal yang diikutinya.

Posting sebagai bot

Gunakan token bot untuk panggilan API apa pun; POST /api/v4/posts adalah yang paling umum (lihat Sumber utama). Untuk menulis langsung ke seseorang, buka kanal Pesan Langsung terlebih dahulu:

# 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'"]'

Untuk bereaksi terhadap apa yang dikatakan orang lain, ikuti WebSocket dengan token bot dan jawab peristiwa posted yang Anda pedulikan. Abaikan pesan bot itu sendiri untuk menghindari loop.

Pesan yang hanya dapat dilihat oleh satu orang (pesan sementara) dikirim dengan POST /api/v4/posts/ephemeral dan {"user_id", "post": {"channel_id", "message"}}. Hal ini memerlukan izin create_post_ephemeral, yang secara default hanya dimiliki oleh admin sistem. Integrasi biasanya mengirim pesan sementara sebagai jawaban untuk perintah garis miring dan tombol.

Pesan interaktif: tombol dan menu

Setiap pesan dengan lampiran dapat membawa aksi: tombol, dan menu untuk memilih. Mereka berfungsi dalam pesan yang diposting dengan API, webhook, dan jawaban perintah garis miring. Ketika seseorang menggunakannya, Antimatter memanggil URL integrasi Anda.

{
  "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 atau select.
• id: huruf, angka, tanda hubung, dan garis bawah, berbeda untuk setiap aksi pesan. Ini akan dibuat jika Anda mengosongkannya.
• style (tombol): default, primary, success, good, warning, danger, atau warna heksadesimal.
• options (menu), atau data_source: users atau channels untuk memilih orang atau kanal. default_option pramemilih nilai.
• integration.url: tempat klik dikirim. Aplikasi (plugin) dapat menggunakan rute miliknya sendiri, seperti /plugins/com.example.deploy/actions. integration.context adalah milik Anda: nilai ini dikembalikan bersama klik, dan klien tidak pernah melihatnya.

Permintaan yang diterima integrasi Anda

{
  "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"}
}

Untuk menu, type adalah select dan context.selected_option menyimpan nilai yang dipilih.

Jawaban Anda

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

• update: mengganti teks dan properti pesan, misalnya untuk menghapus tombol setelah digunakan (dengan props kosong).
• ephemeral_text: pesan yang hanya terlihat oleh orang yang mengklik.
• goto_location: URL untuk dibuka.
• Isi kosong tidak mengubah apa pun.

Server menunggu selama yang diizinkan oleh Timeout permintaan integrasi (30 detik secara bawaan). URL integrasi pada alamat jaringan privat harus diizinkan oleh admin sistem, seperti halnya webhook.

Dialog

Dialog adalah formulir yang terbuka di atas obrolan. Anda hanya dapat membukanya sebagai tanggapan terhadap sesuatu yang baru saja dilakukan orang tersebut, yaitu perintah garis miring atau tombol, karena dialog memerlukan trigger_id dari permintaan tersebut. trigger_id berlaku selama batas waktu permintaan integrasi.

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"}
      ]
    }
  }'

Setiap elemen menerima display_name, name, help_text, placeholder, default, dan optional.

Ketika orang tersebut mengirim, Antimatter melakukan POST ke url dialog:

{
  "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
}

Jawab dengan isi kosong untuk menutup dialog, atau biarkan terbuka dan tampilkan apa yang salah:

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

{"error": "…"} menampilkan pesan untuk seluruh formulir. Dengan notify_on_cancel, menutup dialog mengirim "cancelled": true. Dialog bekerja dengan cara yang sama di aplikasi: OpenInteractiveDialog dari API plugin menerima permintaan yang sama.