बॉट और इंटरैक्टिव मैसेज

बॉट अकाउंट किसी प्रोग्राम के लिए बनाया गया यूज़र है। इसका अपना नाम, तस्वीर और टोकन होते हैं, और इसके नाम के बगल में एक BOT टैग दिखता है। यह पेज मैसेज के इंटरैक्टिव हिस्सों पर भी प्रकाश डालता है: बटन, मेन्यू और डायलॉग, जिन्हें कोई भी इंटिग्रेशन इस्तेमाल कर सकता है।

बॉट अकाउंट क्यों

इसके मैसेज एक स्पष्ट पहचान से आते हैं, जिसमें बॉट टैग होता है, किसी सहकर्मी के अकाउंट से नहीं।
जब तक सर्वर ने निष्क्रिय मालिकों के बॉट को निष्क्रिय नहीं किया है (नीचे देखें), उसके टोकन तब भी काम करते हैं जब जो व्यक्ति ने इसे सेटअप किया था, वह अपनी भूमिका बदल दे या छोड़ दे।
बॉट पासवर्ड से साइन इन नहीं कर सकते, और वे कभी भी वेब ऐप नहीं देखते।

ऐप्स प्लगइन API (EnsureBotUser) के माध्यम से अपने स्वयं के बॉट बनाती हैं, जैसे कि Todo या Playbooks बॉट।

बॉट अकाउंट चालू करें

सिस्टम एडमिन सिस्टम कंसोल › इंटिग्रेशन › बॉट अकाउंट में बॉट अकाउंट निर्माण सक्षम करें (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION) चालू करता है। यह डिफ़ॉल्ट रूप से बंद होता है। सिर्फ सिस्टम एडमिन ही बॉट बना सकते हैं, जब तक कि वे परमिशन सेटिंग्स में अन्य भूमिकाओं को यह अधिकार न दें।

उसी पेज पर, जब मालिक निष्क्रिय हो, तब बॉट अकाउंट निष्क्रिय करें (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, डिफ़ॉल्ट रूप से चालू) तब बॉट को बंद कर देता है जब उसके मालिक का अकाउंट निष्क्रिय हो जाता है।

बॉट बनाएं

ऊपर दाईं ओर अपने अवतार पर क्लिक करें, फिर इंटिग्रेशन › बॉट अकाउंट, और फिर बॉट अकाउंट जोड़ें चुनें।
एक यूज़रनेम दर्ज करें (छोटे अक्षर, अंक, पूर्णांक, डैश और अंडरस्कोर), और वैकल्पिक रूप से एक बॉट आइकन, प्रदर्शित नाम और विवरण।
भूमिका चुनें: सदस्य, या सर्वर प्रबंधन करने वाले बॉट के लिए सिस्टम एडमिन। बॉट को केवल उतना ही दें जितना उसे चाहिए।
इसे हर सार्वजनिक चैनल में पोस्ट करने की अनुमति देने के लिए post:channels पर टिक करें, या हर चैनल, निजी चैनल और डायरेक्ट मैसेज सहित, सदस्यता के बिना पोस्ट करने के लिए post:all।
इसके डिफ़ॉल्ट टोकन की समाप्ति का समय निर्धारित करें, फिर बॉट अकाउंट बनाएं चुनें।
दिखाए गए एक्सेस टोकन की कॉपी करें। यह दोबारा नहीं दिखाया जाएगा।

बाद में, बॉट की पंक्ति पर नया टोकन बनाएं से एक टोकन जोड़ा जा सकता है, और प्रत्येक टोकन को निष्क्रिय या हटाया जा सकता है। व्यक्तिगत एक्सेस टोकन लोगों के लिए बंद होने पर भी बॉट टोकन काम करते हैं।

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 सेकंड)। निजी नेटवर्क पताओं पर इंटिग्रेशन URL को वेबहूक की तरह एक सिस्टम एडमिन द्वारा अनुमत होना चाहिए।

डायलॉग

डायलॉग एक फॉर्म है जो चैट के ऊपर खुलता है। आप इसे केवल उस चीज़ के जवाब में खोल सकते हैं जो व्यक्ति ने अभी किया है, जैसे एक स्लैश कमंड या बटन, क्योंकि इसके लिए उस अनुरोध का 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"}
      ]
    }
  }'

एलिमेंट प्रकार	यह क्या दिखाता है
`text`	एक-पंक्ति फील्ड। `subtype`: `text`, `email`, `number`, `password`, `tel` या `url`। `min_length` और `max_length` इसे सीमित करते हैं।
`textarea`	एक बहु-पंक्ति फील्ड।
`select`	एक सूची: `options`, या `data_source` `users`, `channels`, या `dynamic` जिसमें `data_source_url` हो। `multiselect` कई मानों की अनुमति देता है।
`bool`	एक चेकबॉक्स।
`radio`	`options` में से एक विकल्प।
`date`, `datetime`	एक तिथि, या तिथि और समय।

हर एलिमेंट 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 वही अनुरोध लेता है।