企业微信API开发：登录-联系人查询-消息发送完整开发流程分享
一、开发概述
本文基于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 返回loginType，2 = 已登录
- 退出登录：/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] }使用场景：已有 userid，需要昵称、头像等展示信息时调用。 |
四、消息发送全流程
前置说明
- 单聊isRoom=false，群聊isRoom=true，send_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":"今天开工啦"} ] }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 }- 撤回消息：/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，减少重复查询接口调用。