wecom-customer-service

name	wecom-customer-service
description	当用户提到'微信客服'、'客服消息'、'客户咨询'、'智能客服'、'客服接待'、'转人工'、'客服账号'，或需要通过企业微信管理微信客服会话时使用此技能。管理微信客服账号、收发客服消息、分配会话、处理客户咨询。
version	0.1.0
metadata	{"openclaw":{"emoji":"💬","requires":{"env":["WECOM_CORP_ID","WECOM_CORP_SECRET"],"bins":["curl","jq"]},"primaryEnv":"WECOM_CORP_ID"}}

企业微信客服操作技能

通过企业微信微信客服 API，实现 AI 接管客服会话——接收客户消息、自动回复、智能分配人工客服。

前置条件

1. 企业微信管理后台 → 应用管理 → 微信客服 → 开启"通过 API 管理微信客服"
2. 自建应用需配置客服账号到"通过 API 管理微信客服账号 - 企业内部开发"
3. 接待人员需在应用可见范围内（否则返回错误码 60030）

获取 Access Token

ACCESS_TOKEN=$(curl -s "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${WECOM_CORP_ID}&corpsecret=${WECOM_CORP_SECRET}" | jq -r '.access_token')

核心操作

1. 获取客服账号列表

curl -s -X GET "https://qyapi.weixin.qq.com/cgi-bin/kf/account/list?access_token=${ACCESS_TOKEN}" | jq '.account_list'

返回：open_kfid（客服账号 ID）、name、avatar

2. 获取客服消息（拉取客户发来的消息）

curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/kf/sync_msg?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "cursor": "",
    "token": "<从回调中获取的token>",
    "limit": 100,
    "voice_format": 0
  }' | jq '.msg_list'

消息类型包括：text、image、voice、video、file、location、event（进入/退出会话事件）。

3. 发送客服消息（回复客户）

发送文本消息：

curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/kf/send_msg?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "touser": "<external_userid>",
    "open_kfid": "<客服账号open_kfid>",
    "msgtype": "text",
    "text": {
      "content": "您好，您咨询的商品目前有货，预计3天内发出。还有其他问题吗？"
    }
  }'

发送图文链接：

curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/kf/send_msg?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "touser": "<external_userid>",
    "open_kfid": "<客服账号open_kfid>",
    "msgtype": "link",
    "link": {
      "title": "退换货政策",
      "desc": "7天无理由退换，点击查看详情",
      "url": "https://example.com/return-policy",
      "thumb_media_id": ""
    }
  }'

4. 转人工客服（会话分配）

将当前 AI 接待的会话转给人工接待人员：

curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/kf/service_state/trans?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "open_kfid": "<客服账号open_kfid>",
    "external_userid": "<客户external_userid>",
    "service_state": 3,
    "servicer_userid": "<接待人员userid>"
  }'

service_state 值：

• 0: 未处理
• 1: 由智能助手接待
• 2: 待接入池等待（排队中）
• 3: 由人工接待
• 4: 已结束

5. 获取客户基础信息

curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/kf/customer/batchget?access_token=${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "external_userid_list": ["<external_userid1>", "<external_userid2>"]
  }' | jq '.customer_list'

返回：nickname、avatar、unionid（如已绑定微信开放平台）。

6. 获取接待人员列表

curl -s -X GET "https://qyapi.weixin.qq.com/cgi-bin/kf/servicer/list?access_token=${ACCESS_TOKEN}&open_kfid=<客服账号open_kfid>" | jq '.servicer_list'

AI 客服接待工作流

1. 配置回调 URL，接收 kf_msg_or_event 事件
2. 收到事件后调用 sync_msg 拉取新消息
3. 对文本消息：送入 RAG 知识库检索 → LLM 生成回复 → send_msg 回复客户
4. 对图片/语音：先识别内容（OCR / ASR），再走知识库流程
5. 判断置信度：低置信度 → 生成客户摘要 → service_state/trans 转人工
6. 对 event 类型（客户进入/退出）做会话生命周期管理

注意事项

• external_userid 是客户在该企业内的唯一标识，不同企业/第三方获取到的不同
• 消息拉取有延迟（实测 3-8 秒），关键路径应优化
• 单条消息内容最大 2048 字节
• 客服账号需先在管理后台创建，API 仅用于消息收发和会话管理
• 同一客户同一时间只能被一个接待人员服务