บอทและข้อความอันตรกัม

บัญชีบอทคือผู้ใช้ท่ีสร้างขึ้่นเพือ่ โปรแกรม ท่ีมีชื่อบุคคล หน้าผุ้ใช้ และโทเคนเป็นของตัวเอง และแสดงแท็ก BOT ข้างชื่อบุคคล หน้านี้ยงั ครอบคลุมส่วนท่ีมีปฏิสัมพันธ์ในข้อความ: ปุ่้ม เมนู และไดอะล็อก ท่ีการรวมระบบ (integration) ใด ๆ สามารถใช้งานได้

เหตุใดจึงต้องใช้อะคเคาน์บอท

ข้อความท่ีส่งมาจากบอทจะมี BOT แสดงไว้ ชัดเจนว่ามาจากบอท ไมใช่จากแอคเคาน์ของสมาชิกในทีม
โทเคนของบอทยังคงทำงานได้แม้ผู้ตั้้งค่าจะเปลี่่ยนบทบาทหรือออกจากทีม (ยกเว้นแต่ว่าเซิร์ฟเวอร์จะปิดบอทของผู้ดู้แลระบบท่ีไม่ได้ออกใช้งานแล้ว ดูข้้อมูลเพิ่่มเติมข้่าล่าง)
บอทไม่สามารถลงชื่อเข้้าด้วยรหัสผ่าน และจะไม่เคยเห็นแอปบนเว็บ

แอปสร้างบอทของตัวมันเอง เช่น บอท Todo หรือ Playbooks ผ่าน plugin API (EnsureBotUser).

เปิดใช้งานบัญชีบอท

ผู้ดูลำดับระบบเปิดใช้เปิดใช้งานการสร้างบัญชีบอท ในคอนโซลระบบ › อินทิเกรชัน › บัญชีบอท (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"}'

จากบรรทัดคำสั่ง (command line) โดยเข้าสู่ระบบในฐานะผู้ดูลำดับ (not in local mode): 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 events เฉพาะช่องท่ีอยู้ในเท่านั้่น

โพสต์ในนามของบอท

ใชโทเคนของบอทกบัคำสั่ง API ใด ๆ; POST /api/v4/posts เป็นท่ีใชบ่อยท่ีสุด (ดู Main resources). เพื่อบันทึกข้่อความส่วตัวกบัใครบางคน ใหเปิ่ดข้่อความส่วตัวก่่อน:

# 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 events ท่ีคุณสนใจ ใหละเลยข้่อความของบอทเองเพื่่อหลีกเลี่ยงลูป

ข้่อความท่ีมีเพีงคนเดีียวท่ีจะเห็น (ephemeral message) ส่งผาน POST /api/v4/posts/ephemeral และ {"user_id", "post": {"channel_id", "message"}}. ต้องมี create_post_ephemeral permission ท่ีโดยพื้่นฐานมีเพีงผู้ดูลำดับระบบเท่านั้่น การบูรณาการโดยพื้่นฐานจะส่ง ephemeral messages เป็นคำตอบกบัคำสั่งสแลชและปุ่ม

ข้่อความอันตفاع: ปุ่มและเมนู

ข้่อความใด ๆ ท่ีมีไฟล์แนบสามารถมื้่อการ: ปุ่ม และเมนูเพื่่อเลืกได้ ใชงานในข้่อความท่ีโพสต์ผาน 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, หรือสี hex.
options (เมนู), หรือ data_source: users หรือ channels เพื่่อเลืกคนหรือช่อง. default_option เลืกค่าไว้ก่่อน.
integration.url: ที่อยู่ปลายทางที่คำขอจะถูกส่งไป แอป (ปลั๊กอิน) สามารถใช้เส้นทาง (route) ของตัวเองได้ เช่น /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 ที่ต้องการเปิด
หากส่ง body ว่างเปล่า จะไม่มีการเปลี่ยนแปลงใด ๆ

เซิร์ฟเวอร์จะรอตามTimeout สำหรบัคำขอ Integration (30 วินาทีโดยค่าเริ่มต้น) URL ของ Integration ที่อยู่บนเครือข่ายส่วนตัวต้องได้รับอนุญาตจากผู้ดูลำดับระบบ เช่นเดียวกับเว็บฮุค

ไดอะล็อก

ไดอะล็อกคือแบบฟอร์มที่เปิดทับหน้าแชท คุณสามารถเปิดไดอะล็อกได้เฉพาะเมื่อเป็นคำตอบต่อสิ่งที่ผู้ใช้เพิ่งทำไป เช่น คำสั่งสแลช (slash command) หรือการกดปุ่ม เนื่องจากจำเป็นต้องใช้ trigger_id จากคำขอนั้น trigger_id จะใช้งานได้จนกว่าจะหมดเวลาตาม Integration request timeout

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`	ช่องทำเครื่องหมาย (checkbox)
`radio`	ตัวเลือกเดียวจาก `options`
`date`, `datetime`	วันที่ หรือวันที่และเวลา

ทุกองค์ประกอบรองรับ 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
}

ตอบกลับด้วย body ว่างเปล่าเพื่อปิดไดอะล็อก หรือเปิดไว้และแสดงว่าอะไรผิดพลาด:

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

{"error": "…"} จะแสดงข้อความสำหรับทั้งแบบฟอร์ม หากใช้ notify_on_cancel การปิดไดอะล็อกจะส่ง "cancelled": true ไดอะล็อกทำงานในแอปด้วยวิธีเดียวกัน: OpenInteractiveDialog ในปลั๊กอิน API รับคำขอในรูปแบบเดียวกัน