> ## 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 Documentation

> Use this documentation to call the API and embed MarsMind’s conversational capabilities into your own chat window. This is intended for users who want to self-integrate. Both secret and client must be obtained from MarsMind.

## Request Parameters

### Main Structure

| Parameter     | Type   | Required | Description                                          |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| client        | string | Yes      | Business identifier, must be confirmed with MarsMind |
| signature     | string | Yes      | Signature, see algorithm below                       |
| timestamp     | int    | Yes      | Timestamp (Unix, seconds)                            |
| message\_info | object | Yes      | Message details, see fields below                    |

### `message_info` Fields

| Field                | Type      | Required                    | Description                                                                |
| -------------------- | --------- | --------------------------- | -------------------------------------------------------------------------- |
| msg\_id              | string    | Required for assist\_dialog | Unique message ID; mandatory in assist\_dialog scenario                    |
| group\_id            | string    | Depends on scenario         | Group chat ID. If both `from_user_id` and `group_id` are empty → error 400 |
| group\_name          | string    | No                          | Group name                                                                 |
| from\_user\_id       | string    | Yes                         | Sender ID                                                                  |
| from\_user\_nickname | string    | No                          | Sender nickname                                                            |
| to\_user\_id         | string    | No                          | Receiver ID                                                                |
| to\_user\_nickname   | string    | No                          | Receiver nickname                                                          |
| at\_list             | string\[] | No                          | List of mentioned users (@). Only supported in auto\_dialog                |
| content              | string    | Required if no files\_info  | Message text content                                                       |
| message\_type        | int       | Yes                         | 1 = normal message, 2 = quoted message                                     |
| event\_type          | string    | Yes                         | auto\_dialog \| assist\_dialog \| website\_dialog \| cmd\_dialog           |
| from\_user\_type     | int       | Required for auto\_dialog   | 1=bound account, 2=customer, 3=support agent, 4=AI message                 |
| create\_timestamp    | int       | Yes                         | Message creation time (Unix timestamp)                                     |
| files\_info          | File\[]   | Required if no content      | File attachments, see below                                                |
| quote                | object    | Required if message\_type=2 | Quoted message object, must include msg\_id and message\_type              |

#### `files_info` Structure

| Field      | Type                       | Required | Description             |
| ---------- | -------------------------- | -------- | ----------------------- |
| content    | string (URL/base64)        | Yes      | File URL or base64 data |
| file\_type | "image"/"document"/"voice" | Yes      | File type               |

***

## Conversation Scenarios

### auto\_dialog (Automatic Dialog)

* `event_type = auto_dialog`
* Provide `send_url`. MarsMind will control sending logic automatically.
* Supports text, image, or file (only one type per request).

**from\_user\_type Guidelines:**

* If bound to a specific account: all non-AI messages should use `1`.
* If not bound: external customer = `2`, internal staff = `3`.

***

### assist\_dialog (Assisted Dialog)

* `event_type = assist_dialog`
* Immediately returns the processed result.
* If parameters match a previous auto\_dialog message, the same context will be reused.

***

### website\_dialog (Web Dialog)

* `event_type = website_dialog`
* Message is processed immediately and appended to context.
* `send_url` is not supported.

***

### cmd\_dialog (Command Control)

* `event_type = cmd_dialog`
* `content` should contain the command. Currently supported:
  * `stop_auto_reply`: stop auto-reply (only valid in auto\_dialog).

***

## Example Usage

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