سلاش کمانڈز

کسٹم سلاش کمانڈ کے ذریعے لوگ پیغام کے خانے میں /کچھ لکھ کر آپ کے سروس کو کال کر سکتے ہیں۔ Antimatter کمانڈ کو آپ کے URL پر بھیجتا ہے اور آپ کا جواب دکھاتا ہے، چاہے وہ صرف اس شخص کو ہو یا پورے چینل میں۔

سلاش کمانڈ کیسے کام کرتی ہے

1. کوئی شخص /weather Paris لکھ کر بھیجتا ہے۔ یہ متن چینل میں پوسٹ نہیں ہوتا۔
2. Antimatter کمانڈ کے URL پر ایک HTTP درخواست بھیجتا ہے، جس میں یہ شامل ہوتا ہے کہ کس نے ٹائپ کیا، کہاں، اور ٹریگر کے بعد کیا متن تھا۔
3. آپ کا سروس درخواست کے ٹائم آؤٹ (معیاری طور پر 30 سیکنڈ) کے اندر ایک پیغام کے ساتھ جواب دیتا ہے۔
4. Antimatter جواب دکھاتا ہے: صرف اس شخص کو (ephemeral) یا چینل میں سب کے لیے۔

کمانڈز کسی کمیونٹی سے تعلق رکھتے ہیں، اور ٹریگر لفظ اس کے اندر منفرد ہوتا ہے۔ /join، /msg یا /away جیسے درجہ بندی شدہ کمانڈز کو تبدیل نہیں کیا جا سکتا۔ ایپس (پلگ انز) بھی کمانڈز رجسٹر کر سکتی ہیں؛ دیکھیں سرور کا حصہ۔

کمانڈ بنائیں

کسٹم سلاش کمانڈز پہلے سے فعال ہوتے ہیں (سسٹم کنسول › انضمامات › انٹیگریشن مینجمنٹ میں کسٹم سلاش کمانڈز فعال کریں، ServiceSettings.EnableCommands)۔ کمیونٹی ایڈمنز اور سسٹم ایڈمنز پہلے سے انہیں بنانے کی اجازت رکھتے ہیں۔

1. اوپر دائیں جانب اپنے ایواٹار پر کلک کریں، پھر انضمامات › سلاش کمانڈز، اور پھر سلاش کمانڈ شامل کریں۔
2. عنوان اور تفصیل (جو انضمامات کے صفحات پر دکھائی جاتی ہے) پُر کریں۔
3. کمانڈ ٹریگر لفظ درج کریں، سلاش کے بغیر اور خالی جگہ کے بغیر، مثال کے طور پر weather۔
4. درخواست URL درج کریں اور درخواست طریقہ منتخب کریں: POST (معیاری) یا GET۔
5. اختیاری طور پر جواب کے لیے صارف نام اور ردعمل آئیکن مقرر کریں۔ یہ صرف اس وقت استعمال ہوتے ہیں جب سرور انضمامات کو ناموں اور آئیکنز کو تبدیل کرنے کی اجازت دے (دیکھیں نام اور آئیکن)۔
6. جب لوگ / ٹائپ کریں تو کمانڈ کو فہرست میں دکھانے کے لیے آٹو کمپلیٹ پر ٹک کریں، ساتھ ہی آٹو کمپلیٹ ہنٹ (جیسے [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> ہیڈر میں بھی موجود ہوتا ہے۔

جواب

200 کے ساتھ JSON (Content-Type: application/json) جواب دیں:

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

JSON سے غیر متعلقہ جواب ایک ایفیمیرل پیغام کے طور پر دکھایا جاتا ہے جس کا متن باڈی ہوتا ہے۔ 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) میں اس کی اجازت دینی ہوگی۔

مؤخر جوابات

اگر کام ٹائم آؤٹ سے زیادہ وقت لے، تو فوراً جواب دیں (مثلاً ایک عارضی پیغام "کام جاری ہے…")، پھر حقیقی جواب کو response_url پر POST کریں۔ اس میں response کے جیسا ہی JSON استعمال ہوتا ہے، اور یہ کمانڈ کے 30 منٹ کے اندر 5 بار تک کام کرتا ہے۔

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 وہ کمانڈز لسٹ کرتا ہے جو لوگ کسی کمیونٹی میں آٹو کمپلیٹ کر سکتے ہیں۔

آٹو کمپلیٹ

انٹیگریشنز صفحات پر بنائی گئی کمانڈز اپنے trigger، hint اور description کے ساتھ آٹو کمپلیٹ ہوتی ہیں۔ ایپس کے ذریعے رجسٹر کی گئی کمانڈز اپنے subcommands اور arguments کی تفصیل AutocompleteData کے ذریعے بیان کر سکتی ہیں، جو model.NewAutocompleteData(trigger, hint, helpText) سے آتی ہے:

• AddCommand(sub) ایک subcommand شامل کرتا ہے، جو خود ایک AutocompleteData ہوتا ہے۔
• AddTextArgument(helpText, hint, pattern) مفت متن (free text) شامل کرتا ہے۔
• AddStaticListArgument(helpText, required, items) AutocompleteListItem{Item, Hint, HelpText} کی ایک مقررہ فہرست پیش کرتا ہے۔
• AddDynamicListArgument(helpText, url, required) لوگوں کے ٹائپ کرنے پر آپ کی ایپ سے تجاویز مانگتا ہے۔ URL آپ کی ایپ کا ایک route ہوتا ہے، جیسے /plugins/com.example.weather/cities۔ یہ صارف، چینل اور کمیونٹی کو وصول کرتا ہے، اور {"Item", "Hint", "HelpText"} کی ایک JSON فہرست واپس کرتا ہے۔

Named… ویریئنٹس (AddNamedTextArgument وغیرہ) --name value فلگس شامل کرتے ہیں۔ دونوں ویب انٹرفیسز ان تجاویز کو دکھاتے ہیں۔

جب کوئی شخص کمانڈ ٹائپ کرتا ہے، تو Fusion کمانڈ اور اس کے ہر آرگومنٹ کو ایک بلاک کے طور پر دکھاتا ہے، جس میں جو آرگومنٹ ٹائپ کیا جا رہا ہو، اسے اس کی مدد کے متن کے ساتھ نمایاں کیا جاتا ہے۔ آرگومنٹس AutocompleteData سے آتے ہیں، یا اگر وہ موجود نہ ہو تو ہنٹ سے: ایک ہنٹ جیسے @[username]... #[channel] میں، @ سے شروع ہونے والے الفاظ افراد کے آرگومنٹ کے لیے جاتے ہیں اور # سے شروع ہونے والے چینل کے آرگومنٹ کے لیے، چاہے ان کا ترتیب کچھ بھی ہو؛ ... کا مطلب ہے کہ آرگومنٹ بار بار آتا ہے، اور آخری آرگامنٹ باقی تمام متن کو لیتا ہے۔

آرگومنٹس میں چینلز

کمانڈ کے آرگومنٹس میں، @ افراد کی تجویز کرتا ہے، # چینلز کی تجویز کرتا ہے اور انہیں #channel-name کے طور پر مکمل کرتا ہے، اور ~ انہیں ~channel-name کے طور پر مکمل کرتا ہے۔ Antimatter کا ویب انٹرفیس اور موبائل ایپ چینل لنکس # کے ساتھ لکھتی ہیں، اس لیے کوئی بھی کمانڈ جو چینل لے، دونوں شکلوں کو قبول کرنی چاہیے: درجہ بند /join، /mute اور /invite ایسا ہی کرتے ہیں، اور ان کے ہنٹس #[channel] لکھتے ہیں۔