企业微信 API 开发：登录、联系人查询与消息发送完整流程

基于企微 iPad 协议，完整讲解账号初始化、扫码登录、联系人查询与全类型消息发送开发流程，含接口示例与注意事项。

2026-08-01 12 分钟阅读极客互动

登录流程联系人查询消息发送iPad协议

一、文档概述

本文基于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 消息辅助操作接口

撤回消息：/wxwork/RevokeMsg，传入 msgid、roomid（单聊填 0）

{    "uuid": "xxx",    "msgid":1063645,    "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，减少重复查询接口调用。

需要落地这套方案？

添加客服微信获取演示与接入支持，也可查阅完整在线接口文档。

咨询接入查看 API 文档

一、文档概述

通用接口规范

二、账号完整登录流程

2.1 步骤总览

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

接口地址

参数说明

返回示例

2.3 获取登录二维码

接口地址

请求参数

返回字段说明

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

接口地址

请求示例

异常说明

2.5 历史账号自动登录

接口地址

请求体

2.6 辅助登录接口

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

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

接口地址

请求示例

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

接口地址

请求示例

四、消息发送全流程

前置说明

4.1 ：发送纯文本消息

接口地址

4.2 文本 + 表情混合消息

接口地址

请求示例

4.3 CDN 图片消息（25M 内）

4.4 群 @消息（群专属）

接口地址

4.5 高级消息类型简表

4.6 消息辅助操作接口

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

六、开发注意事项

1. 登录风控

2. 联系人使用

3. 消息发送风控限制

4. 缓存建议

需要落地这套方案？

更多博文