Mattermost

🟡 アウトバウンドはすぐ使用可能。インバウンドは outgoing webhook 経由でパブリックチャンネルのみ対応。 最も手軽な構成です。DM やプライベートチャンネルに対応した Mattermost の WebSocket bot モードは、今後追加予定の機能です。

できること

• アウトバウンドのテキスト送信: ボットの個人アクセストークンを使って POST /api/v4/posts を呼び出します。root_id によるスレッド返信にも対応しています。
• インバウンドの outgoing webhook: /webhooks/mattermost エンドポイントで受信します。設定したトリガーワードがパブリックチャンネルに投稿されると、Mattermost がこの URL に POST します。
• テキストのみ対応（本リリース時点）: Mattermost の Files API を使ったファイルアップロードや添付ファイルの解析は、今後対応予定です。
• テキスト上限は 16383 文字（Mattermost のデフォルト PostMessageMaxRunes に準拠）。

セットアップ

1. ボットアカウントの作成

1. Mattermost にシステム管理者としてサインインします
2. System Console → "Integrations" → "Bot Accounts" → "Add Bot Account" を選択します
3. ユーザー名（例: minara）、表示名、任意のアバターを設定します。保存するとボットの個人アクセストークンが表示されます。後から取得できないため、必ず控えておいてください
4. ボットを対象チャンネルに招待します: チャンネルのメッセージ入力欄に /invite @minara と入力して実行します

2. Outgoing webhook の設定（任意: インバウンドに必要）

1. 同じ画面の "Integrations" → "Outgoing Webhooks" → "Add Outgoing Webhook" を選択します
2. 以下の項目を設定します:
   • Channel: webhook が監視するパブリックチャンネル
   • Trigger words: @bot、!minara など（メッセージがこれらの文字列で始まった場合のみ webhook が発火します）
   • Callback URLs: https://<your-host>/webhooks/mattermost
3. 保存後、生成されたトークンをコピーします（MATTERMOST_OUTGOING_WEBHOOK_TOKEN として使用します）

3. Minara の設定

minara auth messaging add
# リストから `mattermost` を選択してください。

または、環境変数を直接設定します:

MATTERMOST_URL=https://mattermost.example.com
MATTERMOST_BOT_TOKEN=<personal access token>
MATTERMOST_DEFAULT_CHANNEL_ID=<channel id from Channel URL>
MATTERMOST_OUTGOING_WEBHOOK_TOKEN=<outgoing-webhook token>

チャンネル ID は、チャンネルを開いたときの URL から確認できます: https://mattermost.example.com/team/channels/<id> の <id> 部分がそれに該当します。

4. テスト

minara auth messaging test mattermost

インバウンド webhook

Mattermost の outgoing webhook は、/webhooks/mattermost に対して application/x-www-form-urlencoded 形式で POST します。送信されるフィールドは以下のとおりです:

token=<webhook token>
channel_id=<channel id>
user_id=<user id>
user_name=<username>
text=<the user's message>
post_id=<message id>
trigger_word=<matched trigger>
from_webhook=false

Minara は token フィールドを MATTERMOST_OUTGOING_WEBHOOK_TOKEN と定数時間で比較して検証します。from_webhook === "true" フラグは、ボット自身の投稿がトリガーを再び発火させる自己ループを防ぐために使用します。

制限事項と注意点

• Outgoing webhook はパブリックチャンネルでのみ発火します。 プライベートチャンネルや DM には WebSocket bot 経由のパスが必要です（実装予定）。アクティブなチャンネルで Agent に大量のリクエストが集中しないよう、トリガーワードを慎重に設定してください。
• トリガーワードはメッセージの先頭にある場合のみ有効です。 @bot hello は機能しますが、hello @bot は機能しません。
• 定数時間比較を使用しています（HMAC ではありません）。 インバウンドの認証はトークンのみで行っています。トークンはシークレットとして厳重に管理してください。
• ストリーミング編集には非対応です。 Mattermost には PUT /posts/<id> が存在しますが、現時点のゲートウェイには実装されていません。

トラブルシューティング

アウトバウンド送信時に "401 Unauthorized" が返る

• MATTERMOST_BOT_TOKEN が誤っているか、有効期限切れか、別のチームにスコープされています。System Console で新しいトークンを生成し、環境変数を更新してください。

"Outgoing webhook が発火しない"

• チャンネルがプライベート（パブリックチャンネルのみ対応）
• メッセージがトリガーワードで始まっていない
• webhook が別のチャンネルに設定されている

"インバウンドで 401 が返る"

• MATTERMOST_OUTGOING_WEBHOOK_TOKEN が一致していません。webhook を再作成するとトークンが更新されるため、環境変数と同期してください。

リファレンス

• 環境変数: MATTERMOST_*
• アウトバウンド: apps/agent/src/messaging/mattermost.ts
• インバウンド仕様: apps/agent/src/messaging/inbound/specs/mattermost.ts
• Mattermost インテグレーションガイド: docs.mattermost.com / Outgoing Webhooks