# 建立對話與訊息

## 建立對話

建立一個新的對話。

**端點：** [`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`: 發送的訊息