# 消息接收
为获得企微推送的消息，云 BU 应用需要先在企微中台注册回调地址（API 或界面方式）。然后，消息处理会和上游的消息接收配合按注册信息将企微消息回调给云 BU 应用。
# 回调服务配置
接收事件之前，需要在中台注册回调配置，具体详见 API 章节。其中 token 和 encoding_aes_key 用于消息加密，加密算法与企微保持一致企微消息回调 (opens new window)。
# 回调服务需要实现的功能
# 1. 回调服务需要实现 HTTP POST 请求接收业务数据
假设企业的接收消息的 URL 设置为http://api.3dept.com。当用户触发回调行为时，企业微信会发送回调消息到填写的 URL，请求内容如下：
请求方式： POST
请求地址 ： http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=13500001234&nonce=123412323&corp_id=wx5823bf96d3bd56c7&app_id=39fdda6e-a341-5e67-e243-d4ec9da063b8
接收数据格式 ：
JsDHxnNCKXXpL9wrdtlBTQVS9xDOrQlau4HZCT9Rs3aFvbEUyszc/wi3N0PksapRMOPzSTTucp6jfVncnBy3nVUpny3E9c+MacM9pUGZPSVwYmS1dAw6noBZp6FOcWt4EoNnDhmvZ2sODun4vIAnihlSm2oXKsJYX0tYskliA7oj/lEWRp1B5xIQns2pHAOp7Q6DSsqqzttsum4UCgaaq0IqcDbfDuKRO61zJhpcaZ3M5VQXQAUYqhl4Tx08d/gzgIs/KUfvdCpwf5XtZrTDHfLM+r8LR0x/dJ/aIU6vAvmmlDa5h445BF6y0m+/Lx3Foolqy6pcoFLnP1aNqICOELfc4Y+tblKbHQABlaxxX3WP+mBxqq7oClhUweO8TxVZ8kCaCnTellINSFWfjBeTrMV6VUb1bySscrwhM6Y0aFAffl65qmKbJJ07mUpYclB27mhYoy7M7PWryutMcPvsmKlCmZZt3MdVZ6kHAfC7X7zBqx0rBB2pKEpgSjoJz35KjcAb3uce+mADbyzwukxlN7rCD/aZfnr+AEiBr9616Ek=
使用解密功能解密后，会还原成企微推送的 xml 字符串：
<xml>
<ToUserName>toUser</ToUserName>
<FromUserName>sys</FromUserName>
<CreateTime>1403610513</CreateTime>
<MsgType>event</MsgType>
<Event>change_external_contact</Event>
<ChangeType>add_external_contact</ChangeType>
<UserID>zhangsan></UserID>
<ExternalUserID>woAJ2GCAAAXtWyujaWJHDDGi0mAAAA></ExternalUserID>
<State>teststate></State>
<WelcomeCode>WELCOMECODE></WelcomeCode>
</xml>
xml 里的或个属性与 企微接口中的属性保持一致，具体含义可以查看企微文档。
# 消息处理器开放 API
| API 名称 | 定义 | 说明 |
|---|---|---|
| 注册消息处理器 | 查看 | |
| 更新消息处理器 | 查看 | |
| 删除消息处理器 | 查看 | |
| 通过企微中台应用 id 获取消息处理器 | 查看 | |
| 通过企微中台组织代码获取消息处理器 | 查看 |
# 支持订阅的企微原生事件
| 事件名称 | 事件代码 |
|---|---|
| 标签成员变更事件 | change_contact_update_tag |
| 企业客户标签创建事件 | change_external_tag_create |
| 企业客户标签变更事件 | change_external_tag_update |
| 企业客户标签删除事件 | change_external_tag_delete |
| 客户群创建事件 | change_external_chat_create |
| 客户群变更事件 | change_external_chat_add_member |
| 客户群解散事件 | change_external_chat_dismiss |
| 客户接替失败事件 | change_external_contact_transfer_fail |
| 删除跟进成员事件 | change_external_contact_del_follow_user |
| 外部联系人免验证添加成员事件 | change_external_contact_add_half_external_contact |
| 添加企业客户事件 | change_external_contact_add_external_contact |
| 编辑企业客户事件 | change_external_contact_edit_external_contact |
| 删除企业客户事件 | change_external_contact_del_external_contact |
| 成员关注事件 | subscribe |
| 进入应用 | enter_agent |
| 上报地理位置 | LOCATION |
| 异步任务完成事件推送 | batch_job_result |
| 扫码推事件的事件推送 | scancode_push |
| 扫码推事件且弹出“消息接收中”提示框的事件推送 | scancode_waitmsg |
| 弹出系统拍照发图的事件推送 | pic_sysphoto |
| 弹出拍照或者相册发图的事件推送 | pic_photo_or_album |
| 弹出微信相册发图器的事件推送 | pic_weixin |
| 弹出地理位置选择器的事件推送 | location_select |
| 点击菜单拉取消息的事件推送 | click |
| 点击菜单跳转链接的事件推送 | view |
| 审批状态通知事件 | open_approval_change |
| 任务卡片事件推送 | taskcard_click |
| 共享应用事件回调 | share_agent_change |
| 新增成员事件 | change_contact_create_user |
| 更新成员事件 | change_contact_update_user |
| 删除成员事件 | change_contact_delete_user |
| 新增部门事件 | change_contact_create_party |
| 更新部门事件 | change_contact_update_party |
| 删除部门事件 | change_contact_delete_party |
# 支持订阅的企微中台事件
| 事件名称 | 事件代码 |
|---|---|
| 客户继承状态变更事件 | change_external_contact_transfer_status_change |
| 会话产生事件 | msgaudit_session_created |
| 会话 NLP 分析成功事件 | msgaudit_session_nlp_analysis_success |
| 聊天消息产生事件 | msgaudit_qw_msg_created |
| 新增公费电话记录事件 | change_dial_record_add |
| 更新公费电话记录事件 | change_dial_record_update |
| 渠道码变更事件 | change_channel_code |
| 客户信息变更事件 | change_customer_info_update |
| 客户发起咨询事件 | kf_msg_enter |
| 客户接入人工服务事件 | kf_msg_human_handle |
| 客户聊天消息产生事件 | kf_msg_create |
| 触发记录产生事件 | msgaudit_trigger_record_create |
# 客户继承状态变更事件
客户继承（离职继承、在职继承）所产生的客户接替状态变更事件，企微中台会向接入方推送该事件。
结构示例：
<xml>
<ToUserName>ww3e3e5b8f4aa4fd94</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>change_external_contact</Event>
<ChangeType>transfer_status_change</ChangeType>
<UpdateType>on_job_inherit</UpdateType>
<Status>3</Status>
<TakeoverTime>1648806036</TakeoverTime>
<QwUserIdHandover>godfrey</QwUserIdHandover>
<QwUserIdTakerover>yuzhongjian</QwUserIdTakerover>
<QwExternalUserid>wm-TUtCAAA8MNXcGpHjLExE4MO6F9Jew</QwExternalUserid>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 CorpID |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，此时固定为 change_external_contact |
| ChangeType | string | 此时固定为 transfer_status_change |
| UpdateType | string | 变更分类，quit_inherit-离职继承，on_job_inherit-在职继承 |
| Status | int32 | 接替状态， 1-接替完毕 2-等待接替 3-客户拒绝 4-接替成员客户达到上限 |
| TakeoverTime | int64 | 接替客户的时间，如果是等待接替状态，则为未来的自动接替时间，时间戳 |
| QwUserIdHandover | string | 企业原跟进成员的企微 UserID |
| QwUserIdTakerover | string | 企业接替成员的企微 UserID |
| QwExternalUserid | string | 客户的 userid，注意不是企业成员的帐号 |
# 会话产生事件
注册该事件订阅时需指定 app_id。
示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>msgaudit_session</Event>
<ChangeType>created</ChangeType>
<AppId>xxxxxx</AppId>
<ChatId>xxxxxx</ChatId>
<SessionId>xxxxxx</SessionId>
<AgentId>1000110</AgentId>
<Repair>0</Repair>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，此时固定为 msgaudit_session |
| ChangeType | string | 此时固定为 created |
| AppId | string | 企微中台应用 id |
| ChatId | string | 聊天 id |
| SessionId | string | 产生的会话 id |
| AgentId | string | 企业微信应用 id |
| Repair | int | 是否补数据：0-否，1-是 |
# 会话 NLP 分析成功事件
注册该事件订阅时需指定 app_id。
示例：
<xml>
<ToUserName>xxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>msgaudit_session</Event>
<ChangeType>nlp_analysis_success</ChangeType>
<AppId>xxxxxx</AppId>
<ChatId>xxxxxx</ChatId>
<SessionId>xxxxxx</SessionId>
<AgentId>1000110</AgentId>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，此时固定为 msgaudit_session |
| ChangeType | string | 此时固定为 nlp_analysis_success |
| AppId | string | 企微中台应用 id |
| ChatId | string | 聊天 id |
| SessionId | string | 会话 id |
| AgentId | string | 企业微信应用 id |
# 聊天消息产生事件
不包含 switch 类型消息，不包含机器人发送的、成员相互发送的消息。
示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>msgaudit_qw_msg</Event>
<ChangeType>created</ChangeType>
<ChatId>xxxxxx</ChatId>
<ChatRecordId>xxxxxx</ChatRecordId>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，此时固定为 msgaudit_qw_msg |
| ChangeType | string | 此时固定为 created |
| ChatId | string | 聊天 id |
| ChatRecordId | string | 聊天消息记录 id |
# 公费电话拨打记录变更事件
公费电话拨打记录产生变更时（新增和更新），企微中台会向接入方推送该事件。
结构示例：
<xml>
<Event>change_dial_record</Event>
<ChangeType>change_dial_record_add</ChangeType>
<ToUserName>ww4044a793663ad2da</ToUserName>
<AppId>39fdf3a9-d89f-1fee-82cd-e12d78b15714</AppId>
<DialRecordId>3a05ebb3-a0ab-1d80-9efb-85348da2fc12</DialRecordId>
<CallerId>tianhy</CallerId>
<CallTime>1660215718</CallTime>
<CallType>1</CallType>
<TotalDuration>2</TotalDuration>
<CallerDuration>2</CallerDuration>
<CalleeMsg>
<CalleeId>tianhy</CalleeId>
<CalleeDuration>2</CalleeDuration>
</CalleeMsg>
<FromUserName>ewmp</FromUserName>
<CreateTime>1661845646</CreateTime>
<MsgType>event</MsgType>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| Event | string | 事件的类型，固定为 change_dial_record |
| ChangeType | string | 公费电话新增（change_dial_record_add） + 公费电话更新（change_dial_record_update） |
| ToUserName | string | 企业微信 CorpID |
| AppId | string | 企微中台应用 ID |
| DialRecordId | string | 企微中台公费电话记录唯一 id |
| CallerId | string | 主叫用户的企微成员 ID |
| CallTime | int64 | 主叫用户拨出时间的十位秒级时间戳 |
| CallType | int32 | 通话类型，1-单人通话 2-多人通话 |
| TotalDuration | int64 | 总通话时长，单位/分钟 |
| CallerDuration | int64 | 主叫用户的通话时长，单位/分钟 |
| CalleeMsg | object[] | 被叫用户的通话信息 |
| CalleeMsg[0].CalleeId | string | 企业原跟进成员的企微 UserID |
| CalleeMsg[0].CalleePhone | string | 企业原跟进成员的企微 UserID |
| CalleeMsg[0].CalleeDuration | int64 | 企业原跟进成员的企微 UserID |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台事件消息 |
| CreateTime | string | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
# 渠道码变更事件
渠道码产生变更时（新增、更新、失效、删除），企微中台会向接入方推送该事件。
注意：失效和删除，企微码都会释放不能再扫了，但失效操作后企微中台还能查询到记录，删除操作则不能查询。
结构示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>change_channel</Event>
<MsgType>event</MsgType>
<ChangeType>create</ChangeType>
<ChannelId>xxxxxx</ChannelId>
<EId>xxxxxx</EId>
<AppId>xxxxxx</AppId>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，此时固定为 change_channel |
| ChangeType | string | 变更类型：create-创建、update-更新、delete-删除、disable-失效 |
| ChannelId | string | 渠道码 id |
| EId | string | 中台企业 id |
| AppId | string | 中台应用 id |
# 客户信息更新事件
客户信息产生变更时（更新），企微中台会向接入方推送该事件。
结构示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<CreateTime>1649494800</CreateTime>
<MsgType>event</MsgType>
<Event>change_customer_info</Event>
<ChangeType>update</ChangeType>
<EId>xxxxxx</EId>
<AppId>xxxxxx</AppId>
<UserId>xxxxxx</UserId>
<ExternalUserId>xxxxxx</ExternalUserId>
<AddTag>xxxxxx</AddTag>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，此时固定为 change_customer_info |
| ChangeType | string | 变更类型：create-创建、update-更新、delete-删除、disable-失效 |
| EId | string | 中台企业 id |
| AppId | string | 中台应用 id |
| UserId | string | 员工 id |
| ExternalUserId | string | 外部联系人 id |
| AddTagId | string | 外部联系人添加标签，多个使用英文逗号隔开 |
| RemoveTagId | string | 外部联系人删除标签，多个使用英文逗号隔开 |
# 客户发起咨询事件
客户发起咨询客服时，企微中台会向接入方推送该事件。
结构示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<Event>kf_msg</Event>
<ChangeType>enter</ChangeType>
<AppId>xxxx</AppId>
<MsgType>event</MsgType>
<KefuId>xxx</KefuId>
<ChannelId>xxxxx</ChannelId>
<ChannelType>1</ChannelType>
<QwExternalUserid>xxxx</QwExternalUserid>
<ExtParam>xxxxxx</ExtParam>
<CreateTime>1649494800</CreateTime>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| MsgType | string | 消息的类型，此时固定为 event |
| Event | string | 事件的类型，固定为 kf_msg |
| ChangeType | string | 变更类型：固定为 enter |
| AppId | string | 中台应用 id |
| KefuId | string | 客服账号 id |
| ChannelId | string | 渠道 id |
| ChannelType | int64 | 渠道类型：1-小程序、2-公众号、3-视频号、4-抖音、5-快手、6-其他 |
| QwExternalUserid | string | 外部联系人 id |
| ExtParam | string | 接入方自定义参数，json 字符串（可包含 unionid，手机号，接入方来源等） |
| CreateTime | int64 | 消息创建时间 （时间戳） |
# 客户接入人工服务事件
客户转接人工时，企微中台会向接入方推送该事件。
结构示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<Event>kf_msg</Event>
<ChangeType>human_handle</ChangeType>
<AppId>xxxx</AppId>
<MsgType>event</MsgType>
<ChannelId>xxxxx</ChannelId>
<ChannelType>1</ChannelType>
<KefuId>xxx</KefuId>
<QwExternalUserid>xxxx</QwExternalUserid>
<QwUserId>xxxx</QwUserId>
<ExtParam>xxxxxx</ExtParam>
<CreateTime>1649494800</CreateTime>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| Event | string | 事件的类型，固定为 kf_msg |
| ChangeType | string | 变更类型：固定为 human_handle |
| AppId | string | 中台应用 id |
| MsgType | string | 消息的类型，此时固定为 event |
| ChannelId | string | 渠道 id |
| ChannelType | int64 | 渠道类型：1-小程序、2-公众号、3-视频号、4-抖音、5-快手、6-其他 |
| KefuId | string | 客服账号 id |
| QwExternalUserid | string | 外部联系人 id |
| QwUserId | string | 接待人企微成员 id |
| ExtParam | string | 接入方自定义参数，json 字符串 （可包含 unionid，手机号，接入方来源等） |
| CreateTime | int64 | 消息创建时间 （时间戳） |
# 客服聊天消息产生事件
客户给成员发送消息，成员给客户发送消息时，企微中台会向接入方推送该事件。
结构示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<Event>kf_msg</Event>
<ChangeType>create</ChangeType>
<AppId>xxxx</AppId>
<MsgType>event</MsgType>
<ChannelType>1</ChannelType>
<ChannelId>xxxxx</ChannelId>
<KefuId>xxx</KefuId>
<QwExternalUserid>xxxx</QwExternalUserid>
<QwUserId>xxxx</QwUserId>
<KefuMsgId>xxxx</KefuMsgId>
<SenderType>1</SenderType>
<ExtParam>xxxxxx</ExtParam>
<CreateTime>1649494800</CreateTime>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| Event | string | 事件的类型，固定为 kf_msg |
| ChangeType | string | 变更类型：固定为 create |
| AppId | string | 中台应用 id |
| MsgType | string | 消息的类型，此时固定为 event |
| ChannelId | string | 渠道 id |
| ChannelType | int64 | 渠道类型：1-小程序、2-公众号、3-视频号、4-抖音、5-快手、6-其他 |
| KefuId | string | 客服账号 id |
| QwExternalUserid | string | 外部联系人 id |
| QwUserId | string | 接待人企微成员 id |
| KefuMsgId | string | 客服消息 id |
| SenderType | int64 | 发送人类型：0-未知、1-成员、2-外部联系人、3-机器人 |
| ExtParam | string | 接入方自定义参数，json 字符串（可包含 unionid，手机号，接入方来源等） |
| CreateTime | int64 | 消息创建时间 （时间戳） |
# 触发记录产生事件
注册该事件订阅时需指定 app_id。
示例：
<xml>
<ToUserName>xxxxxxxx</ToUserName>
<FromUserName>ewmp</FromUserName>
<MsgType>event</MsgType>
<Event>msgaudit_trigger_record</Event>
<ChangeType>created</ChangeType>
<CreateTime>1649494800</CreateTime>
<AppId>xxxxxx</AppId>
<TriggerRecordId>xxxxxxxx</TriggerRecordId>
<TriggerRecodeType>xxxxxx</TriggerRecodeType>
</xml>
参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| ToUserName | string | 企业微信 corp_id |
| FromUserName | string | 此事件该值固定为 ewmp，表示该消息由企微中台内部产生 |
| MsgType | string | 消息的类型，此时固定为event |
| Event | string | 事件的类型，此时固定为 msgaudit_trigger_record |
| ChangeType | string | 此时固定为 created |
| CreateTime | int64 | 消息创建时间 （时间戳） |
| AppId | string | 企微中台应用id |
| TriggerRecordId | string | 触发记录id |
| TriggerRecodeType | int32 | 触发记录类型（1-员工 2-客户） |
← 页面插件接入