API v2 對話

列出並匯出對話、讀取訊息、重試回覆、提交工具結果，以及管理訊息意見回饋。

使用以下端點讀取對話紀錄，並操作 API v2 訊息。本頁的每個端點都需要 Authorization: Bearer YOUR_API_KEY，以及對 {agentId} 的存取權限。

對話範圍

唯讀對話端點預設使用 source=api_v2。設定 source=widget 可回傳小工具與 Playground 對話；Playground 記錄會以 widget 來源儲存。設定 source=all 可回傳 API v2、小工具與 Playground 對話。結果永遠僅限於已驗證帳戶所擁有的代理程式。無效的 source 值，或帶有一個以上的 source 查詢參數，會回傳 400 VALIDATION_INVALID_BODY。對話延續、重試、意見回饋、訊息列表與依使用者查詢，僅適用於 API v2 對話。

回應物件

對話摘要包含：

欄位	類型	備註
`id`	string	對話的公開參考 ID。
`title`	string	第一則使用者訊息，截斷至 80 個字元；若無可用內容則為 `New conversation`。
`createdAt`	integer	Unix 時間戳記（秒）。
`updatedAt`	integer	Unix 時間戳記（秒）。
`userId`	string 或 null	透過 API v2 聊天提供的終端使用者 ID。
`source`	string 或 null	通常為 `api_v2` 或 `widget`。Playground 對話會以 `widget` 儲存。
`status`	string	已儲存的對話狀態；若無儲存狀態則為 `ongoing`。

訊息物件包含：

欄位	類型	備註
`id`	string	以字串序列化的數字資料庫訊息 ID。
`role`	string	助理發送者為 `assistant`；其他情況為 `user`。
`parts`	array	一個 `{ "type": "text", "text": "..." }` 部分。
`createdAt`	integer	Unix 時間戳記（秒）。
`feedback`	string 或 null	`positive`、`negative` 或 `null`。
`metadata`	任意 JSON 值	已持久化的訊息中繼資料。

工具類型的訊息紀錄不會出現在對話文字紀錄或訊息列表中。

列出對話

路徑：/api/v2/agents/{agentId}/conversations

GET /api/v2/agents/{agentId}/conversations

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

查詢參數	是否必填	限制
`limit`	否	1 到 100 之間的整數，預設為 20。
`cursor`	否	前一頁回傳的不透明游標。請原封不動地重複使用。
`source`	否	`api_v2`（預設）、`widget` 或 `all`。只能出現一次。

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations?source=all&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

無效的 limit、cursor、source 值，以及重複的 source 參數，都會回傳 400 VALIDATION_INVALID_BODY。

匯出對話

路徑：/api/v2/agents/{agentId}/conversations/export

GET /api/v2/agents/{agentId}/conversations/export

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

查詢參數	是否必填	限制
`limit`	否	1 到 20 之間的整數，預設為 20。
`cursor`	否	前一頁回傳的不透明游標。請原封不動地重複使用。
`source`	否	`api_v2`（預設）、`widget` 或 `all`。只能出現一次。

匯出功能使用與列表端點相同的對話排序方式與游標機制，但每頁上限為 20 筆對話。每筆對話包含所有非工具類型的訊息，依由舊到新排序。

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/export?source=api_v2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing",
      "messages": [
        {
          "id": "122",
          "role": "user",
          "parts": [{ "type": "text", "text": "Where is my order?" }],
          "createdAt": 1784332800,
          "feedback": null,
          "metadata": null
        }
      ]
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

取得單一對話

路徑：/api/v2/agents/{agentId}/conversations/{conversationId}

GET /api/v2/agents/{agentId}/conversations/{conversationId}

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

查詢參數	是否必填	限制
`source`	否	`api_v2`（預設）、`widget` 或 `all`。只能出現一次。

回應包含完整的非工具類型文字紀錄，依由舊到新排序。此端點不支援游標分頁；如需分頁存取 API v2 訊息，請使用訊息列表端點。

成功：200 OK

{
  "data": {
    "id": "b2mD4kL8pQ1sT6vX",
    "title": "Where is my order?",
    "createdAt": 1784332800,
    "updatedAt": 1784332860,
    "userId": "customer_123",
    "source": "api_v2",
    "status": "ongoing",
    "messages": [
      {
        "id": "122",
        "role": "user",
        "parts": [{ "type": "text", "text": "Where is my order?" }],
        "createdAt": 1784332800,
        "feedback": null,
        "metadata": null
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

在所選來源範圍內找不到對話時，會回傳 404 RESOURCE_NOT_FOUND。

列出訊息

路徑：/api/v2/agents/{agentId}/conversations/{conversationId}/messages

GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。此對話必須是 API v2 對話。

查詢參數	是否必填	限制
`limit`	否	1 到 100 之間的整數，預設為 20。
`cursor`	否	前一頁回傳的不透明游標。請原封不動地重複使用。

由於訊息使用 bigint 型別的 ID，訊息游標是唯一一種伺服器端 ID 部分會以數字字串驗證的 v2 分頁游標。其他每一種可分頁的 v2 資源都會以 UUID 驗證 ID。請將兩種形式都視為不透明權杖；切勿自行建構或解析游標。每一頁回傳的訊息，都會依由舊到新排序。

成功：200 OK

{
  "data": [
    {
      "id": "122",
      "role": "user",
      "parts": [{ "type": "text", "text": "Where is my order?" }],
      "createdAt": 1784332800,
      "feedback": null,
      "metadata": null
    },
    {
      "id": "123",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Please share your order number." }],
      "createdAt": 1784332860,
      "feedback": "positive",
      "metadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 2
  }
}

找不到指定的 API v2 對話時，會回傳 404 RESOURCE_NOT_FOUND；無效的 limit 或 cursor 會回傳 400 VALIDATION_INVALID_BODY。

重試助理回覆

路徑：/api/v2/agents/{agentId}/conversations/{conversationId}/retry

POST /api/v2/agents/{agentId}/conversations/{conversationId}/retry

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。此對話必須是 API v2 對話。

主體欄位	是否必填	類型與限制
`messageId`	是	可轉換為正整數的字串或數字。必須對應該對話中的一則 AI 助理訊息。
`stream`	否	布林值；預設為 `true`。

重試操作會刪除前一則使用者訊息、所選的助理回覆，以及之後的所有訊息，接著重播該則使用者文字內容以重新生成回覆。若重新生成的結果無法持久化，已刪除的資料列會被還原。

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"123","stream":false}'

成功：200 OK。當 stream: true 時，回應是使用與聊天相同事件格式的 Server-Sent Events 串流。當 stream: false 時，回應為：

{
  "data": {
    "id": "124",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Here is a regenerated answer." }],
    "metadata": {
      "conversationId": "b2mD4kL8pQ1sT6vX",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

格式錯誤的 JSON 會回傳 400 VALIDATION_INVALID_JSON。無效的主體會回傳 400 VALIDATION_INVALID_BODY。請參見錯誤目錄中的 CHAT_RETRY_MESSAGE_NOT_FOUND、CHAT_RETRY_NO_USER_MESSAGE、RESOURCE_NOT_FOUND 與 INTERNAL_SERVER_ERROR。

提交工具結果

路徑：/api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

POST /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

主體欄位	是否必填	類型與限制
`toolCallId`	是	非空字串。
`output`	是	任意 JSON 值。

{
  "toolCallId": "call_123",
  "output": { "available": true }
}

回應：符合的待處理動作只會被領取一次，助理延續內容會以 text/event-stream 回傳。未知或已過期的呼叫回傳 404；競爭或衝突的結果回傳 409。

設定或清除訊息意見回饋

路徑：/api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

PATCH /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。此對話必須是 API v2 對話。

{messageId} 必須可轉換為正整數，且必須對應指定對話中的一則 AI 助理訊息。

主體欄位	是否必填	類型與限制
`feedback`	是	`positive`、`negative` 或 `null`。使用 `null` 可清除意見回饋。

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/messages/123/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"feedback":"positive"}'

成功：200 OK

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Please share your order number." }],
    "createdAt": 1784332860,
    "feedback": "positive",
    "metadata": null
  }
}

格式錯誤的 JSON 會回傳 400 VALIDATION_INVALID_JSON；無效的主體會回傳 400 VALIDATION_INVALID_BODY；找不到對話會回傳 404 RESOURCE_NOT_FOUND；找不到訊息會回傳 404 RESOURCE_MESSAGE_NOT_FOUND；目標不是 AI 助理訊息時，會回傳 422 RESOURCE_MESSAGE_NOT_ASSISTANT。

列出某使用者的對話

路徑：/api/v2/agents/{agentId}/users/{userId}/conversations

GET /api/v2/agents/{agentId}/users/{userId}/conversations

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

{userId} 必須是 1 到 128 個字元，且只能包含字母、數字、.、_ 與 -。

查詢參數	是否必填	限制
`limit`	否	1 到 100 之間的整數，預設為 20。
`cursor`	否	前一頁回傳的不透明游標。請原封不動地重複使用。
`source`	否	省略或使用 `api_v2`。使用 `widget` 或 `all` 會回傳 `400 VALIDATION_INVALID_BODY`；重複或無效的值同樣會回傳 400。

只有 API v2 聊天會寫入 userId，因此此端點僅會回傳 API v2 對話。其成功回應與列出對話使用相同的分頁對話摘要封裝格式。

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/users/customer_123/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK。無效的使用者 ID、limit、cursor，或 source 使用方式，都會回傳 400 VALIDATION_INVALID_BODY。

API v2 對話

列出並匯出對話、讀取訊息、重試回覆、提交工具結果，以及管理訊息意見回饋。

對話範圍

回應物件

列出對話

匯出對話

取得單一對話

列出訊息

重試助理回覆

提交工具結果

設定或清除訊息意見回饋

列出某使用者的對話

參考文件