機器人与互动消息

机器人账号是专为程序建立的用户。它拥有独立的使用者名称、头像与令牌，并在名称旁显示「BOT」标签。本页也涵盖消息的互动元素：按钮、菜单与对话框，任何整合皆可使用。

为何使用机器人账号

其消息来自明确的身份，并带有 機器人 标签，而非来自同事的账号。
即使建立者变更角色或离开，其令牌仍可继续运作（除非伺服器停用已停权拥有者的机器人，详见下文）。
机器人无法使用密码登入，也永远不会看到网页应用。

应用程式会通过插件 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"}'

從命令列以管理員身分登入（非本地模式）：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、Webhook 和斜線指令回應發布的訊息。當有人使用其中一個操作時，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 必須經過系統管理員允許，如同 Webhook 一樣。

對話框

對話框是覆蓋在聊天視窗上的表單。您只能在回應使用者剛執行的動作（例如斜線指令或按鈕）時開啟它，因為它需要該請求的 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`，或帶有 `data_source_url` 的 `dynamic`。`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 接受相同的請求。