會話訊息列表
依游標分頁返回指定會話的訊息記錄。此介面面向伺服器端對接,只返回適合對外輸出的訊息欄位。
請求
POST https://apichat.twt.com/openapi/chat/list_msg
Header 參數
| 參數名 | 類型 | 必填 | 說明 |
|---|---|---|---|
x-chat-signature | string | 是 | 使用原始 JSON Body 計算的 HMAC-SHA256 簽名 |
Accept | string | 否 | 預設值:application/json |
Content-Type | string | 是 | application/json |
lang | string | 否 | 回應語言,控制介面提示文案。支援值請參閱語言設定。可選,預設 zh-cn;未傳或非法時回退 zh-cn。此請求頭不參與 HMAC 計算。 |
Body 參數
| 參數名 | 類型 | 必填 | 說明 |
|---|---|---|---|
appid | string | 是 | 應用標識,客服端-設置-開發設置查看 |
timestamp | integer | 是 | Unix 秒級時間戳。正式環境超過 2 分鐘的請求會被拒絕 |
ranstr | string | 是 | 非空隨機字串 |
chat_id | integer | 是 | 會話 ID,可對應工單、單聊或群聊會話 |
direction | string | 是 | prev 載入更早訊息,next 載入更新訊息 |
pos_id | integer | 條件必填 | direction=next 時必填;首次載入更早訊息時不傳 |
limit | integer | 否 | 每頁數量,可選 10、20、50、100,預設 20 |
分頁規則
訊息按 ID 倒序返回,即從新到舊排列。
- 首屏:傳
direction=prev,不傳pos_id。 - 載入更早訊息:將
direction設為prev,並將pos_id設為上一頁返回的next_id。 - 載入更新訊息:將
direction設為next,並將pos_id設為上一頁返回的prev_id。 prev_id是目前頁最新訊息 ID。next_id是目前頁最舊訊息 ID。- 目前頁為空時,兩個游標都返回
null。
請求範例
curl --location --request POST 'https://apichat.twt.com/openapi/chat/list_msg' \
--header 'x-chat-signature: 7ac03ccc306902234f3b40cbe797fcb0f' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'lang: zh-tw' \
--data-raw '{
"appid": "1b621280becdb0fa3d3e041ff69e1e1f",
"timestamp": 0,
"ranstr": "string",
"chat_id": 0,
"direction": "prev",
"limit": 20
}'
返回響應
200 成功
| 參數名 | 類型 | 說明 |
|---|---|---|
code | integer | 成功時為 1 |
msg | string | 成功時為 ok |
data.list | array | 訊息列表,按 ID 倒序 |
data.prev_id | integer/null | 目前頁最新訊息 ID |
data.next_id | integer/null | 目前頁最舊訊息 ID |
訊息欄位
| 參數名 | 類型 | 說明 |
|---|---|---|
id | integer | 訊息 ID |
chat_id | integer | 會話 ID |
pid | integer | 回覆的父訊息 ID,非回覆訊息為 0 |
lx | integer | 訊息類型 |
content | string/object | 訊息內容,結構由 lx 決定 |
fs_lx | integer | 發送方:1 訪客,2 客服,3 系統 |
tjuid | integer | 發送方內部使用者 ID |
zt | integer | 訊息狀態:1 正常,2 撤回 |
is_nb | integer | 0 普通訊息,1 內部回覆 |
is_ap | integer | 0 普通訊息,1 Autopilot 訊息 |
tjsj | string | 訊息建立時間 |
at_uids | array | @ 的使用者 ID,無人被 @ 時為空陣列 |
pcontent | string/object | pid > 0 時返回父訊息內容 |
ptjuid | integer | pid > 0 時返回父訊息發送方 ID |
pfs_lx | integer | pid > 0 時返回父訊息發送方類型 |
lx 與 content 結構
lx | 含義 | 常見 content 結構 |
|---|---|---|
1 | 文字 | 字串 |
2 | 圖片 | 包含 file_url、file_origin_url、file_full_url、width、height 的物件 |
3 | 語音 | 包含 file_url、sc、is_fan、fan_text 的物件 |
4 | 影片 | 包含 file_url、slt_url、sc、size、width、height 的物件 |
5 | 檔案 | 包含 file_url、origin_name、size、ext 的物件 |
8 | 歡迎語快捷回覆 | 包含快捷回覆項的結構化物件或陣列 |
9 | 會話後表單 | 存在時返回表單快照結構化資料 |
10 | Autopilot 快捷卡片 | 包含卡片內容和操作的結構化物件 |
90+ | 系統事件 | 依事件類型返回字串或結構化物件 |
成功範例
{
"code": 1,
"msg": "ok",
"data": {
"list": [
{
"id": 90126,
"chat_id": 1841,
"pid": 0,
"lx": 1,
"content": "可以發一下最新報價嗎?",
"fs_lx": 1,
"tjuid": 20056,
"zt": 1,
"is_nb": 0,
"is_ap": 0,
"tjsj": "2026-10-23 10:30:00",
"at_uids": []
},
{
"id": 90124,
"chat_id": 1841,
"pid": 90110,
"lx": 1,
"content": "報價單已發送,請查收。",
"fs_lx": 2,
"tjuid": 10078,
"zt": 1,
"is_nb": 0,
"is_ap": 0,
"tjsj": "2026-10-23 10:29:00",
"at_uids": [],
"pcontent": "請把報價單發給我。",
"ptjuid": 20056,
"pfs_lx": 1
}
],
"prev_id": 90126,
"next_id": 90124
}
}
失敗範例
{
"code": -1,
"msg": "token驗證失敗!",
"data": ""
}
{
"code": -1,
"msg": "抱歉, 參數錯誤!",
"data": ""
}
注意事項
- 簽名必須基於實際發送的原始 JSON body 計算,欄位順序、空格和換行都需要保持一致。
- 系統會使用
appid對應站點校驗chat_id,跨站點會話統一返回抱歉, 會話不存在!。 is_nb=1表示內部回覆,接入方不得直接展示給訪客。- 介面按客服側訊息視圖返回,並裁剪內部已讀、刪除、撤回、未讀計數和 AI 提問關聯欄位。
- 空頁屬於成功響應,返回
data.list: []、prev_id: null、next_id: null。