查询访客未读消息

按访客外部 ID 查询最近会话的未读消息数量，并可返回未读消息列表。

请求参数

名称	类型	必填	描述
appKey	string	是	企业 AppKey。
time	int64	是	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数。
checksum	string	是	请求签名，签名规则参考通用说明的数据校验。
checksumAlgorithm	int32	否	签名算法版本，默认 0。

请求体

名称	类型	必填	描述	示例值
foreignId	string	是	访客外部账号	visitor_001
getUnreadList	boolean	否	是否返回未读消息列表。true 表示返回最近未读消息列表，false 或不传表示只返回未读数和最近一条消息	true

返回参数

名称	类型	描述	示例值
code	int32	业务状态码，200 表示成功。	200
message	string	响应信息。成功时该字段通常为空或不返回。	success
data	object	访客未读消息信息。
└count	int32	未读消息数量。	2
└lastMessage	object	最近一条未读消息；getUnreadList 未传或为 false 时返回。
└content	string	消息内容。文本消息为文本内容，其他消息类型通常为 JSON 字符串。	您好
└type	string	消息类型展示值。	text
└time	int64	消息发送时间，毫秒时间戳。	1716446400000
└msgIdClient	string	消息客户端 ID。	msg_001
└sessionStartTime	int64	会话开始时间，毫秒时间戳。	1716446300000
└kefuId	int64	客服 ID；返回消息列表时可能返回。	10001
└kefuName	string	客服昵称；返回消息列表时可能返回。	张三
└messageList	object[]	未读消息列表；getUnreadList 为 true 时返回，最多返回配置允许的条数。
└content	string	消息内容。文本消息为文本内容，其他消息类型通常为 JSON 字符串。	您好
└type	string	消息类型展示值。	text
└time	int64	消息发送时间，毫秒时间戳。	1716446400000
└msgIdClient	string	消息客户端 ID。	msg_001
└sessionStartTime	int64	会话开始时间，毫秒时间戳。	1716446300000
└kefuId	int64	客服 ID；返回消息列表时可能返回。	10001
└kefuName	string	客服昵称；返回消息列表时可能返回。	张三

错误码

状态码	描述
400	请求参数格式错误、缺少必要字段或请求体不是合法 JSON。
401	鉴权失败、签名错误、AppKey 不存在或 time 超出允许范围。
500	服务端处理异常。
8002	业务错误码，HTTP 状态码仍为 200：参数错误，常见于请求体 JSON 不合法、缺少必填字段或字段格式不合法。
8003	业务错误码，HTTP 状态码仍为 200：业务状态错误，例如质检任务状态错误或任务类型不匹配。
14001	业务错误码，HTTP 状态码仍为 200：AppKey 不存在或无效。
14002	业务错误码，HTTP 状态码仍为 200：checksum 签名校验失败。
14003	业务错误码，HTTP 状态码仍为 200：time 与服务器时间相差超过允许范围，或时间参数为空。
14004	业务错误码，HTTP 状态码仍为 200：请求内容错误，例如请求体格式错误、缺少必填字段或字段值不合法。
14005	业务错误码，HTTP 状态码仍为 200：无客服在线。
14006	业务错误码，HTTP 状态码仍为 200：访客正在排队。
14008	业务错误码，HTTP 状态码仍为 200：IP 白名单限制或 IP 被拦截。
14009	业务错误码，HTTP 状态码仍为 200：请求过于频繁。
14010	业务错误码，HTTP 状态码仍为 200：留言功能关闭。
14011	业务错误码，HTTP 状态码仍为 200：接口未开放或被停用。
14014	业务错误码，HTTP 状态码仍为 200：访客处于挂起状态。
14015	业务错误码，HTTP 状态码仍为 200：访客正在分流中。
14500	业务错误码，HTTP 状态码仍为 200：系统内部错误。

postEndpoint

/openapi/message/getUnread

curl -X POST "https://qiyukf.com/openapi/message/getUnread?appKey=string&time=0&checksum=string" \  -H "Content-Type: application/json" \  -d '{    "foreignId": "visitor_001"  }'

{
  "code": 200,
  "message": "success",
  "data": {
    "count": 2,
    "lastMessage": {
      "content": "您好",
      "type": "text",
      "time": 1716446400000,
      "msgIdClient": "msg_001",
      "sessionStartTime": 1716446300000,
      "kefuId": 10001,
      "kefuName": "张三"
    },
    "messageList": [
      {
        "content": "您好",
        "type": "text",
        "time": 1716446400000,
        "msgIdClient": "msg_001",
        "sessionStartTime": 1716446300000,
        "kefuId": 10001,
        "kefuName": "张三"
      }
    ]
  }
}

空

{
  "code": 8002,
  "message": "参数错误，常见于请求体 JSON 不合法、缺少必填字段或字段格式不合法。"
}

{
  "code": 8003,
  "message": "业务状态错误，例如质检任务状态错误或任务类型不匹配。"
}

{
  "code": 14001,
  "message": "AppKey 不存在或无效。"
}

{
  "code": 14002,
  "message": "checksum 签名校验失败。"
}

{
  "code": 14003,
  "message": "time 与服务器时间相差超过允许范围，或时间参数为空。"
}

{
  "code": 14004,
  "message": "请求内容错误，例如请求体格式错误、缺少必填字段或字段值不合法。"
}

{
  "code": 14005,
  "message": "无客服在线。"
}

{
  "code": 14006,
  "message": "访客正在排队。"
}

{
  "code": 14008,
  "message": "IP 白名单限制或 IP 被拦截。"
}

{
  "code": 14009,
  "message": "请求过于频繁。"
}

{
  "code": 14010,
  "message": "留言功能关闭。"
}

{
  "code": 14011,
  "message": "接口未开放或被停用。"
}

{
  "code": 14014,
  "message": "访客处于挂起状态。"
}

{
  "code": 14015,
  "message": "访客正在分流中。"
}

{
  "code": 14500,
  "message": "系统内部错误。"
}