> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marsmind.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# API ドキュメント

> 以下のドキュメントを利用して API を呼び出し、会話機能を独自のウィンドウに組み込むことができます。主に自主的に適応したいユーザー向けです。secret と client は MarsMind から取得してください。

## リクエストパラメータ

### メイン構造

| パラメータ         | 型      | 必須 | 説明                         |
| ------------- | ------ | -- | -------------------------- |
| client        | string | はい | ビジネス識別子。MarsMind と確認してください |
| signature     | string | はい | 署名。下記アルゴリズム参照              |
| timestamp     | int    | はい | タイムスタンプ（Unix 秒）            |
| message\_info | object | はい | メッセージ詳細。以下フィールドを参照         |

### `message_info` フィールド

| フィールド                | 型         | 必須                         | 説明                                                               |
| -------------------- | --------- | -------------------------- | ---------------------------------------------------------------- |
| msg\_id              | string    | assist\_dialog では必須        | メッセージ ID。assist\_dialog の場合必須                                    |
| group\_id            | string    | シナリオによる                    | グループチャット ID。from\_user\_id と group\_id が両方空の場合は 400 エラー          |
| group\_name          | string    | いいえ                        | グループ名                                                            |
| from\_user\_id       | string    | はい                         | 送信者 ID                                                           |
| from\_user\_nickname | string    | いいえ                        | 送信者のニックネーム                                                       |
| to\_user\_id         | string    | いいえ                        | 受信者 ID                                                           |
| to\_user\_nickname   | string    | いいえ                        | 受信者のニックネーム                                                       |
| at\_list             | string\[] | いいえ                        | @ 対象ユーザー ID リスト（auto\_dialog のみ対応）                               |
| content              | string    | content または files\_info 必須 | メッセージ本文                                                          |
| message\_type        | int       | はい                         | 1 = 通常メッセージ、2 = 引用メッセージ                                          |
| event\_type          | string    | はい                         | auto\_dialog \| assist\_dialog \| website\_dialog \| cmd\_dialog |
| from\_user\_type     | int       | auto\_dialog では必須          | 1=特定アカウントに紐付く 2=顧客 3=カスタマーサポート 4=AI メッセージ                        |
| create\_timestamp    | int       | はい                         | メッセージ作成時間（Unix タイムスタンプ）                                          |
| files\_info          | File\[]   | content または files\_info 必須 | 添付ファイル一覧。下表参照                                                    |
| quote                | object    | message\_type=2 の場合必須      | 引用メッセージオブジェクト。msg\_id、message\_type を含む必要あり                      |

#### `files_info` 構造

| フィールド      | 型                          | 必須 | 説明                      |
| ---------- | -------------------------- | -- | ----------------------- |
| content    | string (URL/base64)        | はい | ファイル URL または base64 データ |
| file\_type | "image"/"document"/"voice" | はい | ファイルタイプ                 |

***

## 会話シナリオの種類

### auto\_dialog（自動対話）

* `event_type = auto_dialog`
* `send_url` を提供し、MarsMind が自動で送信ロジックを制御
* テキスト・画像・ファイルをサポート（リクエストごとに 1 種類のみ）

**from\_user\_type 設定ガイドライン：**

* 特定ユーザーに紐付く場合：AI 以外のメッセージはすべて 1
* 特定ユーザーに紐付かない場合：外部顧客は 2、自社スタッフは 3

***

### assist\_dialog（補助対話）

* `event_type = assist_dialog`
* リアルタイムで結果を返却
* auto\_dialog と同一のパラメータであれば、既存のコンテキストを利用

***

### website\_dialog（Web 対話）

* `event_type = website_dialog`
* 即時に結果を返却し、会話履歴に追加
* `send_url` は利用不可

***

### cmd\_dialog（コマンド制御）

* `event_type = cmd_dialog`
* content にコマンドを指定。現在サポートしているのは：
  * `stop_auto_reply`：自動返信を停止（auto\_dialog シナリオのみ有効）

***

## 利用例

### auto\_dialog

```bash theme={null}
curl -X POST http://127.0.0.1:7002/custom-im/chat-messages \
-H "Content-Type: application/json" \
-d '{
  "client": "test",
  "signature": "d97b383a532466b6c6c451e76a2ab57b",
  "timestamp": 1748584621,
  "message_info": {
    "content": "",
    "message_type": 1,
    "group_id": "98765@chatroom",
    "event_type": "auto_dialog",
    "from_user_id": "aa123",
    "from_user_type": 2,
    "msg_id": "9005",
    "create_timestamp": 1748584621,
    "files_info": [
      { "content": "https://example.com/img.png", "file_type": "image" }
    ]
  }
}'
```