בוטים והודעות אינטראקטיביות

חשבון בוט הוא משתמש שנוצר עבור תוכנה. יש לו שם, תמונה ואסימונים משלו, ולצד שמו מופיע תגית BOT. עמוד זה מכסה גם את החלקים האינטראקטיביים של הודעות: כפתורים, תפריטים ודיאלוגים, שכל אינטגרציה יכולה להשתמש בהם.

למה חשבון בוט

• ההודעות שלו מגיעות מזהות ברורה, עם תגית בוט, ולא מחשבון של עמית לעבודה.
• האסימונים שלו ממשיכים לפעול גם אם האדם שגייס אותו משנה תפקיד או עוזב (אלא אם כן השרת משבית בוטים של בעלים מושבתים, ראו להלן).
• בוטים אינם יכולים להתחבר עם סיסמה, והם לעולם אינם רואים את אפליקציית ה-Web.

אפליקציות יוצרות בוטים משלהן, כגון בוטי 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, Webhooks ותשובות לפקודות לוכסן. כשאדם משתמש באחת מהם, Antimatter קוראת לכתובת האינטגרציה שלכם.

{
  "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, או צבע בשפה hex.
• 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 שניות כברירת מחדל). כתובות אינטגרציה על כתובות רשת פרטיות חייבות להיות מאושרות על ידי מנהל מערכת, כפי שמקובל עבור Webhooks.

תיבות דיאלוג

תיבת דיאלוג היא טופס שנפתח מעל השיחה. ניתן לפתוח אותה רק בתשובה למשהו שהאדם עשה עכשיו, פקודת לוכסן או כפתור, מכיוון שדורשת את 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 שולח בקשת POST ל־url של הדיאלוג:

{
  "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. דיאלוגים עובדים באותו אופן באפליקציות: OpenInteractiveDialog של API התוספים מקבל את אותה בקשה.