دستورهای اسلش

یک دستور اسلش سفارشی به افراد اجازه می‌دهد در کادر پیام /something را تایپ کنند تا سرویس شما فراخوانده شود. Antimatter دستور را به URL شما ارسال می‌کند و پاسخ شما را نمایش می‌دهد، یا فقط برای آن شخص یا برای کل کانال.

نحوه کار دستور اسلش

1. شخصی /weather Paris را تایپ کرده و ارسال می‌کند. متن در کانال منتشر نمی‌شود.
2. Antimatter یک درخواست HTTP به URL دستور ارسال می‌کند که شامل این موارد است: چه کسی تایپ کرده، کجا، و متنی که بعد از کلمه محرک آمده است.
3. سرویس شما در محدوده مهلت درخواست (به‌طور پیش‌فرض ۳۰ ثانیه) با یک پیام پاسخ می‌دهد.
4. Antimatter پاسخ را نمایش می‌دهد: فقط برای آن شخص (موقتی) یا در کانال برای همه.

دستورها به یک جامعه تعلق دارند و کلمه محرک در آن منحصربه‌فرد است. دستورهای داخلی مانند /join، /msg یا /away قابل جایگزینی نیستند. برنامه‌ها (افزونه‌ها) نیز می‌توانند دستورات را ثبت کنند؛ به بخش سرور مراجعه کنید.

ایجاد یک دستور

دستورات اسلش سفارشی به‌طور پیش‌فرض فعال هستند (دستورات اسلش سفارشی را فعال کنید در کنسول سیستم › ادغام ها › مدیریت یکپارچه سازی، ServiceSettings.EnableCommands). مدیران جامعه و مدیران سیستم به‌طور پیش‌فرض می‌توانند آن‌ها را ایجاد کنند.

1. منوی تیم را باز کنید، سپس تنظیمات تیم را انتخاب کنید، در انتهای زبانه‌ها روی ادغام ها کلیک کنید، سپس دستورهای اسلش و دستور اسلش را اضافه کنید را انتخاب کنید.
2. عنوان و شرح (که در صفحات یکپارچه‌سازی نمایش داده می‌شود) را پر کنید.
3. کلمه تریگر دستور را بدون اسلش و بدون فاصله وارد کنید، برای مثال weather.
4. آدرس URL درخواستی را وارد کنید و روش درخواست را انتخاب کنید: ارسال (POST) (پیش‌فرض) یا دریافت (GET).
5. در صورت نیاز، پاسخ نام کاربری و نماد پاسخ را تنظیم کنید. این موارد فقط زمانی استفاده می‌شوند که سرور به یکپارچه‌سازی‌ها اجازه تغییر نام و نماد را بدهد (به نام و نماد مراجعه کنید).
6. گزینه تکمیل خودکار را تیک بزنید تا دستور هنگام تایپ / توسط کاربران فهرست شود، همراه با راهنما(Hint) تکمیل شونده خودکار (آرگومان‌های آن، مانند [city]) و توضیحات تکمیل شونده خودکار.
7. صرفه جویی را انتخاب کنید و توکن نمایش‌داده‌شده را کپی کنید. سرویس شما از آن برای اطمینان از اینکه درخواست‌ها از سرور شما می‌آیند استفاده می‌کند.

با استفاده از API: POST /api/v4/commands همراه با {"team_id", "trigger", "url", "method": "P", "display_name", "description", "auto_complete": true, "auto_complete_hint", "auto_complete_desc", "username", "icon_url"}. مقدار P برای POST و G برای GET است. PUT /api/v4/commands/{command_id}/regen_token یک توکن جدید صادر می‌کند.

درخواستی که سرویس شما دریافت می‌کند

یک دستور POST بدنه‌ای با فرمت فرم (application/x-www-form-urlencoded) ارسال می‌کند؛ یک دستور GET فیلدهای مشابه را در رشته کوئری ارسال می‌کند. توکن همچنین در هدر Authorization: Token <token> موجود است.

پاسخ

با JSON (Content-Type: application/json) پاسخ 200 بدهید:

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

پاسخی که JSON نباشد به صورت یک پیام ephemeral با بدنه به عنوان متن نمایش داده می‌شود. 204 No Content چیزی نمایش نمی‌دهد. هر وضعیت خارج از محدوده 200–299 یک خطا را به کاربر نشان می‌دهد.

سرویس نمونه

یک سرویس دستور حداقلی در Python، فقط با کتابخانه استاندارد:

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

اگر سرویس روی یک آدرس شبکه خصوصی اجرا می‌شود، یک مدیر سیستم باید آن را در اتصالات داخلی غیرقابل اعتماد را مجاز کنید (ServiceSettings.AllowedUntrustedInternalConnections) مجاز کند.

پاسخ‌های تأخیری

برای کارهایی که طولانی‌تر از مهلت زمانی (timeout) هستند، فوراً پاسخ دهید (مثلاً با یک پیام موقتی «در حال انجام است…») و سپس پاسخ واقعی را به response_url ارسال کنید (POST). این آدرس همان JSON پاسخ را می‌پذیرد و تا ۵ بار در ۳۰ دقیقه پس از دستور قابل استفاده است.

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

اجرای دستور با API

اسکریپت‌ها و ربات‌ها می‌توانند هر دستوری را، داخلی یا سفارشی، گویی خودشان تایپ کرده‌اند، اجرا کنند:

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 دستورهایی که افراد می‌توانند در یک جامعه (community) تکمیل خودکار (autocomplete) کنند را فهرست می‌کند.

تکمیل خودکار

دستورهای ایجادشده در صفحات یکپارچه‌سازی (integrations) با محرک (trigger)، راهنما (hint) و توضیح خود تکمیل خودکار می‌شوند. دستورهای ثبت‌شده توسط اپلیکیشن‌ها می‌توانند زیردستورها و آرگومان‌های خود را با جزئیات در AutocompleteData توصیف کنند، از model.NewAutocompleteData(trigger, hint, helpText):

• AddCommand(sub) یک زیردستور اضافه می‌کند که خود یک AutocompleteData است.
• AddTextArgument(helpText, hint, pattern) متن آزاد اضافه می‌کند.
• AddStaticListArgument(helpText, required, items) یک فهرست ثابت از AutocompleteListItem{Item, Hint, HelpText} ارائه می‌دهد.
• AddDynamicListArgument(helpText, url, required) هنگام تایپ کاربران از اپلیکیشن شما برای دریافت پیشنهادات می‌پرسد. URL یک مسیر (route) از اپلیکیشن شماست، مانند /plugins/com.example.weather/cities. این مسیر کاربر، کانال و جامعه را دریافت می‌کند و یک فهرست JSON از {"Item", "Hint", "HelpText"} برمی‌گرداند.

انواع Named… (مانند AddNamedTextArgument و سایر موارد) پرچم‌های --name value را اضافه می‌کنند. هر دو رابط وب این پیشنهادها را نشان می‌دهند. مقداری که شامل فاصله است را می‌توان داخل گیومه قرار داد تا به عنوان یک آرگومان تکمیل خودکار شود، برای مثال --name "my remote": گیومه دوتایی برای همه دستورات کار می‌کند و دستورات خود Antimatter که پرچم می‌پذیرند، گیومه تکی یا گیومه آکولاد را نیز می‌پذیرند.

هنگامی که کاربر در حال تایپ یک دستور است، Fusion دستور و هر یک از آرگومان‌های آن را به صورت بلوک نمایش می‌دهد؛ بلوکی که در حال تایپ است، همراه با متن راهنمای آن، برجسته نمایش داده می‌شود. آرگومان‌ها از AutocompleteData یا در صورت نبود آن، از راهنما (hint) گرفته می‌شوند: در راهنمایی مانند @[username]... #[channel]، کلماتی که با @ شروع می‌شوند به آرگومان افراد و کلماتی که با # شروع می‌شوند به آرگومان کانال‌ها اختصاص می‌یابند، صرف‌نظر از ترتیب آن‌ها؛ ... به این معناست که آرگومان تکرار می‌شود و آرگومان آخر، باقی‌مانده متن را در بر می‌گیرد.

کانال‌ها در آرگومان‌ها

در آرگومان‌های یک دستور، @ افراد را پیشنهاد می‌دهد، # کانال‌ها را پیشنهاد داده و آن‌ها را به صورت #channel-name تکمیل می‌کند، و ~ آن‌ها را به صورت ~channel-name تکمیل می‌کند. رابط وب و اپلیکیشن موبایل Antimatter پیوندهای کانال را با # می‌نویسند، بنابراین دستوری که کانال را به عنوان ورودی می‌گیرد باید هر دو فرمت را بپذیرد: دستورات داخلی /join، /mute و /invite این کار را انجام می‌دهند و راهنمای آن‌ها #[channel] است.