Skip to content

openapi‐chat‐records

Jump to bottom
zjc1750514326 edited this page Nov 10, 2025 · 6 revisions

聊天记录接口

通过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
  • 需要鉴权：是

请求参数

header参数：

参数名 类型 必选 示例值 说明
accessKey String 是 fme2****di3ki 用户身份标识
ts String 是 1655710885431 当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType String 是 2 WhatsApp业务类型，取固定值"2"
action String 是 mt WhatsApp业务操作，取固定值"mt"
sign String 是 6e95061f289501d32c365826 API入参参数签名，公共约定

parameter 参数：

参数名 类型 必选 示例值 说明
tenant_id Long 是 1 租户ID
appkey String 是 pem2****kje 应用appkey
page_number integer 是 1 页数
page_size integer 是 10 每页个数,最大100
saas_conversation_id String 是 会话ID 会话ID
channel integer 是 渠道 2：WhatsApp 目前只支持2

返回参数说明

参数名 类型 说明
list array[data JsonObject] 请求结果
message string 请求结果说明
code integer 结果编码
total integer 列表总数量
page_number integer 页数
page_size integer 每页数量

data

参数名 类型 说明
id String 消息记录ID
channel integer 2 whatsapp
user_channel_id String 商户唯一标识符,例如WhatsApp商户号码
from String 发送方
to String 接收方
customer_id String 客户ID
customer_name String 客户名称
user_id String 坐席ID
user_name String 坐席名称
chat_type integer 消息方向 0下行 1上行 2系统消息
message_type String 消息类型(text/image/video/audio/document/template等)
content String 消息内容
message_id String 消息ID
status String 消息状态(sent/delivered/read/failed等)
tenant_id String 租户ID
filename String 文件名(媒体消息特有)
media_link String 媒体文件链接(媒体消息特有)
mime_type String 媒体类型(媒体消息特有)
template Object 模板信息对象(模板消息特有)
user_emoji String 用户表情回复
context String 引用的消息ID(引用消息特有)
remark String 备注信息,通常包含错误详情
created_at String 创建时间
updated_at String 更新时间

template对象字段说明(仅模板消息type='template'时包含)

参数名 类型 说明
id String 模板ID
name String 模板名称
language String 模板语言
category String 模板类型
枚举值:
MARKETING: 包括促销或优惠、信息更新或邀请客户回应/采取行动的信息。任何不符合效用或身份验证用途均为营销
UTILITY: 促成商定的某个具体请求或交易，或向客户提供与进行中的交易相关的最新信息，包括售后通知和定期账单
status String 审核状态枚举
枚举值:
APPROVED: 使用中
IN_APPEAL: 已提出上诉
PENDING: 待处理
REJECTED: 已拒绝
PENDING_DELETION: 待删除
DELETED: 已删除
DISABLED: 不可用
PAUSED: 暂时停用
LIMIT_EXCEEDED: 超出限制
rejected_reason String 拒绝原因
quality_score Object 模板质量对象
components Array[component object] 模板组件数组
parameter_format String 变量类型 POSITIONAL(数字)/NAMED(名称)

quality_score对象字段说明

参数名 类型 说明
score String 模板质量枚举
枚举值:
GREEN: 高
YELLOW: 中
RED: 低
UNKNOWN: 质量待定

component对象字段说明

参数名 类型 说明
type String 组件类型,取值包括：HEADER, BODY, FOOTER, BUTTONS
format String 仅type=HEADER时有此项，描述HEADER里内容的类型，类型包括TEXT，DOCUMENT，IMAGE，VIDEO
text String type=HEADER且format=text时，为HEADER文本内容；
type=BODY时，为BODY的文本内容；
type=FOOTER时，为FOOTER的文本内容
example Object 变量示例，当HEADER或者BODY内容中配置了变量及示例值时，有此项
buttons Array[button object] 仅type=BUTTONS时有此项，描述模板按钮的配置信息

example对象字段说明

参数名 类型 说明
header_handle String 头部媒体资源链接
custom_header_handle_url String 自定义头部媒体资源链接，当创建/编辑时选择custom_header_handle_url有值
header_text Array[string] 头部文本变量示例，数组中仅有1个值
body_text Array[array[string]] 内容文本变量示例，根据模板BODY的内容配置，数组中可能有1个或多个值

button对象字段说明

参数名 类型 说明
type String 按钮类型，包括QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, FLOW
1. QUICK_REPLY即快速回复按钮
2. URL即行动号召url按钮
3. PHONE_NUMBER即行动号召phone_number按钮
4. COPY_CODE 复制优化码
5. FLOW
text String 按钮上的显示文字
url String 行动号召按钮上配置的网址，仅type=URL时有此项
phone_number String 行动号召按钮上配置的电话，仅type=PHONE_NUMBER时有此项
example Array[string] 示例的URL,例如:https://www.baidu.com/user
flow_id String 当type=Flow时有值, WhatsApp提供的流程的唯一标识符。流程必须已发布
flow_action String 当type=Flow时有值, navigate或data_exchange 默认：navigate
navigate_screen String 当type=Flow时有值, 仅在flow_action为navigate时，此为必要项。流程的第一个屏幕

响应示例

文本消息
{
  "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": "空格键",
      "user_id": "708",
      "user_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"
    }
  ]
}
模板消息
{
  "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": "空格键",
      "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"
    }
  ]
}
媒体消息(图片)
{
  "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": "樱花.jpg",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "空格键",
      "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"
    }
  ]
}
表情回复消息
{
  "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": "好的",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "空格键",
      "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"
    }
  ]
}
引用消息
{
  "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": "是的",
      "context": "wamid.HBgLODUyOTI5MDQxMTUVAgARGBJDMj****RThFRTNFNzYA",
      "tenant_id": "123",
      "user_channel_id": "155xxxx2740",
      "customer_id": "1184532470154289152",
      "customer_name": "空格键",
      "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"
    }
  ]
}

响应码说明

code message 解决办法
0 请求成功
-1 请求失败 请联系技术人员排除问题
1000~100X 鉴权问题 详情查看API鉴权部分
21058 参数异常 tenant_id 必填
21059 参数异常 appkey必填
22016 参数异常 商户未配置WhatsApp应用
22072 参数异常 参数错误异常

简介

短信

语音

云呼叫中心（NXLink）

云呼叫中心（AI自动外呼）

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Clone this wiki locally