回调模式

在回调模式下，企业不仅可以主动调用企业号接口，还可以接收成员的消息或事件。接收的信息使用XML数据格式、UTF8编码，并以AES方式加密。

企业号的每个应用都有自己的回调模式开关。在管理端开启并设置好相关参数后，此应用的回调模式才生效。

针对加解密的处理，微信提供了各种语言的库，企业可以在附录中下载。

开启应用的回调模式

当你开启应用的回调模式时，企业号会要求你填写应用的URL、Token、EncodingAESKey三个参数。

URL是企业应用接收企业号推送请求的访问协议和地址，支持http或https协议。

Token可由企业任意填写，用于生成签名。

EncodingAESKey用于消息体的加密，是AES密钥的Base64编码。

验证URL、Token以及加密的详细处理请参考后续'接收消息时的加解密处理'的章节。

验证URL有效性

当你提交以上信息时，企业号将发送GET请求到填写的URL上，GET请求携带四个参数，企业在获取时需要做urldecode处理，否则会验证不成功。

参数

描述

是否必带

msg_signature

微信加密签名，msg_signature结合了企业填写的token、请求中的timestamp、nonce参数、加密的消息体

是

timestamp

时间戳

是

nonce

随机数

是

echostr

加密的随机字符串，以msg_encrypt格式提供。需要解密并返回echostr明文，解密后有random、msg_len、msg、$CorpID四个字段，其中msg即为echostr明文

首次校验时必带

企业通过参数msg_signature对请求进行校验，如果确认此次GET请求来自企业号，那么企业应该对echostr参数解密并原样返回echostr明文(不能加引号，不能带bom头，不能带换行符)，则接入验证生效，回调模式才能开启。

后续回调企业时都会在请求URL中带上以上参数(echostr除外)，校验方式与首次验证URL一致。

使用回调模式

企业号在回调企业URL时，会对消息体本身做AES加密，以XML格式POST到企业应用的URL上；企业在被动响应时，也需要对数据加密，以XML格式返回给微信。企业的回复支持文本、图片、语音、视频、图文等格式。

微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。如果在调试中，发现成员无法收到响应的消息，可以检查是否消息处理超时。

当接收成功后，http头部返回200表示接收ok，其他错误码一律当做失败并发起重试

关于重试的消息排重，有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime排重。

假如企业无法保证在五秒内处理并回复，可以直接回复空串，企业号不会对此作任何处理，并且不会发起重试。这种情况下，可以使用发消息接口进行异步回复。

请求说明：

回调数据格式：

1.msg_encrypt为经过加密的密文(消息明文格式参见 接收普通消息，事件明文格式参见 接收事件)

2.AgentID为接收的应用id，可在应用的设置页面获取

3.ToUserName为企业号的CorpID

企业需要对msg_signature进行校验，并解密msg_encrypt，得出msg的原文。

被动响应给微信的数据格式：

timestamp

1.msg_encrypt为经过加密的密文(消息明文格式参见 被动响应消息)，算法参见附录

2.MsgSignature为签名，算法参见附录

3.TimeStamp为时间戳，Nonce为随机数，由企业自行生成

接收消息时的加解密处理

企业可以直接使用微信提供的库进行加解密的处理，目前提供的有c++/python/php/java/c#等语言版本。代码提供了解密、加密、验证URL三个接口，企业可根据自身需要下载 (参见附录的加解密库下载)。以下为库函数的使用说明(以c++为例)，更详细的加解密方案请参考(附录)。

1、解密函数

int DecryptMsg(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sPostData, string &sMsg);

参数说明

参数

必须

说明

sMsgSignature

是

从回调URL中获取的msg_signature参数

sTimeStamp

是

从回调URL中获取的timestamp参数

sNonce

是

从回调URL中获取的nonce参数

sPostData

是

从回调URL中获取的整个post数据

sMsg

是

用于返回解密后的msg，以xml组织

返回说明

请参阅附录加解密部分。

2、加密函数

int EncryptMsg(const string &sReplyMsg, const string &sTimeStamp, const string &sNonce, string &sEncryptMsg);

参数说明

参数

必须

说明

sReplyMsg

是

返回的消息体原文

sTimeStamp

是

时间戳，调用方生成

sNonce

是

随机数，调用方生成

sEncryptMsg

是

用于返回的密文，以xml组织

返回说明

请参阅附录加解密部分。

3、验证URL函数

int VerifyURL(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sEchoStr, string &sReplyEchoStr);

参数说明

参数

必须

说明

sMsgSignature

是

从回调URL中获取的msg_signature参数

sTimeStamp

是

从回调URL中获取的timestamp参数

sNonce

是

从回调URL中获取的nonce参数

sEchoStr

是

从回调URL中获取的echostr参数。注意，此参数必须是urldecode后的值

sReplyEchoStr

是

解密后的echostr，用于回包。注意，必须原样返回，不要做加引号或其它处理

返回说明

请参阅附录加解密部分。

获取微信服务器的ip段

请求说明

Https请求方式: GET

参数说明

参数

必须

说明

access_token

是

调用接口凭证

返回结果

{

"ip_list": ["101.226.103.*", "101.226.62.*"]

}