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
| Parameter | Type | Required | Description |
|---|---|---|---|
x-chat-signature | string | Yes | HMAC-SHA256 signature calculated from the exact raw JSON body |
Accept | string | No | Default: application/json |
Content-Type | string | Yes | application/json |
lang | string | No | Response 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
| Parameter | Type | Required | Description |
|---|---|---|---|
appid | string | Yes | Application identifier from the console |
timestamp | integer | Yes | Unix timestamp in seconds. In production, requests older than 2 minutes are rejected |
ranstr | string | Yes | Non-empty random string used to make each request unique |
chat_id | integer | Yes | Session ID. It can identify a ticket, direct chat, or group chat session |
direction | string | Yes | prev to load older messages, next to load newer messages |
pos_id | integer | Conditional | Required when direction is next; omit it on the first prev request |
limit | integer | No | Page 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=prevwithoutpos_id. - Load older messages: set
directiontoprevand setpos_idto the previous page'snext_id. - Load newer messages: set
directiontonextand setpos_idto the previous page'sprev_id. prev_idis the newest message ID in the current page.next_idis the oldest message ID in the current page.- Both cursor fields are
nullwhen 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
| Parameter | Type | Description |
|---|---|---|
code | integer | 1 on success |
msg | string | ok on success |
data.list | array | Messages in descending ID order |
data.prev_id | integer/null | Newest message ID in this page |
data.next_id | integer/null | Oldest message ID in this page |
Message Fields
| Parameter | Type | Description |
|---|---|---|
id | integer | Message ID |
chat_id | integer | Session ID |
pid | integer | Parent message ID for a reply; 0 when the message is not a reply |
lx | integer | Message type |
content | string/object | Message payload. Its shape depends on lx |
fs_lx | integer | Sender side: 1 visitor, 2 agent, 3 system |
tjuid | integer | Internal user ID of the sender |
zt | integer | Message state: 1 normal, 2 recalled |
is_nb | integer | 0 normal message, 1 internal reply |
is_ap | integer | 0 normal message, 1 Autopilot message |
tjsj | string | Created time |
at_uids | array | Mentioned user IDs; empty when nobody is mentioned |
pcontent | string/object | Parent message content when pid > 0 |
ptjuid | integer | Parent message sender ID when pid > 0 |
pfs_lx | integer | Parent message sender side when pid > 0 |
Content by Message Type
lx | Meaning | Typical content shape |
|---|---|---|
1 | Text | String |
2 | Image | Object with file_url, file_origin_url, file_full_url, width, and height |
3 | Audio | Object with file_url, sc, is_fan, and fan_text |
4 | Video | Object with file_url, slt_url, sc, size, width, and height |
5 | File | Object with file_url, origin_name, size, and ext |
8 | Welcome-message quick reply | Structured object or array containing quick-reply items |
9 | Post-chat form | Structured form snapshot when present |
10 | Autopilot action card | Structured object containing card content and actions |
90+ | System event | String 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_idis always checked against the site represented byappid. A session from another site is reported asSorry, session does not exist!.- Messages with
is_nb=1are 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, andnext_id: null.