微信客服 API 配置

凭证与默认账号

企业 ID 与 Secret 须来自已在「微信客服 → 可调用接口的应用」中授权的自建应用。可只填本地保存项；亦可依赖同目录 .env 中的 WECOM_CORP_ID 与 WECOM_KF_SECRET（或 WECOM_APP_SECRET）。

Corp ID 客服应用 Secret（保存到本地 JSON，勿提交 Git）默认 open_kfid（可选）

本地文件路径： ·

客服账号管理

客户在微信里看到的客服昵称与头像由企微客服账号决定。添加须名称+头像；已有账号用下方 修改 account/update改名称/头像（至少改一项）。文档：添加、修改、链接

本地上传头像图 → media_id

选 PNG/JPG（建议方形），上传成功后会把 media_id 自动填入下面「添加」「修改」的头像框。

添加 account/add

客服名称 name

头像 media_id

删除 account/del

open_kfid

修改 account/update（改对外昵称/头像）

open_kfid

新名称 name（最多约 16 字，可选）

新头像 media_id（可选，可先上传图片）

名称与 media_id 至少填一项；仅改名称可不传头像。

获取客服链接 add_contact_way

open_kfid

scene（可选）

列表 account/list

offset

limit（1–100）

接待人员管理

userid_list：JSON 数组如 ["zhangsan"] 或英文逗号分隔。部门： department_id_list 如 [2,4] 或 2,4。与官方一致须至少填其一。文档

open_kfid

添加 servicer/add

userid_list department_id_list

删除 servicer/del

userid_list department_id_list

列表 servicer/list（GET）

分配客服会话

状态码参见官方说明（0 未处理 … 4 已结束）。转人工接待 service_state=3 时常需 servicer_userid。

open_kfid external_userid（客户）

获取会话状态 service_state/get

变更会话状态 service_state/trans

service_state（目标状态数字）

servicer_userid（可选）

同步消息 sync_msg

open_kfid

cursor（可选）

回调 token（可选，10 分钟内有效）

发送消息 send_msg（文本）

open_kfid touser（客户 external_userid） content

发送事件响应消息 send_msg_on_event

用于欢迎语 welcome_code、转接返回的 msg_code 等，效期很短。文档

code 文本 content（与下方 JSON 二选一） msgid（可选）

高级：完整请求 JSON（若填写则忽略上方 code/content）

「接收消息」请在企微填本服务地址：/kf/callback（默认），并配置环境变量 WECOM_KF_CALLBACK_TOKEN、WECOM_KF_CALLBACK_ENCODING_AES_KEY、 WECOM_KF_CALLBACK_RECEIVE_ID（可同 CorpID）。推送后本机用 token 调 sync_msg 再走大模型。