Botlar ve etkileşimli iletiler

Bir bot hesabı, bir program için oluşturulmuş bir kullanıcıdır. Kendine ait bir adı, resmi ve token'ları vardır ve adının yanında bir BOT etiketi gösterilir. Bu sayfa, herhangi bir entegrasyonun kullanabileceği iletilerin etkileşimli kısımlarını da kapsar: düğmeler, menüler ve diyaloglar.

Neden bir bot hesabı

• İletileri, bir meslektaşın hesabından değil, BOT etiketiyle net bir kimlikten gelir.
• Token'ları, onu kuran kişi rol değiştirdiğinde veya ayrıldığında bile çalışmaya devam eder (sunucu, devre dışı bırakılan sahiplerin botlarını devre dışı bırakmıyorsa, aşağıda belirtildiği üzere).
• Botlar şifreyle giriş yapamaz ve asla web uygulamasını göremez.

Uygulamalar, Todo veya Playbooks botları gibi kendi botlarını eklenti API'si (EnsureBotUser) aracılığıyla oluşturur.

Bot hesaplarını etkinleştirin

Bir sistem yöneticisi, Sistem Konsolu › Bütünleştirmeler › Bot hesapları bölümünde Bot hesabı eklenebilsin seçeneğini etkinleştirir (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Bu seçenek varsayılan olarak kapalıdır. Bot oluşturabilme yetkisi, izin ayarlarında başka rollere verilmedikçe yalnızca sistem yöneticilerine aittir.

Aynı sayfada, Sahibi kullanımdan kaldırılan bot hesapları da kullanımdan kaldırılsın seçeneği (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, varsayılan olarak açık) botun sahibi kullanımdan kaldırıldığında botu devre dışı bırakır.

Bot oluşturun

1. Sağ üstteki profil resminize (avatar) tıklayın, ardından Bütünleştirmeler › Bot hesapları ve Bot hesabı ekle seçeneklerini seçin.
2. Bir Kullanıcı adı (küçük harfler, rakamlar, nokta, tire ve alt çizgi) girin; isteğe bağlı olarak bir Bot simgesi, Görüntülenecek ad ve Açıklama ekleyin.
3. Rol seçin: Üye veya sunucuyu yöneten bir bot için Sistem Yöneticisi. Bir bota yalnızca ihtiyacı olan en az yetkiyi verin.
4. Botun her herkese açık kanala iletebilmesi için ileti:kanallar seçeneğini işaretleyin; üye olmadan her kanala, özel kanallara ve doğrudan iletilere iletebilmesi için ise ileti:tümü seçeneğini kullanın.
5. Varsayılan token'ının ne zaman sona ereceğini ayarlayın, ardından Bot Hesabı Oluştur seçeneğini seçin.
6. Gösterilen erişim token'ını kopyalayın. Tekrar gösterilmez.

Daha sonra, botun satırındaki Yeni Belirteç Oluştur seçeneğiyle bir belirteç ekleyebilirsiniz; her belirteç devre dışı bırakılabilir veya silinebilir. Kişisel erişim belirteçleri kişiler için kapalı olsa bile bot belirteçleri çalışmaya devam eder.

API ile:

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

Komut satırından, yönetici olarak (yerel modda değil) oturum açın: amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Diğer uç noktalar: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable ve /enable, ayrıca sahibi değiştirmek için POST /api/v4/bots/{bot_user_id}/assign/{user_id}.

Botu topluluklara ve kanallara ekleyin

Yeni bir bot hiçbir toplulukta yer almaz. Bunu, topluluğun üye yönetimi bölümünden veya API aracılığıyla bir kişi gibi ekleyin:

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

ileti:kanallar veya ileti:tümü yetkisine sahip bir bot, üye olmadan iletebilir; ancak yalnızca içinde bulunduğu kanallar için WebSocket olayları alır.

Bot adına gönderi yapın

Botun token'ını herhangi bir API çağrısında kullanın; en yaygın olanı POST /api/v4/posts'tur (bkz. Ana kaynaklar). Birine doğrudan yazmak için önce Doğrudan ileti kanalını açın:

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

İnsanların söylediklerine tepki vermek için, botun token'ıyla WebSocket bağlantısını izleyin ve ilgilendiğiniz posted olaylarına yanıt verin. Döngülerden kaçınmak için botun kendi iletilerini yok sayın.

Yalnızca bir kişinin görebileceği bir ileti (geçici ileti), POST /api/v4/posts/ephemeral ve {"user_id", "post": {"channel_id", "message"}} ile gönderilir. Bunun için create_post_ephemeral yetkisi gerekir; bu yetkiye varsayılan olarak yalnızca sistem yöneticileri sahiptir. Entegrasyonlar genellikle geçici iletileri, slash komutlarının ve düğmelerin yanıtları olarak gönderir.

Etkileşimli iletiler: düğmeler ve menüler

Ek dosyaları olan herhangi bir ileti, düğmeler ve seçim yapabileceğiniz menüler gibi eylemler taşıyabilir. Bunlar, API, webhook'lar ve slash komutu yanıtlarıyla gönderilen iletilerde çalışır. Birisi bunlardan birini kullandığında, Antimatter entegrasyonunuzun URL'sini çağırır.

{
  "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 veya select.
• id: harfler, rakamlar, tireler ve alt çizgiler; iletilerdeki her eylem için farklı olmalıdır. Boş bırakılırsa otomatik olarak oluşturulur.
• style (düğmeler): default, primary, success, good, warning, danger veya bir onaltılık renk.
• options (menüler) veya data_source: bir kişi veya kanal seçmek için users veya channels. default_option bir değeri önceden seçer.
• integration.url: tıklamanın gönderildiği adres. Bir uygulama (eklenti), /plugins/com.example.deploy/actions gibi kendi rotasını kullanabilir. integration.context size aittir: tıklamayla birlikte geri döner ve istemciler bunu asla görmez.

Entegrasyonunuzun aldığı istek

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

Bir menü için type değeri select olur ve context.selected_option seçilen değeri içerir.

Yanıtınız

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

• update: iletinin metnini ve özelliklerini değiştirir; örneğin kullanıldıktan sonra düğmeleri kaldırmak için (boş props).
• ephemeral_text: yalnızca tıklama yapan kişinin gördüğü bir ileti.
• goto_location: açılacak bir URL.
• Boş bir gövde hiçbir şeyi değiştirmez.

Sunucu, Bütünleştirme isteği zaman aşımı ayarına (varsayılan olarak 30 saniye) izin verdiği sürece bekler. Özel ağ adreslerindeki bütünleştirme URL'leri, webhooks'lerde olduğu gibi bir sistem yöneticisi tarafından izin verilmelidir.

Diyaloglar

Bir diyalog, sohbetin üzerine açılan bir formdur. Bir diyalogu yalnızca kişinin o an yaptığı bir işleme (bir slash komutu veya düğme) yanıt olarak açabilirsiniz, çünkü bu isteğin trigger_id değerine ihtiyaç duyar. trigger_id, entegrasyon istek zaman aşımı boyunca geçerlidir.

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

Her öğe display_name, name, help_text, placeholder, default ve optional değerlerini alır.

Kişi gönderdiğinde, Antimatter diyalogun url adresine POST isteği gönderir:

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

Diyalogu kapatmak için boş bir gövdeyle yanıt verin veya açık bırakıp neyin yanlış olduğunu gösterin:

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

{"error": "…"} tüm form için bir mesaj gösterir. notify_on_cancel kullanıldığında, diyalog kapatıldığında "cancelled": true gönderilir. Uygulamalarda diyaloglar aynı şekilde çalışır: eklenti API'sinin OpenInteractiveDialog metodu aynı isteği alır.