ربات‌ها و پیام‌های تعاملی

حساب ربات کاربری است که برای یک برنامه ساخته شده است. این حساب نام، تصویر و توکن‌های مخصوص خود را دارد و برچسب BOT را در کنار نام خود نمایش می‌دهد. این صفحه همچنین شامل عامل‌های هوش مصنوعی است که خودتان آن‌ها را اجرا می‌کنید، و بخش‌های تعاملی پیام‌ها: دکمه‌ها، منوها و گفتگوها که هر یکپارچه‌سازی می‌تواند از آن‌ها استفاده کند.

چرا حساب ربات

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

برنامه‌ها ربات‌های خود را از طریق API افزونه (EnsureBotUser) ایجاد می‌کنند، مانند ربات‌های To-do یا Playbooks. عامل‌های هوش مصنوعی نیز نوعی حساب ربات هستند که با برچسب AGENT نمایش داده می‌شوند: به عامل‌ها مراجعه کنید.

فعال‌سازی حساب‌های ربات

یک مدیر سیستم گزینه فعال کردن ایجاد حساب ربات را در کنسول سیستم › ادغام ها › حساب‌های ربات (ServiceSettings.EnableBotAccountCreation، AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION) فعال می‌کند. این گزینه به‌طور پیش‌فرض غیرفعال است. تنها مدیران سیستم می‌توانند ربات ایجاد کنند، مگر اینکه در تنظیمات دسترسی، این حق را به نقش‌های دیگر بدهند.

در همان صفحه، گزینه غیرفعال کردن حساب های ربات در صورت غیرفعال شدن مالک (ServiceSettings.DisableBotsWhenOwnerIsDeactivated، که به‌طور پیش‌فرض فعال است) ربات را غیرفعال می‌کند اگر حساب مالک آن غیرفعال شود.

ساخت ربات

منوی تیم را باز کنید، سپس روی تنظیمات تیم کلیک کنید، در انتهای تب‌های آن روی ادغام ها کلیک کنید، سپس حساب‌های ربات و اضافه کردن حساب ربات را انتخاب کنید.
یک نام کاربری وارد کنید (حروف کوچک، اعداد، نقطه، خط تیره و زیرخط)، و در صورت نیاز یک نماد ربات، یک نام نمایشی و یک شرح.
نقش را انتخاب کنید: عضو، یا مدیر سیستم برای رباتی که سرور را مدیریت می‌کند. کمترین دسترسی مورد نیاز را به ربات بدهید.
گزینه پست: کانال ها را تیک بزنید تا بتواند در تمام کانال‌های عمومی پیام بفرستد، یا پست: همه را برای تمام کانال‌ها، از جمله کانال‌های خصوصی و پیام‌های مستقیم، بدون نیاز به عضویت.
زمان انقضای توکن پیش‌فرض را تنظیم کنید، سپس ایجاد حساب ربات را انتخاب کنید.
توکن دسترسی نمایش‌داده‌شده را کپی کنید. دیگر نمایش داده نمی‌شود.

بعداً، با کلیک روی ایجاد توکن جدید در ردیف ربات، توکن اضافه می‌شود و هر توکن می‌تواند غیرفعال یا حذف شود. توکن‌های ربات حتی زمانی که توکن‌های دسترسی شخصی برای افراد غیرفعال شده باشند، کار می‌کنند.

یک ربات می‌تواند ویژگی‌های سرور (همان ویژگی‌هایی که در کنسول سیستم › ویژگی‌های سیستم تنظیم شده‌اند) را داشته باشد. این ویژگی‌ها را می‌توان در فرم افزودن/ویرایش ربات یا از طریق ویرایش ویژگی‌ها… در منوی ⋯ ربات تنظیم کرد. هر کسی که ربات را مدیریت می‌کند می‌تواند آن‌ها را تنظیم کند: مالک ربات با مجوز مدیریت ربات‌ها، یا هر کسی با مجوز مدیریت ربات‌های دیگران؛ برای ویژگی‌های مدیریت‌شده توسط مدیر سیستم، همچنان نیاز به یک مدیر سیستم است. از آنجایی که ربات یک عامل هوش مصنوعی متعلق به هیچ‌کس نیست، تنها کسی با مجوز مدیریت ربات‌های دیگران یا یک مدیر سیستم می‌تواند ویژگی‌های آن را تنظیم کند.

با 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'"}'

ربات دارای پست: کانال ها یا پست: همه می‌تواند بدون عضویت پیام بفرستد، اما فقط رویدادهای 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 نیاز دارد که به طور پیش‌فرض فقط مدیران سیستم آن را دارند. یکپارچه‌سازی‌ها معمولاً پیام‌های موقتی را به عنوان پاسخ به دستورات اسلش و دکمه‌ها ارسال می‌کنند.

عامل‌ها

یک عامل، حساب رباتی از نوع agent است: کاربران دارای "is_agent": true هستند، ربات‌ها دارای "kind": "agent" هستند، و رابط کاربری به جای برچسب BOT، برچسب AGENT را نشان می‌دهد. عامل‌ها فقط توسط مدیران سیستم (عامل‌های در سطح سرور) در کنسول سیستم › هوش مصنوعی › اتصالات مدل، و مدیران تیم (عامل‌های تیم خودشان) در تب هوش مصنوعی تنظیمات تیم، یا با استفاده از /api/v4/ai/agents (به API مراجعه کنید) ساخته می‌شوند. رباتی که با POST /bots یا توسط یک برنامه ساخته می‌شود، همیشه یک ربات معمولی است.

پاسخ یک عامل داخلی توسط سرور و با استفاده از یک اتصال مدل داده می‌شود. یک عامل خارجی متعلق به شماست و باید خودتان آن را اجرا کنید: برنامه‌ای در جای دیگر (مثلاً یک عامل کدنویسی روی یک پروژه) که به عنوان عامل وارد می‌شود و مانند یک انسان پاسخ می‌دهد. Antimatter پاسخی برای آن ارائه نمی‌دهد.

وضعیت یک عامل داخلی توسط سرور تعیین می‌شود: آنلاین زمانی که اتصال مدل آن پاسخ می‌دهد، غایب زمانی که پاسخ نمی‌دهد (از کار افتاده، زمان‌پاسخ‌دهی به پایان رسیده، یا کلید رد شده است)، و آفلاین زمانی که خاموش است یا اتصال یا مدل قابل استفاده‌ای ندارد. این وضعیت زمانی بررسی می‌شود که عامل یا اتصال آن تغییر کند، زمانی که یک اتصال آزمایش می‌شود، در هر فراخوانی مدل عامل، و هر ۱۰ دقیقه یک‌بار. هیچ‌کس نمی‌تواند وضعیت یک عامل داخلی را تنظیم کند: PUT /users/{id}/status و نقاط پایانی وضعیت سفارشی با 403 (api.status.agent.app_error) پاسخ می‌دهند، حتی برای مدیران سیستم، و UpdateUserStatus، SetUserStatusTimedDND، UpdateUserCustomStatus و RemoveUserCustomStatus در API افزونه نیز به همان شکل آن را رد می‌کنند. وضعیت یک عامل خارجی بر اساس اتصال خودش تعیین می‌شود و تنها توکن خودش می‌تواند آن را تغییر دهد.

اجرای یک عامل خارجی

یک مدیر عامل را در کنسول سیستم › هوش مصنوعی › اتصالات مدل (یا در تب هوش مصنوعی یک جامعه) با نوع عامل خارجی اضافه می‌کند و مشخص می‌کند چه کسانی می‌توانند با آن صحبت کنند. سپس صفحه نحوه اتصال به آن را نشان می‌دهد.
به آن یک توکن بدهید: یک مدیر سیستم ادغام ها › حساب‌های ربات را باز می‌کند، حساب عامل را پیدا می‌کند و ایجاد توکن جدید را انتخاب می‌کند، یا با استفاده از شناسه کاربری عامل، API توکن‌ها را فراخوانی می‌کند:
```
curl -X POST https://chat.example.com/api/v4/users/$AGENT_USER_ID/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"description": "agent"}'
```
برنامه API را فراخوانی می‌کند و WebSocket را با Authorization: Bearer <token> باز می‌کند، اشاره‌ها و پیام‌های مستقیم خود را از رویدادهای posted می‌خواند و با POST /posts در رشته پیام پاسخ می‌دهد.

با تنظیم فعالیت خود، به افراد نشان می‌دهد که چه کاری انجام می‌دهد:

curl -X PUT https://chat.example.com/api/v4/ai/agents/$AGENT_USER_ID/activity \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"state": "working", "text": "Running the tests", "thread_post_id": "'$ROOT_ID'"}'

شناسه عامل در این مسیرها همان شناسه کاربری آن است. توکن را محرمانه نگه دارید: هر کسی که آن را داشته باشد می‌تواند به عنوان عامل پست بگذارد.

فعالیت

state: idle، thinking، working، waiting (برای کسی)، blocked یا offline. حالت‌های مشغول (thinking، working، waiting، blocked) پس از expires_in_seconds به idle بازمی‌گردند: به طور پیش‌فرض ۱۰ دقیقه، حداکثر ۲۴ ساعت.
text: چند کلمه درباره وظیفه، حداکثر یک خط با ۲۰۰ کاراکتر. رابط کاربری آن را در لیست اعضا و روی کارت مشخصات نشان می‌دهد.
thread_post_id: رشته‌ای که در آن کار می‌کند و برنامه باید بتواند آن را بخواند. این شناسه تنها به کسانی داده می‌شود که اجازه خواندن آن را دارند.

چه کسی می‌تواند ببیند که عامل فعالیت خود را می‌خواند (GET /ai/agents/{agent_id}/activity، یا POST /ai/agents/activity/ids با فهرستی از شناسه‌ها) و رویداد WebSocket agent_activity_changed را بدون رشته دریافت می‌کند. عوامل داخلی فعالیت خود را به صورت خودکار تنظیم می‌کنند.

در حالی که یک عامل داخلی پاسخ خود را می‌نویسد، سرور متن در حال رشد را در رویدادهای agent_post_stream به کانال ارسال می‌کند: post_id، channel_id، root_id، user_id، message (متن تا این لحظه) و control (start، text، end، error یا cancel). رویداد post_edited پیام نهایی را می‌آورد. کلاینت‌هایی که استریم را نادیده می‌گیرند، پاسخ را پس از ذخیره شدن می‌بینند.

پیام‌های تعاملی: دکمه‌ها و منوها

هر پیامی که پیوست داشته باشد می‌تواند اقدامات را در بر بگیرد: دکمه‌ها و منوها برای انتخاب. این‌ها در پیام‌هایی که با 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 برای باز شدن.
بدنه خالی هیچ تغییری ایجاد نمی‌کند.

سرور تا زمانی که مهلت انتظار درخواست یکپارچه‌سازی اجازه می‌دهد (به‌طور پیش‌فرض ۳۰ ثانیه) صبر می‌کند. آدرس‌های 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`	یک تاریخ، یا تاریخ و ساعت.
`action_button`	دکمه‌ای که به صورت مستقل از ارسال گفتگو، `action_button_url` را فراخوانی می‌کند. `help_text` آن در زیر دکمه نمایش داده می‌شود.
`collapsible`	یک گروه تاشو از عناصر. با `sub_type: "grid"`، کانتینرهای فرزند آن به صورت جدول چیده می‌شوند به جای اینکه روی هم قرار بگیرند: هر کانتینر یک ردیف است و عناصر خودِ آن سلول‌های آن ردیف هستند.

هر عنصر display_name، name، help_text، placeholder، default و optional می‌پذیرد.

submit_buttons در گفتگو، نام یک عنصر select ثابت را مشخص می‌کند: گزینه‌های آن به عنوان دکمه‌های ارسال گفتگو عمل می‌کنند، به ازای هر گزینه یک دکمه، به جای یک دکمه ارسال واحد، و خودِ آن select نمایش داده نمی‌شود. size («small»، «medium» یا «large»؛ اگر وارد نشود «small» است) درخواست گفتگوی پهن‌تر را می‌کند. refresh_on_return (نیازمند source_url) پس از بسته شدن گفتگویی که روی این گفتگو باز شده است، گفتگو را از source_url دوباره واکشی می‌کند تا تغییرات را نشان دهد. size یا sub_type ناشناخته مانع از باز شدن گفتگو نمی‌شود: به حالت پیش‌فرض برمی‌گردد و سرور فقط آن را در لاگ ثبت می‌کند.

وقتی شخص فرم را ارسال می‌کند، 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 ارسال می‌کند. جعبه‌های گفتگو در اپ‌ها به همان شیوه کار می‌کنند: OpenInteractiveDialog در API افزونه همان درخواست را می‌پذیرد.