openapi‐chat‐records - nxtele/nxcloud-doc-en GitHub Wiki

Query Chat Records

Query chat records via API.

URL: https://api-hk.nxlink.ai/saas/openapi/chat/records?page_number={page_number}&page_size={page_size}&tenant_id={tenant_id}&appkey={appkey}&saas_conversation_id={dimension}&channel={channel}
Method: GET
Content-Type: application/json
Requires authentication: Yes (AI Hub)

Request Parameters

Header Parameters

Parameter	Type	Required	Example	Description
accessKey	String	Yes	fme2****di3ki	User identity key
ts	String	Yes	1655710885431	Timestamp in milliseconds. Max allowed time drift is 60 seconds.
bizType	String	Yes	2	WhatsApp business type, fixed value "2"
action	String	Yes	mt	WhatsApp action, fixed value "mt"
sign	String	Yes	6e95061f289501d32c365826	Signature, see common auth rules

Query Parameters

Parameter	Type	Required	Example	Description
tenant_id	Long	Yes	1	Tenant ID
appkey	String	Yes	pem2****kje	Application appkey
channel	integer	Yes	2	Channel. 2 = WhatsApp (only 2 is supported)
page_number	integer	Yes	1	Page number
page_size	integer	Yes	10	Page size, max 100
business_channel_id	String	No	10086	Business channel ID
customer_id	String	No	1	Customer ID
saas_conversation_id	String	No	-	Conversation ID
agent_account	String	No	[email protected]	Agent account
start_time	String	No	2025-01-01 00:00:00	Start time, format yyyy-MM-dd HH:mm:ss
end_time	String	No	2025-01-01 23:59:59	End time, format yyyy-MM-dd HH:mm:ss
order_by	String	No	desc	Sort order: asc/desc (default desc)

Response Parameters

Parameter	Type	Description
list	array[data JsonObject]	Result list
message	string	Message
code	integer	Result code
total	integer	Total count
page_number	integer	Page number
page_size	integer	Page size

data

Parameter	Type	Description
id	String	Message record ID
channel	integer	2 = WhatsApp
user_channel_id	String	Business unique ID, e.g., WhatsApp business phone
from	String	Sender
to	String	Recipient
customer_id	String	Customer ID
customer_name	String	Customer name
saas_conversation_id	String	Conversation ID
agent_id	String	Agent ID (original user_id)
agent_name	String	Agent name (original user_name)
agent_account	String	Agent account (use request value if provided; otherwise default agent email)
chat_type	integer	Direction: 0 outbound, 1 inbound, 2 system
message_type	String	Message type (text/image/video/audio/document/template, etc.)
content	String	Message content
message_id	String	Message ID
status	String	Message status (sent/delivered/read/failed, etc.)
tenant_id	String	Tenant ID
filename	String	Filename (media messages)
media_link	String	Media link (valid 60 minutes)
mime_type	String	Media MIME type
template	Object	Template object (template messages only)
user_emoji	String	User emoji reaction
context	String	Referenced message ID (reply messages)
remark	String	Remarks, usually error details
created_at	String	Created time
updated_at	String	Updated time

template object (only when type='template')

Parameter	Type	Description
id	String	Template ID
name	String	Template name
language	String	Template language
category	String	Template category. Values: MARKETING, UTILITY
status	String	Status. Values: APPROVED, IN_APPEAL, PENDING, REJECTED, PENDING_DELETION, DELETED, DISABLED, PAUSED, LIMIT_EXCEEDED
rejected_reason	String	Rejection reason
quality_score	Object	Quality score object
components	Array[component object]	Components
parameter_format	String	POSITIONAL or NAMED

quality_score object

Parameter	Type	Description
score	String	GREEN / YELLOW / RED / UNKNOWN

component object

Parameter	Type	Description
type	String	HEADER, BODY, FOOTER, BUTTONS
format	String	HEADER only: TEXT, DOCUMENT, IMAGE, VIDEO
text	String	Text for HEADER/BODY/FOOTER
example	Object	Example values when variables are used
buttons	Array[button object]	BUTTONS only

example object

Parameter	Type	Description
header_handle	String	Header media link
custom_header_handle_url	String	Custom header media link
header_text	Array[string]	Header text variable examples
body_text	Array[array[string]]	Body variable examples

button object

Parameter	Type	Description
type	String	QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, FLOW
text	String	Button text
url	String	URL (type=URL)
phone_number	String	Phone number (type=PHONE_NUMBER)
example	Array[string]	URL examples, e.g. https://www.baidu.com/user
flow_id	String	Flow ID (type=FLOW)
flow_action	String	navigate or data_exchange (default navigate)
navigate_screen	String	First screen when flow_action=navigate

Response Examples

Text Message

{
  "code": 0,
  "message": null,
  "traceId": "ee0e7427****4dd58c43****92ed9958.316.17223233548652651",
  "total": 4,
  "page_number": 1,
  "page_size": 10,
  "list": [
    {
      "id": "1184532473820278785",
      "channel": 2,
      "saas_conversation_id": "xxxxxxx111111",
      "user_channel_id": "155xxxx2740",
      "from": "852xxxx4115",
      "to": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "SpaceKey",
      "agent_id": "708",
      "agent_name": "Sandy****@nxcloud.com",
      "chat_type": 1,
      "message_type": "text",
      "content": "hello",
      "created_at": "2025-10-13 16:29:09",
      "updated_at": "2025-10-13 16:29:09"
    }
  ]
}

Template Message

{
  "code": 0,
  "message": null,
  "traceId": "ee0e7427****4dd58c43****92ed9958.316.17223233548652651",
  "total": 1,
  "page_number": 1,
  "page_size": 10,
  "list": [
    {
      "id": "1185539581697126400",
      "channel": 2,
      "saas_conversation_id": "xxxxxxx111111",
      "from": "155xxxx2740",
      "to": "852xxxx4115",
      "status": "read",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "SpaceKey",
      "agent_id": "677",
      "agent_name": "Wendy****",
      "agent_account": "Wendy****",
      "chat_type": 0,
      "message_type": "template",
      "message_id": "wamid.HBgLODUyOTI5MDQxMTUVAgARGBI2NzYxQT****3k3NkMA",
      "template": {
        "name": "hi",
        "language": "af",
        "category": "MARKETING",
        "status": "APPROVED",
        "components": [
          {
            "type": "BODY",
            "text": "hi"
          }
        ],
        "rejected_reason": "NONE"
      },
      "created_at": "2025-10-16 11:11:02",
      "updated_at": "2025-10-16 11:11:10"
    }
  ]
}

Media Message (Image)

{
  "code": 0,
  "message": null,
  "traceId": "ee0e7427****4dd58c43****92ed9958.316.17223233548652651",
  "total": 1,
  "page_number": 1,
  "page_size": 10,
  "list": [
    {
      "id": "1185539581697126401",
      "channel": 2,
      "saas_conversation_id": "xxxxxxx111111",
      "from": "155xxxx2740",
      "to": "852xxxx4115",
      "status": "read",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "SpaceKey",
      "agent_id": "677",
      "agent_name": "Wendy****",
      "agent_account": "Wendy****",
      "chat_type": 0,
      "message_type": "image",
      "message_id": "wamid.HBgLODUyOTI5MDQxMTUVAgARGBI2NzYxQT****3k3NkMA",
      "content": "image",
      "filename": "sakura.jpg",
      "media_link": "https://xxxxxxx.com/23?Expires=1760597396&",
      "mime_type": "image/jpeg",
      "created_at": "2025-10-16 11:11:02",
      "updated_at": "2025-10-16 11:11:10"
    }
  ]
}

Emoji Reaction Message

{
  "code": 0,
  "message": null,
  "traceId": "ee0e7427****4dd58c43****92ed9958.316.17223233548652651",
  "total": 1,
  "page_number": 1,
  "page_size": 10,
  "list": [
    {
      "id": "1185592273696833536",
      "channel": 2,
      "saas_conversation_id": "xxxxxxx111111",
      "from": "852xxxx4115",
      "to": "155xxxx2740",
      "content": "ok",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "SpaceKey",
      "agent_id": "677",
      "agent_name": "Wendy****",
      "agent_account": "Wendy****",
      "chat_type": 1,
      "message_type": "text",
      "message_id": "wamid.HBgLODUyOTI5MDQxMTUVAgASGBQzQU****MDgwMzFDNzhGRjczOAA=",
      "user_emoji": "+1",
      "created_at": "2025-10-16 14:40:25",
      "updated_at": "2025-10-16 14:41:28"
    }
  ]
}

Quoted Message

{
  "code": 0,
  "message": null,
  "traceId": "ee0e7427****4dd58c43****92ed9958.316.17223233548652651",
  "total": 1,
  "page_number": 1,
  "page_size": 10,
  "list": [
    {
      "id": "1185593370125647872",
      "channel": 2,
      "saas_conversation_id": "xxxxxxx111111",
      "from": "852xxxx4115",
      "to": "155xxxx2740",
      "content": "yes",
      "context": "wamid.HBgLODUyOTI5MDQxMTUVAgARGBJDMj****RThFRTNFNzYA",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "SpaceKey",
      "agent_id": "677",
      "agent_name": "Wendy****",
      "agent_account": "Wendy****",
      "chat_type": 1,
      "message_type": "text",
      "message_id": "wamid.HBgLODUyOTI5MDQxMTUVAgASGBQzQU****RUU4MTY5MTUwOEQxMwA=",
      "created_at": "2025-10-16 14:44:46",
      "updated_at": "2025-10-16 14:44:49"
    }
  ]
}

Response Codes

code	message	solution
0	Success	-
-1	Failure	Contact support
1000~100X	Authentication failed	See authentication section
21058	Parameter error	tenant_id required
21059	Parameter error	appkey required
22016	Parameter error	Business does not configure WhatsApp app
22072	Parameter error	Invalid parameter