# 商家客服
## 开发前准备
- **功能了解**：开发前建议先阅读以下运营文档了解完整业务流程
- [微信小店客服——使用操作指引](https://docs.qq.com/doc/DWmJXVURKTlhrY1N2)：平台内置客服工作台的功能介绍与操作说明，了解客服模式、聊天记录、自动回复等完整业务流程
- [微信小店商家客服服务管理规则](https://store.weixin.qq.com/chengzhang/webdoc/wiki/1867/33b2557de242beba/growth_center_rule_for_store/8?bpath=%2Frule%2Fshop)：客服服务规范与违规处理规则
- **权限与凭证**：商家自研可直接调用，使用小店 access_token。本模块不支持第三方服务商调用
- **消息推送配置**：需提前配置消息推送回调 URL，详见 [消息通知（回调）说明](/doc/store/shop/dev_before/message_push)
**重要：测试先行，避免咨询丢失**
务必先在测试店铺完成客服 API 对接及自研客服工具开发，确认无误后再对正式店铺进行模式切换。**一旦切换到 API 模式，新增用户咨询均走 API 路径传递，若自研系统未完成开发，用户咨询可能丢失且不可恢复。**
## 客服模式说明
微信小店提供两种互斥的客服模式，同一店铺同一时间只能选择其中一种来接待用户咨询。
| 模式 | 说明 |
|------|------|
| 微信小店客服工作台 | 平台内置的客服工具，开箱即用，内建欢迎语、离线语、自动回复、客服人员管理、数据面板等能力。操作指引见 [微信小店客服——使用操作指引](https://docs.qq.com/doc/DWmJXVURKTlhrY1N2) |
| 自研客服 API | 商家通过客服 API 自建客服系统，消息通过回调接收、API 发送。本文档详细介绍此模式的接入方式 |
> 两种模式的聊天记录不互通。工作台模式的聊天记录在客服工作台查询，API 模式的聊天记录由商家自行管理。
## 接入流程
接入自研客服 API 共分为三个阶段：消息推送配置、模式切换、消息收发对接。
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%%
flowchart LR
A[配置消息推送地址] --> B[超管授权切换API模式]
B --> C["[事件] 客服消息事件
commkf_send_msg_to_kf"]
C --> D["[API] 上传多媒体资源
cosupload"]
D --> E["[API] 发送消息
sendmsg"]
style A fill:#ffffff,stroke:#0ab8a6,color:#666666
style B fill:#ffffff,stroke:#0ab8a6,color:#666666
```
### 阶段一：配置消息推送地址
客服 API 共用微信小店的消息推送地址，配置方法详见 [消息通知（回调）说明](/doc/store/shop/dev_before/message_push)。
> 注意：一个店铺只能配置一个消息推送地址。若该地址已有其他业务在使用，需在服务端通过 `Event` 字段区分不同事件，避免处理逻辑冲突。
### 阶段二：切换到 API 模式
**切换不可逆风险提示**：切换后新增用户咨询立即走 API 通道，请确保自研系统已通过测试店铺验证，再对正式店铺执行此操作。
前往「[微信小店后台](https://store.weixin.qq.com/shop/customerservice/home) - 店铺管理 - 客服管理 - 客服设置」，点击「接入自研客服」，按提示阅读接入须知、确认消息推送配置，最后由店铺超级管理员扫码授权完成切换。
切换后对原客服工作台的影响：
| 功能 | 切换到 API 模式后的影响 |
|------|----------------------|
| 消息收发 | 新增咨询通过 API 通道收发，不再通过客服工作台 |
| 进行中的会话 | 可在客服工作台继续完成，该轮会话结束后用户再次咨询走 API 通道 |
| 历史聊天记录 | 工作台历史记录仍可查询，但两种模式记录不互通 |
| 欢迎语 / 离线语 / 自动回复 | 不再生效，需在自研系统中自行实现 |
| 客服人员管理 | 工作台的人员管理和会话查询对 API 模式会话无效，需自行管理 |
| 数据面板 | 不统计 API 通道的咨询数据，原历史数据仍可查询 |
### 阶段三：消息收发对接
#### 接收用户消息
用户发起客服咨询后，系统将消息通过 [事件] [客服消息事件 / commkf_send_msg_to_kf](/doc/store/shop/notify/kf_callback/kf_msg_event) 转发到已配置的消息推送地址。
如果已切换 API 模式但未设置推送地址，事件消息将被丢弃。设置推送地址后，需确保接收消息的服务器可正常接收数据。
消息重试机制：如果服务器回包不符合预期，系统会进行重试推送，总重试时长约 3.5 小时，总重试次数 10 次。
#### 发送多媒体素材
发送图片、文件类型的消息前，需先通过 [API] [上传多媒体资源 / cosupload](/doc/store/shop/API/kf/api_cosupload) 上传文件获取 `cos_url`，再将 `cos_url` 填入发送消息接口的对应字段。
文件大小限制均不超过 30MB，上传后有效期 14 天。
#### 回复用户消息
通过 [API] [发送消息 / sendmsg](/doc/store/shop/API/kf/api_sendmsg) 向用户发送客服消息。
> 回复限制：用户发消息后，且在用户下一次发送消息之前，客服只可在 48 小时内回复，且最多回复 5 条消息。
## 消息类型支持
| 消息类型 | 说明 | 接收（回调） | 发送（API） |
|---------|------|:----------:|:----------:|
| text | 文本消息 | ✅ | ✅ |
| image | 图片消息 | ✅ | ✅ |
| video | 视频消息 | ✅ | ❌ 暂不支持 |
| file | 文件消息 | ✅ | ✅ |
| product_share | 商品卡片 | ✅ | ✅ |
| order_share | 订单卡片 | ✅ | ✅ |
| voice | 语音消息 | ✅ | ❌ 暂不支持 |
- 接收语音消息时，回调中包含语音转文字结果（`voice.translated_msg`）和语音时长（`voice.play_length`，单位毫秒）
- 接收视频消息时，回调中包含视频下载地址（`video.cos_url`）、封面图地址（`video.ld_img_url`）和视频秒数（`video.play_length`）；视频消息暂不支持通过 API 发送
- 以下消息类型暂不支持接收和发送：聊天记录、代发起售后等结构化消息卡片、视频号动态、视频号直播、视频号名片等
## 接口全览
### API 接口
| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [发送消息](/doc/store/shop/API/kf/api_sendmsg) / sendmsg | `POST /channels/ec/commkf/sendmsg` | 向指定用户发送客服消息 |
| [上传多媒体资源](/doc/store/shop/API/kf/api_cosupload) / cosupload | `POST /channels/ec/commkf/cosupload` | 上传图片、视频、文件至微信服务器 |
### 事件通知
| 中文名 / 英文名 | 事件标识 | 功能说明 |
|----------------|---------|---------|
| [客服消息事件](/doc/store/shop/notify/kf_callback/kf_msg_event) / commkf_send_msg_to_kf | `Event: commkf_send_msg_to_kf` | 用户发消息或有行为动作时回调通知 |
> 本模块仅支持自研商家调用，不支持第三方服务商（ISV）调用，无独立权限集 ID。
## 常见问题 FAQ
**Q：切换到 API 模式后能否切回工作台模式？**
A：可以切回。但需注意两种模式的聊天记录不互通，切换过程中正在进行的会话可在原模式继续完成。
文档变更日志（1条）
2026 年 05 月 07 日新增 商家客服 开发指南