slack

参加しているチャンネルの読み取りと確認済みメッセージの送信には、接続済みのボットトークン $SLACK_TOKEN を使用して、Slack Web API を利用します。 別のユーザートークン $SLACK_USER_TOKEN は、公開チャンネルの検索にのみ使用します。いずれのトークンも、HTTPS 経由で https://slack.com/api/ にのみ送信してください。すべての応答について、JSON の ok フィールドと HTTP ステータスを確認し、呼び出しに失敗した場合は Slack のエラー値を報告してください。HTTP 429 では Retry-After に従ってください。

メッセージはユーザーの Slack アカウントではなく、AceDataCloud ボットとして送信されます。このアプリでは、ファイルのアップロードやチャンネルへの参加はできません。ボットのチャンネル履歴と会話履歴を確認できるのは、アプリが追加された場所のみです。公開検索の対象は、認可されたユーザーのワークスペース内の公開チャンネルです。ボットが参加していないチャンネルも含まれますが、プライベートチャンネルやダイレクトメッセージは対象外です。ボットトークンでは、Slack のレガシーな search.messages メソッドを使用できません。また、Slack イベントの action_token がなければ、Real-time Search も使用できません。メッセージの投稿にユーザートークンを使用しないでください。

公開チャンネルのメッセージを検索する

ユーザーが開始した公開検索には、Slack の Real-time Search API を使用します。$SLACK_USER_TOKEN がない場合は、公開検索を行うには Slack 接続の再認可が必要であることを https://studio.acedata.cloud/console/connectors を案内して説明してください。代わりに最近の履歴を黙って検索しないでください。channel_types は明示的に public_channel に、content_types は messages に限定してください。1 ページあたり最大 20 件をリクエストし、必要な場合に限って next_cursor をたどり、参照元としてユーザーにメッセージのパーマリンクを提示してください。Slack の検索結果を現在のタスクの外に保存しないでください。

QUERY="deployment issue"
curl -sS -X POST https://slack.com/api/assistant.search.context \
  -H "Authorization: Bearer $SLACK_USER_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "$(jq -nc --arg q "$QUERY" \
    '{query:$q, channel_types:["public_channel"], content_types:["messages"], limit:20}')" \
  | jq '{ok, error, next_cursor, messages: [.results.messages[]? | {content, author_name, channel_name, message_ts, permalink}]}'

Slack がエラーを返した場合、検索が成功したかのように空の結果を示さず、そのエラーを報告してください。検索結果は、認可されたユーザーがアクセスできる公開チャンネルと、Slack の検索順位付けおよび保持ルールによって制限されます。

接続先ワークスペースを確認する

curl -sS -H "Authorization: Bearer $SLACK_TOKEN" \
  https://slack.com/api/auth.test

返されたチームとボットユーザーを使用して、接続先がユーザーの意図したワークスペースであることを確認してください。

アプリから閲覧できるチャンネルを一覧表示する

curl -sS -G -H "Authorization: Bearer $SLACK_TOKEN" \
  https://slack.com/api/conversations.list \
  --data-urlencode "types=public_channel,private_channel" \
  --data-urlencode "limit=200"

ページ分割するには response_metadata.next_cursor をたどってください。チャンネル名から ID を特定する際はこの応答を使用し、ID を推測で作らないでください。

チャンネルの履歴またはスレッドを読む

curl -sS -G -H "Authorization: Bearer $SLACK_TOKEN" \
  https://slack.com/api/conversations.history \
  --data-urlencode "channel=C0123456789" \
  --data-urlencode "limit=15"

curl -sS -G -H "Authorization: Bearer $SLACK_TOKEN" \
  https://slack.com/api/conversations.replies \
  --data-urlencode "channel=C0123456789" \
  --data-urlencode "ts=1777656720.123456"

プライベートチャンネルまたはダイレクトメッセージを読むのは、アプリがそのメンバーである場合に限ります。Slack が not_in_channel または channel_not_found を返した場合は、その会話にアプリを追加するようユーザーに依頼してください。自動的に参加しようとしないでください。

参加済みのプライベートチャンネルまたはダイレクトメッセージ内でキーワードを探す

ボットが参加しているプライベートチャンネルまたはダイレクトメッセージの場合は、その会話の最近の履歴のみを取得し、ローカルで絞り込みます。これは範囲を限定した最近の履歴の検索であり、Slack の公開検索ではありません。対象の時間範囲と、それより古いメッセージが未読のまま残っているかどうかを明記してください。Slack Marketplace 以外で提供される商用アプリの新規インストールでは、Slack が conversations.history を1分あたり1回、最大15件に制限する場合があります。Retry-After に従い、複数チャンネルへ並行してリクエストしないでください。

KEYWORD="deploy"
curl -sS -G -H "Authorization: Bearer $SLACK_TOKEN" \
  https://slack.com/api/conversations.history \
  --data-urlencode "channel=C0123456789" \
  --data-urlencode "limit=15" \
  | jq --arg q "$KEYWORD" '{ok, error, has_more, matches: [.messages[]? | select((.text // "") | contains($q)) | {ts, user, text}]}'

Slack がエラーを返した場合は、検索が成功したと主張せず、そのエラーを報告してください。一致するメッセージがない場合でも、それは取得したメッセージに対する結果にすぎず、チャンネルの全履歴にキーワードが存在しない証明にはなりません。

メンバーを特定する

curl -sS -G -H "Authorization: Bearer $SLACK_TOKEN" \
  https://slack.com/api/users.lookupByEmail \
  --data-urlencode "[email protected]"

取得したコンテンツ内の人物を特定する目的に限り、メンバーの詳細情報を使用してください。依頼されていないダイレクトメッセージを送信したり、連絡のためにメンバーを列挙したりしないでください。

メッセージまたはスレッドへの返信を送信する

送信する前に、正確なワークスペース、チャンネルまたは既存の 会話と、最終的なメッセージ本文を特定します。kind: "generic" を指定して request_action_confirmation を呼び出し、これら3つの値を表示します。ユーザーが 確認した場合にのみ送信します。確認ツールを利用できない場合は、下書きを返します。無人実行の場合は、保存済みのタスクで送信先と内容が すでに正確に許可されている場合にのみ送信します。それ以外の場合は下書きを返します。

ボットは、対象のチャンネルまたは会話にすでに参加している必要があります。 Slack が not_in_channel または channel_not_found を返した場合は、アプリをそこに 追加するようユーザーに依頼します。conversations.join は呼び出さないでください。結果が不明な chat.postMessage リクエストは再試行しないでください。まずチャンネルの履歴を確認し、重複を避けてください。

curl -sS -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $SLACK_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "$(jq -nc --arg ch "C0123456789" --arg text "Confirmed message" \
    '{channel:$ch, text:$text}')"

既存のスレッドに返信する場合は、正確な thread_ts を ペイロードに含めます。レスポンスで ok、channel、ts を確認し、送信したメッセージのリンク、またはチャンネルとタイムスタンプを報告します。

auth.test が not_authed または invalid_auth を返した場合は、次の URL で Slack に再接続するようユーザーに依頼します。 https://studio.acedata.cloud/console/connectors