登录
基础
连接微信
办公目录
当用户在客户端或管理端进行某种操作后，会回调相应的事件给开发者。通过API进行的操作不会产生回调。
| 应用类型 | 权限要求 | 接收事件开关 |
|---|---|---|
| 自建应用 | 配置到「客户联系- 可调用接口的应用」中 | 外部联系人变更回调 |
| 代开发应用 | 具有「客户联系->客户基础信息」权限 | 无 |
| 第三方应用 | 具有「客户联系->客户基础信息」权限 | 无 |
特别注意：
配置了客户联系功能的成员添加外部联系人时，回调该事件
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_contact]]></Event>
<ChangeType><![CDATA[add_external_contact]]></ChangeType>
<UserID><![CDATA[zhangsan]]></UserID>
<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mAAAA]]></ExternalUserID>
<State><![CDATA[teststate]]></State>
<WelcomeCode><![CDATA[WELCOMECODE]]></WelcomeCode>
</xml>参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_contact |
| ChangeType | 此时固定为add_external_contact |
| UserID | 企业服务人员的UserID |
| ExternalUserID | 外部联系人的userid，注意不是企业成员的账号 |
| State | 添加此用户的「联系我」方式配置的state参数，或在获客链接中指定的customer_channel参数，可用于识别添加此用户的渠道 |
| WelcomeCode | 欢迎语code，可用于发送欢迎语 |
企业可以根据ExternalUserID调用“获取客户详情”读取详情。
企业可以通过配置客户联系「联系我」方式接口来指定State参数，或在获客链接中指定customer_channel参数，当有客户通过对应的联系方式添加企业成员时，State即为用户配置的state/customer_channel参数。
注意:如果外部联系人和成员已经开始聊天或已通过「外部联系人免验证添加成员事件」得到的welcomecode发送欢迎语，则不会继续返回welcomecode。成员添加其他企业的企业微信联系人（商务伙伴）时，将自动递名片打招呼，不再回调welcomecode。
配置了客户联系功能的成员修改外部联系人的备注、手机号或标签时，回调该事件
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_contact]]></Event>
<ChangeType><![CDATA[edit_external_contact]]></ChangeType>
<UserID><![CDATA[zhangsan]]></UserID>
<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mAAAA]]></ExternalUserID>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_contact |
| ChangeType | 此时固定为edit_external_contact |
| UserID | 企业服务人员的UserID |
| ExternalUserID | 外部联系人的userid，注意不是企业成员的账号 |
外部联系人添加了配置了客户联系功能且开启了免验证的成员时（此时成员尚未确认添加对方为好友），回调该事件
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_contact]]></Event>
<ChangeType><![CDATA[add_half_external_contact]]></ChangeType>
<UserID><![CDATA[zhangsan]]></UserID>
<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACAAAA]]></ExternalUserID>
<State><![CDATA[teststate]]></State>
<WelcomeCode><![CDATA[WELCOMECODE]]></WelcomeCode>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_contact |
| ChangeType | 此时固定为add_half_external_contact |
| UserID | 企业服务人员的UserID |
| ExternalUserID | 外部联系人的userid，注意不是企业成员的账号 |
| State | 添加此用户的「联系我」方式配置的state参数，或在获客链接中指定的customer_channel参数，可用于识别添加此用户的渠道 |
| WelcomeCode | 欢迎语code，可用于发送欢迎语 |
企业可以根据ExternalUserID调用“获取客户详情”读取详情。
企业可以通过配置客户联系「联系我」方式接口来指定State参数，或在获客链接中指定customer_channel参数，当有客户通过对应的联系方式添加企业成员时，State即为用户配置的state/customer_channel参数。
注意:如果外部联系人和成员已经开始聊天，则不会返回welcomecode。成员添加其他企业的企业微信联系人（商务伙伴）时，将自动递名片打招呼，不再回调welcomecode。
配置了客户联系功能的成员删除外部联系人时，回调该事件
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_contact]]></Event>
<ChangeType><![CDATA[del_external_contact]]></ChangeType>
<UserID><![CDATA[zhangsan]]></UserID>
<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACAAAA]]></ExternalUserID>
<Source><![CDATA[DELETE_BY_TRANSFER]]></Source>
</xml>参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_contact |
| ChangeType | 此时固定为del_external_contact |
| UserID | 企业服务人员的UserID |
| ExternalUserID | 外部联系人的userid，注意不是企业成员的账号 |
| Source | 删除客户的操作来源，DELETE_BY_TRANSFER表示此客户是因在职继承自动被转接成员删除 |
配置了客户联系功能的成员被外部联系人删除时，回调该事件
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_contact]]></Event>
<ChangeType><![CDATA[del_follow_user]]></ChangeType>
<UserID><![CDATA[zhangsan]]></UserID>
<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mACHAAA]]></ExternalUserID>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_contact |
| ChangeType | 此时固定为del_follow_user |
| UserID | 企业服务人员的UserID |
| ExternalUserID | 外部联系人的userid，注意不是企业成员的账号 |
企业将客户分配给新的成员接替后，客户添加失败时回调该事件
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_contact]]></Event>
<ChangeType><![CDATA[transfer_fail]]></ChangeType>
<FailReason><![CDATA[customer_refused]]></FailReason>
<UserID><![CDATA[zhangsan]]></UserID>
<ExternalUserID><![CDATA[woAJ2GCAAAXtWyujaWJHDDGi0mAAAA]]></ExternalUserID>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （整型） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_contact |
| ChangeType | 此时固定为transfer_fail |
| FailReason | 接替失败的原因, customer_refused-客户拒绝， customer_limit_exceed-接替成员的客户数达到上限 |
| UserID | 接替失败的企业服务人员的UserID |
| ExternalUserID | 外部联系人的userid，注意不是企业成员的账号 |
如果此客户在企业内仍有其他在职的跟进人，则企业仍可以根据ExternalUserID调用“获取客户详情”读取详情，否则无法获取。
有新增客户群时，回调该事件。收到该事件后，企业可以调用获取客户群详情接口获取客户群详情。
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_chat]]></Event>
<ChatId><![CDATA[CHAT_ID]]></ChatId>
<ChangeType><![CDATA[create]]></ChangeType>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_chat |
| ChatId | 群ID |
| ChangeType | 此时固定为create |
客户群被修改后（群名变更，群成员增加或移除，群主变更，群公告变更），回调该事件。收到该事件后，企业需要再调用获取客户群详情接口，以获取最新的群详情。
事件示例：
<xml>
<ToUserName><![CDATA[ww55ca070cb9b7eb22]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_chat]]></Event>
<ChatId><![CDATA[wrx7HUARsKwGRaQBVKPBTcEyzdHA4HrQ]]></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>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_chat |
| 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 | 当是成员入群或退群时有值。变更后的群成员版本号 |
关于客户群变更事件中，群成员版本号的使用技巧
客户群变更较为频繁，开发者希望直接通过回调事件来更新群成员，因此事件新增变更成员列表信息。而变更事件的回调过程并不可靠（接收方可能丢失或乱序），为了让开发者能准确判断本次接收到的客户群变更事件是否可信任，变更事件中新增两个版本号：变更前的群成员版本号、变更后的群成员版本号。开发者可以存储每个群的最新版本号，当接收到客户群变更事件后，如果是成员入群或成员退群事件，则对比事件中的变更前版本号与自己存储的最新版本号是否一致，如果一致则说明本次事件可信任，并更新最新版本号；如果不一致，则说明本次收到的事件不可靠，可以通过拉客户群详情来获取最新信息和最新版本号。以此在不需要增加调用量的前提下，实现数据一致性。
当客户群被群主解散后，回调该事件。
需注意的是，如果发生群信息变动，会立即收到此事件，但是部分信息是异步处理，可能需要等一段时间(例如2秒)调用获取客户群详情接口才能得到最新结果
事件示例：
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_chat]]></Event>
<ChatId><![CDATA[CHAT_ID]]></ChatId>
<ChangeType><![CDATA[dismiss]]></ChangeType>
</xml>
参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_chat |
| ChatId | 群ID |
| ChangeType | 此时固定为dismiss |
企业/管理员创建客户标签/标签组时（包括规则组的标签），回调此事件。收到该事件后，企业需要调用获取企业标签库来获取标签/标签组的详细信息。
事件示例：
<xml>
<ToUserName><![CDATA[CORPID]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_tag]]></Event>
<Id><![CDATA[TAG_ID]]></Id>
<TagType><![CDATA[tag]]></TagType>
<ChangeType><![CDATA[create]]></ChangeType>
<StrategyId>1</StrategyId>
</xml>参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_tag |
| Id | 标签或标签组的ID |
| TagType | 创建标签时，此项为tag，创建标签组时，此项为tag_group |
| ChangeType | 此时固定为create |
| StrategyId | 标签或标签组所属的规则组id，只回调给“客户联系”应用 |
当企业客户标签/标签组（包括规则组的标签）被修改时，回调此事件。收到该事件后，企业需要调用获取企业标签库来获取标签/标签组的详细信息。
事件示例：
<xml>
<ToUserName><![CDATA[CORPID]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_tag]]></Event>
<Id><![CDATA[TAG_ID]]></Id>
<TagType><![CDATA[tag]]></TagType>
<ChangeType><![CDATA[update]]></ChangeType>
<StrategyId>1</StrategyId>
</xml>参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_tag |
| Id | 标签或标签组的ID |
| TagType | 变更标签时，此项为tag，变更标签组时，此项为tag_group |
| ChangeType | 此时固定为update |
| StrategyId | 标签或标签组所属的规则组id，只回调给“客户联系”应用 |
当企业客户标签/标签组被删除时，回调此事件。删除标签组时，该标签组下的所有标签将被同时删除，但不会进行回调。
事件示例：
<xml>
<ToUserName><![CDATA[CORPID]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_tag]]></Event>
<Id><![CDATA[TAG_ID]]></Id>
<TagType><![CDATA[tag]]></TagType>
<ChangeType><![CDATA[delete]]></ChangeType>
<StrategyId>1</StrategyId>
</xml>参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_tag |
| Id | 标签或标签组的ID |
| TagType | 删除标签时，此项为tag，删除标签组时，此项为tag_group |
| ChangeType | 此时固定为delete |
| StrategyId | 标签或标签组所属的规则组id，只回调给“客户联系”应用 |
当企业管理员在终端/管理端调整标签顺序时，可能导致标签顺序整体调整重排，引起大部分标签的order值发生变化，此时会回调此事件，收到此事件后企业应尽快全量同步标签的order值，防止后续调用接口排序出现非预期结果。
事件示例：
<xml>
<ToUserName><![CDATA[CORPID]]></ToUserName>
<FromUserName><![CDATA[sys]]></FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[change_external_tag]]></Event>
<Id><![CDATA[TAG_ID]]></Id>
<StrategyId><![CDATA[STRATEGY_ID]]></StrategyId>
<ChangeType><![CDATA[shuffle]]></ChangeType>
</xml>参数说明：
| 参数 | 说明 |
|---|---|
| ToUserName | 企业微信CorpID |
| FromUserName | 此事件该值固定为sys，表示该消息由系统生成 |
| CreateTime | 消息创建时间 （unix时间戳） |
| MsgType | 消息的类型，此时固定为event |
| Event | 事件的类型，此时固定为change_external_tag |
| Id | 标签组的id，表示只有此标签组内的标签发生了重排，如果为空，则表示全部标签组顺序都发生了变化 |
| StrategyId | 规则组id，如果修改了规则组标签的顺序，则回调时会带上此标签所属规则组的id |
| ChangeType | 此时固定为shuffle |
基础连接微信办公基础连接微信办公基础连接微信办公