API

第三方回调协议

[TOC]

概述

在发生授权、通讯录变更、ticket变化等事件时，企业微信服务器会向应用的“指令回调URL”推送相应的事件消息。消息结构体将使用创建应用时的EncodingAESKey进行加密（特别注意, 在第三方回调事件中使用加解密算法，receiveid的内容为suiteid），请参考接收消息解析数据包。

本章节的回调事件，服务商在收到推送后都必须直接返回字符串 “success”，若返回值不是 “success”，企业微信会把返回内容当作错误信息。

以下各个事件皆假设指令回调URL设置为：https://127.0.0.1/suite/receive

收到的数据包中ToUserName为产生事件的SuiteId，AgentID为空

以下各个事件的xml包仅是接收的数据包中的Encrypt参数解密后的内容说明

推送suite_ticket

企业微信服务器会定时（每十分钟）推送ticket。ticket会实时变更，并用于后续接口的调用。
请求方式：POST（HTTPS）
请求地址：https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

    <xml>
        <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
        <InfoType> <![CDATA[suite_ticket]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
        <SuiteTicket><![CDATA[asdfasfdasdfasdf]]></SuiteTicket>
    </xml>

参数说明：

参数 说明
SuiteId 第三方应用的SuiteId
InfoType suite_ticket
TimeStamp 时间戳
SuiteTicket Ticket内容，最长为512字节

授权成功通知

从企业微信应用市场发起授权时，企业微信后台会推送授权成功通知。

从第三方服务商网站发起的应用授权流程，由于授权完成时会跳转第三方服务商管理后台，因此不会通过此接口向第三方服务商推送授权成功通知。

请求方式：POST（HTTPS）
请求地址：https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

    <xml>
        <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></ SuiteId>
        <AuthCode><![CDATA[AUTHCODE]]></AuthCode>
        <InfoType><![CDATA[create_auth]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
    </xml>

服务商的响应必须在1000ms内完成，以保证用户安装应用的体验。建议在接收到此事件时，先记录下AuthCode，并立即回应企业微信，之后再做相关业务的处理。

参数说明：

参数 说明
SuiteId 第三方应用的SuiteId
AuthCode 授权的auth_code,最长为512字节。用于获取企业的永久授权码。5分钟内有效
InfoType create_auth
TimeStamp 时间戳

变更授权通知

当授权方（即授权企业）在企业微信管理端的授权管理中，修改了对应用的授权后，企业微信服务器推送变更授权通知。
服务商接收到变更通知之后，需自行调用获取企业授权信息进行授权内容变更比对。

请求方式：POST（HTTPS）
请求地址：https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

    <xml>
        <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
        <InfoType><![CDATA[change_auth]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
        <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    </xml>

服务商的响应必须在1000ms内完成，以保证用户变更授权的体验。建议在接收到此事件时，立即回应企业微信，之后再做相关业务的处理。

参数说明：

参数 说明
SuiteId 第三方应用的SuiteId
InfoType change_auth
TimeStamp 时间戳
AuthCorpId 授权方的corpid

取消授权通知

当授权方（即授权企业）在企业微信管理端的授权管理中，取消了对应用的授权托管后，企业微信后台会推送取消授权通知。
请求方式：POST（HTTPS）
请求地址：https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

    <xml>
        <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></ SuiteId>
        <InfoType><![CDATA[cancel_auth]]></InfoType>
        <TimeStamp>1403610513</TimeStamp>
        <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    </xml>

服务商的响应必须在1000ms内完成，以保证用户取消授权的体验。建议在接收到此事件时，立即回应企业微信，之后再做相关业务的处理。

参数说明：

参数 说明
SuiteId 第三方应用的SuiteId
InfoType cancel_auth
TimeStamp 时间戳
AuthCorpId 授权方企业的corpid

通讯录变更事件通知

当企业微信成员或者部门变更时，企业微信后台会推送通讯录变更通知到权限范围内的应用的“指令回调URL”。
注意：由第三方应用调用接口触发的变更事件不回调给该应用本身；第三方应用通讯录权限等级为单个基本信息只读的，也不回调通讯录变更事件。

新增成员事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[create_user]]></ChangeType>
    <UserID><![CDATA[zhangsan]]></UserID>
    <Name><![CDATA[张三]]></Name>
    <Department><![CDATA[1,2,3]]></Department>
    <Mobile><![CDATA[15913215421]]></Mobile>
    <Position><![CDATA[产品经理]]></Position>
    <Gender>1</Gender>
    <Email><![CDATA[zhangsan@gzdev.com]]></Email>
    <Avatar><![CDATA[http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0]]></Avatar>
    <EnglishName><![CDATA[zhangsan]]></EnglishName>
    <IsLeader>1</IsLeader>
    <Telephone><![CDATA[020-3456788]]></Telephone>
    <ExtAttr>
        <Item>
        <Name><![CDATA[爱好]]></Name>
        <Value><![CDATA[旅游]]></Value>
        </Item>
        <Item>
        <Name><![CDATA[卡号]]></Name>
        <Value><![CDATA[1234567234]]></Value>
        </Item>
    </ExtAttr>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为create_user
UserID 成员UserID
Name 成员名称
Department 更新后成员所在部门列表
Mobile 手机号码，仅通讯录管理应用可获取
Position 职位信息。长度为0~64个字节，仅通讯录管理应用可获取
Gender 性别。1表示男性，2表示女性
Email 邮箱，仅通讯录管理应用可获取
Status 激活状态：1=激活或关注， 2=禁用， 4=未激活 已激活代表已激活企业微信或已关注微工作台（原企业号）。未激活代表既未激活企业微信又未关注微工作台（原企业号）
Avatar 头像url。注：如果要获取小图将url最后的”/0”改成”/100”即可，仅通讯录管理应用可获取
EnglishName 英文名
IsLeader 上级字段，标识是否为上级。0表示普通成员，1表示上级。仅通讯录管理应用可获取
Telephone 座机，仅通讯录管理应用可获取
ExtAttr 扩展属性，仅通讯录管理应用可获取

说明： 对用户具有通讯录基本信息只读权限的应用只返回基本字段。由通讯录应用发起的新增成员触发的事件不回调给通讯录应用。

更新成员事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[update_user]]></ChangeType>
    <UserID><![CDATA[zhangsan]]></UserID>
    <NewUserID><![CDATA[zhangsan001]]></NewUserID>
    <Name><![CDATA[张三]]></Name>
    <Department><![CDATA[1,2,3]]></Department>
    <Mobile><![CDATA[15913215421]]></Mobile>
    <Position><![CDATA[产品经理]]></Position>
    <Gender>1</Gender>
    <Email><![CDATA[zhangsan@gzdev.com]]></Email>
    <Status>1</Status>
    <Avatar><![CDATA[http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0]]></Avatar>
    <EnglishName><![CDATA[zhangsan]]></EnglishName>
    <IsLeader>1</IsLeader>
    <Telephone><![CDATA[020-3456788]]></Telephone>
    <ExtAttr>
        <Item>
        <Name><![CDATA[爱好]]></Name>
        <Value><![CDATA[旅游]]></Value>
        </Item>
        <Item>
        <Name><![CDATA[卡号]]></Name>
        <Value><![CDATA[1234567234]]></Value>
        </Item>
    </ExtAttr>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为update_user
UserID 变更信息的成员UserID
NewUserID 新的UserID，变更时推送（userid由系统生成时可更改一次）
Name 成员名称，变更时推送
Department 更新后成员所在部门列表
Mobile 手机号码，变更时推送，仅通讯录应用可获取
Position 职位信息。长度为0~64个字节，仅通讯录管理应用可获取
Gender 性别，变更时推送。1表示男性，2表示女性
Email 邮箱，变更时推送 ，仅通讯录应用可获取
Avatar 头像url。注：如果要获取小图将url最后的”/0”改成”/100”即可。变更时推送，仅通讯录管理应用可获取
Status 激活状态：1=激活或关注， 2=禁用， 4=未激活（重新启用未激活用户或者退出企业并且取消关注时触发）
EnglishName 英文名
IsLeader 上级字段，标识是否为上级。0表示普通成员，1表示上级。仅通讯录管理应用可获取
Telephone 座机，仅通讯录应用可获取
ExtAttr 扩展属性，变更时推送，仅通讯录应用可获取

说明： 对用户具有通讯录基本信息只读权限的应用只返回基本字段，只变更敏感字段信息不回调事件给基本信息只读的应用。由通讯录应用发起的更新成员触发的事件不回调给通讯录应用。（更新成员部门的操作导致退出应用权限范围的也会收到成员部门变更事件的回调）

删除成员事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[delete_user]]></ChangeType>
    <UserID><![CDATA[zhangsan]]></UserID>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为delete_user
UserID 变更信息的成员UserID

说明： 由通讯录应用发起的删除成员触发的事件不回调给通讯录应用。

新增部门事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[create_party]]></ChangeType>
    <Id>2</Id>
    <Name><![CDATA[张三]]></Name>
    <ParentId><![CDATA[1]]></ParentId>
    <Order>1</Order>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为create_party
Id 部门Id
Name 部门名称
ParentId 父部门id
Order 部门排序

说明： 由通讯录应用发起的新增部门触发的事件不回调给通讯录应用。

更新部门事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[update_party]]></ChangeType>
    <Id>2</Id>
    <Name><![CDATA[张三]]></Name>
    <ParentId><![CDATA[1]]></ParentId>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为update_party
Id 部门Id
Name 部门名称，仅当该字段发生变更时传递
ParentId 父部门id，仅当该字段发生变更时传递

说明： 由通讯录应用发起的更新部门触发的事件不回调给通讯录应用。

删除部门事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[delete_party]]></ChangeType>
    <Id>2</Id>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为delete_party
Id 部门Id

说明： 由通讯录应用发起的删除部门触发的事件不回调给通讯录应用。

标签成员变更事件

请求方式：POST（HTTPS）
请求地址： https://127.0.0.1/suite/receive?msg_signature=3a7b08bb8e6dbce3c9671d6fdb69d15066227608&timestamp=1403610513&nonce=380320359

请求包体：

<xml>
    <SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
    <AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
    <InfoType><![CDATA[change_contact]]></InfoType>
    <TimeStamp>1403610513</TimeStamp>
    <ChangeType><![CDATA[update_tag]]></ChangeType>
    <TagId>1</TagId>
    <AddUserItems><![CDATA[zhangsan,lisi]]></AddUserItems>
    <DelUserItems><![CDATA[zhangsan1,lisi1]]></DelUserItems>
    <AddPartyItems><![CDATA[1,2]]></AddPartyItems>
    <DelPartyItems><![CDATA[3,4]]></DelPartyItems>
</xml>

参数说明：

参数 说明
SuiteId 第三方应用ID
AuthCorpId 授权企业的CorpID
InfoType 固定为change_contact
TimeStamp 时间戳
ChangeType 固定为update_tag
TagId 标签Id
AddUserItems 标签中新增的成员userid列表，用逗号分隔
DelUserItems 标签中删除的成员userid列表，用逗号分隔
AddPartyItems 标签中新增的部门id列表，用逗号分隔
DelPartyItems 标签中删除的部门id列表，用逗号分隔

说明： 回调设置在授权应用可见范围内的标签的变更事件。由第三方应用调用接口触发的标签变更事件不回调给该应用本身。

© 1998 - 2021 Tencent Inc. All Rights Reserved