跳至主要内容

會話訊息列表

依游標分頁返回指定會話的訊息記錄。此介面面向伺服器端對接,只返回適合對外輸出的訊息欄位。

請求​

POST https://apichat.twt.com/openapi/chat/list_msg

Header 參數​

參數名類型必填說明
x-chat-signaturestring是使用原始 JSON Body 計算的 HMAC-SHA256 簽名
Acceptstring否預設值:application/json
Content-Typestring是application/json
langstring否回應語言,控制介面提示文案。支援值請參閱語言設定。可選,預設 zh-cn;未傳或非法時回退 zh-cn。此請求頭不參與 HMAC 計算。

Body 參數​

參數名類型必填說明
appidstring是應用標識,客服端-設置-開發設置查看
timestampinteger是Unix 秒級時間戳。正式環境超過 2 分鐘的請求會被拒絕
ranstrstring是非空隨機字串
chat_idinteger是會話 ID,可對應工單、單聊或群聊會話
directionstring是prev 載入更早訊息,next 載入更新訊息
pos_idinteger條件必填direction=next 時必填;首次載入更早訊息時不傳
limitinteger否每頁數量,可選 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 成功​

參數名類型說明
codeinteger成功時為 1
msgstring成功時為 ok
data.listarray訊息列表,按 ID 倒序
data.prev_idinteger/null目前頁最新訊息 ID
data.next_idinteger/null目前頁最舊訊息 ID

訊息欄位​

參數名類型說明
idinteger訊息 ID
chat_idinteger會話 ID
pidinteger回覆的父訊息 ID,非回覆訊息為 0
lxinteger訊息類型
contentstring/object訊息內容,結構由 lx 決定
fs_lxinteger發送方:1 訪客,2 客服,3 系統
tjuidinteger發送方內部使用者 ID
ztinteger訊息狀態:1 正常,2 撤回
is_nbinteger0 普通訊息,1 內部回覆
is_apinteger0 普通訊息,1 Autopilot 訊息
tjsjstring訊息建立時間
at_uidsarray@ 的使用者 ID,無人被 @ 時為空陣列
pcontentstring/objectpid > 0 時返回父訊息內容
ptjuidintegerpid > 0 時返回父訊息發送方 ID
pfs_lxintegerpid > 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會話後表單存在時返回表單快照結構化資料
10Autopilot 快捷卡片包含卡片內容和操作的結構化物件
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。