Bot dan mesej interaktif

Akaun bot ialah pengguna yang dibuat untuk program. Ia mempunyai nama, gambar dan token sendiri, serta tag BOT di sebelah namanya. Halaman ini juga merangkumi bahagian interaktif mesej: butang, menu dan dialog, yang boleh digunakan oleh sebarang integrasi.

Mengapa akaun bot

• Mesejnya datang daripada identiti yang jelas, dengan tag BOT, bukannya daripada akaun rakan sekerja.
• Token bot terus berfungsi apabila orang yang menetapkannya menukar peranan atau keluar (kecuali pelayan melumpuhkan bot pemilik yang dinyahaktifkan, lihat di bawah).
• Bot tidak boleh log masuk dengan kata laluan, dan tidak pernah melihat aplikasi web.

Aplikasi mencipta bot mereka sendiri, seperti bot Senarai tugasan atau Buku Taktik, melalui API plugin (EnsureBotUser).

Aktifkan akaun bot

Pentadbir sistem mengaktifkan Aktifkan Penciptaan Akaun Bot dalam Konsol Sistem › Integrasi › Akaun bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Ia dimatikan secara lalai. Hanya pentadbir sistem boleh mencipta bot, melainkan mereka memberikan hak ini kepada peranan lain dalam tetapan kebenaran.

Pada halaman yang sama, Lumpuhkan akaun bot apabila pemilik dilumpuhkan (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, diaktifkan secara lalai) mematikan bot apabila akaun pemiliknya dilumpuhkan.

Cipta bot

1. Buka avatar anda di bahagian kanan atas, kemudian Integrasi › Akaun bot, kemudian Tambah Akaun Bot.
2. Masukkan Nama Pengguna (huruf kecil, nombor, titik, sengkang dan garisan bawah), dan secara pilihan, Ikon Bot, Nama Paparan dan Penerangan.
3. Pilih Peranan: Ahli, atau Pentadbir Sistem untuk bot yang mengurus pelayan. Berikan bot hanya apa yang diperlukan.
4. Tanda post:channels untuk membolehkannya hantar dalam setiap Saluran Awam, atau post:all untuk setiap saluran, termasuk Saluran Peribadi dan Mesej Terus, tanpa perlu menjadi ahli.
5. Tetapkan bila token lalainya tamat tempoh, kemudian pilih Cipta Akaun Bot.
6. Salin token akses yang dipaparkan. Ia tidak dipaparkan lagi.

Kemudian, Cipta Token Baharu pada baris bot menambah token, dan setiap token boleh dilumpuhkan atau dipadam. Token bot berfungsi walaupun token akses peribadi dimatikan untuk pengguna.

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 arahan, log masuk sebagai pentadbir (bukan dalam mod tempatan): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Titik akhir lain: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable dan /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} untuk mengubah pemiliknya.

Tambah bot ke komuniti dan saluran

Bot baharu tidak berada dalam mana-mana komuniti. Tambahnya seperti orang biasa, daripada pengurusan ahli komuniti atau melalui 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 boleh memuat naik tanpa menjadi ahli, tetapi ia hanya menerima peristiwa WebSocket untuk saluran yang diikutinya.

Muat naik sebagai bot

Gunakan token bot dengan mana-mana panggilan API; POST /api/v4/posts adalah yang paling biasa (lihat Sumber utama). Untuk menulis terus kepada seseorang, buka saluran Mesej Terus 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 bertindak balas terhadap apa yang orang katakan, ikuti WebSocket dengan token bot dan jawab peristiwa posted yang anda pedulikan. Abaikan mesej bot sendiri untuk mengelakkan gelung.

Mesej yang hanya boleh dilihat oleh satu orang (mesej sementara) dihantar dengan POST /api/v4/posts/ephemeral dan {"user_id", "post": {"channel_id", "message"}}. Ia memerlukan kebenaran create_post_ephemeral, yang hanya ada pada pentadbir sistem secara lalai. Integrasi biasanya menghantar mesej sementara sebagai jawapan kepada arahan garis miring dan butang.

Mesej interaktif: butang dan menu

Mana-mana mesej dengan lampiran boleh membawa tindakan: butang, dan menu untuk dipilih. Ia berfungsi dalam mesej yang dimuat naik melalui API, webhook dan jawapan arahan garis miring. Apabila 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, nombor, sengkang dan garisan bawah, berbeza untuk setiap tindakan mesej. Ia dijana apabila anda tidak memasukkannya.
• style (butang): default, primary, success, good, warning, danger, atau warna heks.
• options (menu), atau data_source: users atau channels untuk memilih orang atau saluran. default_option pramilih satu nilai.
• integration.url: ke mana klik dihantar. Aplikasi (plugin) boleh menggunakan laluan miliknya sendiri, seperti /plugins/com.example.deploy/actions. integration.context adalah milik anda: ia dikembalikan bersama klik, dan klien tidak pernah melihatnya.

Permintaan yang diterima oleh 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 ialah select dan context.selected_option memegang nilai yang dipilih.

Jawapan anda

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

• update: menggantikan teks dan sifat mesej, contohnya untuk membutang butang sekali digunakan (kosong props).
• ephemeral_text: mesej yang hanya dilihat oleh orang yang mengklik.
• goto_location: URL untuk dibuka.
• Badan kosong tidak mengubah apa-apa.

Pelayan menunggu selama yang dibenarkan oleh Masa tamat permintaan integrasi (30 saat secara lalai). URL integrasi pada alamat rangkaian peribadi mesti dibenarkan oleh pentadbir sistem, seperti untuk webhook.

Dialog

Dialog ialah borang yang dibuka di atas sembang. Anda hanya boleh membukanya sebagai jawapan kepada sesuatu yang baru dilakukan oleh pengguna, arahan garis miring atau butang, kerana ia memerlukan trigger_id daripada permintaan tersebut. trigger_id sah selama tempoh masa tamat 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 mengambil display_name, name, help_text, placeholder, default dan optional.

Apabila pengguna menghantar, Antimatter 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 badan kosong untuk menutup dialog, atau biarkan ia terbuka dan tunjukkan apa yang salah:

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

{"error": "…"} memaparkan mesej untuk keseluruhan borang. Dengan notify_on_cancel, menutup dialog menghantar "cancelled": true. Dialog berfungsi dengan cara yang sama dalam aplikasi: OpenInteractiveDialog API plugin mengambil permintaan yang sama.