Mattermost
本ドキュメントでは、MattermostをAgentic Engineに接続する方法を説明します。このチャネルは、Mattermost REST API v4でメッセージを送信・編集し、WebSocketでメッセージを受信します。ユーザーの身元の連携には、OAuth認証またはワンタイム連携コードを使用できます。
1. 前提条件
- Mattermostのシステム管理者権限を持ち、Bot Accountを作成できること。OAuthを使用する場合は、OAuth 2.0 Applicationも作成する必要があります。
- Agentic Engineの「システム管理 → チャンネル管理」の権限を持っていること。
- Botが使用できるTeamとChannelを用意していること。
- Agentic EngineのサーバーからMattermost Site URL、
/api/v4/**、/api/v4/websocketにアクセスできること。 - OAuth連携を使用する場合は、ユーザーのブラウザからアクセスできるAgentic EngineのURLを用意していること。本番環境ではHTTPSの使用を推奨します。
対応範囲：Mattermost Cloudとセルフホスト環境のどちらでも使用できます。Site URLにはデプロイ先のサブパスを含めることができます。
2. Mattermost Botを作成して認証情報を取得する
Mattermostのシステム管理者アカウントで、次の手順で操作します：
- System Console → Integrations → Bot Accounts に進み、Enable Bot Account Creation を true に設定します。
- Product menu → Integrations → Bot Accounts を開き、Add Bot Account をクリックします。
- Bot Username、Display Name、Descriptionを入力します。本番環境では通常のMember権限のままにし、最小権限の原則に従って権限を付与することを推奨します。
- Create Bot Account をクリックし、生成されたAccess Tokenをすぐにコピーします。
- 使用するTeamとChannelにBotを追加します。
Bot Tokenは一度しか表示されません。すぐに管理されたパスワード管理システムに保存し、コードリポジトリ、チケット、チャット履歴には書き込まないでください。Tokenが漏洩した場合は、Mattermostで取り消して再生成してください。
Botには少なくとも次の機能が必要です：
| 機能 | 用途 |
|---|---|
| 対象Channelの読み取り | ダイレクトメッセージ、チャンネル、非公開チャンネル、グループチャットのメッセージを受信します。 |
| Postの作成 | 通常の返信と最終結果を送信します。 |
| 自身が作成したPostの編集 | 同じPost内でストリーミング返信を表示します。 |
| ファイルの読み取りとアップロード | ユーザーの添付ファイルを処理し、Agentが生成したファイルを元のチャンネルと元のthreadに送り返します。 |
Mattermost Site URLを記録する
現在のMattermostサイトのURLを記録します。例：
https://chat.example.com
サイトがサブパスにデプロイされている場合は、次のように入力できます：
https://example.com/mattermost
/api/v4、クエリパラメータ、fragmentを付加したり、URLにユーザー名とパスワードを埋め込んだりしないでください。
3. OAuth 2.0アプリを作成する（任意）
OAuthは、Botがメッセージを送受信するための必須項目ではありません。OAuthをオフにしても、ユーザーは6桁のワンタイム連携コードで連携できます。ユーザーが入口をクリックしてそのまま認証・連携できるようにする場合は、続けて次の設定を行います：
- System Console → Integrations → Integration Management に進み、Enable OAuth 2.0 Service Provider を true に設定します。
- Product menu → Integrations → OAuth 2.0 Applications に進み、Add OAuth 2.0 Application をクリックします。
- Is Public Client を No に設定し、Confidential Clientを作成します。
- Is Trusted は No のままにし、ユーザーが初回連携時に認証を明示的に確認するようにすることを推奨します。
- Callback URLを入力し、保存後にClient IDとClient Secretを控えます。
Callback URLは、Agentic Engineの実際のアクセスURLと完全に一致している必要があります：
https://your-domain/agent/api/mattermost-oauth/callback
OAuthアプリはMattermostインスタンスごとに登録します。Client ID、Client Secret、Server URLは同じMattermostインスタンスのものである必要があり、インスタンスをまたいで再利用することはできません。
4. Agentic EngineでMattermostチャネルを追加する
管理者がAgentic Engineにログインし、「システム管理 → チャンネル管理」に進みます：
- 「新規チャンネル」をクリックし、チャンネルタイプで Mattermost を選択します。
- 次の設定項目を入力します。
| 構成項目 | 必須 | 説明 |
|---|---|---|
| チャンネル名 | 必須 | 表示名。例：「Mattermostボット」。 |
Server URL | 必須 | Mattermost Site URL。デプロイ先のサブパスを含めることはできますが、/api/v4は含めないでください。 |
Bot Token | 必須 | Bot Accountの作成後に生成されたAccess Token。 |
| OAuth 連携を有効にする | 任意 | オンにすると、ユーザーはブラウザでの認証を優先して使用します。オフにしてもワンタイム連携コードを使用できます。 |
OAuth Client ID | 条件付き必須 | OAuthを有効にする場合は必須です。 |
OAuth Client Secret | 条件付き必須 | OAuthを有効にする場合は必須です。 |
| デフォルトモデル | 任意 | 選択しない場合は、システム全体のデフォルトモデルを使用します。 |
| システムプロンプト | 任意 | このチャネルのAgent会話にのみ適用されます。 |
- 「保存」をクリックし、チャンネルの「有効」スイッチをオンにします。
- チャネルのステータスが正常であることを確認します。有効にすると、システムは
/api/v4/users/meを呼び出してBot TokenとBotの身元を検証し、その後<Site URL>/api/v4/websocketに接続します。
Secretの編集：既存のチャネルを編集する際、Bot TokenまたはOAuth Client Secretを空欄のままにすると、元の値が保持されます。保存済みのSecretはシステムに表示されません。
5. ユーザーがMattermostアカウントを連携する
方法1：OAuth認証による連携
- ユーザーがAgentic Engineにログインし、左下の個人メニューをクリックして Mattermost を選択します。
- ブラウザで、現在のMattermostインスタンスの認証ページが開きます。
- ユーザーがログインして認証を確認すると、ウィンドウが閉じ、メニューのステータスが「連携済」に変わります。
OAuth access tokenはコールバック処理中に一時的に使用されるだけで、データベースには書き込まれず、チャネル設定のBot Tokenを置き換えることもありません。
方法2：ワンタイム連携コード
OAuthがオンになっていない場合、またはシステムが認証URLを取得できない、認証URLが無効である、ブラウザが認証ウィンドウをブロックした場合は、自動的に連携コードが使用されます：
- 左下の個人メニューで Mattermost をクリックします。
- ポップアップに表示された連携コマンドをコピーします。
- MattermostでBotとのダイレクトメッセージを開き、そのコマンドを送信します。
- Botが連携成功を返信すると、Agentic Engineは連携ステータスを自動的に更新します。
+bind ABC234
連携コードの有効期間はデフォルトで10分間で、1回しか使用できません。漏洩を防ぐため、システムはチャンネルやグループチャットでの連携コマンドを受け付けません。同じMattermostアカウントを複数のAgentic Engineユーザーに同時に連携することはできません。
連携解除
- 左下の個人メニューをクリックし、Mattermostの行で「連携解除」をクリックします。
- 確認すると、ステータスが「未連携」に変わります。Agentic Engineアカウントを変更する場合は、先に元のアカウントの連携を解除してください。
6. 使い方
| シナリオ | 操作の説明 |
|---|---|
| プライベートチャット | Botに直接質問を送信します。 |
| 公開/非公開チャンネルとグループチャット | @Bot用户名 问题内容の形式で送信します。Botを@メンションしていない通常のメッセージは無視されます。 |
| スレッド | 既存のthreadで質問すると、返信はそのthreadに留まります。チャンネルのルートメッセージから質問すると、Botはそのメッセージをrootとしてthreadを作成して返信します。 |
| ユーザーの回答待ち | 「回答を入力」をクリックしてDialogを開くか、Botの案内に従って直接テキストで返信します。最大ラウンド数に達した場合は、「実行を続行」をクリックするか、「続行」と返信できます。 |
| Agentへの添付ファイル送信 | ダイレクトメッセージでは添付ファイルを直接送信できます。チャンネルでは、添付ファイル付きメッセージの本文でBotを@メンションする必要があります。 |
| Agentファイルの受信 | Agentが生成したファイルは、新しいPostとして元のチャンネルと元のthreadに送り返されます。 |
| タスク通知 | Agent Teamの即時タスクと定期タスクでは、Mattermostを選択できます。結果は、タスク作成者の連携済みアカウントへのダイレクトメッセージで送信されます。 |
よく使うコマンド
| コマンド | 説明 | 例 |
|---|---|---|
+bind <CODE> | ワンタイム連携コードでアカウントを連携します。 | +bind ABC234 |
+new | 新しい会話を開始します。 | +new |
+agent <Agent名称> <问题> | 指定したAgentにメッセージを送信します。 | +agent rhea 帮我分析数据 |
チャンネルでコマンドを使用する場合も、先に@Bot用户名を付ける必要があります。
7. トラブルシューティング
保存時に設定が無効と表示される
- Server URLは、完全な
http://またはhttps://のURLである必要があります。 /api/v4は入力せず、query、fragment、URLに埋め込んだ認証情報も含めないでください。- チャネルを新規作成する場合、Bot Tokenは空にできません。編集時に空欄のままにした場合のみ、元のTokenが保持されます。
チャネルを有効にした後、オフラインになる、または再接続を繰り返す
- 同じBot Tokenで
GET <Site URL>/api/v4/users/meをリクエストし、Botユーザーが返されることを確認します。 - Agentic EngineからMattermostへのDNS、TLS、ネットワーク接続を確認します。
- リバースプロキシが
/api/v4/websocketのWebSocket Upgradeを許可していることを確認します。 - Botが削除または無効化されておらず、Tokenが取り消しまたは再生成されていないことを確認します。
Botがチャンネルのメッセージを受信できない
- Botが対象のTeamとChannelに参加していることを確認します。
- 公開チャンネル、非公開チャンネル、グループチャットでは、
@Bot用户名で正しくメンションする必要があります。 - チャネルが有効になっており、正常な状態であることを確認します。
メッセージは受信できるが返信できない
- Botに対象ChannelでPostを作成する権限があることを確認します。
- ストリーミング返信を行うには、Botが自身の作成したPostを編集できる必要があります。
- 高度な権限スキームを使用している場合は、メンバーが自身の作成したPostを編集することが禁止されていないことを確認します。
添付ファイルのダウンロードまたはアップロードができない
- Botが対象Channelのメンバーであり、ファイルの読み取りとアップロードの権限を持っていることを確認します。
channel.mattermost.fileUploads.enabledが有効になっているか、またサイズ、数、タイムアウトの制限を確認します。- デフォルトでは、1件のメッセージにつき最大5個の添付ファイルを処理し、各ファイルは2 MiB以下である必要があります。拡張子、MIME、実際のファイル内容が一致しない場合は拒否されることがあります。
連携コードが無効
- 連携コードを再生成し、10分以内に使用します。
- コマンドが、現在のテナントに設定されたMattermost Botに送信されていることを確認します。
- 連携コマンドは、Botとのダイレクトメッセージでのみ送信できます。
OAuth認証に失敗する
- MattermostでOAuth 2.0 Service Providerが有効になっており、OAuth ApplicationがConfidential Clientを使用していることを確認します。
- Client ID、Client Secret、Server URLが同じMattermostインスタンスのものであることを確認します。
- Callback URLは、Agentic Engineの管理画面に表示されるURLと完全に一致し、実際のbasePathを含んでいる必要があります。
- Agentic EngineのOriginを
ALLOWED_ORIGINSに追加します。本番環境ではHTTPSを使用し、Cookieのセキュリティ設定がプロトコルと一致していることを確認します。 - ローカルからアクセスする場合は、
http://localhost:3000のように実際のブラウザのOriginを使用し、OAuth Callback URLに0.0.0.0を入力しないでください。
関連ページと次のステップ
- 他のプラットフォームの接続手順を確認する：チャンネル管理。
- チャネル接続と連携の全体的な流れを確認する：チャネルの概要と連携。
- 使用するAgentを設定する：Agent。
- プラットフォーム内での会話の使い方を確認する：会話。