Slash komutları

Özel bir slash komut, kullanıcıların mesaj kutusuna /birşey yazarak hizmetinizi çağırmasını sağlar. Antimatter komutu URL'nize gönderir ve yanıtınızı yalnızca o kişiye veya tüm kanala gösterir.

Bir slash komutun çalışma biçimi

1. Bir kişi /weather Paris yazar ve gönderir. Metin gönderilmez.
2. Antimatter, komutun URL'sine bir HTTP isteği gönderir; bu istekte kimin yazdığı, nerede olduğu ve tetikleyici kelimenin sonrasındaki metin bulunur.
3. Hizmetiniz, istek zaman aşımı içinde (varsayılan olarak 30 saniye) bir mesajla yanıt verir.
4. Antimatter yanıtı gösterir: yalnızca o kişiye (geçici) veya herkes için kanala.

Komutlar bir topluluğa aittir ve bir topluluk içinde tetikleyici kelime benzersizdir. /join, /msg veya /away gibi yerleşik komutlar değiştirilemez. Uygulamalar (eklentiler) de komut kaydedebilir; bkz. Sunucu bölümü.

Komut oluşturma

Özel slash komutlar varsayılan olarak açıktır (Sistem Konsolu › Bütünleştirmeler › Bütünleştirme yönetimi içindeki Özel bölü komutları kullanılsın, ServiceSettings.EnableCommands). Topluluk yöneticileri ve sistem yöneticileri varsayılan olarak bunları oluşturabilir.

1. Sağ üstteki avatarınıza tıklayın, ardından Bütünleştirmeler › Bölü komutları ve Bölü komutu ekle seçeneğine gidin.
2. Başlık ve Açıklama alanlarını doldurun (bütünleştirmeler sayfalarında gösterilir).
3. Slash işareti ve boşluk olmadan Komutu tetikleyecek sözcük girin, örneğin weather.
4. İstek adresi girin ve İstek yöntemi seçin: POST (varsayılan) veya GET.
5. İsteğe bağlı olarak bir Yanıt kullanıcı adı ve bir Yanıt simgesi belirleyin. Bunlar yalnızca sunucu, bütünleştirmelerin adları ve simgeleri değiştirmesine izin verdiğinde kullanılır (bkz. Ad ve simge).
6. Kullanıcılar / yazdıklarında komutun listelenmesi için Otomatik tamamla seçeneğini işaretleyin; bir Otomatik tamamlama ipucu (örneğin [city] gibi argümanları) ve bir Otomatik tamamlama açıklaması ekleyin.
7. Kaydet seçeneğini seçin ve gösterilen belirteci (token) kopyalayın. Hizmetiniz, isteklerin sunucunuzdan geldiğini doğrulamak için bunu kullanır.

API ile: POST /api/v4/commands ve {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Method alanı POST için P, GET için G olmalıdır. PUT /api/v4/commands/{command_id}/regen_token yeni bir token oluşturur.

Hizmetinizin aldığı istek

POST komutu form kodlu bir gövde (application/x-www-form-urlencoded) gönderir; GET komutu aynı alanları sorgu dizisinde gönderir. Token ayrıca Authorization: Token <token> başlığında da bulunur.

Yanıt

200 yanıtı ile JSON döndürün (Content-Type: application/json):

{
  "response_type": "in_channel",
  "text": "Paris: 18 °C, light rain",
  "attachments": []
}

JSON olmayan bir yanıt, gövdesi metin olarak kullanılan geçici (ephemeral) bir iletide gösterilir. 204 No Content hiçbir şey göstermez. 200–299 aralığı dışındaki herhangi bir durum kodu kişiye bir hata gösterir.

Örnek hizmet

Yalnızca standart kütüphaneyle yazılmış, minimal bir Python komut servisi:

import hmac
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs

TOKEN = "the token shown when you saved the command"

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers["Content-Length"])).decode()
        form = {key: values[0] for key, values in parse_qs(body).items()}
        if not hmac.compare_digest(form.get("token", ""), TOKEN):
            self.send_response(401)
            self.end_headers()
            return
        answer = {
            "response_type": "ephemeral",
            "text": f"Hello @{form['user_name']}, you asked for: {form.get('text', '')}",
        }
        data = json.dumps(answer).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(data)

HTTPServer(("0.0.0.0", 8080), Handler).serve_forever()

Servis bir özel ağ adresinde çalışıyorsa, bir sistem yöneticisinin Şuraya yapılan güvenilmemiş iç bağlantılara izin verilsin (ServiceSettings.AllowedUntrustedInternalConnections) ayarında buna izin vermesi gerekir.

Gecikmeli yanıtlar

Zaman aşımından daha uzun süren işler için hemen (örneğin geçici bir "Çalışıyorum…" ile) yanıt verin, ardından gerçek yanıtı response_url adresine POST edin. Yanıtla aynı JSON'u alır ve komuttan sonraki 30 dakika içinde en fazla 5 kez çalışır.

curl -X POST "$RESPONSE_URL" -H 'Content-Type: application/json' \
  -d '{"response_type": "in_channel", "text": "Report ready: https://reports.example.com/42"}'

Komutları API ile çalıştırma

Betikler ve botlar, sanki kendileri yazmış gibi yerleşik veya özel herhangi bir komutu çalıştırabilir:

curl -X POST https://chat.example.com/api/v4/commands/execute \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"channel_id": "'$CHANNEL_ID'", "command": "/weather Paris"}'

GET /api/v4/teams/{team_id}/commands/autocomplete, bir toplulukta insanların otomatik tamamlama yapabileceği komutları listeler.

Otomatik tamamlama

Entegrasyon sayfalarında oluşturulan komutlar, tetikleyicileri, ipuçları ve açıklamalarıyla otomatik tamamlanır. Uygulamalar tarafından kaydedilen komutlar, alt komutlarını ve argümanlarını AutocompleteData ile ayrıntılı olarak açıklayabilir; bu veri model.NewAutocompleteData(trigger, hint, helpText) ile oluşturulur:

• AddCommand(sub), kendisi bir AutocompleteData olan bir alt komut ekler.
• AddTextArgument(helpText, hint, pattern), serbest metin ekler.
• AddStaticListArgument(helpText, required, items), AutocompleteListItem{Item, Hint, HelpText} öğelerinden oluşan sabit bir liste sunar.
• AddDynamicListArgument(helpText, url, required), kişiler yazarken öneriler için uygulamanıza sorar. URL, uygulamanızın bir yoludur, örneğin /plugins/com.example.weather/cities. Kullanıcı, kanal ve topluluğu alır ve {"Item", "Hint", "HelpText"} öğelerinden oluşan bir JSON listesi döndürür.

Named… varyantları (AddNamedTextArgument ve diğerleri) --name value bayrakları ekler. Her iki web arayüzü de bu önerileri gösterir.

Birisi komut yazarken Fusion, komutu ve her bir argümanını ayrı ayrı bir blok olarak gösterir; yazılan blok, yardım metniyle birlikte vurgulanır. Argümanlar AutocompleteData'den ya da yoksa ipucundan gelir: @[username]... #[channel] gibi bir ipucunda, @ ile başlayan kelimeler people argümanına, # ile başlayan kelimeler ise channel argümanına gider; sıraları ne olursa olsun. ..., argümanın tekrarlandığını, son argümanın ise metnin geri kalanını aldığını belirtir.

Argümanlardaki kanallar

Bir komutun argümanlarında @ kişiler, # kanallar önerir ve onları #channel-name olarak tamamlar, ~ ise onları ~channel-name olarak tamamlar. Antimatter'ın web arayüzü ve mobil uygulaması kanal bağlantılarını # ile yazar, bu nedenle kanal alan bir komut her iki biçimi de kabul etmelidir: yerleşik /join, /mute ve /invite bunu yapar ve ipuçları #[channel] der.