消息接口

处理一条用户入站消息并同步返回分身回复。

POST /open/v1/message

请求字段

字段	类型	必填	说明
messageId	string	是	请求唯一标识，1—128 个字符；重试复用原值
externalUserId	string	是	外部用户稳定标识，1—128 个字符
externalUserName	string	否	用户昵称，最长 64 个字符
externalUserMaskedId	string	否	脱敏业务标识，最长 64 个字符；不要传手机号等明文敏感信息
conversationKey	string	否	会话键，默认 default，最长 128 个字符
messageType	string	是	text 或 image
text	string	文本时是	文本内容，1—8000 个字符
image	object	图片时是	图片信息
image.url	string	图片时是	公开可访问的 HTTPS 地址，最长 2048 个字符

每次请求只能使用一种消息类型。messageType 为 text 时不得同时提供 image；为 image 时不得同时提供 text。图片地址不能指向本机、局域网或其他私网资源。

请求示例

{
  "messageId": "msg_20260722_001",
  "externalUserId": "customer_10086",
  "externalUserName": "陈先生",
  "externalUserMaskedId": "****0086",
  "conversationKey": "after_sales",
  "messageType": "text",
  "text": "我的订单什么时候发货？"
}

图片请求示例：

{
  "messageId": "msg_20260722_002",
  "externalUserId": "customer_10086",
  "externalUserName": "陈先生",
  "externalUserMaskedId": "****0086",
  "conversationKey": "after_sales",
  "messageType": "image",
  "image": {
    "url": "https://cdn.example.com/customer-photo.png"
  }
}

成功响应

字段	类型	说明
code	number	0 表示成功
message	string	结果说明
requestId	string	服务端请求标识，用于排查
messageId	string	原请求消息标识
replyType	string	当前为 text
replyText	string	分身回复内容

{
  "code": 0,
  "message": "OK",
  "requestId": "req_01",
  "messageId": "msg_20260722_001",
  "replyType": "text",
  "replyText": "我来帮你查询发货进度。"
}

失败响应结构与处理方式见错误码。