# 建立對話與訊息

## 建立對話

建立一個新的對話。

**端點：** [`https://api.maiagent.ai/api/v1/conversations`](https://api.maiagent.ai/api/v1/conversations/)

**請求方法：** `POST`

**請求標頭：**

```
Authorization: Api-Key <您的API金鑰>
Content-Type: application/json
```

**請求內容：**

「Web Chat ID」請由「AI 助理」詳細頁面最下方取得

```json
{
    "webChat": "String"  // Web Chat ID
}
```

**請求範例：**

```python
import requests

response = requests.post(
    url='https://api.maiagent.ai/api/v1/conversations/',
    headers={
        'Authorization': 'Api-Key <您的API金鑰>'
    },
    json={
        'webChat': '您的 Web Chat ID'
    }
)
```

**回應內容：**

若是要用於串接訊息，只需要將「ID」記下來。對話「ID」能取得整個對話中的所有訊息，也能用於透過「對話 ID」來知道目前訊息 Webhook 是在哪一個對話內。

```json
{
    "id": "string",                    // 對話唯一識別碼，UUID 格式
    "contact": {
        "id": "string",                // 聯絡人唯一識別碼，UUID 格式
        "name": "string",              // 聯絡人名稱
        "avatar": "string",            // 大頭貼網址
        "createdAt": "string"          // 建立時間戳記，毫秒為單位
    },
    "inbox": {
        "id": "string",                // 收件匣唯一識別碼，UUID 格式
        "name": "string",              // 收件匣名稱
        "channelType": "string"        // 頻道類型，例如："web"
    },
    "title": "string",                 // 對話標題
    "lastMessage": null,               // 最後一則訊息，可能為 null
    "lastMessageCreatedAt": "string",  // 最後一則訊息建立時間戳記
    "unreadMessagesCount": number,     // 未讀訊息數量
    "autoReplyEnabled": boolean,       // 是否啟用自動回覆
    "isAutoReplyNow": boolean,         // 目前是否正在自動回覆
    "lastReadAt": null,                // 最後讀取時間，可能為 null
    "createdAt": "string"              // 對話建立時間戳記
}
```

***

## 傳送訊息

建立一則新訊息

**端點：** `https://api.maiagent.ai/api/v1/messages/`

**請求方法：** `POST`

**請求標頭：**

```
Authorization: Api-Key 您的API金鑰
Content-Type: application/json
```

**請求內容：**

```json
{
    "conversation": "string",   // 對話 ID，必填
    "content": "string",        // 訊息內容，必填
    "attachments": [            // 附件陣列，選填
        // 附件物件列表
    ]
}
```

**請求參數說明：**

<table><thead><tr><th width="279">參數名稱</th><th>類型</th><th>必填</th><th>說明</th></tr></thead><tbody><tr><td>conversation</td><td>string</td><td>是</td><td>對話的唯一識別碼</td></tr><tr><td>content</td><td>string</td><td>是</td><td>要發送的訊息內容</td></tr><tr><td>attachments</td><td>array</td><td>否</td><td>附件陣列，預設為空陣列 []</td></tr></tbody></table>

#### **附件物件欄位說明**

| 附件欄位名稱   | 類型     | 必填 | 說明       |
| -------- | ------ | -- | -------- |
| id       | string | 是  | 附件的唯一識別碼 |
| type     | string | 是  | 附件的類型    |
| filename | string | 是  | 附件的檔案名稱  |
| file     | string | 是  | 附件的URL   |

**請求範例：**

Python 範例

```python
import requests

response = requests.post(
    url='<https://api.maiagent.ai/api/v1/messages/>',
    headers={
        'Authorization': 'Api-Key 您的API金鑰'
    },
    json={
        'conversation': '對話ID',
        'content': '訊息內容',
        'attachments': [
            {
                "id": "附件ID",
                "type": "附件類型",
                "filename": "附件檔案名稱",
                "file": "附件檔案的 URL"
            }
        ]
    }
)

```

cURL 範例

```bash
curl -X POST '<https://api.maiagent.ai/api/v1/messages/>' \\
-H 'Authorization: Api-Key 您的API金鑰' \\
-H 'Content-Type: application/json' \\
-d '{
    "conversation": "對話ID",
    "content": "訊息內容",
    "attachments": [
        {
            "id": "附件ID",
            "type": "附件類型",
            "filename": "附件檔案名稱",
            "file": "附件檔案的 URL"
        }
    ]
}'

```

**回應格式：**

收到回應代表訊息建立成功，回覆的訊息會以 Webhook 的方式提供，請參考 Webhook 章節

```json
{
    "id": "string",                    // 訊息唯一識別碼，UUID 格式
    "conversation": "string",          // 對話唯一識別碼，UUID 格式
    "sender": {
        "id": number,                  // 發送者 ID
        "name": "string",              // 發送者名稱
        "avatar": "string"             // 發送者頭像 URL
    },
    "type": "string",                  // 訊息類型，例如："incoming"
    "content": "string",               // 訊息內容
    "feedback": null,                  // 訊息回饋，可能為 null
    "createdAt": "string",             // 建立時間戳記，毫秒為單位
    "attachments": [],                 // 附件陣列
    "citations": [],                   // 引用來源陣列
    "citationNodes": []                // 引用節點陣列
}

```

**回應範例：**

```python
{
    "id": "2491074a-6d23-4289-af45-caa12531420e",
    "conversation": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "sender": {
        "id": 324816370485542537671391323877394598747,
        "name": "AI 智能客服",
        "avatar": "https://whizchat-media-prod-django.playma.app/media/users/user/bb5f49ef-31ae-4ccf-bc0e-6fe8c5001721.png"
    },
    "type": "incoming",
    "content": "你好",
    "feedback": null,
    "createdAt": "1732495353000",
    "attachments": [],
    "citations": [],
    "citationNodes": []
}
```

**回應欄位說明**

<table><thead><tr><th width="209">欄位名稱</th><th>類型</th><th>說明</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>訊息唯一識別碼 (UUID)</td></tr><tr><td>conversation</td><td>string</td><td>對話唯一識別碼 (UUID)</td></tr><tr><td>sender</td><td>object</td><td>發送者資訊物件</td></tr><tr><td><a href="http://sender.id/">sender.id</a></td><td>number</td><td>發送者唯一識別碼</td></tr><tr><td><a href="http://sender.name/">sender.name</a></td><td>string</td><td>發送者名稱</td></tr><tr><td>sender.avatar</td><td>string</td><td>發送者頭像網址</td></tr><tr><td>type</td><td>string</td><td>訊息類型 (incoming/outgoing)</td></tr><tr><td>content</td><td>string</td><td>訊息內容</td></tr><tr><td>feedback</td><td>object</td><td>null</td></tr><tr><td>createdAt</td><td>string</td><td>訊息建立時間戳記</td></tr><tr><td>attachments</td><td>array</td><td>附件清單</td></tr><tr><td>citations</td><td>array</td><td>引用來源文件列表</td></tr><tr><td>citationNodes</td><td>array</td><td>引用來源節點列表</td></tr></tbody></table>

### 訊息類型說明

* `incoming`: 收到的訊息
* `outgoing`: 發送的訊息


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/api-integration/dui-hua-yu-xun-xi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.