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

# API 文档

> 通过 MarsMind API 接入对话能力，并把它嵌入自己的业务系统或对话窗口。

## 接入前先确认

如果你只是使用 MarsMind 后台和标准聊天入口，不需要从这里开始。API 适合已经有自有系统、需要把对话能力接入现有窗口或消息渠道的团队。正式调用前，请先向 MarsMind 获取 `client` 和 `secret`，并确认你要接入的是自动对话、辅助对话、网页对话还是命令控制。

## 请求参数

### 主体结构

<ParamField body="client" type="string" required>
  业务标识，请与 MarsMind 智能确定
</ParamField>

<ParamField body="signature" type="string" required>
  签名，见下方算法
</ParamField>

<ParamField body="timestamp" type="integer" required>
  时间戳（Unix 秒级）
</ParamField>

<ParamField body="message_info" type="object" required>
  消息详情，见下方字段定义
</ParamField>

### `message_info` 字段

<ParamField body="msg_id" type="string">
  唯一消息 ID，assist\_dialog 场景下必填
</ParamField>

<ParamField body="group_id" type="string">
  群聊 ID，from\_user\_id 与 group\_id 同为空报错 400
</ParamField>

<ParamField body="group_name" type="string">
  群聊名称
</ParamField>

<ParamField body="from_user_id" type="string" required>
  发送者 ID
</ParamField>

<ParamField body="from_user_nickname" type="string">
  发送者昵称
</ParamField>

<ParamField body="to_user_id" type="string">
  接收者 ID
</ParamField>

<ParamField body="to_user_nickname" type="string">
  接收者昵称
</ParamField>

<ParamField body="at_list" type="string[]">
  @ 的用户 ID 列表（仅 auto\_dialog 支持）
</ParamField>

<ParamField body="content" type="string">
  消息文本内容，content 与 files\_info 至少有一个必填
</ParamField>

<ParamField body="message_type" type="integer" required>
  1 = 普通消息，2 = 引用消息
</ParamField>

<ParamField body="event_type" type="string" required>
  auto\_dialog | assist\_dialog | website\_dialog | cmd\_dialog
</ParamField>

<ParamField body="from_user_type" type="integer">
  1=机器人绑定账号 2=客户 3=客服 4=机器人消息。auto\_dialog 必填
</ParamField>

<ParamField body="create_timestamp" type="integer" required>
  消息创建时间（Unix 时间戳）
</ParamField>

<ParamField body="files_info" type="File[]">
  附件列表，见下表。content 与 files\_info 至少有一个必填
</ParamField>

<ParamField body="quote" type="object">
  引用消息对象，需含 msg\_id、message\_type。message\_type=2 必填
</ParamField>

#### `files_info` 结构

<ParamField body="content" type="string" required>
  文件地址或 base64 数据
</ParamField>

<ParamField body="file_type" type="string" required>
  "image"/"document"/"voice"
</ParamField>

***

## 对话场景说明

### auto\_dialog（自动对话）

* `event_type = auto_dialog`
* 提供 `send_url`，由 MarsMind 智能自动控制消息逻辑
* 支持文本、图片、文件（每次请求类型唯一）

**from\_user\_type 填写建议：**

* 绑定对象：除智能助手本身消息外，均填 1
* 未绑定对象：外部客户填 2，同公司人员填 3

***

### assist\_dialog（辅助对话）

* `event_type = assist_dialog`
* 实时返回消息处理结果
* 参数若与 auto\_dialog 消息一致，将复用上下文

***

### website\_dialog（网页对话）

* `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" }
    ]
  }
}'
```