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

Chat Records

Get chat records through 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
Authentication Required: Yes, using AI Hub

Request Parameters

Header Parameters:

Parameter	Type	Required	Example	Description
accessKey	String	Yes	fme2****di3ki	User identity identifier
ts	String	Yes	1655710885431	Current request timestamp (in milliseconds), server allows maximum time deviation of 60 seconds
bizType	String	Yes	2	WhatsApp business type, fixed value "2"
action	String	Yes	mt	WhatsApp business operation, fixed value "mt"
sign	String	Yes	6e95061f289501d32c365826	API parameter signature, common convention

Query Parameters:

Parameter	Type	Required	Example	Description
tenant_id	Long	Yes	1	Tenant ID
appkey	String	Yes	pem2****kje	Application appkey
channel	integer	Yes	Channel	2: WhatsApp (currently only supports 2)
page_number	integer	Yes	1	Page number
page_size	integer	Yes	10	Items per page, maximum 100
business_channel_id	String	No	10086	Merchant channel ID
customer_id	String	No	1	Customer ID
saas_conversation_id	String	No	Conversation ID	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: ascending desc: descending, default is descending

| Response Parameters

Parameter	Type	Description
list	array[data JsonObject]	Request result
message	string	Request result description
code	integer	Result code
total	integer	Total number of items
page_number	integer	Page number
page_size	integer	Items per page

data

Parameter	Type	Description
id	String	Message record ID
channel	integer	2 whatsapp
user_channel_id	String	Merchant unique identifier, e.g. WhatsApp merchant number
from	String	Sender
to	String	Receiver
customer_id	String	Customer ID
customer_name	String	Customer name
saas_conversation_id	String	Conversation ID
agent_id	String	Agent ID, formerly user_id
agent_name	String	Agent name, formerly user_name
agent_account	String	Agent account (uses input value if provided, otherwise defaults to agent email)
chat_type	integer	Message direction 0: outbound 1: inbound 2: system message
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 (specific to media messages)
media_link	String	Media file link (specific to media messages), valid for 60 minutes, remember to download and save
mime_type	String	Media type (specific to media messages)
template	Object	Template information object (specific to template messages)
user_emoji	String	User emoji reaction
context	String	Referenced message ID (specific to reply messages)
remark	String	Remark information, usually contains error details
created_at	String	Created time
updated_at	String	Updated time

template Object Fields (only included when message type='template')

Parameter	Type	Description
id	String	Template ID
name	String	Template name
language	String	Template language
category	String	Template typeEnum values:MARKETING: Includes promotional or offer messages, information updates or invitations for customers to respond/take action. Any message that does not serve utility or authentication purposes is marketingUTILITY: Facilitates a specific agreed-upon request or transaction, or provides updates to customers about an ongoing transaction, including post-sale notifications and recurring billing
status	String	Approval status enumEnum values:APPROVED: In useIN_APPEAL: AppealedPENDING: PendingREJECTED: RejectedPENDING_DELETION: Pending deletionDELETED: DeletedDISABLED: DisabledPAUSED: Temporarily pausedLIMIT_EXCEEDED: Limit exceeded
rejected_reason	String	Rejection reason
quality_score	Object	Template quality object
components	Array[component object]	Template components array
parameter_format	String	Parameter type POSITIONAL(numeric)/NAMED(named)

quality_score Object Fields

Parameter	Type	Description
score	String	Template quality enumEnum values:GREEN: HighYELLOW: MediumRED: LowUNKNOWN: Quality pending

component Object Fields

Parameter	Type	Description
type	String	Component type, values include: HEADER, BODY, FOOTER, BUTTONS
format	String	Only present when type=HEADER, describes content type in HEADER, types include TEXT, DOCUMENT, IMAGE, VIDEO
text	String	When type=HEADER and format=text, contains HEADER text content;When type=BODY, contains BODY text content;When type=FOOTER, contains FOOTER text content
example	Object	Parameter examples, present when variables and example values are configured in HEADER or BODY content
buttons	Array[button object]	Only present when type=BUTTONS, describes template button configuration

example Object Fields

Parameter	Type	Description
header_handle	String	Header media resource link
custom_header_handle_url	String	Custom header media resource link, has value when custom_header_handle_url is selected during create/edit
header_text	Array[string]	Header text parameter examples, array contains only 1 value
body_text	Array[array[string]]	Body text parameter examples, array may contain 1 or more values depending on template BODY content configuration

button Object Fields

Parameter	Type	Description
type	String	Button type, includes QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, FLOW1. QUICK_REPLY - quick reply button2. URL - call-to-action url button3. PHONE_NUMBER - call-to-action phone_number button4. COPY_CODE - copy optimization code5. FLOW
text	String	Display text on button
url	String	URL configured on call-to-action button, only present when type=URL
phone_number	String	Phone number configured on call-to-action button, only present when type=PHONE_NUMBER
example	Array[string]	Example URL, e.g.: https://www.baidu.com/user
flow_id	String	Present when type=Flow, WhatsApp-provided unique identifier for the flow. Flow must be published
flow_action	String	Present when type=Flow, navigate or data_exchange, default: navigate
navigate_screen	String	Present when type=Flow, required only when flow_action is navigate. First screen of the flow

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": "空格键",
      "agent_id": "708",
      "agent_name": "Sandy****@nxcloud.com",
      "chat_type": 1,
      "message_type": "text",
      "content": "你好",
      "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": "空格键",
      "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": "1185578765833007104",
      "channel": 2,
      "saas_conversation_id": "xxxxxxx111111",
      "from": "155xxxx2740",
      "to": "852xxxx4115",
      "status": "delivered",
      "filename": "樱花.jpg",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "空格键",
      "agent_id": "677",
      "agent_name": "Wendy****",
      "agent_account": "Wendy****",
      "chat_type": 0,
      "message_type": "image",
      "media_link": "https://xxxxxxx.com/23?Expires=1760597396&",
      "mime_type": "image/jpeg",
      "created_at": "2025-10-16 13:46:45",
      "updated_at": "2025-10-16 13:46:49"
    }
  ]
}

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": "好的",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "空格键",
      "agent_id": "677",
      "agent_name": "Wendy****",
      "agent_account": "Wendy****",
      "chat_type": 1,
      "message_type": "text",
      "message_id": "wamid.HBgLODUyOTI5MDQxMTUVAgASGBQzQU****MDgwMzFDNzhGRjczOAA=",
      "user_emoji": "👍",
      "created_at": "2025-10-16 14:40:25",
      "updated_at": "2025-10-16 14:41:28"
    }
  ]
}

Reply 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": "是的",
      "context": "wamid.HBgLODUyOTI5MDQxMTUVAgARGBJDMj****RThFRTNFNzYA",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "空格键",
      "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 Code Description

code	message	Solution
0	Request successful
-1	Request failed	Please contact technical personnel to troubleshoot the issue
1000~100X	Authentication issue	See API authentication section for details
21058	Parameter error	tenant_id is required
21059	Parameter error	appkey is required
22016	Parameter error	Merchant has not configured WhatsApp application
22072	Parameter error	Invalid parameter error