接入指南

从第一次登录到稳定调用

下面是登录、二次验证、掉线重连和两类常见回调问题。字段级说明以接口文档为准。

登录四步

新账号按这个顺序调用。新设备首次登录会进入验证码校验。

  1. 初始化企业微信。 使用默认参数发起请求,接口返回一个 UUID。
  2. 获取登录二维码。 传入上一步的 UUID。接口返回二维码和 Key,用企业微信手机端扫码。
  3. 提交验证码。 调用验证码设置,把 UUID、Key 和手机端验证码一起 POST。登录没完成前,不要关闭手机上的验证码页面。
  4. 配置回调并调用。 账号登录到服务端后,设置消息回调地址,即可收发消息和做业务操作。

二次验证

首次登录后,大约 30 分钟内可能出现二次验证。建议账号上线后先观察这一段时间。

  1. 触发时,回调会推送登录分类下的二次验证通知。
  2. 接口也可能直接返回错误。示例:errcode 为 -11025,提示出现二次验证,需要重新获取二维码登录。
  3. 收到该结果后,调用「获取二次验证二维码」。
  4. 用企业微信扫码。页面出现确认弹窗后点确定,验证完成。

自动登录与重连

账号已经完成过首次登录,之后执行登出,或服务关闭再启动,可以走自动登录。

  1. 首次登录顺序:初始化、按需设置回调、获取登录二维码、输入验证码。
  2. 再次登录:初始化时把参数 vid 填成首次登录得到的账号 vid,以 1688 开头。然后调用自动登录。
  3. 自动登录成功,表示账号已经登录完成。
  4. 自动登录失败时,直接获取登录二维码,不必再次初始化。初始化时已经传入 vid,会复用首次登录的设备信息,扫码即可,不会当成新设备。

使用注意

重复回调

同一条消息出现多次回调时,看 JSON 里的 referid。referid 为 0 是原始消息;不为 0 是基于原消息的后续操作,例如已读。

文件下载

个人微信发来的图片、视频、文件,走外部联系人下载。外部企业好友和内部联系人发来的图片、视频、文件、语音,走 CDN 文件下载。

开发语言

按 HTTP 接入即可,不绑定某一种语言。

Java Python C++ Go Node.js PHP C#