Lệnh gạch chéo

Lệnh gạch chéo tùy chỉnh cho phép người dùng nhập /something trong ô nhắn tin để gọi dịch vụ của bạn. Antimatter sẽ gửi lệnh đến URL của bạn và hiển thị câu trả lời, chỉ cho riêng người đó hoặc cho cả kênh.

Cách lệnh gạch chéo hoạt động

1. Một người nhập /weather Paris và gửi đi. Nội dung này không được đăng lên kênh.
2. Antimatter gửi một yêu cầu HTTP đến URL của lệnh, kèm theo thông tin về người đã nhập, vị trí và phần văn bản sau từ kích hoạt.
3. Dịch vụ của bạn phải trả lời trong thời gian chờ của yêu cầu (mặc định là 30 giây) bằng một tin nhắn.
4. Antimatter hiển thị câu trả lời: chỉ cho riêng người đó (tạm thời) hoặc trong kênh cho tất cả mọi người.

Lệnh thuộc về một cộng đồng, và từ kích hoạt phải là duy nhất trong cộng đồng đó. Các lệnh tích hợp sẵn như /join, /msg hoặc /away không thể bị thay thế. Các ứng dụng (plugin) cũng có thể đăng ký lệnh; xem Phần máy chủ.

Tạo một lệnh

Lệnh gạch chéo tùy chỉnh được bật theo mặc định (Bật Lệnh Slash Tùy chỉnh trong Bảng điều khiển Hệ thống › Tích Hợp › Quản lý tích hợp, ServiceSettings.EnableCommands). Quản trị viên cộng đồng và quản trị viên hệ thống có thể tạo chúng theo mặc định.

1. Mở ảnh đại diện của bạn ở góc trên bên phải, sau đó chọn Tích Hợp › Lệnh gạch chéo, rồi chọn Thêm Slash Command.
2. Điền vào Tiêu đề và Mô tả (hiển thị trên các trang tích hợp).
3. Nhập Command Trigger Word, không kèm dấu gạch chéo và không có khoảng trắng, ví dụ weather.
4. Nhập URL yêu cầu và chọn Phương thức Yêu cầu: POST (mặc định) hoặc GET.
5. Tùy chọn, đặt Tên người dùng phản hồi và Biểu tượng phản hồi. Chúng chỉ được sử dụng khi máy chủ cho phép các tích hợp ghi đè tên và biểu tượng (xem Tên và biểu tượng).
6. Đánh dấu Tự động hoàn thành để liệt kê lệnh khi người dùng nhập /, kèm theo Gợi ý tự động điền (các đối số của nó, chẳng hạn [city]) và Mô tả Tự động Hoàn thành.
7. Chọn Lưu, và sao chép token được hiển thị. Dịch vụ của bạn sẽ sử dụng nó để xác minh rằng các yêu cầu đến từ máy chủ của bạn.

Với API: POST /api/v4/commands bằng {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. Phương thức là P cho POST hoặc G cho GET. PUT /api/v4/commands/{command_id}/regen_token phát hành một token mới.

Yêu cầu mà dịch vụ của bạn nhận được

Lệnh POST gửi một thân yêu cầu dạng biểu mẫu (application/x-www-form-urlencoded); lệnh GET gửi các trường tương tự trong chuỗi truy vấn. Token cũng có trong tiêu đề Authorization: Token <token>.

Phản hồi

Trả lời 200 với JSON (Content-Type: application/json):

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

Phản hồi không phải JSON sẽ được hiển thị như một tin nhắn tạm thời với thân yêu cầu làm nội dung văn bản. 204 No Content không hiển thị gì. Bất kỳ mã trạng thái nào ngoài khoảng 200–299 sẽ hiển thị cho người dùng một lỗi.

Dịch vụ ví dụ

Một dịch vụ lệnh tối thiểu bằng Python, chỉ sử dụng thư viện chuẩn:

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

Nếu dịch vụ chạy trên một địa chỉ mạng riêng, quản trị viên hệ thống phải cho phép nó trong Cho phép các kết nối nội bộ không đáng tin cậy vào (ServiceSettings.AllowedUntrustedInternalConnections).

Trả lời chậm

Đối với các tác vụ mất nhiều thời gian hơn thời gian chờ, hãy trả lời ngay lập tức (ví dụ bằng một tin nhắn tạm thời "Đang xử lý…"), sau đó POST câu trả lời thực sự đến response_url. Nó nhận cùng một JSON như phản hồi và hoạt động tối đa 5 lần trong vòng 30 phút kể từ lệnh.

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

Chạy lệnh bằng API

Các script và bot có thể chạy bất kỳ lệnh nào, tích hợp sẵn hoặc tùy chỉnh, như thể chúng đã nhập nó:

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 liệt kê các lệnh mà người dùng có thể tự động hoàn thành trong một cộng đồng.

Tự động hoàn thành

Các lệnh được tạo trên các trang tích hợp sẽ tự động hoàn thành với kích hoạt, gợi ý và mô tả của chúng. Các lệnh được đăng ký bởi ứng dụng có thể mô tả chi tiết các lệnh con và đối số của chúng bằng AutocompleteData, từ model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) thêm một lệnh con, bản thân nó là một AutocompleteData.
• AddTextArgument(helpText, hint, pattern) thêm văn bản tự do.
• AddStaticListArgument(helpText, required, items) cung cấp một danh sách cố định các AutocompleteListItem{Item, Hint, HelpText}.
• AddDynamicListArgument(helpText, url, required) yêu cầu ứng dụng của bạn cung cấp các gợi ý khi người dùng nhập. URL là một route của ứng dụng của bạn, chẳng hạn như /plugins/com.example.weather/cities. Nó nhận người dùng, kênh và cộng đồng, và trả về một danh sách JSON của {"Item", "Hint", "HelpText"}.

Các biến thể Named… (AddNamedTextArgument và các biến thể khác) thêm các cờ --name value. Cả hai giao diện web đều hiển thị các gợi ý này.

Khi một người dùng đang nhập lệnh, Fusion hiển thị lệnh và từng đối số của nó dưới dạng khối, với khối đang được nhập được làm nổi bật cùng văn bản trợ giúp. Các đối số được lấy từ AutocompleteData hoặc, nếu không có, từ gợi ý: trong một gợi ý như @[username]... #[channel], các từ bắt đầu bằng @ sẽ thuộc đối số người dùng và các từ bắt đầu bằng # sẽ thuộc đối số kênh, bất kể thứ tự; ... có nghĩa là đối số có thể lặp lại, và đối số cuối cùng sẽ nhận phần còn lại của văn bản.

Kênh trong các đối số

Trong các đối số của một lệnh, @ sẽ gợi ý người dùng, # sẽ gợi ý kênh và hoàn thành chúng dưới dạng #channel-name, còn ~ sẽ hoàn thành chúng dưới dạng ~channel-name. Giao diện web và ứng dụng di động của Antimatter viết liên kết kênh bằng #, do đó một lệnh nhận kênh nên chấp nhận cả hai dạng: các lệnh tích hợp sẵn /join, /mute và /invite đều làm như vậy, và gợi ý của chúng ghi là #[channel].