Bot và tin nhắn tương tác

Tài khoản bot là người dùng dành cho chương trình. Nó có tên, ảnh đại diện và token riêng, và hiển thị thẻ BOT cạnh tên. Trang này cũng bao gồm các phần tương tác của tin nhắn: nút, menu và hộp thoại, mà bất kỳ tích hợp nào cũng có thể sử dụng.

Tại sao cần tài khoản bot

Tin nhắn của nó đến từ một danh tính rõ ràng, có thẻ BOT, thay vì từ tài khoản của đồng nghiệp.
Token của nó tiếp tục hoạt động khi người thiết lập thay đổi vai trò hoặc rời đi (trừ khi máy chủ vô hiệu hóa bot của chủ sở hữu đã bị vô hiệu hóa, xem bên dưới).
Bot không thể đăng nhập bằng mật khẩu và không bao giờ thấy ứng dụng web.

Ứng dụng tạo bot của riêng chúng, chẳng hạn như bot Todo hoặc Playbooks, thông qua API plugin (EnsureBotUser).

Bật tài khoản bot

Quản trị viên hệ thống bật Bật Tạo tài khoản Bot trong Bảng điều khiển Hệ thống › Tích Hợp › Tài khoản Bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Tùy chọn này tắt mặc định. Chỉ quản trị viên hệ thống có thể tạo bot, trừ khi họ cấp quyền này cho các vai trò khác trong cài đặt phân quyền.

Trang đó cũng có tùy chọn Tắt account bot khi chủ sở hữu không hoạt động (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, bật mặc định), giúp tắt bot khi tài khoản của chủ sở hữu bị vô hiệu hóa.

Tạo bot

Mở ảnh đại diện của bạn ở góc trên bên phải, sau đó chọn Tích Hợp › Tài khoản Bot, rồi chọn Thêm tài khoản Bot.
Nhập Tên người dùng (chữ thường, số, dấu chấm, dấu gạch ngang và dấu gạch dưới), và tùy chọn thêm Biểu tượng Bot, Tên Hiển Thị và Mô tả.
Chọn Vai trò: Thành viên, hoặc Quản trị viên hệ thống cho bot quản lý máy chủ. Chỉ cấp cho bot những quyền tối thiểu cần thiết.
Đánh dấu post: channel để bot có thể đăng bài trong mọi kênh công khai, hoặc post: all để đăng trong mọi kênh, bao gồm kênh riêng tư và tin nhắn trực tiếp, mà không cần là thành viên.
Đặt thời gian hết hạn cho token mặc định, sau đó chọn Tạo tài khoản Bot.
Sao chép token truy cập được hiển thị. Nó sẽ không được hiển thị lại.

Sau này, chọn Tạo Token Mới trên dòng của bot để thêm token, và mỗi token có thể bị vô hiệu hóa hoặc xóa. Token của bot vẫn hoạt động ngay cả khi token truy cập cá nhân bị tắt cho người dùng.

Với 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"}'

Từ dòng lệnh, đăng nhập với tư cách quản trị viên (không ở chế độ cục bộ): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Các điểm cuối khác: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable và /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} để thay đổi chủ sở hữu.

Thêm bot vào các cộng đồng và kênh

Một bot mới không thuộc cộng đồng nào. Hãy thêm nó như một người dùng, từ quản lý thành viên của cộng đồng hoặc qua 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'"}'

Bot có quyền post: channel hoặc post: all có thể đăng bài mà không cần là thành viên, nhưng chỉ nhận sự kiện WebSocket cho các kênh mà nó đã tham gia.

Đăng bài với tư cách bot

Sử dụng token của bot cho bất kỳ lời gọi API nào; POST /api/v4/posts là phổ biến nhất (xem Tài nguyên chính). Để gửi tin nhắn trực tiếp cho ai đó, hãy mở kênh tin nhắn trực tiếp trước:

# 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'"]'

Để phản ứng với những gì mọi người nói, hãy theo dõi WebSocket bằng token của bot và trả lời các sự kiện posted mà bạn quan tâm. Bỏ qua các tin nhắn của chính bot để tránh lặp vô hạn.

Tin nhắn chỉ một người có thể xem (tin nhắn tạm thời) được gửi bằng POST /api/v4/posts/ephemeral và {"user_id", "post": {"channel_id", "message"}}. Nó cần quyền create_post_ephemeral, mặc định chỉ quản trị viên hệ thống có. Các tích hợp thường gửi tin nhắn tạm thời như câu trả lời cho lệnh gạch chéo và nút bấm.

Tin nhắn tương tác: nút và menu

Bất kỳ tin nhắn nào có tệp đính kèm đều có thể chứa các hành động: nút, và menu để chọn. Chúng hoạt động trong các tin nhắn được đăng qua API, webhook và câu trả lời cho lệnh gạch chéo. Khi ai đó sử dụng một hành động, Antimatter sẽ gọi URL của tích hợp của bạn.

{
  "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 hoặc select.
id: chữ cái, số, dấu gạch ngang và dấu gạch dưới, phải khác nhau cho mỗi hành động của tin nhắn. Nó sẽ được tạo tự động nếu bạn bỏ trống.
style (nút): default, primary, success, good, warning, danger, hoặc một màu hex.
options (menu), hoặc data_source: users hoặc channels để chọn một người hoặc một kênh. default_option chọn trước một giá trị.
integration.url: nơi gửi yêu cầu khi người dùng nhấp. Ứng dụng (plugin) có thể sử dụng route riêng của mình, chẳng hạn /plugins/com.example.deploy/actions. integration.context do bạn định nghĩa: nó được gửi lại kèm theo cú nhấp và client không bao giờ nhìn thấy nó.

Yêu cầu mà tích hợp của bạn nhận được

{
  "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"}
}

Đối với menu, type là select và context.selected_option chứa giá trị đã chọn.

Câu trả lời của bạn

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

update: thay thế văn bản và thuộc tính của tin nhắn, ví dụ để xóa các nút sau khi sử dụng (một props trống).
ephemeral_text: tin nhắn chỉ người nhấp mới nhìn thấy.
goto_location: một URL để mở.
Thân yêu cầu trống sẽ không thay đổi gì.

Máy chủ sẽ chờ trong thời gian cho phép bởi Thời gian chờ yêu cầu tích hợp (mặc định là 30 giây). Các URL tích hợp trên địa chỉ mạng riêng phải được quản trị viên hệ thống cho phép, giống như với webhook.

Hộp thoại

Hộp thoại là một biểu mẫu mở trên khung trò chuyện. Bạn chỉ có thể mở nó như một phản hồi đối với hành động mà người dùng vừa thực hiện, một lệnh gạch chéo hoặc một nút, vì nó cần trigger_id của yêu cầu đó. trigger_id có hiệu lực trong suốt thời gian chờ yêu cầu tích hợp.

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"}
      ]
    }
  }'

Loại phần tử	Nội dung hiển thị
`text`	Trường một dòng. `subtype`: `text`, `email`, `number`, `password`, `tel` hoặc `url`. `min_length` và `max_length` giới hạn độ dài.
`textarea`	Trường nhiều dòng.
`select`	Danh sách: `options`, hoặc `data_source` là `users`, `channels`, hoặc `dynamic` kèm `data_source_url`. `multiselect` cho phép chọn nhiều giá trị.
`bool`	Hộp kiểm.
`radio`	Một lựa chọn trong số `options`.
`date`, `datetime`	Một ngày, hoặc ngày và giờ.

Mọi phần tử đều nhận display_name, name, help_text, placeholder, default và optional.

Khi người dùng gửi, Antimatter sẽ POST đến url của hộp thoại:

{
  "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
}

Trả lời bằng thân trống để đóng hộp thoại, hoặc giữ nó mở và hiển thị lỗi:

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

{"error": "…"} hiển thị thông báo cho toàn bộ biểu mẫu. Với notify_on_cancel, việc đóng hộp thoại sẽ gửi "cancelled": true. Hộp thoại hoạt động theo cách tương tự trong ứng dụng: OpenInteractiveDialog của API plugin nhận cùng một yêu cầu.