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

Chat Records API

Get chat records via API

URL: https://api.nxcloud.com/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

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 error 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

Parameter Arguments:

Parameter	Type	Required	Example	Description
tenant_id	Long	Yes	1	Tenant ID
appkey	String	Yes	pem2****kje	Application appkey
page_number	integer	Yes	1	Page number
page_size	integer	Yes	10	Items per page, maximum 100
saas_conversation_id	String	Yes	Conversation ID	Conversation ID
channel	integer	Yes	Channel	2: WhatsApp (currently only supports 2)

| Response Parameters

Parameter	Type	Description
list	array[data JsonObject]	Request result
message	string	Request result description
code	integer	Result code
total	integer	Total list count
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
user_id	String	Agent ID
user_name	String	Agent name
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	File name (media messages only)
media_link	String	Media file link (media messages only)
mime_type	String	Media type (media messages only)
template	Object	Template information object (template messages only)
user_emoji	String	User emoji reaction
context	String	Referenced message ID (quoted messages only)
remark	String	Remark information, usually contains error details
created_at	String	Creation time
updated_at	String	Update time

template Object Field Description (included only 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 informational updates or invitations for customers to respond/take action. Any content that doesn't qualify as utility or authentication is marketingUTILITY: Facilitates a specific agreed-upon request or transaction, or provides updates related to an ongoing transaction, including post-sale notifications and recurring billing
status	String	Review status enumEnum values:APPROVED: In useIN_APPEAL: Appeal submittedPENDING: PendingREJECTED: RejectedPENDING_DELETION: Pending deletionDELETED: DeletedDISABLED: DisabledPAUSED: PausedLIMIT_EXCEEDED: Limit exceeded
rejected_reason	String	Rejection reason
quality_score	Object	Template quality object
components	Array[component object]	Template component array
parameter_format	String	Variable type: POSITIONAL (numeric) / NAMED (named)

quality_score Object Field Description

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

component Object Field Description

Parameter	Type	Description
type	String	Component type, values include: HEADER, BODY, FOOTER, BUTTONS
format	String	Only present when type=HEADER, describes the type of content in HEADER, types include TEXT, DOCUMENT, IMAGE, VIDEO
text	String	When type=HEADER and format=text, this is the HEADER text content;When type=BODY, this is the BODY text content;When type=FOOTER, this is the FOOTER text content
example	Object	Variable example, 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 information

example Object Field Description

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 creation/editing
header_text	Array[string]	Header text variable example, array contains only 1 value
body_text	Array[array[string]]	Content text variable example, array may contain 1 or multiple values based on template BODY content configuration

button Object Field Description

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 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	Has value when type=Flow, unique identifier for the flow provided by WhatsApp. Flow must be published
flow_action	String	Has value when type=Flow, navigate or data_exchange, default: navigate
navigate_screen	String	Has value when type=Flow, required only when flow_action is navigate. The 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,
      "user_channel_id": "155xxxx2740",
      "from": "852xxxx4115",
      "to": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "Test User",
      "user_id": "708",
      "user_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,
      "from": "155xxxx2740",
      "to": "852xxxx4115",
      "status": "read",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "Test User",
      "user_id": "677",
      "user_name": "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,
      "from": "155xxxx2740",
      "to": "852xxxx4115",
      "status": "delivered",
      "filename": "flower.jpg",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "Test User",
      "user_id": "677",
      "user_name": "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,
      "from": "852xxxx4115",
      "to": "155xxxx2740",
      "content": "OK",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "Test User",
      "user_id": "677",
      "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"
    }
  ]
}

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,
      "from": "852xxxx4115",
      "to": "155xxxx2740",
      "content": "Yes",
      "context": "wamid.HBgLODUyOTI5MDQxMTUVAgARGBJDMj****RThFRTNFNzYA",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "Test User",
      "user_id": "677",
      "user_name": "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 support to troubleshoot
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