事件格式 - 文档 - 企业微信开发者中心

第三方应用开发

快速入门服务端API 客户端API 工具与资源运营规范附录更新日志联系我们

第三方应用开发

服务端API

客户联系

回调通知

事件格式

最后更新：2024/06/03

添加企业客户事件

授权企业中配置了客户联系功能的成员添加外部联系人时，企业微信服务器会向应用的“指令回调URL”推送该事件

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_contact]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChangeType><![CDATA[add_external_contact]]></ChangeType>
	<UserID><![CDATA[zhangsan]]></UserID>
	<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACH71w]]></ExternalUserID>
	<State><![CDATA[teststate]]></State>
	<WelcomeCode><![CDATA[WELCOMECODE]]></WelcomeCode>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为change_external_contact
TimeStamp	时间戳
ChangeType	此时固定为add_external_contact
UserID	企业服务人员的UserID
ExternalUserID	外部联系人的userid，注意不是企业成员的账号
State	添加此用户的「联系我」方式配置的state参数，可用于识别添加此用户的渠道
WelcomeCode	欢迎语code，可用于发送欢迎语

第三方应用可以根据ExternalUserID调用“获取客户详情”读取详情。
注意:如果外部联系人和成员已经开始聊天或已通过「外部联系人免验证添加成员事件」得到的welcomecode发送欢迎语，则不会继续返回welcomecode。成员添加其他企业的企业微信联系人（商务伙伴）时，将自动递名片打招呼，不再回调welcomecode。

编辑企业客户事件

授权企业中配置了客户联系功能的成员编辑外部联系人的备注信息(不包括备注手机号码)或企业标签时，企业微信服务器会向应用的“指令回调URL”推送该事件，但仅修改外部联系人备注手机号时不会触发回调。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_contact]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChangeType><![CDATA[edit_external_contact]]></ChangeType>
	<UserID><![CDATA[zhangsan]]></UserID>
	<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACH71w]]></ExternalUserID>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为change_external_contact
TimeStamp	时间戳
ChangeType	此时固定为edit_external_contact
UserID	企业服务人员的UserID
ExternalUserID	外部联系人的userid，注意不是企业成员的账号

外部联系人免验证添加成员事件

外部联系人添加了配置了客户联系功能且开启了免验证的成员时（此时成员尚未确认添加对方为好友），企业微信服务器会向应用的“指令回调URL”推送该事件

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_contact]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChangeType><![CDATA[add_half_external_contact]]></ChangeType>
	<UserID><![CDATA[zhangsan]]></UserID>
	<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACH71w]]></ExternalUserID>
	<State><![CDATA[teststate]]></State>
	<WelcomeCode><![CDATA[WELCOMECODE]]></WelcomeCode>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为change_external_contact
TimeStamp	时间戳
ChangeType	此时固定为add_half_external_contact
UserID	企业服务人员的UserID
ExternalUserID	外部联系人的userid，注意不是企业成员的账号
State	添加此用户的「联系我」方式配置的state参数，可用于识别添加此用户的渠道
WelcomeCode	欢迎语code，可用于发送欢迎语

第三方应用可以根据ExternalUserID调用“获取客户详情”读取详情。
注意:如果外部联系人和成员已经开始聊天或已通过「外部联系人免验证添加成员事件」得到的welcomecode发送欢迎语，则不会继续返回welcomecode。企业成员添加其他企业的企业微信联系人（商务伙伴）时，将自动递名片打招呼，不再回调welcomecode。

删除企业客户事件

授权企业中配置了客户联系功能的成员删除外部联系人时，企业微信服务器会向应用的“指令回调URL”推送该事件

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_contact]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChangeType><![CDATA[del_external_contact]]></ChangeType>
	<UserID><![CDATA[zhangsan]]></UserID>
	<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACH71w]]></ExternalUserID>
	<Source><![CDATA[DELETE_BY_TRANSFER]]></Source>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为change_external_contact
TimeStamp	时间戳
ChangeType	此时固定为del_external_contact
UserID	企业服务人员的UserID
ExternalUserID	外部联系人的userid，注意不是企业成员的账号
Source	删除客户的操作来源，`DELETE_BY_TRANSFER`表示此客户是因在职继承自动被转接成员删除

删除跟进成员事件

授权企业中配置了客户联系功能的成员被外部联系人删除时，企业微信服务器会向应用的“指令回调URL”推送该事件

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_contact]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChangeType><![CDATA[del_follow_user]]></ChangeType>
	<UserID><![CDATA[zhangsan]]></UserID>
	<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACH71w]]></ExternalUserID>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为change_external_contact
TimeStamp	时间戳
ChangeType	此时固定为del_follow_user
UserID	企业服务人员的UserID
ExternalUserID	外部联系人的userid，注意不是企业成员的账号

客户接替失败事件

企业将客户分配给新的成员接替后，当客户添加失败时，企业微信服务器会向应用的“指令回调URL”推送该事件

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_contact]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChangeType><![CDATA[transfer_fail]]></ChangeType>
	<FailReason><![CDATA[customer_refused]]></FailReason>
	<UserID><![CDATA[zhangsan]]></UserID>
	<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACH71w]]></ExternalUserID>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为change_external_contact
TimeStamp	时间戳
ChangeType	此时固定为transfer_fail
FailReason	接替失败的原因, customer_refused-客户拒绝， customer_limit_exceed-接替成员的客户数达到上限
UserID	企业服务人员的UserID
ExternalUserID	外部联系人的userid，注意不是企业成员的账号

客户群创建事件

有新增客户群时，回调该事件。收到该事件后，企业可以调用获取客户群详情接口获取客户群详情。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_chat]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChatId><![CDATA[CHAT_ID]]></ChatId>
	<ChangeType><![CDATA[create]]></ChangeType>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为`change_external_chat`
TimeStamp	时间戳
ChatId	群ID
ChangeType	此时固定为`create`

客户群变更事件

客户群被修改后（群名变更，群成员增加或移除，群公告变更），回调该事件。收到该事件后，企业需要再调用获取客户群详情接口，以获取最新的群详情。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_chat]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChatId><![CDATA[CHAT_ID]]></ChatId>
	<ChangeType><![CDATA[update]]></ChangeType>
	<UpdateDetail><![CDATA[add_member]]></UpdateDetail>
    <JoinScene>1</JoinScene>
    <QuitScene>0</QuitScene>
    <MemChangeCnt>10</MemChangeCnt>
    <MemChangeList>
		<Item>Jack</Item>
		<Item>Rose</Item>
	</MemChangeList>
	<LastMemVer>9c3f97c2ada667dfb5f6d03308d963e1</LastMemVer>
	<CurMemVer>71217227bbd112ecfe3a49c482195cb4</CurMemVer>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为`change_external_chat`
TimeStamp	时间戳
ChatId	群ID
ChangeType	此时固定为`update`
UpdateDetail	变更详情。目前有以下几种： add_member : 成员入群 del_member : 成员退群 change_owner : 群主变更 change_name : 群名变更 change_notice : 群公告变更
JoinScene	当是成员入群时有值。表示成员的入群方式 0 - 由成员邀请入群（包括直接邀请入群和通过邀请链接入群） 3 - 通过扫描群二维码入群
QuitScene	当是成员退群时有值。表示成员的退群方式 0 - 自己退群 1 - 群主/群管理员移出
MemChangeCnt	当是成员入群或退群时有值。表示成员变更数量
MemChangeList	当是成员入群或退群时有值。变更的成员列表
LastMemVer	当是成员入群或退群时有值。变更前的群成员版本号
CurMemVer	当是成员入群或退群时有值。变更后的群成员版本号

关于客户群变更事件中，群成员版本号的使用技巧
客户群变更较为频繁，开发者希望直接通过回调事件来更新群成员，因此事件新增变更成员列表信息。而变更事件的回调过程并不可靠（接收方可能丢失或乱序），为了让开发者能准确判断本次接收到的客户群变更事件是否可信任，变更事件中新增两个版本号：变更前的群成员版本号、变更后的群成员版本号。开发者可以存储每个群的最新版本号，当接收到客户群变更事件后，如果是成员入群或成员退群事件，则对比事件中的变更前版本号与自己存储的最新版本号是否一致，如果一致则说明本次事件可信任，并更新最新版本号；如果不一致，则说明本次收到的事件不可靠，可以通过拉客户群详情来获取最新信息和最新版本号。以此在不需要增加调用量的前提下，实现数据一致性。

客户群解散事件

当客户群被群主解散后，回调该事件。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_chat]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<ChatId><![CDATA[CHAT_ID]]></ChatId>
	<ChangeType><![CDATA[dismiss]]></ChangeType>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为`change_external_chat`
TimeStamp	时间戳
ChatId	群ID
ChangeType	此时固定为`dismiss`

企业客户标签创建事件

企业/管理员创建客户标签/标签组时，企业微信服务器将向具有企业客户权限的第三方应用指令回调URL回调此事件。收到该事件后，第三方服务商需要调用获取企业标签库来获取标签/标签组的详细信息。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_tag]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<Id><![CDATA[TAG_ID]]></Id>
	<TagType><![CDATA[tag]]></TagType>
	<ChangeType><![CDATA[create]]></ChangeType>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为`change_external_tag`
TimeStamp	unix时间戳
Id	标签或标签组的ID
TagType	创建标签时，此项为`tag`，创建标签组时，此项为`tag_group`
ChangeType	此时固定为`create`

企业客户标签变更事件

当企业客户标签/标签组被修改时，企业微信服务器将向具有企业客户权限的第三方应用指令回调URL回调此事件。收到该事件后，第三方服务商需要调用获取企业标签库来获取标签/标签组的详细信息。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_tag]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<Id><![CDATA[TAG_ID]]></Id>
	<TagType><![CDATA[tag]]></TagType>
	<ChangeType><![CDATA[update]]></ChangeType>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为`change_external_tag`
TimeStamp	unix时间戳
Id	标签或标签组的ID
TagType	变更标签时，此项为`tag`，变更标签组时，此项为`tag_group`
ChangeType	此时固定为`update`

企业客户标签删除事件

当企业客户标签/标签组被删除改时，企业微信服务器将向具有企业客户权限的第三方应用指令回调URL回调此事件。删除标签组时，该标签组下的所有标签将被同时删除，但不会进行回调。

请求示例：

<xml>
	<SuiteId><![CDATA[ww4asffe99e54c0f4c]]></SuiteId>
	<AuthCorpId><![CDATA[wxf8b4f85f3a794e77]]></AuthCorpId>
	<InfoType><![CDATA[change_external_tag]]></InfoType>
	<TimeStamp>1403610513</TimeStamp>
	<Id><![CDATA[TAG_ID]]></Id>
	<TagType><![CDATA[tag]]></TagType>
	<ChangeType><![CDATA[delete]]></ChangeType>
</xml>

参数说明：

参数	说明
SuiteId	第三方应用ID
AuthCorpId	授权企业的CorpID
InfoType	固定为`change_external_tag`
TimeStamp	unix时间戳
Id	标签或标签组的ID
TagType	删除标签时，此项为`tag`，删除标签组时，此项为`tag_group`
ChangeType	此时固定为`delete`

企业客户标签重排事件

当企业管理员在终端/管理端调整标签顺序时，可能导致标签顺序整体调整重排，引起大部分标签的order值发生变化，此时会回调此事件，收到此事件后企业应尽快全量同步标签的order值，防止后续调用接口排序出现非预期结果。