event_type に応じて処理結果を返すか、auto_dialog シナリオでは指定した send_url へメッセージを自動送信します。MarsMind の管理画面と標準のチャット窓口だけを利用する場合は、ここから始める必要はありません。
このページが必要なとき
- 自社のアプリ、サポートシステム、メッセージチャネルがあり、標準のチャット窓口だけでなく MarsMind の対話機能を組み込みたい。
- 自社システムから呼び出した時点で、あるメッセージに対する AI の処理結果をリアルタイムに取得したい。
- コマンドでメッセージ処理を制御したい。たとえば特定シナリオの自動返信を停止する場合。
連携前の準備
このページに対応する管理画面のメニューはありません。リクエストは自社システムから送信するもので、セルフサービスでの申請もできません。呼び出しの前に、次の4つを準備してください。本番エンドポイント、client と secret、署名アルゴリズムの説明は MarsMind から提供されます（sales@marsmind.co までお問い合わせください）。連携するシナリオ（event_type）は業務に合わせて選択します：- 本番エンドポイント：例に登場する
{本番エンドポイント}が実際の接続先ドメインです。本ページでは固定値を記載しません。 - 認証情報：
client（業務識別子）とsecret。 - 署名アルゴリズム：
signatureの計算方法は MarsMind が提供する連携資料に準拠します。本ページでは詳しく扱いません。 - シナリオの確認：auto_dialog、assist_dialog、website_dialog、cmd_dialog の4つから1つを選びます。パラメータ要件と応答の動作はそれぞれ異なります。「対話シナリオの説明」を参照してください。
event_type も決まっていること。
認証について
すべてのリクエストにclient、signature、timestamp の3つのフィールドが必須です。いずれか1つでも欠かせません。signature のアルゴリズムは sales@marsmind.co までお問い合わせください。各フィールドの型と説明は、下記「リクエストパラメータ」の「リクエストボディ」表を参照してください。
この3つのフィールドに加えて、リクエストボディにはメッセージ内容を格納する message_info オブジェクトも必ず含めます。
リクエストパラメータ
リクエストボディ
message_info のフィールド
files_info の構造
対話シナリオの説明
auto_dialog（自動対話）
event_type = auto_dialogsend_urlを指定すると、以降のメッセージ送信は MarsMind が自動制御します- テキスト、画像、ファイルに対応（1回のリクエストにつき1種類のみ）
from_user_type の指定目安：
- 連携済みの対象：AI アシスタント自身のメッセージを除き、すべて1を指定します
- 未連携の対象：社外の顧客は2、自社の担当者は3を指定します
assist_dialog（アシスト対話）
- メッセージの処理結果をリアルタイムに返します
msg_idは必須です- パラメータが特定の auto_dialog メッセージと一致する場合、そのメッセージのコンテキストを再利用します
website_dialog（ウェブ対話）
- 結果を即時に返し、コンテキストに追加します
send_urlには対応していません
cmd_dialog（コマンド制御）
contentに具体的なコマンドを指定します。現在対応しているものは次のとおりです：stop_auto_reply：自動返信を停止します（auto_dialog シナリオでのみ有効）
呼び出し手順
1
本番エンドポイントと認証情報を取得する
sales@marsmind.co までお問い合わせのうえ、本番エンドポイント、client、secret、signature アルゴリズムの説明を取得します。この手順が完了するまでは、例に記載されたアドレスやプレースホルダーの値を実際の呼び出しに使用しないでください。判断の目安：本番エンドポイントのドメイン、client、secret、署名アルゴリズムの説明という4つが手元にあること。
2
シナリオを選び、message_info を組み立てる
まず
event_type を決め、上のフィールド表に沿って各項目を組み立てます。特に漏れやすいのは次の4点です：contentとfiles_infoのうち少なくとも一方を指定するmessage_typeが 2（引用メッセージ）の場合はquoteが必須で、quoteにmsg_idとmessage_typeを含めるfrom_user_idとgroup_idを同時に空にしない（どちらも空だとエラー400になります）- auto_dialog シナリオでは
from_user_typeも指定する
3
リクエストを送信する
リクエスト先は「本番エンドポイント + /custom-im/chat-messages」です。POST で送信し、判断の目安：assist_dialog と website_dialog は、応答でこのメッセージの処理結果をリアルタイムに返します。auto_dialog はリクエストが受け付けられると、MarsMind が
Content-Type: application/json を指定します。例の {本番エンドポイント} は取得したドメインに置き換えてください。client、signature、メッセージ ID などはすべてプレースホルダーです：send_url に従って自動送信するため、送信 API を手動で呼び出す必要はありません。4
管理画面で処理状況を確認する（任意）
メッセージがシステムに取り込まれたら、管理画面の明細データで今回の処理を確認できます。タブを「チャットデータ詳細」（AI と顧客の会話のみ）に切り替え、「集計ウィンドウ」と期間で絞り込み、「ユーザー問い合わせ」をクリックして「メッセージ処理チェーン」を開きます。「実行ステップ」「参照知識（N）」の2つのタブで順に照合してください。実行ステップは「当時の会話コンテキスト → グループチャットの処理 → 返信判定 → スキル呼び出し → ナレッジ生成 → 安全ガードレール」の順に表示されます。パネル上部の「返信の生成」「顧客への配信」「ガードレールによるブロック」の3つの証跡は独立して表示され、記録が取得できない項目は「不明」と表示されます。注意：絞り込みを変更した後は、「検索」をクリックしないと結果が更新されません。判断の目安：今回の呼び出しに対応するメッセージを特定でき、チェーンのどのステップまで進んだかを確認できます。ステップが欠けている場合は「実行ステップ」に直接表示されるため、どこで止まっているかを判断できます。
チェックポイント
- assist_dialog、website_dialog：応答でこのメッセージの処理結果が返ります。
- auto_dialog：
send_urlに MarsMind から送信されたメッセージが届いていれば、自動送信の経路は機能しています。 - コンテキストの再利用：assist_dialog のパラメータが特定の auto_dialog メッセージと一致する場合、処理はゼロからではなく、そのコンテキストを引き継ぎます。
- コマンド制御：cmd_dialog で
stop_auto_replyを送信すると、対応する自動返信が停止します。 - パラメータが受け付けられている：400が返らない（
from_user_idとgroup_idが同時に空の場合、400になります）。
注意事項
4つのシナリオの役割分担（送信を担うのはどれか、呼び出し時に結果をリアルタイムに返すのはどれか）は、上記の「対話シナリオの説明」と下記の「よくある質問」を参照してください。
よくある質問
どの event_type を使えばよいですか？
- MarsMind に送信ロジックを自動制御させたい（返信内容や送信タイミングを MarsMind が判断）→ auto_dialog。
send_urlの指定が必要です。 - 呼び出し時にこのメッセージの処理結果を取得したい → assist_dialog（
msg_idが必須）。 - ウェブでの対話 → website_dialog（結果を即時に返してコンテキストに追加。
send_urlには対応していません）。 - コマンドを送信したい → cmd_dialog。
contentにコマンド自体を指定します。
本番エンドポイントと client、secret はどこで申請しますか？
セルフサービスでの申請はできません。API のアドレス、認証情報、署名アルゴリズムはすべて MarsMind から提供されます。sales@marsmind.co までお問い合わせください。取得するまでは、例に記載された{本番エンドポイント}、client: "test"、例の署名を実際の呼び出しに使用しないでください。
リクエストで400が返るのはなぜですか？
まず次の3点を確認してください。from_user_id と group_id が同時に空になっていないか（どちらも空だと400になります）。content と files_info のうち少なくとも一方を指定しているか。message_type が 2 の場合に quote（msg_id と message_type を含む）を指定しているか。修正後、もう一度リクエストを送信してください。
auto_dialog と assist_dialog の違いは何ですか？
auto_dialog は MarsMind が送信ロジックを自動制御し、指定したsend_url から送信します。テキスト、画像、ファイルに対応（1回のリクエストにつき1種類のみ）。assist_dialog は呼び出し時に処理結果をリアルタイムに返し、パラメータが特定の auto_dialog メッセージと一致する場合はそのコンテキストを再利用します。msg_id は必須です。「自動で送信」なら前者、「その場で結果を確認」なら後者を選びます。
メッセージが実際に処理されたかを確認するには？
呼び出し側では応答とsend_url を確認します。システム側で管理画面から確認する方法は、「呼び出し手順」のステップ4を参照してください。