一、开发概述

本文基于https://wechatapi.apifox.cn/企微 iPad 协议接口文档，聚焦账号登录流程、联系人查询、全类型消息发送三大核心链路，提供完整调用步骤、请求示例、参数说明、开发注意事项，适用于机器人、SCRM 系统企微消息自动化开发。

通用接口规范

1. API官网：https://www.jikehudong.com/
2. 请求地址基础域名：http://172.0.0.1:8083
3. 请求方式：POST
4. 请求头：Content-Type: application/json（文件上传除外）
5. 统一返回体格式

{ "data": {}, "errcode": 0, // 0=成功，非0为错误码 "errmsg": "ok" }

1. 核心标识uuid：初始化接口生成，单账号唯一，所有登录、联系人、消息接口必传，生命周期全程复用。

二、账号完整登录流程

2.1 步骤总览

初始化实例 → 获取登录二维码 → 扫码 / 验证码登录 / 历史账号自动登录 → 登录状态校验

2.2 初始化企微实例（所有操作前置）

接口地址

POST /wxwork/init

参数说明

| 参数 | 类型 | 是否必传 | 说明 |
|------|------|--------|
| vid | string | 否 | 16888 开头账号 ID；首次登录传空，历史登录账号传 vid 实现免扫码 |
| ip/port/proxyType | string | 否 | http 代理配置，无代理留空 |
| userName/passward | string | 否 | 代理账号密码，无代理不传 |
| proxySituation | int | 否 | 0 = 临时代理（可取消）；1 = 全局长效代理 |
| deverType | string | 是 | 固定值ipad|

新账号首次登录请求示例（无代理）

{ "vid": "", "ip": "", "port": "", "proxyType": "", "userName": "", "passward": "", "proxySituation": 0, "deverType": "ipad" }

返回示例

{ "data": { "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "is_login": "false" }, "errcode": 0, "errmsg": "ok" }

2.3 获取登录二维码

接口地址

POST /wxwork/getQrCode

请求参数

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e" }

返回字段说明

• qrcode：二维码在线访问链接

• qrcode_data：二维码 base64 字符串，前端可直接渲染

• Key：验证码校验凭证

2.4 验证码提交（首次扫码需要）

扫码后手机弹出验证码弹窗时调用，未关闭验证码窗口前调用。

接口地址

POST /wxwork/CheckCode

请求示例

{ "uuid":"cbba2997c55b8d8b036816e03c19e5a0", "qrcodeKey":"096F100D9D140448DF2973876F2E1D9F", //qr_codekey "code":"406269"//验证码 }

异常说明

返回qrcode_not need verify代表提前关闭验证码弹窗，需重新获取二维码。

2.5 历史账号自动登录

初始化时传入登录过的vid，无需扫码一键登录。

接口地址

POST /wxwork/automaticLogin

请求体

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e" }

2.6 辅助登录接口

1. 二次验证二维码（风控拦截时使用）：/wxwork/SecondaryValidation

1. 查询账号登录状态：/wxwork/GetRunClientByUuid，传入 uuid 返回loginType，2 = 已登录

1. 退出登录：/wxwork/LoginOut

三、联系人查询（获取接收人 userid）

发送消息前必须获取目标联系人send_userid，区分内部企业联系人、外部客户两套接口。

3.1获取外部客户（微信好友）列表

接口地址

POST /wxwork/GetExternalContacts

请求示例

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "limit": 100, "seq": 0 }

状态说明 status 字段

• 正常好友：非 0/2049/8

• 2049：对方删除我方

• 8：我方拉黑对方

• 0：双向删除

3.2根据 userid 批量查询联系人详情

接口地址

POST /wxwork/GetUserInfoByVids

请求示例

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "vids": [7881302555913738, 1688853790599424] }

四、消息发送全流程

前置说明

1. 单聊isRoom=false，群聊isRoom=true，send_userid传群 roomid；

1. 媒体消息（图片 / 文件 / 视频）需要先调用 CDN / 大文件上传接口，拿到cdnkey、aeskey、md5再发送；

1. 所有消息发送接口必填：uuid、send_userid、isRoom。

4.1 ：发送纯文本消息

接口地址

POST /wxwork/SendTextMsg

请求示例（单聊）

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "kf_id": 0, "send_userid": 7881302555913738, "isRoom": false, "content": "你好，这是测试消息" }

返回核心

msg_id：消息唯一 ID，用于撤回、语音转文字。

4.2 文本 + 表情混合消息

接口地址

POST /wxwork/SendTextAndExpMsg

请求示例

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "send_userid": 7881302555913738, "isRoom": false, "content": [ {"msgtype":0,"msg":"早上好"}, {"msgtype":3,"msg":"[微笑]"}, {"msgtype":0,"msg":"今天开工啦"} ] }

msgtype：0 = 文字，3 = 表情

4.3 CDN 图片消息（25M 内）

前置：调用 CDN 上传接口拿到 cdnkey/aeskey/md5

发送接口

POST /wxwork/SendCDNImgMsg

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "send_userid": "7881302555913738", "kf_id": 0, "isRoom": false, "cdnkey": "xxx", "aeskey": "xxx", "md5": "xxx", "fileSize": 3243381, "width": 1279, "height": 1706, "thumb_image_height": 512, "thumb_image_width": 384, "thumb_file_size": 15195, "thumb_file_md5": "xxx", "is_hd": 1 }

4.4 群 @消息（群专属）

接口地址

POST /wxwork/SendTextAtMsg

请求示例（@指定成员）

{ "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e", "send_userid": 10696052955013024, "atids":[7881302555913738], "content":"通知全体成员开会", "isRoom":true }

格式化 @（支持 @所有人）接口：SendTextAtMsgTwo，vid=0代表 @全体

4.5 高级消息类型简表

| 消息类型 | 接口地址 | 前置依赖 |
|---------|---------|
| CDN 文件 | SendCDNFileMsg | CDN 上传文件接口 |
| CDN 语音 | SendCDNVoiceMsg | CDN 上传 silk 语音 |
| 短视频 (<25M) | SendCDNVideoMsg | CDN 上传视频 |
| 超大视频 / 文件 | SendCDNBigVideoMsg / SendCDNBigFileMsg | 大文件上传链路 |
| 链接卡片 | SendLinkMsg | 无需上传，直接传 url、标题、封面 |
| 小程序 | SendAppMsg | 小程序封面 CDN 资源 |
| GIF 表情 | SendEmotionMessage | 图片 url |
| 名片消息 | SendBusinessCardMsg | 目标用户 id |
| 位置消息 | SendLocationMsg | 经纬度、地址 |
| 视频号 / 直播 | SendVideoNumber / SendVideoNumberZhiBo | 视频号链接参数 |
| 引用回复 | sendQuoteMsg | 原消息完整元数据 |

4.6 消息辅助操作接口

{ "uuid": "xxx", "msgid":1063645, "roomid":0 }

1. 撤回消息：/wxwork/RevokeMsg，传入 msgid、roomid（单聊填 0）
2. 语音转文字：/wxwork/SpeechToText，传入语音消息 msgid
3. 标记消息已读：/wxwork/MarkAsRead，消除小红点

1. 批量群发（单人每日 1 次限制）：SendGroupsMsg

五、完整业务执行流程（端到端链路）

1. 初始化实例：调用/wxwork/init，获取全局唯一 uuid；

1. 登录账号

• 新账号：获取二维码 → 扫码 → 提交验证码完成登录；

• 老账号：init 携带 vid，调用automaticLogin自动登录；

1. 获取联系人：调用GetInnerContacts/GetExternalContacts拿到目标用户send_userid；

1. 资源预处理（媒体消息）：图片 / 文件 / 视频调用 CDN / 大文件上传接口，获取 cdnkey 等参数；

1. 发送消息：根据消息类型调用对应 Send 接口，传入 uuid、接收人 id、内容；

1. 后续操作：撤回 / 标记已读 / 语音转文字等辅助接口。

六、开发注意事项

1. 登录风控

• 二维码短时效，获取后立即渲染；

• 频繁切换设备、共用代理 IP 会触发二次验证；

• 登录后建议配置消息回调接口，实时接收回复消息。

2. 联系人使用

• 内外联系人接口不可混用；

• status 字段校验，过滤已拉黑 / 删除客户，避免消息发送失败。

3. 消息发送风控限制

• 单账号每秒发送不超过 2 条；

• 群发接口每人每日仅可推送 1 次，不可高频调用；

• 媒体消息必须完成上传再发送，缺少 cdnkey/aeskey 直接报错。

4. 缓存建议

Redis 缓存映射关系：账号vid -> uuid、uuid -> 登录状态、用户昵称-userid，减少重复查询接口调用。