Skip to main content

List Messages

Return the message history of one session with cursor-based pagination. The response is designed for server-to-server integrations and returns only fields that are safe to expose outside the agent console.

Request​

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

Header Parameters​

ParameterTypeRequiredDescription
x-chat-signaturestringYesHMAC-SHA256 signature calculated from the exact raw JSON body
AcceptstringNoDefault: application/json
Content-TypestringYesapplication/json
langstringNoResponse language for API messages. Supported values: Language Configuration. Optional; default zh-cn. If omitted or invalid, falls back to zh-cn. The header is not part of the HMAC payload.

Body Parameters​

ParameterTypeRequiredDescription
appidstringYesApplication identifier from the console
timestampintegerYesUnix timestamp in seconds. In production, requests older than 2 minutes are rejected
ranstrstringYesNon-empty random string used to make each request unique
chat_idintegerYesSession ID. It can identify a ticket, direct chat, or group chat session
directionstringYesprev to load older messages, next to load newer messages
pos_idintegerConditionalRequired when direction is next; omit it on the first prev request
limitintegerNoPage size. Allowed values: 10, 20, 50, 100. Default: 20

Pagination​

Messages are returned in descending ID order, from newest to oldest.

  • First page: send direction=prev without pos_id.
  • Load older messages: set direction to prev and set pos_id to the previous page's next_id.
  • Load newer messages: set direction to next and set pos_id to the previous page's prev_id.
  • prev_id is the newest message ID in the current page.
  • next_id is the oldest message ID in the current page.
  • Both cursor fields are null when the page is empty.

Request Example​

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: en' \
--data-raw '{
"appid": "1b621280becdb0fa3d3e041ff69e1e1f",
"timestamp": 0,
"ranstr": "string",
"chat_id": 0,
"direction": "prev",
"limit": 20
}'

Response​

200 Success​

ParameterTypeDescription
codeinteger1 on success
msgstringok on success
data.listarrayMessages in descending ID order
data.prev_idinteger/nullNewest message ID in this page
data.next_idinteger/nullOldest message ID in this page

Message Fields​

ParameterTypeDescription
idintegerMessage ID
chat_idintegerSession ID
pidintegerParent message ID for a reply; 0 when the message is not a reply
lxintegerMessage type
contentstring/objectMessage payload. Its shape depends on lx
fs_lxintegerSender side: 1 visitor, 2 agent, 3 system
tjuidintegerInternal user ID of the sender
ztintegerMessage state: 1 normal, 2 recalled
is_nbinteger0 normal message, 1 internal reply
is_apinteger0 normal message, 1 Autopilot message
tjsjstringCreated time
at_uidsarrayMentioned user IDs; empty when nobody is mentioned
pcontentstring/objectParent message content when pid > 0
ptjuidintegerParent message sender ID when pid > 0
pfs_lxintegerParent message sender side when pid > 0

Content by Message Type​

lxMeaningTypical content shape
1TextString
2ImageObject with file_url, file_origin_url, file_full_url, width, and height
3AudioObject with file_url, sc, is_fan, and fan_text
4VideoObject with file_url, slt_url, sc, size, width, and height
5FileObject with file_url, origin_name, size, and ext
8Welcome-message quick replyStructured object or array containing quick-reply items
9Post-chat formStructured form snapshot when present
10Autopilot action cardStructured object containing card content and actions
90+System eventString or structured event object depending on the event type

Example​

{
"code": 1,
"msg": "ok",
"data": {
"list": [
{
"id": 90126,
"chat_id": 1841,
"pid": 0,
"lx": 1,
"content": "Can you share the latest price?",
"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": "Here is the quotation.",
"fs_lx": 2,
"tjuid": 10078,
"zt": 1,
"is_nb": 0,
"is_ap": 0,
"tjsj": "2026-10-23 10:29:00",
"at_uids": [],
"pcontent": "Please send me the quotation.",
"ptjuid": 20056,
"pfs_lx": 1
}
],
"prev_id": 90126,
"next_id": 90124
}
}

Error Example​

{
"code": -1,
"msg": "Token verification failed!",
"data": ""
}
{
"code": -1,
"msg": "Sorry, parameter error!",
"data": ""
}

Notes​

  • The signature must be calculated from the exact raw JSON body sent in the HTTP request.
  • chat_id is always checked against the site represented by appid. A session from another site is reported as Sorry, session does not exist!.
  • Messages with is_nb=1 are internal replies. API consumers must not display them directly to visitors.
  • The endpoint uses the agent-side message view and excludes fields used only for internal read, deletion, recall, unread-count, and AI question correlation logic.
  • Empty pages are successful responses with data.list: [], prev_id: null, and next_id: null.