Perintah Garis Miring

Perintah garis miring kustom memungkinkan pengguna mengetik /sesuatu di kotak pesan untuk memanggil layanan Anda. Antimatter mengirim perintah ke URL Anda dan menampilkan jawaban Anda, baik hanya untuk orang tersebut maupun untuk seluruh kanal.

Cara kerja perintah garis miring

1. Seseorang mengetik /weather Paris dan mengirimnya. Teks tersebut tidak dipublikasikan.
2. Antimatter mengirim permintaan HTTP ke URL perintah, beserta informasi siapa yang mengetik, di mana, dan teks setelah kata pemicu.
3. Layanan Anda merespons dalam batas waktu permintaan (30 detik secara bawaan) dengan sebuah pesan.
4. Antimatter menampilkan jawaban: hanya untuk orang tersebut (ephemeral) atau di kanal untuk semua orang.

Perintah dimiliki oleh komunitas, dan kata pemicu bersifat unik di dalamnya. Perintah bawaan seperti /join, /msg, atau /away tidak dapat diganti. Aplikasi (plugin) juga dapat mendaftarkan perintah; lihat Bagian server.

Buat perintah

Perintah garis miring kustom diaktifkan secara bawaan (Aktifkan Perintah Garis Miring Kustom di Konsol Sistem › Integrasi › Manajemen Integrasi, ServiceSettings.EnableCommands). Admin komunitas dan admin sistem dapat membuatnya secara bawaan.

1. Buka avatar Anda di kanan atas, lalu Integrasi › Perintah Garis Miring, lalu Tambah Perintah Garis Miring.
2. Isi Judul dan Deskripsi (ditampilkan di halaman integrasi).
3. Masukkan Kata Pemicu Perintah, tanpa garis miring dan tanpa spasi, misalnya weather.
4. Masukkan URL Permintaan dan pilih Metode Permintaan: POST (bawaan) atau GET.
5. Secara opsional, atur Nama Pengguna Respons dan Ikon Respons. Keduanya hanya digunakan jika server mengizinkan integrasi untuk menimpa nama dan ikon (lihat Nama dan ikon).
6. Centang Penyelesaian Otomatis untuk menampilkan perintah saat orang mengetik /, lengkap dengan Petunjuk Autocomplete (argumennya, seperti [city]) dan Deskripsi Autocomplete.
7. Pilih Simpan, lalu salin token yang ditampilkan. Layanan Anda menggunakannya untuk memverifikasi bahwa permintaan berasal dari server Anda.

Dengan API: POST /api/v4/commands dengan {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Metode adalah P untuk POST atau G untuk GET. PUT /api/v4/commands/{command_id}/regen_token menerbitkan token baru.

Permintaan yang diterima layanan Anda

Perintah POST mengirim tubuh form-encoded (application/x-www-form-urlencoded); perintah GET mengirim bidang yang sama dalam string kueri. Token juga ada di header Authorization: Token <token>.

Respons

Jawab dengan 200 menggunakan JSON (Content-Type: application/json):

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

Respons yang bukan JSON ditampilkan sebagai pesan ephemeral dengan tubuh sebagai teksnya. 204 No Content tidak menampilkan apa pun. Status apa pun di luar 200–299 menampilkan kesalahan kepada orang tersebut.

Layanan contoh

Layanan perintah minimal dalam Python, hanya dengan pustaka standar:

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()

Jika layanan berjalan di alamat jaringan privat, admin sistem harus mengizinkannya di Izinkan koneksi internal yang tidak tepercaya ke (ServiceSettings.AllowedUntrustedInternalConnections).

Jawaban tertunda

Untuk pekerjaan yang memakan waktu lebih lama dari batas waktu, jawab segera (misalnya dengan pesan sementara "Sedang diproses…"), lalu POST jawaban sebenarnya ke response_url. Ini menerima JSON yang sama dengan respons, dan berfungsi hingga 5 kali dalam 30 menit setelah perintah.

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

Jalankan perintah dengan API

Skrip dan bot dapat menjalankan perintah apa pun, bawaan atau kustom, seolah-olah mereka mengetikkannya:

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 mendaftar perintah yang dapat dilengkapi otomatis oleh pengguna dalam komunitas.

Pelengkapan Otomatis

Perintah yang dibuat di halaman integrasi dilengkapi otomatis dengan pemicu, petunjuk, dan deskripsinya. Perintah yang didaftarkan oleh aplikasi dapat menjelaskan subperintah dan argumennya secara detail dengan AutocompleteData, dari model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) menambahkan subperintah, yang juga merupakan AutocompleteData.
• AddTextArgument(helpText, hint, pattern) menambahkan teks bebas.
• AddStaticListArgument(helpText, required, items) menawarkan daftar tetap AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) meminta saran dari aplikasi Anda saat pengguna mengetik. URL adalah rute aplikasi Anda, seperti /plugins/com.example.weather/cities. Ini menerima pengguna, kanal, dan komunitas, serta mengembalikan daftar JSON {"Item", "Hint", "HelpText"}.

Varian Named… (AddNamedTextArgument dan lainnya) menambahkan bendera --name value. Kedua antarmuka web menampilkan saran-saran ini.

Saat seseorang mengetik perintah, Fusion menampilkan perintah dan setiap argumennya sebagai blok, dengan blok yang sedang diketik disorot beserta teks bantuannya. Argumen berasal dari AutocompleteData atau, jika tidak ada, dari petunjuk: dalam petunjuk seperti @[username]... #[channel], kata yang diawali dengan @ masuk ke argumen orang dan kata yang diawali dengan # masuk ke argumen kanal, apa pun urutannya; ... berarti argumen tersebut berulang, dan argumen terakhir mengambil sisa teks.

Kanal dalam argumen

Dalam argumen perintah, @ mengusulkan orang, # mengusulkan kanal dan melengkapinya sebagai #channel-name, dan ~ melengkapinya sebagai ~channel-name. Antarmuka web dan aplikasi seluler Antimatter menulis tautan kanal dengan #, jadi perintah yang menerima kanal harus menerima kedua bentuk: /join, /mute, dan /invite bawaan melakukannya, dan petunjuk mereka menyatakan #[channel].