比邻企微与个微后台接入教程

从账号上线，到程序收消息，再到 AI 有规则地回复。

这是账号开通教程的后半篇，可直接交给负责后台的 AI。无需截图。接口说明依据已有文档与微信桥协作核对材料整理；实际接入时，先在比邻后台的「接口文档／回调接口文档」核对当时的字段。本篇不代表已经替读者部署或完成真实收发。

给执行 AI：需要人配合时必须主动提醒

遇到手机操作、验证码、实名验证、管理员审核或系统权限确认，AI 必须主动告诉对应的人现在要做什么，不能默默等待，也不能跳过后宣称完成。 先完成自己能做的准备，再说明“谁、在哪个页面或设备、做哪一步、完成后如何告知”。一次只提出当前所需动作。

遇到的步骤	AI 必须怎样提醒	人完成后 AI 怎样核对
扫码与手机登录确认	展示当前有效二维码，明确用微信还是企业微信扫码；个微授权码与登录码分别提醒	检查后台下一步状态及账号在线结果，不能仅凭“扫了”认定成功
输入验证码	提醒本人查看手机提示，并在当前后台验证码框直接填写、提交；不要求把验证码发到聊天里	检查提交结果或登录状态；过期则说明需重新取得验证码
人脸／实名验证	仅在实际触发时提醒本人，指向本教程对应步骤并说明有效时间；姓名、身份证和人脸由本人操作	本人完成后核对登录结果；没有触发就继续，不要求额外验证
基础服务或账号权限待审核	提醒本人联系负责审核的管理员或客服，提供可复制的申请说明；AI 未获发送授权时不代发	回到后台刷新，确认审核通过或服务“使用中”；提交申请不等于开通
群保存到通讯录	先提醒本人在对应手机微信／企微中把目标群保存到通讯录，完成后告知	再同步待开通群并点“查询”，核对目标群与所属账号后开通；没出现就报告，不反复空刷
UIP 管理员确认或安全软件拦截	说明电脑上要确认的具体按钮；拦截按交接文档报告证据，等待本人授权具体处理	核对服务、日志及连接；窗口打开不等于安装成功
付费、测试消息与手机实收	在必要时请本人确认具体订单或目标；验收时说清谁向谁发哪一条新标记，以及请谁查看实收	分别记录操作结果与手机实收，不把接口受理当作送达

提醒示例：“现在需要你在手机企业微信中，把准备开通的目标群保存到群通讯录。完成后告诉我‘已保存’，我再同步待开通群并点击查询。”

等待期间写明当前停点。本人回复完成后，AI 应接着核对并继续原流程；不重新启动整套操作、不重复下单或提交申请。没有可用后台轮询能力时，明确请本人完成后回来告知，不承诺会自动发现。

1．你先准备，AI 再接手

AI 提醒点： AI 应逐项核对前置条件。缺扫码、验证码、审核或群通讯录保存时，主动给本人具体操作提示，等待并核对结果后接续，不仅列一张准备清单就停下。

账号已经扫码上线。个微、企微分别购买对应端口。
在「接口管理 → 我的应用」申请并开通的是 基础服务，需要审核时联系服务商客服。
需要接收消息的群先保存到手机通讯录，再到对应的待开通群列表同步，点击「查询」刷新，选择目标群开通。
群开通、接口订阅、回调接通是三件不同的事。 未开通群不能作为已具备采集能力的群，个微、企微都一样。
准备一个由自己控制的后台运行环境和可被平台访问的 HTTPS 回调地址。具体路径由项目决定。
准备一个愿意配合测试的联系人或测试群。

你负责扫码、必要的实名验证、付费及确认测试对象。AI 负责程序配置、解析、存储和诊断。应用密钥通过本机受限配置文件或系统密钥存储提供，不放进教程、聊天截图、Git 或同步目录。

2．先取得应用访问权限

应用 Key 对应接口参数 clientId，应用密钥对应 clientSecret。

POST https://gateway.bilinl.com/thirdparty/user/login/client
Content-Type: application/json

{"clientId":"<APPLICATION_KEY>","clientSecret":"<APPLICATION_SECRET>"}

成功后读取 data.value 作为 Token，data.expiredTime 为到期的绝对毫秒时间戳。后续请求带上：

Authorization: Bearer <TOKEN>
Content-Type: application/json

同一应用统一管理 Token。 不要每次请求都重新登录取 Token；新 Token 可能使旧 Token 失效。单进程可集中缓存，多进程必须协调读取和刷新。可以提前 60 秒判定临近过期。明确失效时处理缓存，让下一次新请求重新取 Token；不要因此自动重发上一条发送结果未知的消息。

接手旧项目时，可能看到 BAIYIN_CLIENT_ID 等历史兼容变量名，它们指向比邻配置，不是平台强制要求的变量名。无需为了教程改名而修改正在运行的配置。

3．把账号和收件对象认准

项目	个微	企微
发送时的账号类型	`wxType=1`	`wxType=2`
私聊回调类型	`5001`	`400005`
群聊回调类型	`5003`	`400006`
群回调中的平台群编号	`data.vcChatRoomSerialNo`	`group_serial_no`，按实际层级读取
私聊发送目标	平台好友编号 `freWxId`	平台联系人编号 `freWxId`

账号编号、联系人编号、群编号分别保存，并记录所属平台、账号和编号类型。昵称只用于展示，不能作为发送地址。不要把不同账号下同名联系人自动合并，也不要把群成员编号直接当好友编号。

个微好友查询有 POST /thirdparty/wxFre/selectWxFreList 等接口，但个微上的企微联系人可能不在普通好友查询结果中。查不到就保留为待核对，结合真实来信和平台确认寻找权威编号，不能猜编号试发。/thirdparty/group/getGroupListBySession 已有资料明确标为企微接口，不要套用于个微。

4．先接回调，保持只收不回

AI 先做好接收端，再到「我的应用」填写回调地址。接收端按下面顺序工作：

按当时官方契约检查请求来源与结构；签名方案如有，使用官方方案，不自造字段。
先可靠保存原始记录，再按平台约定返回确认响应。记录保存失败不能假报成功。
识别回调类型，提取账号、消息编号、发言人、群、方向与正文。
去重，过滤自身发送的回声和重复通知。
将业务消息放进后续处理队列；回调请求中不等待模型生成回复。

ACK 的具体响应格式和成功字段由当前回调类型文档确认，不能将某一种回调的成功码推广到全部事件。也不能假定失败后平台一定补投。

起步时明确设置「AI 不生成／发送关闭」。这些是我们程序的开关，不是比邻后台自带的统一参数。

个微与企微正文不同

个微常见字段：vcContent 为 Base64 正文，nMsgType 为消息类型；vcMsgId 与 vcMsgSerialNo 是不同字段，都保留。发件人与收件人常见为 vcFromWxUserSerialNo、vcToWxUserSerialNo。

企微常见字段：msg_id、msg_type、Base64 msg_content、sender_serial_no、receiver_serial_no，群消息另有 group_serial_no。

按实际回调层级解析，不把接收结构直接当发送请求。个微方向判断要结合账号、收发件人、nMsgNum、nPlatformMsgType；不能只看昵称。无法确定方向时记录原因，暂不触发回复。

5．只订阅这次需要的账号和群

个人号私聊订阅示例：

POST /thirdparty/partner/personal/on

{"itemIds":["<PERSONAL_ACCOUNT_SERIAL>"],"subTypes":["5001"]}

群订阅接口为 POST /thirdparty/partner/group/on。例如企微群：

{"itemIds":["<ENTERPRISE_GROUP_SERIAL>"],"subTypes":["400006"]}

个微群使用精确的个微群编号和 5003 类型；企微私聊订阅 400005，执行前在文档核实该账号类型的订阅入口与参数。

不要省略或传空 subTypes，已有文档显示这可能变成订阅全部类型。提交后用 /thirdparty/partner/findWxSubscription 按当前查询契约读回，核对账号、群和类型。账号订阅不等于群订阅。

6．用一条新消息确认收通

由另一个人向目标账号或群发送一条带唯一标记的新文字，例如「接入验证＋当天时间」。AI 检查：

回调确实到达，账号、发言人、群及消息方向正确。
原文解码正确，记录只新增一次，重复回调不产生第二次处理。
当前发送仍关闭，没有自动回复。

先完成一个通路，再按同样方法验证另一个。个微通过不代表企微通过，私聊通过也不代表群聊通过。

7．再接入可以更换的 AI

统一消息先交给程序识别：明确的账号绑定、项目标记、固定格式按规则处理；含义不明确的业务归属，才让模型在允许的选项中判断。不明确的保留待处理，不盲投到某个窗口。

模型连接与消息通路分开配置：连接地址、凭据引用、模型名称、负责角色。可以替换自己的 API；使用已有订阅连接时，必须有该环境实际支持的适配器，不能把订阅账号直接当通用 API 密钥。

先让模型只生成草稿。模型只能读取本次允许的资料，不持有比邻密钥，也不决定收件地址和发送权限。程序决定是否允许发送。连接失败单独记录为技术失败，不冒充「理解不明确」。

8．授权一条普通文字，再验发送

下面都是请求形状，尖括号是待替换占位符，不要原样执行。发送前由本人确认账号、对象及这条消息。

私聊

POST /thirdparty/personal/privateMessage

个微示例：

{
  "wxId":"<PERSONAL_ACCOUNT_SERIAL>",
  "wxType":1,
  "freWxId":"<FRIEND_SERIAL>",
  "data":[{"msgType":2001,"msgContent":"<NEW_TEXT>","msgNum":1}]
}

已验证的企微「我的客户」路径：

{
  "wxId":"<ENTERPRISE_ACCOUNT_SERIAL>",
  "wxType":2,
  "freWxId":"<CONTACT_SERIAL>",
  "privateMsgType":2,
  "merchatId":"<MERCHANT_ID>",
  "data":[{"msgType":2001,"msgContent":"<NEW_TEXT>","msgNum":1}]
}

群聊

POST /thirdparty/group/sendGroupMessage

{
  "wxId":"<ACCOUNT_SERIAL>",
  "wxType":1,
  "vcGroupId":"<GROUP_SERIAL>",
  "merchatId":"<MERCHANT_ID>",
  "data":[{"msgType":2001,"msgContent":"<NEW_TEXT>","msgNum":1,"atWxSerialNos":[]}]
}

企微群将 wxType 设为 2，并同时换成企微账号和群编号。发送中的字段确实拼作 merchatId，不要自行改成查询接口可能使用的 merchantId。发送正文示例为普通文字，不照搬回调 Base64 字段。

程序对同一账号的全部发送出口统一串行，并按平台要求设置间隔。不要因为同时有几个人来信，就并行调用同一账号发消息。

分别记录 HTTP 结果、外层 code、内层 data.resultCode。已有发送契约成功值为两层均 0，但这只说明平台受理。最后必须由手机端确认实际收到。超时、断连或结果不明先停下核对，不自动重发。

9．故障查哪里

现象	下一步
在线却没收到回调	查 HTTPS 地址、基础服务、精确账号订阅、群开通与群订阅
收到但程序没有处理	查类型、字段层级、解码、方向、去重和处理日志
个微查不到企微联系人	查平台是否支持该类联系人；用权威编号核对，不猜绑定
Token 频繁失效	查是否有多个程序分别取新 Token，统一管理缓存与刷新
接口受理但手机未收到	查内层返回、平台发送日志和手机回执，不重发未知结果
对别人说话机器人也插话	查回复对象、引用目标、@ 对象及允许回复规则，不只补人物档案
AI 不满意或漏答	保存相关消息、判断依据与结果，交负责人复核；不自动扩大资料范围
怀疑漏收	需要手机侧原消息或其他可靠对照，单靠接收端无法知道全部未到达消息

10．账号与平台快速切换

切换有两种：同一平台换账号，以及个微、企微互换。保持业务档案、知识库和回复规则，替换通路配置及外部编号映射。切换到其他服务商时，还需要对应服务商的适配器，不能只换域名。

下面是供 AI 实现时参考的配置形状，不是比邻官方接口，也不是现成可运行脚本：

{
  "profile": "personal_test",
  "provider": "bilin",
  "application_secret_ref": "<LOCAL_SECRET_REFERENCE>",
  "wxType": 1,
  "account_serial": "<ACCOUNT_SERIAL>",
  "contact_bindings": {},
  "group_bindings": {},
  "subscriptions": ["5001"],
  "outbound_enabled": false
}

为每个账号单独建立一份配置。contact_bindings 和 group_bindings 保存本系统业务对象与该账号平台编号的对应关系；只有经过确认的映射才能启用。新账号上的同名对象不能自动继承旧编号。

AI 应将切换做成以下可复用流程，具体命令名沿用读者项目已有工具：

预检：读出当前配置和目标配置，检查账号类型、应用凭据引用、已确认映射、订阅及目标在线状态，打印差异，不发消息。
暂停发送：暂停旧账号的新发送任务，等待已在途请求结束。未完成或结果未知的旧任务留在原账号，不搬到新账号重发。
切换配置：备份旧配置，经本人确认后启用目标配置。个微与企微互换时，同时切换回调解析适配和类型，不能只改 wxType。
处理应用凭据：同一应用换账号继续复用该应用的 Token 管理；换应用则使用独立凭据引用和缓存，不能拿旧应用 Token 调新应用。
核对订阅：读回目标账号、精确群及回调类型。只补本次明确需要的订阅，不清空其他业务已有订阅。
只收验收：发一条新标记消息，确认进入目标账号、目标对象和正确业务范围。旧账号迟到回调仍按原账号处理，不能当成新账号消息。
恢复发送：新消息验收通过后，按本人授权恢复目标账号发送门禁与串行规则；如需真实出站，再单独验证一条新文字。
异常回退：保持发送关闭，恢复旧配置；记录本次已变更的订阅及剩余问题。回退不补发历史任务，也不自动重复切换。

比邻提供账号、消息和订阅接口；配置快照、业务档案映射、切换预检及发送队列属于读者后台的实现。我们项目的微信桥、特定端口和跨语言锁只是已有实现方式，不是接入比邻必须安装的一套系统。

11．复制给 AI 的任务说明

请按《比邻企微与个微后台接入教程》接入我的账号。
先核对现有项目和当前官方接口文档，复用已有接收、Token 与发送模块。
请列出我需要提供的非敏感信息，并指导我把凭据写进本机受限配置。
第一阶段只接收并保存消息，不发消息、不自动回复。
按平台、账号和编号类型区分身份；不按昵称猜联系人或群。
只配置这次指定的账号和群，订阅类型不得省略或传空。
给出一条新消息的验收办法，让我确认真实收件结果。
收到后再接模型生成草稿；真实试发前让我确认目标和内容。
同账号发送统一串行；未知结果不重试，不补发历史消息。
请复用现有工具提供账号与平台切换流程：预检、暂停、切换、只收验收、授权恢复、异常回退。
最后交付配置说明、启动与停止方法、脱敏验收记录和剩余问题。
不要复制他人真实账号、机器码、密钥或项目专用端口。

基础文字通路完成后，再单独接图片、文件、语音和原生引用。这些能力各有接口与验收条件，不因普通文字已通就视为完成。

资料范围：依据本项目既有接口核对记录及微信桥协作提供的技术底稿整理，2026 年 9 月 9 日。最新契约以比邻登录后台「接口文档／回调接口文档」为准。本教程未包含任何真实凭据或账号编号。