بوٹس اور انٹرایکٹو پیغامات

بوٹ اکاؤنٹ ایک ایسا صارف ہے جو کسی پروگرام کے لیے بنایا جاتا ہے۔ اس کا اپنا نام، تصویر اور ٹوکنز ہوتے ہیں، اور اس کے نام کے ساتھ BOT ٹیگ دکھائی دیتا ہے۔ یہ صفحہ پیغامات کے انٹرایکٹو حصوں پر بھی روشنی ڈالتا ہے: بٹن، مینو اور ڈائیلاگز، جنہیں کوئی بھی انٹیگریشن استعمال کر سکتا ہے۔

بوٹ اکاؤنٹ کیوں

• اس کے پیغامات ایک واضح شناخت سے آتے ہیں، جس پر بوٹ کا ٹیگ لگا ہوتا ہے، کسی ساتھی کے اکاؤنٹ سے نہیں۔
• اس کے ٹوکنز تب بھی کام کرتے رہتے ہیں جب اسے بنانے والا شخص اپنا کردار بدلتا ہے یا چھوڑ دیتا ہے (مگر اس صورت میں نہیں جب سرور غیر فعال مالکین کے بوٹس کو بند کر دے، نیچے دیکھیں)۔
• بوٹس پاس ورڈ کے ذریعے سائن ان نہیں کر سکتے، اور وہ کبھی ویب ایپ نہیں دیکھتے۔

ایپس اپنے اپنے بوٹس بناتی ہیں، جیسے کہ Todo یا Playbooks بوٹس، پلگ ان API کے ذریعے (EnsureBotUser)۔

بوٹ اکاؤنٹس کو فعال کریں

ایک سسٹم ایڈمن سسٹم کنسول › انضمامات › بوٹ اکاؤنٹس میں بوٹ اکاؤنٹس کی تخلیق فعال کریں کو آن کرتا ہے (ServiceSettings.EnableBotAccountCreation، AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION)۔ یہ پہلے سے بند ہوتا ہے۔ صرف سسٹم ایڈمنز ہی بوٹس بنا سکتے ہیں، جب تک کہ وہ اجازت کی ترتیبات میں دیگر کرداروں کو یہ حق نہ دیں۔

اسی صفحے پر، جب مالک غیر فعال ہو تو بوٹ اکاؤنٹس غیر فعال کریں (ServiceSettings.DisableBotsWhenOwnerIsDeactivated، پہلے سے فعال) بوٹ کو غیر فعال کر دیتا ہے جب اس کے مالک کا اکاؤنٹ غیر فعال ہو جاتا ہے۔

بوٹ بنائیں

1. اوپر دائیں جانب اپنے ایواٹار پر کلک کریں، پھر انضمامات › بوٹ اکاؤنٹس، اور پھر بوٹ اکاؤنٹ شامل کریں۔
2. ایک صارف نام درج کریں (چھوٹے حروف، اعداد، پیریڈز، ڈیشز اور انڈرسکورز)، اور اختیاری طور پر بوٹ آئیکن، ڈسپلے نام اور تفصیل۔
3. کردار منتخب کریں: رکن، یا سرور کو منظم کرنے والے بوٹ کے لیے سسٹم ایڈمن۔ بوٹ کو صرف اتنا ہی دیں جتنی اسے ضرورت ہو۔
4. ہر عوامی چینل میں پوسٹ کرنے کی اجازت دینے کے لیے post:channels کو ٹک کریں، یا ہر چینل، ذاتی چینلز اور براہِ راست پیغامات سمیت، بغیر رکن ہونے کے، post:all منتخب کریں۔
5. اس کی ڈیفالٹ ٹوکن کی میعاد ختم ہونے کا وقت مقرر کریں، پھر بوٹ اکاؤنٹ بنائیں منتخب کریں۔
6. دکھایا گیا ایکسیس ٹوکن کاپی کریں۔ یہ دوبارہ نہیں دکھایا جائے گا۔

بعد میں، بوٹ کی قطار پر نئی ٹوکن بنائیں ایک ٹوکن شامل کرتا ہے، اور ہر ٹوکن کو غیر فعال یا حذف کیا جا سکتا ہے۔ بوٹ ٹوکنز تب بھی کام کرتی ہیں جب لوگوں کے لیے ذاتی رسائی ٹوکنز بند کر دی گئی ہوں۔

API کے ذریعے:

# create the bot (you become its owner)
curl -X POST https://chat.example.com/api/v4/bots \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"username": "deploy-bot", "display_name": "Deploy", "description": "Posts deployments"}'

# give it a token
curl -X POST https://chat.example.com/api/v4/users/$BOT_USER_ID/tokens \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"description": "deploy pipeline"}'

کمانڈ لائن سے، ایڈمن کے طور پر سائن ان ہو کر (لوکل موڈ میں نہیں): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d۔ دیگر انڈ پوائنٹس: GET /api/v4/bots، PUT /api/v4/bots/{bot_user_id}، POST /api/v4/bots/{bot_user_id}/disable اور /enable، اور مالک تبدیل کرنے کے لیے POST /api/v4/bots/{bot_user_id}/assign/{user_id}۔

بوٹ کو کمیونٹیز اور چینلز میں شامل کریں

نیا بوٹ کسی بھی کمیونٹی میں شامل نہیں ہوتا۔ اسے ایک شخص کی طرح شامل کریں، کمیونٹی کے رکن مینجمنٹ سے یا API کے ذریعے:

curl -X POST https://chat.example.com/api/v4/teams/$TEAM_ID/members \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"team_id": "'$TEAM_ID'", "user_id": "'$BOT_USER_ID'"}'

curl -X POST https://chat.example.com/api/v4/channels/$CHANNEL_ID/members \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"user_id": "'$BOT_USER_ID'"}'

post:channels یا post:all کے ساتھ بوٹ بغیر رکن ہونے کے بھی پوسٹ کر سکتا ہے، لیکن وہ صرف ان چینلز کے لیے WebSocket ایونٹس وصول کرتا ہے جن میں وہ شامل ہے۔

بوٹ کے نام سے پوسٹ کریں

کوئی بھی API کال کے لیے بوٹ کا ٹوکن استعمال کریں؛ POST /api/v4/posts سب سے عام ہے (دیکھیں بنیادی وسائل)۔ کسی کے براہِ راست پیغام میں لکھنے کے لیے پہلے براہِ راست پیغام چینل کھولیں:

# returns the channel; use its "id" as channel_id
curl -X POST https://chat.example.com/api/v4/channels/direct \
  -H "Authorization: Bearer $BOT_TOKEN" -H 'Content-Type: application/json' \
  -d '["'$BOT_USER_ID'", "'$USER_ID'"]'

لوگوں کی باتوں پر ردعمل دینے کے لیے، بوٹ کے ٹوکن کے ساتھ WebSocket کو فالو کریں اور ان posted ایونٹس کا جواب دیں جن کے بارے میں آپ کو فکر ہے۔ لوپس سے بچنے کے لیے بوٹ کے اپنے پیغامات کو نظرانداز کریں۔

ایسا پیغام جسے صرف ایک شخص دیکھ سکتا ہے (ایفیمرل پیغام) POST /api/v4/posts/ephemeral اور {"user_id", "post": {"channel_id", "message"}} کے ساتھ بھیجا جاتا ہے۔ اس کے لیے create_post_ephemeral کی اجازت درکار ہے، جو ڈیفالٹ طور پر صرف سسٹم ایڈمنز کے پاس ہوتی ہے۔ انٹگریٹشنز عموماً سلاش کمانڈز اور بٹنوں کے جوابات کے طور پر ایفیمرل پیغامات بھیجتے ہیں۔

انٹرایکٹو پیغامات: بٹن اور مینو

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

{
  "channel_id": "…",
  "message": "Deploy **api 2.4.0** to production?",
  "props": {
    "attachments": [{
      "actions": [
        {
          "id": "approve",
          "type": "button",
          "name": "Approve",
          "style": "primary",
          "integration": {"url": "https://deploy.example.com/actions", "context": {"release": "2.4.0", "action": "approve"}}
        },
        {
          "id": "env",
          "type": "select",
          "name": "Pick an environment",
          "options": [{"text": "Staging", "value": "staging"}, {"text": "Production", "value": "production"}],
          "integration": {"url": "https://deploy.example.com/actions", "context": {"release": "2.4.0", "action": "env"}}
        }
      ]
    }]
  }
}

• type: button یا select۔
• id: حروف، اعداد، ڈیشز اور انڈر سکورز، پیغام کے ہر ایک ایکشن کے لیے مختلف۔ اگر آپ اسے خالی چھوڑ دیتے ہیں تو یہ خود بخود جنریٹ ہو جاتا ہے۔
• style (بٹن کے لیے): default، primary، success، good، warning، danger، یا کوئی ہیکس کلر۔
• options (مینو کے لیے)، یا data_source: users یا channels تاکہ کسی شخص یا چینل کا انتخاب کیا جا سکے۔ default_option کسی قدر کو پہلے سے منتخب کرتا ہے۔
• integration.url: جہاں کلک بھیجی جاتی ہے۔ ایپ (پلگ ان) اپنا اپنا روٹ استعمال کر سکتی ہے، جیسے /plugins/com.example.deploy/actions۔ integration.context آپ کا ہے: یہ کلک کے ساتھ واپس آتا ہے، اور کلائنٹس اسے کبھی نہیں دیکھتے۔

وہ درخواست جو آپ کی انٹیگریشن وصول کرتی ہے

{
  "user_id": "…",
  "user_name": "priya",
  "channel_id": "…",
  "channel_name": "releases",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "post_id": "…",
  "trigger_id": "…",
  "type": "button",
  "context": {"release": "2.4.0", "action": "approve"}
}

ایک مینیو کے لیے، type select ہوتا ہے اور context.selected_option منتخب شدہ ویلیو رکھتا ہے۔

آپ کا جواب

{
  "update": {"message": "Deploy of **api 2.4.0** approved by @priya", "props": {}},
  "ephemeral_text": "Done. The deploy starts in a minute."
}

• update: پیغام کے متن اور خصوصیات کو تبدیل کرتا ہے، مثال کے طور پر استعمال کے بعد بٹنوں کو ہٹانے کے لیے (خالی props)۔
• ephemeral_text: ایک ایسا پیغام جو صرف اس شخص کو نظر آتا ہے جس نے کلک کیا۔
• goto_location: کھولنے کے لیے ایک URL۔
• خالی باڈی کچھ نہیں بدلتی۔

سرور انٹیکریشن درخواست ٹائم آؤٹ کی اجازت کے مطابق انتظار کرتا ہے (پہلے سے 30 سیکنڈ)۔ ذاتی نیٹ ورک ایڈریسز پر موجود انٹیکریشن URLs کو سسٹم ایڈمن کی اجازت ہونی چاہیے، ویب ہکس کی طرح۔

ڈائیلاگز

ایک ڈائیلاگ ایک فارم ہے جو چیٹ کے اوپر کھلتا ہے۔ آپ اسے صرف اس وقت کھول سکتے ہیں جب وہ کسی ایسی چیز کے جواب میں ہو جو شخص نے اسی وقت کی ہو، جیسے سلاش کمانڈ یا بٹن، کیونکہ اسے اس درخواست کا trigger_id درکار ہوتا ہے۔ trigger_id اتنا عرصہ تک درست رہتا ہے جتنا انٹیگریشن درخواست ٹائم آؤٹ۔

curl -X POST https://chat.example.com/api/v4/actions/dialogs/open \
  -H 'Content-Type: application/json' \
  -d '{
    "trigger_id": "'$TRIGGER_ID'",
    "url": "https://deploy.example.com/dialog",
    "dialog": {
      "callback_id": "new-release",
      "title": "New release",
      "introduction_text": "Fill in the release details.",
      "submit_label": "Create",
      "notify_on_cancel": false,
      "state": "anything you want back",
      "elements": [
        {"display_name": "Version", "name": "version", "type": "text", "placeholder": "2.4.0"},
        {"display_name": "Notes", "name": "notes", "type": "textarea", "optional": true},
        {"display_name": "Environment", "name": "env", "type": "select",
         "options": [{"text": "Staging", "value": "staging"}, {"text": "Production", "value": "production"}]},
        {"display_name": "Owner", "name": "owner", "type": "select", "data_source": "users"},
        {"display_name": "Notify the channel", "name": "notify", "type": "bool", "default": "true"}
      ]
    }
  }'

ہر المنٹ display_name، name، help_text، placeholder، default اور optional قبول کرتا ہے۔

جب شخص جمع کرتا ہے، Antimatter ڈائیلاگ کے url پر POST کرتا ہے:

{
  "type": "dialog_submission",
  "callback_id": "new-release",
  "state": "anything you want back",
  "user_id": "…",
  "channel_id": "…",
  "team_id": "…",
  "submission": {"version": "2.4.0", "notes": "", "env": "staging", "owner": "…", "notify": true},
  "cancelled": false
}

ڈائیلاگ بند کرنے کے لیے خالی باڈی کے ساتھ جواب دیں، یا اسے کھلا رکھ کر دکھائیں کہ کیا غلط ہے:

{"errors": {"version": "This version already exists."}}

{"error": "…"} پورے فارم کے لیے ایک پیغام دکھاتا ہے۔ notify_on_cancel کے ساتھ، ڈائیلاگ بند کرنے پر "cancelled": true بھیجا جاتا ہے۔ ڈائیلاگز ایپس میں بھی اسی طرح کام کرتے ہیں: پلگ ان API کا OpenInteractiveDialog اسی طرح کی درخواست لیتا ہے۔