對話與訊息

發送訊息 (串流)

POST /api/chatbots/{chatbotId}/completions/

參數

參數名稱	必填	類型	說明
chatbotId	✅	string	AI 助理的 ID

請求內容

請求參數

欄位	類型	必填	說明
conversation	string (uuid)	否	非必填，取決於是否要繼續現有對話
message	object	是	要發送給 AI 助理的具體訊息內容
message.content	string	是	要發送的訊息內容
message.attachments	array[AttachmentCreateInput]	否	附件陣列，預設為空陣列 []
isStreaming	boolean	否	串流回應模式開關

請求結構範例

{
  "conversation"?: string (uuid) // 非必填
  "message": 
  {
    "content": string
    "attachments"?: [ // 非必填
      {
        "id": string (uuid) // 附件的唯一識別碼
        "type": string (enum: image, audio, other) 
        // * `image` - 圖片類型檔案 * `audio` - 音訊類型檔案  * `other` - 其他類型檔案
        "filename": string // 附件的檔案名稱
        "file": string (uri) // 附件的URL
      }
    ]
  }
  "isStreaming"?: boolean // 非必填
}

請求範例值

{
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "content": "request_string",
    "attachments": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "image",
        "filename": "request_string",
        "file": "request_string"
      }
    ]
  },
  "isStreaming": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST --no-buffer "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "request_string",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": "image",
          "filename": "request_string",
          "file": "request_string"
        }
      ]
    },
    "isStreaming": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

# 註意: 此API返回的是串流數據，可以通過以下方式處理：
# 方法1: 使用jq處理每個JSON數據塊
# 例如: curl -X POST --no-buffer "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "request_string",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": "image",
          "filename": "request_string",
          "file": "request_string"
        }
      ]
    },
    "isStreaming": true
  }' | jq -r .

# 方法2: 使用管道將輸出寫入文件
# 例如: curl -X POST --no-buffer "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "request_string",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": "image",
          "filename": "request_string",
          "file": "request_string"
        }
      ]
    },
    "isStreaming": true
  }' > response.json

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  responseType: 'stream' // 設置為串流回應模式
};

// 請求內容 (payload)
const data = {
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "request_string",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": "image",
          "filename": "request_string",
          "file": "request_string"
        }
      ]
    },
    "isStreaming": true
  };

axios.post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", data, config)
  .then(response => {
    console.log('串流回應開始接收:');
    
    let completeResponse = '';
    
    // 監聽數據塊
    response.data.on('data', (chunk) => {
      // 將 Buffer 轉換為字串
      const chunkText = chunk.toString('utf8');
      console.log(`接收到塊: ${chunkText}`);
      
      completeResponse += chunkText;
      
      // 嘗試解析 JSON 數據塊
      try {
        // 檢查是否為完整的 JSON 物件
        if (chunkText.trim().startsWith('{') && chunkText.trim().endsWith('}')) {
          const chunkData = JSON.parse(chunkText);
          console.log('解析後的塊數據:', JSON.stringify(chunkData, null, 2));
        }
      } catch (err) {
        // 這可能是部分塊，無法解析為 JSON
      }
    });
    
    // 處理串流結束事件
    response.data.on('end', () => {
      console.log('\n完整累積的回應:');
      console.log(completeResponse);
    });
  })
  .catch(error => {
    console.error('串流請求發生錯誤:');
    console.error(error.message);
  });

Python

import requests
import json

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "message": {
        "content": "request_string",
        "attachments": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "type": "image",
            "filename": "request_string",
            "file": "request_string"
          }
        ]
      },
      "isStreaming": True  # 啟用串流模式
    }

# 使用串流方式處理回應
try:
    with requests.post(url, json=data, headers=headers, stream=True) as response:
        print("串流回應開始接收:")
        
        # 用於累積完整回應的變數
        complete_response = ""
        
        # 逐塊接收數據
        for chunk in response.iter_content(chunk_size=1024):
            if chunk:  # 過濾掉保持連接活躍的空塊
                # 嘗試解碼
                chunk_text = chunk.decode('utf-8', errors='replace')
                print(f"接收到塊: {chunk_text}")
                
                complete_response += chunk_text
                
                # 嘗試解析 JSON 數據塊
                try:
                    # 檢查是否為完整的 JSON 物件
                    if chunk_text.strip().startswith('{') and chunk_text.strip().endswith('}'):
                        chunk_data = json.loads(chunk_text)
                        print(f"解析後的塊數據: {json.dumps(chunk_data, indent=2, ensure_ascii=False)}")
                except json.JSONDecodeError:
                    # 這是部分塊，無法單獨解析為JSON
                    pass
        
        print("\n完整累積的回應:")
        print(complete_response)
        
except Exception as e:
    print("串流請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    // 使用串流選項
    $response = $client->post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "conversation": "550e8400-e29b-41d4-a716-446655440000",
            "message": {
                "content": "request_string",
                "attachments": [
                    {
                        "id": "550e8400-e29b-41d4-a716-446655440000",
                        "type": "image",
                        "filename": "request_string",
                        "file": "request_string"
                    }
                ]
            },
            "isStreaming": true
        },
        'stream' => true  // 啟用串流處理
    ]);
    
    echo "串流回應開始接收:\n";
    
    // 用於累積完整回應的變數
    $completeResponse = "";
    
    // 獲取響應體作為流
    $body = $response->getBody();
    
    // 逐塊讀取串流資料
    while (!$body->eof()) {
        $chunk = $body->read(1024);  // 讀取1KB的數據
        
        if ($chunk) {
            echo "接收到塊: " . $chunk . "\n";
            
            $completeResponse .= $chunk;
            
            // 嘗試解析 JSON 數據塊
            if (preg_match('/^\s*{.*}\s*$/', $chunk)) {
                try {
                    // 嘗試解析為 JSON
                    $chunkData = json_decode($chunk, true);
                    if (json_last_error() === JSON_ERROR_NONE) {
                        echo "解析後的塊數據:\n";
                        print_r($chunkData);
                    }
                } catch (Exception $parseError) {
                    // 無法解析為 JSON，可能是部分塊
                }
            }
        }
    }
    
    echo "\n完整累積的回應:\n";
    echo $completeResponse;
    
} catch (Exception $e) {
    echo '串流請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
200	對話回應內容，若是串流則為事件流

---

發送訊息 (建立)

POST /api/messages/

請求內容

請求參數

欄位	類型	必填	說明
conversation	string (uuid)	是	對話的唯一識別碼
content	string	否	要發送的訊息內容
attachments	array[AttachmentCreateInput]	否	附件陣列，預設為空陣列 []

請求結構範例

{
  "conversation": string (uuid)
  "content"?: string // 非必填
  string (enum: like, dislike) // 非必填
  "attachments"?: [ // 非必填
    {
      "id": string (uuid) // 附件的唯一識別碼
      "type"?: object // 附件的類型
      "filename": string // 附件的檔案名稱
      "file": string (uri) // 附件的URL
    }
  ]
}

請求範例值

{
  "conversation": "72251f2b-37ff-44ba-8051-465e40492518",
  "content": "這是一條測試訊息",
  "attachments": [
    {
      "id": "e67d7275-bfae-4355-9502-5e4efdc458dd",
      "type": "file",
      "filename": "string",
      "file": "string"
    }
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/messages/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "72251f2b-37ff-44ba-8051-465e40492518",
    "content": "這是一條測試訊息",
    "attachments": [
      {
        "id": "e67d7275-bfae-4355-9502-5e4efdc458dd",
        "type": "file",
        "filename": "string",
        "file": "string"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "conversation": "72251f2b-37ff-44ba-8051-465e40492518",
    "content": "這是一條測試訊息",
    "attachments": [
      {
        "id": "e67d7275-bfae-4355-9502-5e4efdc458dd",
        "type": "file",
        "filename": "string",
        "file": "string"
      }
    ]
  };

axios.post("https://api.maiagent.ai/api/messages/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/messages/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "conversation": "72251f2b-37ff-44ba-8051-465e40492518",
      "content": "這是一條測試訊息",
      "attachments": [
        {
          "id": "e67d7275-bfae-4355-9502-5e4efdc458dd",
          "type": "file",
          "filename": "string",
          "file": "string"
        }
      ]
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/messages/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "conversation": "72251f2b-37ff-44ba-8051-465e40492518",
            "type": "incoming",
            "content": "這是一條測試訊息",
            "feedback": "like",
            "attachments": [
                {
                    "id": "e67d7275-bfae-4355-9502-5e4efdc458dd",
                    "type": "file",
                    "filename": "string",
                    "file": "string"
                }
            ]
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "conversation": string (uuid)
  "sender": object
  "type"?: string // 非必填
  "content"?: string // 非必填
  "feedback"?: // 可能有不同的類型 (非必填)
  string (enum: like, dislike) // 非必填
  "createdAt": string (timestamp)
  "attachments"?: [ // 非必填
    {
      "id": string (uuid)
      "type"?: object // 非必填
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string
      "file": string (uri)
      "fileType": string
      "size": integer
      "status": object
      "parser": 
      {
        "id": string (uuid)
        "name": string
        "provider": string (enum: maiagent, maiagent_ocr_beta, llama, azure) // * `maiagent` - MaiAgent
* `maiagent_ocr_beta` - MaiAgent OCR Beta
* `llama` - Llama
* `azure` - Azure
        "order"?: integer // 非必填
      }
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": 
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": string (uuid)
        "pageNumber": integer
      }
      "score"?: number (double) // 非必填
      "displayScore": integer
    }
  ]
}

回應範例值

{
  "conversation": "72251f2b-37ff-44ba-8051-465e40492518",
  "type": "incoming",
  "content": "這是一條測試訊息",
  "feedback": "like",
  "attachments": [
    {
      "id": "e67d7275-bfae-4355-9502-5e4efdc458dd",
      "type": "file",
      "filename": "string",
      "file": "string"
    }
  ]
}

---

取得訊息列表

GET /api/messages/

參數

參數名稱	必填	類型	說明
conversation	✅	string	對話 ID
cursor	❌	string	The pagination cursor value.
pageSize	❌	integer	Number of results to return per page.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "conversation": string (uuid)
      "sender": object
      "type"?: string // 非必填
      "content"?: string // 非必填
      "feedback"?: // 可能有不同的類型 (非必填)
      string (enum: like, dislike) // 非必填
      "createdAt": string (timestamp)
      "attachments"?: [ // 非必填
        {
          "id": string (uuid)
          "type"?: object // 非必填
          "filename": string
          "file": string (uri)
          "conversation"?: string (uuid) // 非必填
        }
      ]
      "citations": [
        {
          "id": string (uuid)
          "filename": string
          "file": string (uri)
          "fileType": string
          "size": integer
          "status": object
          "parser": 
          {
            "id": string (uuid)
            "name": string
            "provider": string (enum: maiagent, maiagent_ocr_beta, llama, azure) // * `maiagent` - MaiAgent
* `maiagent_ocr_beta` - MaiAgent OCR Beta
* `llama` - Llama
* `azure` - Azure
            "order"?: integer // 非必填
          }
          "createdAt": string (timestamp)
        }
      ]
      "citationNodes": [
        {
          "chatbotTextNode": 
          {
            "id": string (uuid)
            "charactersCount": integer
            "hitsCount": integer
            "text": string
            "updatedAt": string (timestamp)
            "filename": string
            "chatbotFile": string (uuid)
            "pageNumber": integer
          }
          "score"?: number (double) // 非必填
          "displayScore": integer
        }
      ]
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "sender": {
        "id": 456,
        "name": "response_string",
        "avatar": "response_string"
      },
      "type": "response_string",
      "content": "response_string",
      "feedback": "like",
      "createdAt": "response_string",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "response_string",
          "file": "response_string",
          "conversation": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "citations": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "filename": "response_string",
          "file": "response_string",
          "fileType": "response_string",
          "size": 456,
          "status": {},
          "parser": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "response_string",
            "provider": "maiagent",
            "order": 456
          },
          "createdAt": "response_string"
        }
      ],
      "citationNodes": [
        {
          "chatbotTextNode": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "charactersCount": 456,
            "hitsCount": 456,
            "text": "response_string",
            "updatedAt": "response_string",
            "filename": "response_string",
            "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
            "pageNumber": 456
          },
          "score": 456,
          "displayScore": 456
        }
      ]
    }
  ]
}

---

取得特定訊息

GET /api/messages/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 訊息.
conversation	✅	string	對話 ID

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "conversation": string (uuid)
  "sender": object
  "type"?: string // 非必填
  "content"?: string // 非必填
  "feedback"?: // 可能有不同的類型 (非必填)
  string (enum: like, dislike) // 非必填
  "createdAt": string (timestamp)
  "attachments"?: [ // 非必填
    {
      "id": string (uuid)
      "type"?: object // 非必填
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string
      "file": string (uri)
      "fileType": string
      "size": integer
      "status": object
      "parser": 
      {
        "id": string (uuid)
        "name": string
        "provider": string (enum: maiagent, maiagent_ocr_beta, llama, azure) // * `maiagent` - MaiAgent
* `maiagent_ocr_beta` - MaiAgent OCR Beta
* `llama` - Llama
* `azure` - Azure
        "order"?: integer // 非必填
      }
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": 
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": string (uuid)
        "pageNumber": integer
      }
      "score"?: number (double) // 非必填
      "displayScore": integer
    }
  ]
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "sender": {
    "id": 456,
    "name": "response_string",
    "avatar": "response_string"
  },
  "type": "response_string",
  "content": "response_string",
  "feedback": "like",
  "createdAt": "response_string",
  "attachments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "filename": "response_string",
      "file": "response_string",
      "conversation": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "citations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "response_string",
      "file": "response_string",
      "fileType": "response_string",
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "response_string",
        "provider": "maiagent",
        "order": 456
      },
      "createdAt": "response_string"
    }
  ],
  "citationNodes": [
    {
      "chatbotTextNode": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "charactersCount": 456,
        "hitsCount": 456,
        "text": "response_string",
        "updatedAt": "response_string",
        "filename": "response_string",
        "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
        "pageNumber": 456
      },
      "score": 456,
      "displayScore": 456
    }
  ]
}

---

建立新的對話

POST /api/conversations/

請求內容

請求參數

欄位	類型	必填	說明
webChat	string (uuid)	是

請求結構範例

{
  "webChat": string (uuid)
}

請求範例值

{
  "webChat": "550e8400-e29b-41d4-a716-446655440000"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/conversations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webChat": "550e8400-e29b-41d4-a716-446655440000"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "webChat": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/conversations/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/conversations/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "webChat": "550e8400-e29b-41d4-a716-446655440000"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/conversations/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "webChat": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "contact": 
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 非必填
    "createdAt": string (timestamp)
  }
  "inbox": 
  {
    "id": string (uuid)
    "name": string
    "channelType": object
    "unreadConversationsCount"?: integer // 非必填
    "signAuth"?: object // 非必填
  }
  "title": string
  "lastMessage"?:  // 非必填
  {
    "id": string (uuid)
    "type"?: string // 非必填
    "content"?: string // 非必填
    "feedback"?: // 可能有不同的類型 (非必填)
    string (enum: like, dislike) // 非必填
    "createdAt": string (timestamp)
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention": boolean
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "response_string",
    "avatar": "response_string",
    "createdAt": "response_string"
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "response_string",
    "channelType": {},
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "response_string",
          "url": "response_string",
          "realm": "response_string"
        },
        "line": {
          "liffId": "response_string"
        }
      }
    }
  },
  "title": "response_string",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "response_string",
    "content": "response_string",
    "feedback": "like",
    "createdAt": "response_string"
  },
  "lastMessageCreatedAt": "response_string",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "response_string",
  "createdAt": "response_string",
  "isGroupChat": false,
  "enableGroupMention": false
}

---

取得對話列表

GET /api/conversations/

參數

參數名稱	必填	類型	說明
cursor	❌	string	The pagination cursor value.
inbox	✅	string	收件匣 ID
keyword	❌	string	關鍵字搜尋
pageSize	❌	integer	Number of results to return per page.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "contact": 
      {
        "id": string (uuid)
        "name": string
        "avatar"?: string (uri) // 非必填
        "createdAt": string (timestamp)
      }
      "inbox": 
      {
        "id": string (uuid)
        "name": string
        "channelType": object
        "unreadConversationsCount"?: integer // 非必填
        "signAuth"?: object // 非必填
      }
      "title": string
      "lastMessage"?:  // 非必填
      {
        "id": string (uuid)
        "type"?: string // 非必填
        "content"?: string // 非必填
        "feedback"?: // 可能有不同的類型 (非必填)
        string (enum: like, dislike) // 非必填
        "createdAt": string (timestamp)
      }
      "lastMessageCreatedAt": string (timestamp)
      "unreadMessagesCount": integer
      "autoReplyEnabled": boolean
      "isAutoReplyNow": boolean
      "lastReadAt": string (timestamp)
      "createdAt": string (timestamp)
      "isGroupChat": boolean
      "enableGroupMention": boolean
    }
  ]
}

回應範例值

{
  "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D\"",
  "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contact": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "response_string",
        "avatar": "response_string",
        "createdAt": "response_string"
      },
      "inbox": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "response_string",
        "channelType": {},
        "unreadConversationsCount": 456,
        "signAuth": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "signSource": "550e8400-e29b-41d4-a716-446655440000",
          "signParams": {
            "keycloak": {
              "clientId": "response_string",
              "url": "response_string",
              "realm": "response_string"
            },
            "line": {
              "liffId": "response_string"
            }
          }
        }
      },
      "title": "response_string",
      "lastMessage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "response_string",
        "content": "response_string",
        "feedback": "like",
        "createdAt": "response_string"
      },
      "lastMessageCreatedAt": "response_string",
      "unreadMessagesCount": 456,
      "autoReplyEnabled": false,
      "isAutoReplyNow": false,
      "lastReadAt": "response_string",
      "createdAt": "response_string",
      "isGroupChat": false,
      "enableGroupMention": false
    }
  ]
}

---

取得特定對話

GET /api/conversations/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 對話.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "contact": 
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 非必填
    "createdAt": string (timestamp)
  }
  "inbox": 
  {
    "id": string (uuid)
    "name": string
    "channelType": object
    "unreadConversationsCount"?: integer // 非必填
    "signAuth"?: object // 非必填
  }
  "title": string
  "lastMessage"?:  // 非必填
  {
    "id": string (uuid)
    "type"?: string // 非必填
    "content"?: string // 非必填
    "feedback"?: // 可能有不同的類型 (非必填)
    string (enum: like, dislike) // 非必填
    "createdAt": string (timestamp)
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention": boolean
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "response_string",
    "avatar": "response_string",
    "createdAt": "response_string"
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "response_string",
    "channelType": {},
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "response_string",
          "url": "response_string",
          "realm": "response_string"
        },
        "line": {
          "liffId": "response_string"
        }
      }
    }
  },
  "title": "response_string",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "response_string",
    "content": "response_string",
    "feedback": "like",
    "createdAt": "response_string"
  },
  "lastMessageCreatedAt": "response_string",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "response_string",
  "createdAt": "response_string",
  "isGroupChat": false,
  "enableGroupMention": false
}

---

取得 AI 助理對話紀錄

GET /api/chatbots/{chatbotPk}/records/

參數

參數名稱	必填	類型	說明
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/?page=1&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/?page=1&pageSize=1", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/?page=1&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "inputMessage": string
      "condenseMessage": string // 綜合聊天歷史與上下文後，修飾過後的使用者訊息
      "outputMessage": string
      "context": string
      "faithfulnessScore": number (double) // 判斷chatbot回覆是否符合資料庫內容，是否憑空想像
      "displayFaithfulnessScore": integer
      "answerRelevancyScore": number (double) // 判斷chatbot回覆是否與使用者問題相關
      "displayAnswerRelevancyScore": integer
      "contextPrecisionScore": number (double) // 判斷chatbot回覆是否與參考資料相關
      "displayContextPrecisionScore": integer
      "answerCorrectnessScore": number (double) // 判斷chatbot回覆是否正確(需要有標準答案)
      "displayAnswerCorrectnessScore": integer
      "answerSimilarityScore": number (double) // 判斷chatbot回覆是否與標準答案相似
      "displayAnswerSimilarityScore": integer
      "contextRecallScore": number (double) // 判斷chatbot回覆是否能夠從參考資料中召回相關資料
      "displayContextRecallScore": integer
      "replyTime": string
      "createdAt": string (timestamp)
      "error": string // 儲存執行過程中的錯誤訊息
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inputMessage": "response_string",
      "condenseMessage": "response_string",
      "outputMessage": "response_string",
      "context": "response_string",
      "faithfulnessScore": 456,
      "displayFaithfulnessScore": 456,
      "answerRelevancyScore": 456,
      "displayAnswerRelevancyScore": 456,
      "contextPrecisionScore": 456,
      "displayContextPrecisionScore": 456,
      "answerCorrectnessScore": 456,
      "displayAnswerCorrectnessScore": 456,
      "answerSimilarityScore": 456,
      "displayAnswerSimilarityScore": 456,
      "contextRecallScore": 456,
      "displayContextRecallScore": 456,
      "replyTime": "response_string",
      "createdAt": "response_string",
      "error": "response_string"
    }
  ]
}

---

對話紀錄匯出為 Excel 檔案

GET /api/chatbots/{chatbotPk}/records/export-excel/

參數

參數名稱	必填	類型	說明
chatbotPk	✅	string	A UUID string identifying this Chatbot ID

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
# 請將 YOUR_API_KEY 替換成您的 API 金鑰
# 請將 {chatbotPk} 替換成您的 Chatbot ID
# 預設會將檔案儲存為 export.xlsx，您可以修改 -o 後面的檔案名稱
curl -X GET "https://api.maiagent.ai/api/chatbots/{chatbotPk}/records/export-excel/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -o export.xlsx

# 提示：伺服器可能透過 Content-Disposition 標頭提供建議的檔案名稱。
# 您可以使用 curl -OJ (大寫O, 大寫J) 來嘗試使用伺服器提供的檔名 (如果有的話)。
# 例如: curl -X GET "https://api.maiagent.ai/api/chatbots/{chatbotPk}/records/export-excel/" -H "Authorization: Api-Key YOUR_API_KEY" -OJ

JavaScript

const axios = require('axios');
const fs = require('fs'); // Node.js 環境需要
const path = require('path'); // Node.js 環境需要

// 請將 YOUR_API_KEY 替換成您的 API 金鑰
// 請將 chatbotId 替換成您的 Chatbot ID
const apiKey = 'YOUR_API_KEY';
const chatbotId = '550e8400-e29b-41d4-a716-446655440000'; // 範例 ID，請替換
const url = `https://api.maiagent.ai/api/chatbots/${chatbotId}/records/export-excel/`;

// 設定請求標頭和回應類型
const config = {
  headers: {
    'Authorization': `Api-Key ${apiKey}`
  },
  responseType: 'arraybuffer' // 或者 'blob'，取決於您的環境和偏好
};

axios.get(url, config)
  .then(response => {
    console.log('成功取得回應，準備下載檔案...');

    // 從 Content-Disposition 標頭獲取檔案名稱 (如果可用)
    let filename = 'export.xlsx'; // 預設檔案名稱
    const contentDisposition = response.headers['content-disposition'];
    if (contentDisposition) {
      const filenameMatch = contentDisposition.match(/filename="?(.+)"?/i);
      if (filenameMatch && filenameMatch.length > 1) {
        filename = filenameMatch[1];
      }
    }

    // Node.js 環境儲存檔案範例
    if (typeof window === 'undefined' && fs && path) {
      const outputPath = path.join(__dirname, filename); // 儲存到當前目錄
      fs.writeFileSync(outputPath, Buffer.from(response.data));
      console.log(`檔案已儲存至: ${outputPath}`);
    } else if (typeof window !== 'undefined') {
      // 瀏覽器環境下載檔案範例
      const blob = new Blob([response.data], { type: response.headers['content-type'] || 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
      const downloadUrl = window.URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = downloadUrl;
      a.download = filename;
      document.body.appendChild(a);
      a.click();
      a.remove();
      window.URL.revokeObjectURL(downloadUrl);
      console.log(`檔案 ${filename} 已開始下載。`);
    } else {
      console.log('無法在此環境自動下載檔案。回應資料如下 (部分):');
      // 對於無法直接下載的環境，可以考慮將 response.data (ArrayBuffer) 轉換為 Base64 或其他格式
      console.log(response.data.slice(0, 100)); // 僅顯示前100 bytes 作為範例
    }
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    if (error.response) {
      // API 回應了錯誤狀態碼
      console.error('狀態碼:', error.response.status);
      // 嘗試將錯誤回應的 ArrayBuffer 解碼為文字 (如果錯誤訊息是 JSON 或文字)
      try {
        const errorDataText = Buffer.from(error.response.data).toString('utf8');
        console.error('錯誤資料:', JSON.parse(errorDataText));
      } catch (e) {
        console.error('錯誤資料 (無法解析為 JSON):', Buffer.from(error.response.data).toString('utf8'));
      }
    } else if (error.request) {
      // 請求已發出，但沒有收到回應
      console.error('無回應:', error.request);
    } else {
      // 設定請求時發生錯誤
      console.error('設定錯誤:', error.message);
    }
  });

Python

import requests
import re

# 請將 YOUR_API_KEY 替換成您的 API 金鑰
# 請將 chatbot_pk 替換成您的 Chatbot ID
api_key = "YOUR_API_KEY"
chatbot_pk = "550e8400-e29b-41d4-a716-446655440000" # 範例 ID，請替換
url = f"https://api.maiagent.ai/api/chatbots/{chatbot_pk}/records/export-excel/"

headers = {
    "Authorization": f"Api-Key {api_key}"
}

try:
    response = requests.get(url, headers=headers, stream=True)
    response.raise_for_status()  # 如果 HTTP 狀態碼是 4xx 或 5xx，則會拋出 HTTPError

    # 從 Content-Disposition 標頭獲取檔案名稱
    filename = "export.xlsx" # 預設檔案名稱
    content_disposition = response.headers.get("content-disposition")
    if content_disposition:
        # 使用正則表達式從 Content-Disposition 中提取 filename
        # 例如: attachment; filename="=?UTF-8?B?xxxx?="
        # 或者 attachment; filename="actual_filename.xlsx"
        match = re.search(r'filename="?([^"]+)"?', content_disposition)
        if match:
            filename = match.group(1)
            # 如果檔名是 Base64 編碼 (常見於包含非 ASCII 字元的情況)
            if filename.startswith("=?UTF-8?B?") and filename.endswith("?="):
                import base64
                filename = base64.b64decode(filename[10:-2]).decode('utf-8')
        else:
            # 有些伺服器可能直接給出檔名，不帶 filename=
            # 這裡可以根據實際情況調整
            pass


    # 以二進制寫入模式開啟檔案並寫入內容
    with open(filename, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192): 
            f.write(chunk)
    print(f"成功取得回應，檔案已儲存為: {filename}")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP 錯誤: {http_err}")
    # 嘗試讀取錯誤回應的內容
    try:
        error_content = response.content.decode('utf-8')
        print(f"錯誤內容: {error_content}")
    except Exception as e:
        print(f"無法解碼錯誤內容: {e}")
except requests.exceptions.RequestException as req_err:
    print(f"請求發生錯誤: {req_err}")
except Exception as e:
    print(f"發生未預期的錯誤: {e}")

PHP

<?php
require 'vendor/autoload.php'; // 請確保已安裝 Guzzle

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

// 請將 YOUR_API_KEY 替換成您的 API 金鑰
// 請將 $chatbotPk 替換成您的 Chatbot ID
$apiKey = 'YOUR_API_KEY';
$chatbotPk = '550e8400-e29b-41d4-a716-446655440000'; // 範例 ID，請替換
$url = "https://api.maiagent.ai/api/chatbots/{$chatbotPk}/records/export-excel/";

$client = new Client();

try {
    $response = $client->request('GET', $url, [
        'headers' => [
            'Authorization' => 'Api-Key ' . $apiKey
        ],
        'stream' => true // 以串流方式處理回應，適用於大檔案
    ]);

    if ($response->getStatusCode() == 200) {
        // 從 Content-Disposition 標頭獲取檔案名稱
        $filename = 'export.xlsx'; // 預設檔案名稱
        $contentDisposition = $response->getHeaderLine('Content-Disposition');
        if (!empty($contentDisposition)) {
            if (preg_match('/filename="?([^"]+)"?/', $contentDisposition, $matches)) {
                $filename = $matches[1];
            }
        }
        
        // 獲取回應主體 (檔案串流)
        $body = $response->getBody();
        
        // 儲存檔案
        $savePath = __DIR__ . '/' . $filename; // 儲存到當前目錄，可自行修改路徑
        $fileHandle = fopen($savePath, 'w');
        if ($fileHandle === false) {
            throw new Exception("無法開啟檔案進行寫入: " . $savePath);
        }
        
        while (!$body->eof()) {
            fwrite($fileHandle, $body->read(1024 * 8)); // 每次讀取 8KB
        }
        fclose($fileHandle);
        
        echo "成功取得回應，檔案已儲存為: " . $savePath . "\n";
    } else {
        echo "請求失敗，狀態碼: " . $response->getStatusCode() . "\n";
        echo "回應內容: " . $response->getBody()->getContents() . "\n";
    }

} catch (RequestException $e) {
    echo '請求發生錯誤: ' . $e->getMessage() . "\n";
    if ($e->hasResponse()) {
        echo "錯誤回應: " . $e->getResponse()->getBody()->getContents() . "\n";
    }
} catch (Exception $e) {
    echo '發生未預期的錯誤: ' . $e->getMessage() . "\n";
}
?>

回應內容

狀態碼	說明
200	Excel 檔案下載

---