# 客服消息事件

> 本文档描述服务器端接收的消息或事件，详细说明参见[消息推送](/miniprogram/dev/framework/server-ability/message-push.md)。

事件英文名：commkf_send_msg_to_kf

当微信客户、接待人员发消息或有行为动作时，商家客服后台会将事件的回调数据包发送到指定URL。

相关 API 接口：
- [上传多媒体资源](/doc/store/shop/API/kf/api_cosupload)
- [发送消息](/doc/store/shop/API/kf/api_sendmsg)

相关开发指南：

- [自研客服API接入指引](/doc/store/shop/product/kf/kf_api_guidelines)
- [微信小店接入自研客服API工具说明](/doc/store/shop/product/kf/kf_intro)

## 1. 消息参数

### 请求体 `Request Payload`

```json
[
  {
    "参数名": "ToUserName",
    "类型": "string",
    "说明": "小店UserName"
  },
  {
    "参数名": "FromUserName",
    "类型": "string",
    "说明": "小店用户的OpenID"
  },
  {
    "参数名": "CreateTime",
    "类型": "number",
    "说明": "事件时间，Unix时间戳，即格林威治时间1970年01月01日00时00分00秒(北京时间1970年01月01日08时00分00秒)起至现在的总秒数"
  },
  {
    "参数名": "MsgType",
    "类型": "string",
    "说明": "消息类型，固定为 event"
  },
  {
    "参数名": "Event",
    "类型": "string",
    "说明": "事件类型，本接口固定为 commkf_send_msg_to_kf"
  },
  {
    "参数名": "msg_id",
    "类型": "string",
    "说明": "用户发送该条消息的所捆绑的单调自增msg_id"
  },
  {
    "参数名": "msg_type",
    "类型": "object",
    "说明": "消息类型, 参考发送消息中的消息类型"
  },
  {
    "参数名": "msg_event",
    "类型": "object",
    "说明": "事件类型"
  },
  {
    "参数名": "text",
    "类型": "object",
    "说明": "当msg_type为text时，则会返回text对应消息结构体"
  },
  {
    "参数名": "video",
    "类型": "object",
    "说明": "当msg_type为video时，则会返回video对应消息结构体"
  },
  {
    "参数名": "image",
    "类型": "object",
    "说明": "当msg_type为image时，则会返回image对应消息结构体"
  },
  {
    "参数名": "file",
    "类型": "object",
    "说明": "当msg_type为file时，则会返回file对应消息结构体"
  },
  {
    "参数名": "product_share",
    "类型": "object",
    "说明": "当msg_type为product_share时，则会返回product_share对应消息结构体"
  },
  {
    "参数名": "order_share",
    "类型": "object",
    "说明": "当msg_type为order_share时，则会返回order_share对应消息结构体"
  },
  {
    "参数名": "voice",
    "类型": "object",
    "说明": "当msg_type为voice时，则会返回voice对应消息结构体"
  },
  {
    "参数名": "union_id",
    "类型": "string",
    "说明": "用户的unionid"
  },
  {
    "参数名": "reference",
    "类型": "object",
    "说明": "当 msg_type 为 reference时，则会返回reference对应消息结构体"
  },
  {
    "参数名": "evaluate_result",
    "类型": "object",
    "说明": "当 msg_event 为 EVENT_TYPE_EVALUATE_RESULT时，则会返回evaluate_result对应消息结构体"
  }
]
```

### Body.msg_type `Object Payload`

消息类型, 参考发送消息中的消息类型

```json
[
  {
    "参数名": "text",
    "类型": "object",
    "说明": "msg_type为text"
  },
  {
    "参数名": "video",
    "类型": "object",
    "说明": "msg_type为video"
  },
  {
    "参数名": "image",
    "类型": "object",
    "说明": "msg_type为image"
  },
  {
    "参数名": "file",
    "类型": "object",
    "说明": "msg_type为file"
  },
  {
    "参数名": "product_share",
    "类型": "object",
    "说明": "msg_type为product_share"
  },
  {
    "参数名": "order_share",
    "类型": "object",
    "说明": "msg_type为order_share"
  },
  {
    "参数名": "voice",
    "类型": "object",
    "说明": "msg_type为voice"
  },
  {
    "参数名": "reference",
    "类型": "object",
    "说明": "msg_type为reference"
  }
]
```

### Body.msg_event `Object Payload`

事件类型

```json
[
  {
    "参数名": "EVENT_TYPE_SEND_MSG",
    "类型": "object",
    "说明": "用户发送消息时的回调行为"
  }
]
```

### Body.text `Object Payload`

当msg_type为text时，则会返回text对应消息结构体

```json
[
  {
    "参数名": "content",
    "类型": "string",
    "示例": "测试消息123",
    "说明": "msg_type为text时，必返回的回报消息"
  }
]
```

### Body.video `Object Payload`

当msg_type为video时，则会返回video对应消息结构体

```json
[
  {
    "参数名": "play_length",
    "类型": "uint32",
    "示例": "24",
    "说明": "msg_type为video时，表示返回视频秒数"
  },
  {
    "参数名": "cos_url",
    "类型": "string",
    "示例": "https://channels.weixin.qq.com/shop/commkf/downloadmedia?encrypted_param=xxxxx&timestamp=xxxxx&openid=xxxxxxxxx&msg_type=7",
    "说明": "msg_type为video时，表示返回视频的可下载cos_url"
  },
  {
    "参数名": "ld_img_url",
    "类型": "string",
    "示例": "https://channels.weixin.qq.com/shop/commkf/downloadmedia?encrypted_param=xxxxx&timestamp=xxxxx&openid=xxxxxxxxx&msg_type=2",
    "说明": "msg_type为video时，表示返回视频的封面图"
  }
]
```

### Body.image `Object Payload`

当msg_type为image时，则会返回image对应消息结构体

```json
[
  {
    "参数名": "cos_url",
    "类型": "string",
    "示例": "https://channels.weixin.qq.com/shop/commkf/downloadmedia?encrypted_param=xxxxx&timestamp=xxxxx&openid=xxxxxxxxx&msg_type=2",
    "说明": "msg_type为image时，表示返回图片的可下载cos_url"
  }
]
```

### Body.file `Object Payload`

当msg_type为file时，则会返回file对应消息结构体

```json
[
  {
    "参数名": "cos_url",
    "类型": "string",
    "示例": "https://channels.weixin.qq.com/shop/commkf/downloadmedia?encrypted_param=xxxxx&timestamp=xxxxx&openid=xxxxxxxxx&msg_type=8",
    "说明": "msg_type为file时，表示返回文件的可下载cos_url"
  }
]
```

### Body.product_share `Object Payload`

当msg_type为product_share时，则会返回product_share对应消息结构体

```json
[
  {
    "参数名": "product_id",
    "类型": "string",
    "示例": "1000018045xxxxx",
    "说明": "msg_type为product_share时，表示当前用户发送的卡片商品Id"
  }
]
```

### Body.order_share `Object Payload`

当msg_type为order_share时，则会返回order_share对应消息结构体

```json
[
  {
    "参数名": "order_id",
    "类型": "string",
    "示例": "37265222601xxxxxxxxx",
    "说明": "msg_type为order_share时，表示当前用户发送的卡片订单Id"
  }
]
```

### Body.voice `Object Payload`

当msg_type为voice时，则会返回voice对应消息结构体

```json
[
  {
    "参数名": "translated_msg",
    "类型": "string",
    "示例": "您好，问一下这个商品如何下单",
    "说明": "msg_type为voice时，表示当前用户发送语音翻译成功后的文本"
  },
  {
    "参数名": "play_length",
    "类型": "number",
    "示例": "2287",
    "说明": "msg_type为voice时，表示当前用户发送语音的语音长度，单位为毫秒(ms)"
  },
  {
    "参数名": "translation_succ",
    "类型": "bool",
    "示例": "true",
    "说明": "msg_type为voice时，表示当前用户发送语音文本是否翻译成功"
  }
]
```

### Body.reference `Object Payload`

当 msg_type 为 reference时，则会返回reference对应消息结构体

```json
[
  {
    "参数名": "content",
    "类型": "string",
    "说明": "本消息的文本内容"
  },
  {
    "参数名": "ref_msg",
    "类型": "object",
    "说明": "被引用消息摘要"
  }
]
```

### Body.evaluate_result `Object Payload`

当 msg_event 为 EVENT_TYPE_EVALUATE_RESULT时，则会返回evaluate_result对应消息结构体

```json
[
  {
    "参数名": "value",
    "类型": "number",
    "说明": "评价值：1=不够好，2=一般般，3=挺好的"
  },
  {
    "参数名": "reason_list",
    "类型": "array",
    "说明": "评价原因列表"
  },
  {
    "参数名": "room_id",
    "类型": "number",
    "说明": "会话 ID"
  },
  {
    "参数名": "msg_id",
    "类型": "number",
    "说明": "满意度消息 ID"
  },
  {
    "参数名": "evaluate_time",
    "类型": "timestamp",
    "说明": "评价时间戳"
  }
]
```

### Body.reference.ref_msg `Object Payload`

被引用消息摘要

```json
[
  {
    "参数名": "msg_id",
    "类型": "string",
    "说明": "被引用消息 ID"
  },
  {
    "参数名": "msg_type",
    "类型": "number",
    "说明": "被引用消息类型（enMsgType 数值）"
  },
  {
    "参数名": "content",
    "类型": "string",
    "说明": "被引用消息内容（文本摘要）"
  },
  {
    "参数名": "from_name",
    "类型": "string",
    "说明": "被引用消息发送者昵称"
  }
]
```

## 2. 消息返回

### 返回体 `Response Payload`

回复 `success` 或空字符串（无需加密）

## 3. 注意事项

- 回调url设置和消息推送规则需参考[消息推送文档](/doc/store/shop/dev_before/message_push) ，如果设置的回调url无法访问，商户将无法收微信小店发送的通知；
- 如果已切换API模式，但是没有设置指定URL，事件消息则会丢弃。设置指定URL后，需确保接收消息的服务器是可接收数据的。
- 如果服务器回包数据不符合预期，商家客服后台则会进行消息的重试推送，总重试约3.5小时，共会进行10次消息重试推送。

## 4. 代码示例

本事件无代码示例

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（3条）
2026 年 08 月 25 日`msg_type`  字段新增「reference」枚举值，新增  `reference` 、 `evaluate_result`  字段
2026 年 04 月 27 日新增了用户的unionid字段
2025 年 10 月 31 日优化格式