微信小店
取消
中文
中文
EN
取消
  • 微信小店

    • # 商家客服

    # 开发前准备

    重要：测试先行，避免咨询丢失
    务必先在测试店铺完成客服 API 对接及自研客服工具开发，确认无误后再对正式店铺进行模式切换。一旦切换到 API 模式，新增用户咨询均走 API 路径传递，若自研系统未完成开发，用户咨询可能丢失且不可恢复。

    # 客服模式说明

    微信小店提供两种互斥的客服模式，同一店铺同一时间只能选择其中一种来接待用户咨询。

    模式 说明
    微信小店客服工作台 平台内置的客服工具，开箱即用，内建欢迎语、离线语、自动回复、客服人员管理、数据面板等能力。操作指引见 微信小店客服——使用操作指引
    自研客服 API 商家通过客服 API 自建客服系统，消息通过回调接收、API 发送。本文档详细介绍此模式的接入方式

    两种模式的聊天记录不互通。工作台模式的聊天记录在客服工作台查询，API 模式的聊天记录由商家自行管理。

    # 接入流程

    接入自研客服 API 共分为三个阶段：消息推送配置、模式切换、消息收发对接。

    %%{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["[事件] 客服消息事件<br/>commkf_send_msg_to_kf"] C --> D["[API] 上传多媒体资源<br/>cosupload"] D --> E["[API] 发送消息<br/>sendmsg"] style A fill:#ffffff,stroke:#0ab8a6,color:#666666 style B fill:#ffffff,stroke:#0ab8a6,color:#666666

    # 阶段一：配置消息推送地址

    客服 API 共用微信小店的消息推送地址，配置方法详见 消息通知（回调）说明。

    注意：一个店铺只能配置一个消息推送地址。若该地址已有其他业务在使用，需在服务端通过 Event 字段区分不同事件，避免处理逻辑冲突。

    # 阶段二：切换到 API 模式

    切换不可逆风险提示：切换后新增用户咨询立即走 API 通道，请确保自研系统已通过测试店铺验证，再对正式店铺执行此操作。

    前往「微信小店后台 - 店铺管理 - 客服管理 - 客服设置」，点击「接入自研客服」，按提示阅读接入须知、确认消息推送配置，最后由店铺超级管理员扫码授权完成切换。

    切换后对原客服工作台的影响：

    功能 切换到 API 模式后的影响
    消息收发 新增咨询通过 API 通道收发，不再通过客服工作台
    进行中的会话 可在客服工作台继续完成，该轮会话结束后用户再次咨询走 API 通道
    历史聊天记录 工作台历史记录仍可查询，但两种模式记录不互通
    欢迎语 / 离线语 / 自动回复 不再生效，需在自研系统中自行实现
    客服人员管理 工作台的人员管理和会话查询对 API 模式会话无效，需自行管理
    数据面板 不统计 API 通道的咨询数据，原历史数据仍可查询

    # 阶段三：消息收发对接

    # 接收用户消息

    用户发起客服咨询后，系统将消息通过 [事件] 客服消息事件 / commkf_send_msg_to_kf 转发到已配置的消息推送地址。

    如果已切换 API 模式但未设置推送地址，事件消息将被丢弃。设置推送地址后，需确保接收消息的服务器可正常接收数据。

    消息重试机制：如果服务器回包不符合预期，系统会进行重试推送，总重试时长约 3.5 小时，总重试次数 10 次。

    # 发送多媒体素材

    发送图片、文件类型的消息前，需先通过 [API] 上传多媒体资源 / cosupload 上传文件获取 cos_url，再将 cos_url 填入发送消息接口的对应字段。

    文件大小限制均不超过 30MB，上传后有效期 14 天。

    # 回复用户消息

    通过 [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 接口

    中文名 / 英文名 请求方式 功能说明
    发送消息 / sendmsg POST /channels/ec/commkf/sendmsg 向指定用户发送客服消息
    上传多媒体资源 / cosupload POST /channels/ec/commkf/cosupload 上传图片、视频、文件至微信服务器

    # 事件通知

    中文名 / 英文名 事件标识 功能说明
    客服消息事件 / commkf_send_msg_to_kf Event: commkf_send_msg_to_kf 用户发消息或有行为动作时回调通知

    本模块仅支持自研商家调用，不支持第三方服务商（ISV）调用，无独立权限集 ID。

    # 常见问题 FAQ

    Q：切换到 API 模式后能否切回工作台模式？ A：可以切回。但需注意两种模式的聊天记录不互通，切换过程中正在进行的会话可在原模式继续完成。

    文档变更日志（1条）
    2026 年 05 月 07 日
    新增 商家客服 开发指南