企业微信外部联系人回调事件

企业微信外部联系人回调事件

说明:

1) 下列"外部联系人" 和 "客户联系" 其实都是一个意思,都是指顾客,但是由于企业微信开发文档中叫"外部联系人",管理后台叫"客户联系", 为方便操作,故本文名称跟企业微信保持一致
2) 下列两段代码实例,默认使用者已经有PHP-SDK, 原生代码案例可以自行前往git下载PHP-SDK(地址见官方文档),ThinkPHP5.*版本案例,可以参考本人下载资源中的PHP-SDK,或者根据官方提供的sdk自行修改命名空间; 由于时间问题,原生代码部分由TP5版本代码修改而成,仅供参考代码,暂未实测; ThinkPHP5.*版本代码亲测有效,有异议欢迎提出讨论

1.作用

		企业成员 添加/删除外部联系人 时,可在企业后台接收添加/删除的外部人数据,及时更新企业后台数据

2.运行原理

	1) 开发者验证回调事件url有效性,验证通过后,可在企业微信管理员后台,配置回调所需的3个参数: 回调事件url, Token , EncodingAESKey
	2) 企业微信管理后台给相关企业成员配置"客户联系"权限
	3) 当企业成员(需要配置客户联系操作权限) 添加/删除外部联系人时,企业微信服务器会向外部联系人回调事件url 推送一段加密字符串(xml格式) ,具体事件格式可参照开发文档, 而且务必保证正确处理数据,

3.开发者操作步骤

	1) 管理后台配置外部联系人回调事件url地址,并验证该url有效性
			A) 先调用调试工具,验证回调事件url有效性,具体参见:
			 ![验证回调事件url的详情图片](https://img-blog.csdnimg.cn/20190221220329870.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2R1cmluZ25vbmU=,size_16,color_FFFFFF,t_70)
			B) 除了A)操作,还需要在该url中,返回解密后的加密消息内容,首先两点;
				a) 调用PHP-SDK中的XMLparse类中的VerifyUrl方法(Verify方法可验证回调事件url); PHP-SDK可下载本人下载资源中的SDK(此SDK根据ThinkPHP5.0进行了命名空间的封装),或者参考企业微信开发文档自行编写
				b) **坑一**: 在回调事件中必须 return 企业微信调试工具发送的Get请求结果(ps:企业微信文档中说的是正确响应,经和其技术沟通,并亲测为使用return关键字即可,示例代码如下:
						$params = $_GET;
						$obj = new XMLparse();
						$callbackRes = $obj->VerifyUrl($params);	//调用SDK中的VerifyUrl方法,返回值为解密后的消息,即步骤A)图中的 "测试消息123"
						return $callbackRes;	// 相当于直接返回明文消息: return	"测试消息123";
					)
				
				c) **坑二**: 验证回调事件url有效性时,即调用verifyUrl方法时,必须先urldecode('echoStr参数'),否则会抛出异常; 若使用原生代码示例,务必自行添加urldecode,若使用框架可自行输出参数查看;(本人使用ThinkPHP5.*框架,ThinkPHp5.*框架中做了urldecode的处理,可以不必开发者手动urldecode;)
			
	2) url通过验证后,添加/删除外部联系人时,会想该url推送指定格式的xml数据(加密字符)
		A)  **坑三**: 接收xml数据时,确保接收的数据事原生的,最好使用 $params = file_get_contents('php://input');	(ps: 本人就是因为在框架配置了htmlspecialchars(html标签过滤函数)这个函数将<>转义了,导致SDK中的DOMDocument类的loadXML方法, 无法读取正确的xml数据,抛出异常,记得将数据恢复成xml格式数据,若使用了htmlspecialchars,记得htmlspecialchars_decode一次)
		B)  **坑四**: 因为涉及的字符串长度过长(400~750个字节),使用var_dump,echo,print_r均无法正常输出字符内容,建议使用将字符写入文件中(使用函数fopen(),fwrite(),或者file_put_content())
		C)  具体代码过程参见下列两个版本,以ThinkPHP5.*版本为准,如有异议,欢迎提出讨论
		
	3) 详情参见企业微信api开发文档,
		A)文档地址:
			https://work.weixin.qq.com/api/doc#90000/90135/90664
		B) 接口调试工具地址: 
			https://work.weixin.qq.com/api/devtools/devtool.php		

3.注意:

	1) 上述有提及四个坑点,请各位开发者多留意 (可结合下列示例代码理解)
	2) 必须先登录企业管理后台(管理员身份),配置回调事件的url相关的参数,并给相关企业成员配置"客户联系"权限

4.PHP原生代码示例 (使用前提,需要先获取SDK)

<?php

class External {
	
    protected $_weworkConfig = [
        'corpId' => '',	//企业ID
    ];	
    protected $_externalCallbackEvent = [	//回调事件参数
        'url'	=> 'http://www.test.com/External/callbackEvent',
        'token' => '',
        'encodingAESKey' => ''
    ];	
    protected $_callbackObj;    // 回调事件对象(外部联系人添加/删除)
	
    protected $_callbackErrorMsgArr = [	//企业微信(添加/删除外部联系人)回调事件错误码+错误信息
        '0'=> 'success',
        '-40001'=> '签名验证错误',
        '-40002'=> 'xml解析失败',
        '-40003'=> 'sha加密生成签名失败',
        '-40004'=> 'encodingAesKey 非法',
        '-40005'=> 'corpid 校验错误',
        '-40006'=> 'aes 加密失败',
        '-40007'=> 'aes 解密失败',
        '-40008'=> '解密后得到的buffer非法',
        '-40009'=> 'base64加密失败',
        '-40010'=> 'base64解密失败',
        '-40011'=> '生成xml失败',
    ];
    
    public function __construct() {
        # 回调事件对象
        $this->_callbackObj = new \weworkapi\callback\WXBizMsgCrypt($this->_externalCallbackEvent['token'], $this->_externalCallbackEvent['encodingAESKey'], $this->_weworkConfig['corpId']); //企业应用回调, 消息加密/解密类WXBizMsgCrypt
        
    }
	
	/**
     * 验证(添加/删除外部联系人)回调事件url有效性
     */
    public function verifyUrl($data) {
        $params = $_GET;
        $params2 = $_POST;
        $params = array_merge($params,$params2);    // get数据+post数据
        try {
            if (empty($params['msg_signature'])) {
                throw new \Exception('msg_signature不得为空');
            }
            if (empty($params['timestamp'])) {
                throw new \Exception('timestamp