一、开发概述本文基于https://wechatapi.apifox.cn/企微 iPad 协议接口文档聚焦账号登录流程、联系人查询、全类型消息发送三大核心链路提供完整调用步骤、请求示例、参数说明、开发注意事项适用于机器人、SCRM 系统企微消息自动化开发。通用接口规范API官网https://www.jikehudong.com/请求地址基础域名http://172.0.0.1:8083请求方式POST请求头Content-Type: application/json文件上传除外统一返回体格式{ data: {}, errcode: 0, // 0成功非0为错误码 errmsg: ok }核心标识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 }关键缓存返回uuid后续所有接口依赖该值。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 辅助登录接口二次验证二维码风控拦截时使用/wxwork/SecondaryValidation查询账号登录状态/wxwork/GetRunClientByUuid传入 uuid 返回loginType2 已登录退出登录/wxwork/LoginOut三、联系人查询获取接收人 userid发送消息前必须获取目标联系人send_userid区分内部企业联系人、外部客户两套接口。3.1获取外部客户微信好友列表接口地址POST /wxwork/GetExternalContacts请求示例{ uuid: 427d7ee5-3a1c-4183-a83b-532ba1e7a1e, limit: 100, seq: 0 }状态说明 status 字段正常好友非 0/2049/82049对方删除我方8我方拉黑对方0双向删除3.2根据 userid 批量查询联系人详情接口地址POST /wxwork/GetUserInfoByVids请求示例{ uuid: 427d7ee5-3a1c-4183-a83b-532ba1e7a1e, vids: [7881302555913738, 1688853790599424] }使用场景已有 userid需要昵称、头像等展示信息时调用。四、消息发送全流程前置说明单聊isRoomfalse群聊isRoomtruesend_userid传群 roomid媒体消息图片 / 文件 / 视频需要先调用 CDN / 大文件上传接口拿到cdnkey、aeskey、md5再发送所有消息发送接口必填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:今天开工啦} ] }msgtype0 文字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 }格式化 支持 所有人接口SendTextAtMsgTwovid0代表 全体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 }撤回消息/wxwork/RevokeMsg传入 msgid、roomid单聊填 0语音转文字/wxwork/SpeechToText传入语音消息 msgid标记消息已读/wxwork/MarkAsRead消除小红点批量群发单人每日 1 次限制SendGroupsMsg五、完整业务执行流程端到端链路初始化实例调用/wxwork/init获取全局唯一 uuid登录账号新账号获取二维码 → 扫码 → 提交验证码完成登录老账号init 携带 vid调用automaticLogin自动登录获取联系人调用GetInnerContacts/GetExternalContacts拿到目标用户send_userid资源预处理媒体消息图片 / 文件 / 视频调用 CDN / 大文件上传接口获取 cdnkey 等参数发送消息根据消息类型调用对应 Send 接口传入 uuid、接收人 id、内容后续操作撤回 / 标记已读 / 语音转文字等辅助接口。六、开发注意事项1. 登录风控二维码短时效获取后立即渲染频繁切换设备、共用代理 IP 会触发二次验证登录后建议配置消息回调接口实时接收回复消息。2. 联系人使用内外联系人接口不可混用status 字段校验过滤已拉黑 / 删除客户避免消息发送失败。3. 消息发送风控限制单账号每秒发送不超过 2 条群发接口每人每日仅可推送 1 次不可高频调用媒体消息必须完成上传再发送缺少 cdnkey/aeskey 直接报错。4. 缓存建议Redis 缓存映射关系账号vid - uuid、uuid - 登录状态、用户昵称-userid减少重复查询接口调用。
一、开发概述本文基于https://wechatapi.apifox.cn/企微 iPad 协议接口文档聚焦账号登录流程、联系人查询、全类型消息发送三大核心链路提供完整调用步骤、请求示例、参数说明、开发注意事项适用于机器人、SCRM 系统企微消息自动化开发。通用接口规范API官网https://www.jikehudong.com/请求地址基础域名http://172.0.0.1:8083请求方式POST请求头Content-Type: application/json文件上传除外统一返回体格式{ data: {}, errcode: 0, // 0成功非0为错误码 errmsg: ok }核心标识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 }关键缓存返回uuid后续所有接口依赖该值。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 辅助登录接口二次验证二维码风控拦截时使用/wxwork/SecondaryValidation查询账号登录状态/wxwork/GetRunClientByUuid传入 uuid 返回loginType2 已登录退出登录/wxwork/LoginOut三、联系人查询获取接收人 userid发送消息前必须获取目标联系人send_userid区分内部企业联系人、外部客户两套接口。3.1获取外部客户微信好友列表接口地址POST /wxwork/GetExternalContacts请求示例{ uuid: 427d7ee5-3a1c-4183-a83b-532ba1e7a1e, limit: 100, seq: 0 }状态说明 status 字段正常好友非 0/2049/82049对方删除我方8我方拉黑对方0双向删除3.2根据 userid 批量查询联系人详情接口地址POST /wxwork/GetUserInfoByVids请求示例{ uuid: 427d7ee5-3a1c-4183-a83b-532ba1e7a1e, vids: [7881302555913738, 1688853790599424] }使用场景已有 userid需要昵称、头像等展示信息时调用。四、消息发送全流程前置说明单聊isRoomfalse群聊isRoomtruesend_userid传群 roomid媒体消息图片 / 文件 / 视频需要先调用 CDN / 大文件上传接口拿到cdnkey、aeskey、md5再发送所有消息发送接口必填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:今天开工啦} ] }msgtype0 文字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 }格式化 支持 所有人接口SendTextAtMsgTwovid0代表 全体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 }撤回消息/wxwork/RevokeMsg传入 msgid、roomid单聊填 0语音转文字/wxwork/SpeechToText传入语音消息 msgid标记消息已读/wxwork/MarkAsRead消除小红点批量群发单人每日 1 次限制SendGroupsMsg五、完整业务执行流程端到端链路初始化实例调用/wxwork/init获取全局唯一 uuid登录账号新账号获取二维码 → 扫码 → 提交验证码完成登录老账号init 携带 vid调用automaticLogin自动登录获取联系人调用GetInnerContacts/GetExternalContacts拿到目标用户send_userid资源预处理媒体消息图片 / 文件 / 视频调用 CDN / 大文件上传接口获取 cdnkey 等参数发送消息根据消息类型调用对应 Send 接口传入 uuid、接收人 id、内容后续操作撤回 / 标记已读 / 语音转文字等辅助接口。六、开发注意事项1. 登录风控二维码短时效获取后立即渲染频繁切换设备、共用代理 IP 会触发二次验证登录后建议配置消息回调接口实时接收回复消息。2. 联系人使用内外联系人接口不可混用status 字段校验过滤已拉黑 / 删除客户避免消息发送失败。3. 消息发送风控限制单账号每秒发送不超过 2 条群发接口每人每日仅可推送 1 次不可高频调用媒体消息必须完成上传再发送缺少 cdnkey/aeskey 直接报错。4. 缓存建议Redis 缓存映射关系账号vid - uuid、uuid - 登录状态、用户昵称-userid减少重复查询接口调用。
