メインコンテンツへスキップ

​
概要

Channels API を使用すると、Shannon を外部メッセージングプラットフォームと統合できます。Channel を作成して Slack ワークスペースや LINE アカウントに接続すると、Shannon が Agent システムを通じて受信メッセージを自動的に処理します。

​
機能

  • Slack 統合 — イベントサブスクリプションと Bot メッセージングに対応
  • LINE 統合 — Webhook ベースのメッセージ処理
  • HMAC 署名検証 — インバウンド Webhook のセキュリティを確保
  • Agent ルーティング — agent_name 設定でメッセージを特定の Agent に転送
  • ユーザー分離 — ユーザーごとに type + name の組み合わせがユニーク
  • 認証情報の保護 — 認証情報は API レスポンスに含まれません

​
Channel の作成

新しいメッセージング Channel を作成します。 
curl -X POST http://localhost:8080/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "type": "slack",
    "name": "My Slack Channel",
    "credentials": {
      "signing_secret": "your-slack-signing-secret",
      "bot_token": "xoxb-your-bot-token",
      "app_id": "A0123456789"
    },
    "config": {
      "agent_name": "research-agent"
    }
  }'

​
リクエストボディ

フィールド型必須説明
typestringはいChannel タイプ："slack" または "line"
namestringはいChannel の表示名
credentialsobjectはいプラットフォーム固有の認証情報（下記参照）
configobjectいいえオプション設定（例：agent_name）

​
レスポンス

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "slack",
  "name": "My Slack Channel",
  "config": {
    "agent_name": "research-agent"
  },
  "enabled": true,
  "created_at": "2026-03-10T10:00:00Z",
  "updated_at": "2026-03-10T10:00:00Z"
}
セキュリティのため、credentials フィールドは API レスポンスに含まれません。認証情報はご自身のシステムで安全に保管してください。

​
Channel の一覧取得

認証済みユーザーの全 Channel を一覧表示します。 
curl http://localhost:8080/api/v1/channels \
  -H "Authorization: Bearer <token>"

​
レスポンス

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "type": "slack",
    "name": "My Slack Channel",
    "config": {
      "agent_name": "research-agent"
    },
    "enabled": true,
    "created_at": "2026-03-10T10:00:00Z",
    "updated_at": "2026-03-10T10:00:00Z"
  }
]

​
Channel の取得

特定の Channel の詳細を取得します。 
curl http://localhost:8080/api/v1/channels/{id} \
  -H "Authorization: Bearer <token>"

​
レスポンス

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "slack",
  "name": "My Slack Channel",
  "config": {
    "agent_name": "research-agent"
  },
  "enabled": true,
  "created_at": "2026-03-10T10:00:00Z",
  "updated_at": "2026-03-10T10:00:00Z"
}

​
Channel の更新

既存の Channel を更新します。すべてのフィールドはオプションです — 指定されたフィールドのみ更新されます。 
curl -X PUT http://localhost:8080/api/v1/channels/{id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Renamed Slack Channel",
    "config": {
      "agent_name": "financial-agent"
    },
    "enabled": false
  }'

​
リクエストボディ

フィールド型必須説明
namestringいいえ新しい Channel 名
credentialsobjectいいえ新しいプラットフォーム認証情報
configobjectいいえ新しい設定
enabledbooleanいいえChannel の有効化・無効化

​
レスポンス

更新された Channel オブジェクトを返します（Channel の取得と同じスキーマ）。

​
Channel の削除

Channel を完全に削除します。 
curl -X DELETE http://localhost:8080/api/v1/channels/{id} \
  -H "Authorization: Bearer <token>"

​
レスポンス

Response
{
  "message": "Channel deleted"
}
(HTTP 200 OK with JSON body)

​
インバウンド Webhook

外部プラットフォームからのメッセージを受信します。ユーザーが Slack や LINE でメッセージを送信すると、プラットフォームがこのエンドポイントを呼び出します。 
POST /api/v1/channels/{channel_id}/webhook
このエンドポイントは認証不要です。各プラットフォーム固有の HMAC 署名検証により、リクエストの正当性を確認します。

​
レスポンス

{
  "status": "dispatched"
}
Webhook はインバウンドリクエストを検証し、メッセージを抽出して、Shannon の Agent システムに非同期でディスパッチします。レスポンスは即座に返されます。

​
認証情報のフォーマット

​
Slack 認証情報

{
  "signing_secret": "your-slack-signing-secret",
  "bot_token": "xoxb-your-bot-token",
  "app_id": "A0123456789"
}
フィールド説明
signing_secretSlack アプリの Basic Information ページで確認できます
bot_tokenBot User OAuth Token（xoxb- で始まるもの）
app_idSlack アプリ ID

​
LINE 認証情報

{
  "channel_secret": "your-line-channel-secret",
  "channel_access_token": "your-line-channel-access-token"
}
フィールド説明
channel_secretLINE Developer Console の Channel 設定で確認できます
channel_access_tokenLINE Developer Console から取得した長期有効な Channel Access Token

​
Webhook の動作

​
Slack

  • 署名検証：Channel の signing_secret を使用して HMAC-SHA256 で X-Slack-Request-Timestamp と X-Slack-Signature ヘッダーを検証
  • クロックスキュー：5 分以上経過したリクエストは拒否されます
  • URL 検証：アプリ設定時に Slack の url_verification チャレンジに自動応答
  • Bot フィルタリング：ループ防止のため Bot からのメッセージは無視されます
  • 対応イベント：message と app_mention

​
LINE

  • 署名検証：Channel の channel_secret を使用して HMAC-SHA256（base64 エンコード）で X-Line-Signature ヘッダーを検証
  • 返信動作：Reply Token を使用して即座に “Thinking…” 返信を送信
  • メッセージ処理：イベントペイロードの最初のテキストメッセージを処理

​
Agent ルーティング

Channel の config で agent_name フィールドを設定して、受信メッセージを特定の Agent にルーティングします： 
{
  "config": {
    "agent_name": "research-agent"
  }
}
agent_name が未設定の場合、メッセージは Shannon のデフォルト Agent ルーティングで処理されます。

​
Channel レスポンスオブジェクト

フィールド型説明
idstring (UUID)Channel の一意識別子
user_idstring (UUID)所有ユーザー ID（オプション）
typestringChannel タイプ："slack" または "line"
namestringChannel の表示名
configobjectChannel 設定
enabledbooleanChannel が有効かどうか
created_atstring (ISO 8601)作成タイムスタンプ
updated_atstring (ISO 8601)最終更新タイムスタンプ

​
エラーレスポンス

ステータスエラー説明
400Invalid request必須フィールドの欠落または無効な Channel タイプ
401Unauthorized認証情報の欠落または無効
403Forbidden他のユーザーの Channel にアクセスできません
404Channel not found無効な Channel ID
409ConflictChannel の重複（同一ユーザー + タイプ + 名前）
500Internal server errorサーバー内部エラー
すべてのエラーは標準フォーマットに従います： 
{
  "error": "error message here"
}

​
次のステップ

タスクの送信

API から直接タスクを送信

エージェント

Channel ルーティング用の Agent を設定