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

一、开发概述

本文基于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"
}

|-------------------------|
| 关键：缓存返回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 辅助登录接口

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]
}

|---|
| |

|---------------------------------|
| 使用场景：已有 userid，需要昵称、头像等展示信息时调用。 |

四、消息发送全流程

前置说明

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，减少重复查询接口调用。