企微集成面板

DRY_RUNwwdc467b59cb7eac44

这套系统真接上企业微信之后的形态。当前运行在 DRY_RUN 模式：不发任何网络请求，但每一次调用的接口、参数、前置条件与限制都如实记录在下方台账里。把 WECOM_DRY_RUN=0 加上两个 Secret 就是真实调用，代码不用改。

为什么先做这一页

企微的坑不在写代码，在后台开关和额度：客户联系不勾「可调用接口的应用」白名单，externalcontact/* 一律无权限；可信域名每月只能改 20 次，超限封 30 天。所以整套封装默认 DRY_RUN —— 本地联调一次都不碰真实额度，域名与开关一次性配死再切真。

1 · 连接状态

以下取自企业微信管理后台的实际配置

企业与应用

已认证 · 有效期至 2027-03-11

CorpIDwwdc467b59cb7eac44

自建应用阅读助手　AgentId 1000003

企业规模12 人 · 6 部门

企业域名huaige.cn　已登记

企业可信 IP已配 5 个

经营类目生活服务 · 摄影/扩印（客户联系无行业限制）

已开通的能力

通讯录同步已开启　接口同步 · 读取并编辑

客户联系已开通　API 接收消息已启用

智能机器人支持 MCP 插件　当前插件与工作流为空

微信开发者 ID未绑定

当前运行模式DRY_RUN

外部联系人额度68 / 2,000 位

后台「已服务 68 位」，其中 64 位已入网成为创作者，4 位加了好友未转化。2000 位免费额度，当前用量 3.4%。

2 · 渠道活码台账

8 个在用活码 · 累计加好友 68 位 · 转化创作者 64 位

▲

API 创建的活码在管理后台完全不展示。每企业 50 万个额度且与「加入群聊」活码共用同一个池，没有台账就是把额度扔进黑洞 —— 这个页面就是台账。state 采用可解析命名法，回调 add_external_contact 带回 State，即可自动归因并打渠道标签。

渠道	state（活码参数）	活码 config_id	扫码加好友	转化创作者	转化率	在网活跃	累计结算额
老创作者引荐 · #012	referral_012	cw_referral_012	12	11	92%	7	¥62,877
小红书招募帖 · 09/03	xhs_post_0903	cw_xhs_post_0903	11	10	91%	6	¥93,031
小红书招募帖 · 08/12	xhs_post_0812	cw_xhs_post_0812	11	10	91%	5	¥44,571
主理人微信 1v1 邀约	wechat_1v1	cw_wechat_1v1	10	9	90%	7	¥168,037
2025 BD 名单批量加	bd_list_2025	cw_bd_list_2025	7	7	100%	6	¥34,333
抖音主页简介挂链	douyin_bio	cw_douyin_bio	7	7	100%	7	¥40,904
成都线下活动 · 立牌	offline_chengdu	cw_offline_chengdu	6	6	100%	5	¥143,154
老创作者引荐 · #037	referral_037	cw_referral_037	4	4	100%	3	¥23,849
合计			68	64	94%	46	¥610,756

渠道活码额度（与「加入群聊」活码共用）8 / 500,000 个

临时会话模式每日最多加 10 万人；活码创建后 state 不可改，命名法必须一次定死。

引荐渠道为什么值钱

referral_012 一个人带来 11 位创作者、¥62,877 累计结算额。给每位站台创作者一个专属活码，带来多少人、这些人接了多少单全部自动归因，转介绍奖励可以按成交自动算 —— 这是把「熟人推荐」变成可结算资产的唯一办法。

3 · 企业客户标签体系

等级与来源在企微侧的落地形式。客户标签对客户端完全不可见，这是隔离的基础

等级组

晋升 = 换标签，权限自动跟着走

已创建

L1 · 观察30 位

L2 · 认证20 位

L3 · 金牌10 位

L4 · 签约4 位

平台组

群发按平台定向的筛选维度

已创建

红小红书32 位

B哔哩哔哩24 位

抖抖音22 位

视视频号14 位

博微博11 位

垂类组

本次 add_corp_tag 新建

待创建

宠物11旅拍10婚礼10街拍9纪实9建筑9风光8人像7星空7后期调色6器材测评4美食2

标签额度与限制

企业客户标签总量9 / 10,000 个

已创建 9 个（等级 4 + 平台 5），本次计划新增 20 个（垂类 12 + 渠道 8）。

·每企业最多 1 万个客户标签；标签名与组名 ≤30 字符。
·每个成员对同一位客户最多 3000 个标签。
▲应用只能增删改查自己创建的标签 —— 后台手工建的标签本应用改不了，所以标签体系必须全部由程序建立。
▲客户标签对客户端完全不可见。博主不知道自己被打了什么标签，也看不到别人 —— 这正是辐条型网络在企微侧成立的前提。

4 · 群发配额看板

这些不是待优化的性能问题，是企微的产品约束，派单流程必须绕开它们设计

本月已确认发出

3 条任务

触达 34 人次

待运营手机确认

3 条任务

将触达 42 人次

单客户本月已收

1 / 4 条

全部确认后升至 2 / 4

单次群发覆盖

20 / 200 位

按标签筛选收件人

硬约束逐条

add_msg_template · 创建企业群发

▲接口只创建任务。消息进入成员手机端「客户群发」待办，必须人在手机上逐条点确认才真正发出。「一句话给 200 个博主派单」在企微里做不到。
·每位客户每天最多接收 1 条群发（成员创建与企业创建合并计算）。
·企业统一创建的群发，每位客户每自然月最多 4 条。
·每次群发成员可选择 200 位客户，支持按标签筛选。
·创建频率 10 次/分钟；朋友圈是另一套独立额度（每企业每月 10 万条，jobid 24 小时过期）。

本月各等级触达

按等级分层发不同文案，避免撞配额

等级	任务	收件人	状态
L2 · 认证创作者	bc_bf_001_L2	20	已发出
L3 · 金牌创作者	bc_bf_001_L3	10	已发出
L4 · 签约创作者	bc_bf_001_L4	4	已发出
L1 · 观察创作者	bc_bf_002_L1	12	待手机确认
L2 · 认证创作者	bc_bf_002_L2	20	待手机确认
L3 · 金牌创作者	bc_bf_002_L3	10	待手机确认

配额稀缺反而是好事

既然触达要人工确认、每月每人只有 4 条，派单就必须两段式：群发只发不含任何价格的通用邀约（「有一批秋季旅拍需求，感兴趣点这里」），真实报价走一对一的电子条款单。这既绕开了人力瓶颈，又让差价天然不会出现在任何一条群发里 —— 约束和红线正好指向同一个设计。配套做「催确认」：任务创建后用应用消息推一条待办提醒，2 小时未确认再催一次。

5 · 智能机器人 + MCP 插件

后台实测到的配置形态，以及它对权限设计意味着什么

插件配置形态

智能机器人 → 工具 → 插件

传输协议Streamable HTTP / SSE　（无 stdio）

鉴权方式Header / Query + 静态 token　（不支持 OAuth 2.1）

插件 URLhttps://mcp.huaige.cn/sse

长连接同一机器人同时只允许 1 条活跃连接，新连接踢掉旧的；心跳 30s

response_url有效期 1 小时，且只能调用一次

markdown 上限20480 字节（中文约 6800 字）

▸

后台原文：「仅配置企业域名 URL 时，请求头中将返回提问者 userid」。这一句是整套按人鉴权的地基 —— 用临时域名（trycloudflare / vercel 子域）拿不到 userid，机器人就只能对所有人返回同一份数据，「运营看得到差价、博主看不到」的隔离会直接失效。

创作者自助问答（设想）

同一个问题，不同的人拿到不同的答案

我这单什么时候结款？

外部创作者 · #037

→ MCP get_my_settlement

　 header: x-wecom-userid = （企微注入，不可由调用方指定）

　 header: authorization = Bearer ****

　 scope: creator_self · 字段白名单不含 brandPricePerVideo

你的条款单 ts_0142 已验收，稿酬 ¥1,350，预付 30% 已于 9 月 12 日打出。尾款按你的等级账期 T+7 结算，预计 9 月 26 日到账。
还需要我把完税凭证发你吗？

怀歌助手 · 流式回复

▲智能机器人的服务对象是企业内部成员，外部创作者用不了单聊机器人。对外的等价通道是微信客服（客户主动发消息后 48 小时内最多 5 条）+ H5 深链。
·必须同时校验静态 token 与 userid header（header 可伪造），并限制企微出口 IP。
·异常分支要在 finally 里补发 finish=true，否则消息永远转圈。

为什么非要做机器人

主理人现在的时间全花在一对一回复「什么时候结款」「这条能不能改」上。 12 个人要管 64 位创作者、100–200 条视频，1v1 人力是最先崩的地方。 MCP 按 userid 鉴权意味着同一个机器人，运营问能看到差价与预算，创作者问只能拿到自己那一份 —— 自助问答不是锦上添花，它是让这张网络能扩到 500 人的前提。

本页触发的接口调用 · 8 次

DRY_RUN 模式下没有发出任何网络请求。以下是切到真实模式后会原样发出的请求

调用台账

把 WECOM_DRY_RUN=0 写进 .env.local 并配好两个 Secret，这些请求就会真的发出去

DRY_RUN

01GET/cgi-bin/gettoken取客户联系的 access_token

{
  "corpid": "wwdc467b59cb7eac44",
  "corpsecret": "CVu_········0Y"
}

文档　服务端API · 开发指南 · 获取access_token

前置　「客户联系」已开通，且本应用在「可调用接口的应用」白名单内

限制　2000 次/分/应用；token 有效期 7200s，必须缓存

02GET/cgi-bin/externalcontact/list拉取成员 HuaigeOps 名下的外部联系人 ID

{
  "userid": "HuaigeOps"
}

文档　客户联系 · 客户管理 · 获取客户列表

前置　客户联系已开通；本应用在「可调用接口的应用」白名单内；该成员在应用可见范围内

限制　30 万次/日/企业

03GET/cgi-bin/externalcontact/get取外部联系人 wmDemo0001AAA 的详情（state / 标签 / 添加时间）

{
  "external_userid": "wmDemo0001AAA",
  "cursor": ""
}

文档　客户联系 · 客户管理 · 获取客户详情

前置　客户联系白名单；unionid 需先绑定「微信开发者 ID」

限制　30 万次/日/企业

04POST/cgi-bin/externalcontact/add_contact_way创建渠道活码「老创作者引荐 · #037（2026Q3）」，state=referral_037

{
  "type": 2,
  "scene": 2,
  "remark": "老创作者引荐 · #037（2026Q3）",
  "skip_verify": true,
  "state": "referral_037",
  "user": [
    "HuaigeOps"
  ]
}

文档　客户联系 · 「联系我」与客户入群 · 配置客户联系「联系我」方式

前置　客户联系白名单；user 中的成员必须在应用可见范围内

限制　每企业 50 万个（与「加入群聊」活码共用）；API 创建的活码后台不可见，必须自建台账

05POST/cgi-bin/externalcontact/mark_tag给客户 wmDemo0001AAA 打标签 et_渠道组_1 / et_平台组_2

{
  "userid": "HuaigeOps",
  "external_userid": "wmDemo0001AAA",
  "add_tag": [
    "et_渠道组_1",
    "et_平台组_2"
  ],
  "remove_tag": []
}

文档　客户联系 · 客户标签管理 · 编辑客户企业标签

前置　客户联系白名单；userid 须为实际添加该客户的成员

限制　每成员对同一客户最多 3000 个标签

06POST/cgi-bin/externalcontact/add_corp_tag建立客户标签组「垂类组」，含 12 个标签

{
  "group_name": "垂类组",
  "order": 1,
  "tag": [
    {
      "name": "人像",
      "order": 1
    },
    {
      "name": "风光",
      "order": 2
    },
    {
      "name": "街拍",
      "order": 3
    },
    {
      "name": "纪实",
      "order": 4
    },
    {
      "name": "建筑",
      "order": 5
    },
    {
      "name": "旅拍",
      "order": 6
    },
    {
      "name": "星空",
      "order": 7
    },
    {
      "name": "婚礼",
      "order": 8
    },
    {
      "name": "宠物",
      "order": 9
    },
    {
      "name": "美食",
      "order": 10
    },
    {
      "name": "器材测评",
      "order": 11
    },
    {
      "name": "后期调色",
      "order": 12
    }
  ]
}

文档　客户联系 · 客户标签管理 · 添加企业客户标签

前置　客户联系白名单；应用只能操作自己创建的标签

限制　每企业 1 万个标签；名称 ≤30 字符

07POST/cgi-bin/externalcontact/add_msg_template创建群发任务，覆盖 20 位客户 —— 创建后仍需运营在手机上确认

{
  "chat_type": "single",
  "external_userid": [
    "wmDemo0015AAA",
    "wmDemo0016AAA",
    "wmDemo0017AAA",
    "wmDemo0018AAA",
    "wmDemo0019AAA",
    "wmDemo0020AAA",
    "wmDemo0021AAA",
    "wmDemo0022AAA",
    "wmDemo0023AAA",
    "wmDemo0024AAA",
    "wmDemo0025AAA",
    "wmDemo0026AAA",
    "wmDemo0027AAA",
    "wmDemo0028AAA",
    "wmDemo0029AAA",
    "wmDemo0030AAA",
    "wmDemo0031AAA",
    "wmDemo0032AAA",
    "wmDemo0033AAA",
    "wmDemo0034AAA"
  ],
  "sender": "HuaigeOps",
  "text": {
    "content": "认证创作者你好，有一批秋季旅拍主题的内容需求，档期在 10-15 前。感兴趣点这里查看详情 →"
  },
  "attachments": [
    {
      "msgtype": "link",
      "link": {
        "title": "怀歌创作者计划 · 新需求",
        "url": "https://app.huaige.cn/m/c_015"
      }
    }
  ]
}

文档　客户联系 · 消息推送 · 创建企业群发

前置　客户联系白名单；发送成员需在应用可见范围内

限制　只创建任务，必须成员手机端确认；每客户每天 1 条、企业统一群发每客户每自然月 4 条；每次 200 位客户；10 次/分钟

08POST/cgi-bin/externalcontact/get_user_behavior_data拉取 HuaigeOps 近期的加人 / 会话 / 回复率统计

{
  "userid": [
    "HuaigeOps"
  ],
  "start_time": 1789689600,
  "end_time": 1789862400
}

文档　客户联系 · 统计管理 · 获取「联系客户统计」数据

前置　客户联系白名单；userid 与 partyid 不可同时为空

限制　各最多 100 个；单次跨度 ≤30 天；只保留最近 180 天；多 userid 返回汇总而非按人拆分

真实接入还差什么

按依赖顺序排列。任何一项没做，对应接口一律返回无权限，而不是提示你少了什么

后台前置项 checklist

3 项待办 · 2 项待确认

●

接口同步已开启，权限「读取并编辑」已配置

管理工具 · 通讯录同步·不开则读不到成员 userid

●

已配置 5 个服务器出口 IP已配置

应用管理 · 阅读助手 · 企业可信 IP·不配则报 60020 not allow to access from your ip

●

客户联系已开通，外部联系人额度 2000 位已配置

客户联系·经营类目为摄影/扩印，无行业限制

◐

把「阅读助手」加入白名单（需进后台核对是否已勾选）待确认

客户联系 · 客户 · API · 可调用接口的应用·不勾则 externalcontact/* 全族接口一律无权限 —— 最常见的踩坑点

◐

审批 / 汇报 / 打卡等，用到哪个勾哪个待确认

各 OA 模块 · 可调用应用白名单·结算走审批流时必须先勾，否则审批接口无权限

○

绑定微信开放平台账号未配置

客户联系 · 微信开发者 ID 绑定·不绑则 externalcontact/get 不返回 unionid，将来打通微信生态断路，现在就该绑

○

一次性配 app.huaige.cn（门户）+ mcp.huaige.cn（MCP 插件）并通过归属校验未配置

应用管理 · 网页授权及 JS-SDK · 可信域名·每企业每月最多设置 20 次，超限月级封禁 30 天，且不支持通配符 —— 域名规划必须一次定死

○

打开开关，才能推千人千面的工作台挂件未配置

应用管理 · 阅读助手 · 工作台自定义展示·不开则 set_workbench_template / set_workbench_data 调用无效；keydata 最多 4 项，频控 10 次/分/用户

▲

可信域名是整个项目唯一能被卡死 30 天的地方。本地联调全程用 DRY_RUN，域名与开关一次性配完，正式域名上只做一次联调 —— 这条纪律比任何代码都重要。完整说明见 lib/wecom/README.md。