ボットとインタラクティブメッセージ

ボットアカウントは、プログラム用に作成されたユーザーです。独自の名称、アイコン、トークンを有し、名称の横にBOTタグが表示されます。このページでは、メッセージのインタラクティブな要素であるボタン、メニュー、ダイアログについても扱います。これらはすべての統合で使用できます。

ボットアカウントを使用する理由

メッセージは、同僚のアカウントからではなく、BOTタグが付いた明確なアイデンティティから送信されます。
設定した担当者が役割を変更したり退社したりした場合でも、トークンは引き続き機能します（サーバーが非アクティブ化されたオーナーのボットを無効化する設定が有効な場合を除きます。詳細は後述）。
ボットはパスワードでサインインできず、Webアプリを表示することはありません。

アプリは、プラグインAPI（EnsureBotUser）を通じて、ToDoやプレイブックなどのボットを独自に作成します。

ボットアカウントを有効にする

システム管理者は、システムコンソール › 統合機能 › ボットアカウント で Botアカウントの作成を有効にする をオンにします（ServiceSettings.EnableBotAccountCreation、AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION）。デフォルトではオフです。ボットの作成はシステム管理者のみ可能ですが、権限設定で他のロールにも許可を与えることができます。

同じページにある オーナーが無効化された際にBotアカウントを無効化する（ServiceSettings.DisableBotsWhenOwnerIsDeactivated、デフォルトでオン）を有効にすると、オーナーのアカウントが無効化された際にボットも無効化されます。

ボットの作成

右上のアバターを開き、統合機能 › ボットアカウント、次に Botアカウントを追加する を選択します。
ユーザー名（小文字、数字、ピリオド、ダッシュ、アンダースコア）を入力し、必要に応じて Botアイコン、表示名、説明を入力します。
ロールを選択します：メンバー、またはサーバーを管理するボットの場合はシステム管理者。ボットには必要な最小限の権限のみを付与してください。
投稿:チャンネル にチェックを入れると、すべての公開チャンネルに投稿できるようになります。投稿:全て を選択すると、メンバーでなくてもすべてのチャンネル、非公開チャンネル、ダイレクトメッセージに投稿できます。
デフォルトトークンの有効期限を設定し、Botアカウントを作成する を選択します。
表示されたアクセストークンをコピーします。再度表示されることはありません。

後日、ボットの行で新しいトークンを作成を選択するとトークンを追加でき、各トークンを無効化または削除できます。ボットのトークンは、個人のアクセストークンが人間に対して無効化されている場合でも機能します。

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 イベントに回答します。ループを避けるため、ボット自身のメッセージは無視してください。

1人のユーザーのみが見られるメッセージ(一時的なメッセージ)は、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、または16進カラーコード。
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`	1行フィールド。`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` からの1つの選択。
`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 は同じリクエストを受け取ります。