4.消息配置

微信公众平台服务器配置说明

微信公众号的服务器配置

登录到微信公众平台
选择开发->基础配置，即可找到服务器配置，如下图
1. 服务器地址(URL) : 该地址用于接收微信发送过来的消息或者公众号用户在公众号中发送给服务器的消息
2. 令牌(Token) : 用于消息的加密解密
3. 消息加解密秘钥 : 用于消息的加密解密
4. 消息加密方式

小程序的服务器配置

登录微信公众平台
选择开发->开发设置，即可看到消息推送
与公众号不同之处在于小程序可选择数据格式，或者为XML或者为JSON; 而公众号仅支持JSON格式的数据

LazyWeChat的使用

在configure方法中添加如下代码, 该中间件的作用是监听发送到微信服务器URL地址上的消息

app.UseLazyWeChat();

该方法有4个重载方法

    public static IApplicationBuilder UseLazyWeChat(this IApplicationBuilder app)
    {
        Action<WeChatMessager> _onMessageReceived = (message) => { };
        return app.UseLazyWeChat(_onMessageReceived);
    }    
    
    public static IApplicationBuilder UseLazyWeChat(
        this IApplicationBuilder app,
        Action<WeChatMessager> onMessageReceived)
    {
        Type implementation = UtilRepository.GetImplementation(DEFAULTMESSAGEQUEUE);
        return app.UseMiddleware<LazyWeChatMiddleware>(onMessageReceived, implementation);
    }

    public static IApplicationBuilder UseLazyWeChat<T>(this IApplicationBuilder app) where T : IMessageQueue
    {
        Action<WeChatMessager> _onMessageReceived = (message) => { };
        return app.UseLazyWeChat<T>(_onMessageReceived);
    }

    public static IApplicationBuilder UseLazyWeChat<T>(
        this IApplicationBuilder app,
        Action<WeChatMessager> onMessageReceived) where T : IMessageQueue
    {
        return app.UseMiddleware<LazyWeChatMiddleware>(onMessageReceived, typeof(T));
    }

重载方法1 : 不对监听的消息进行任何处理，仅使用默认的消息队列对微信消息进行保存，仅用于配置服务器路径
重载方法2 : 传递一个委托，这个委托中包含了处理你需要对信息进行的操作
重载方法3 : 传递一个IMessageQueue的实现，该接口用于将接受到的消息存储到消息队列中，如下为该接口的默认实现, 即不传递将以如下结构存储message

public class DefaultMessageQueue : IMessageQueue
{
	private ConcurrentQueue<string> queue = new ConcurrentQueue<string>();    
    public async Task<string> Pop()
    {
        var returnObj = "";
        await Task.Run(() =>
        {
            if (queue.TryDequeue(out string workItem))
            {
                returnObj = workItem;
            }
            else
            {
                throw new ArgumentException(nameof(workItem));
            }
        });
        return returnObj;
    }

    public async Task Push(string item)
    {
        await Task.Run(() => queue.Enqueue(item));
    }
}

重载方法4 : 即传递IMessageQueue的实现，又传递操作message的委托

UseLazyWeChat中Action的说明

为公众号被动回复消息

官方文档 : https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Passive_user_reply_message.html

被动回复消息在用户发送消息给公众号之后的48小时之内仅可回复一条，若想回复多条，请调用客服消息回复接口(48小时内单条消息可以回复20次)

备注 : 小程序无法被动回复消息

被动回复文本消息 : 参数为需要回复给用户的文本

app.UseLazyWeChat(msg =>
{
	msg.replyTextMessage("hello world");
});

Action中msg参数类型为 WeChatMessager，

/// <summary>
/// 微信服务的类型(在配置文件中指定)
/// </summary>
public APIType type { get; set; }

/// <summary>
/// HTTP请求类型
/// </summary>
public string method { get; set; }

/// <summary>
/// 微信传递的signature
/// </summary>
public string signature { get; set; }

/// <summary>
/// 微信传递的timestamp
/// </summary>
public string timestamp { get; set; }

/// <summary>
/// 微信传递的nonce
/// </summary>
public string nonce { get; set; }

/// <summary>
/// 微信传递的echostr
/// </summary>
public string echostr { get; set; }

/// <summary>
/// 是否为微信服务器传递的消息
/// </summary>
public bool validation { get; set; }

/// <summary>
/// 消息内容的dynamic形式
/// </summary>
public dynamic messageBody { get; set; }

/// <summary>
/// 消息格式
/// </summary>
public MessageFormat format { get; set; }

/// <summary>
/// 消息内容的文本形式
/// </summary>
public string message;

public enum APIType
{
    OfficialAccount,	//公众号
    MiniProgram,		//小程序
    QY,					//企业微信
}

signature, timestamp, nonce, echostr为微信向公众号或者小程序发送消息的同时发送的附加消息，用于验证消息来源。

validation为根据上面四项验证的结果，true表示消息来源于微信，false表示来源于微信之外的服务器

messageBody为具体的消息内容

message为公众号或小程序服务器发回给微信的消息

备注 : 微信公众号与小程序有不同的加密方式以及不同的数据格式，在LazyWeChat中无需特殊配置，框架已经在内部集成了所有配置

WeChatMessager类中有如下方法用于回复消息

被动回复图片消息 : 参数为回复给客户的图片media_id

app.UseLazyWeChat(msg =>
{
	msg.replyImageMessage("AtzPvqLEZb0DjSNkZtUljQW_LJwqEB9MYL2a-UJab6c");
});

被动回复语音消息 : replyVoiceMessage, 参数为media_id
被动回复视频消息 : replyVideoMessage, 参数为media_id, title, description
被动回复音乐消息 : replyMusicMessage, 参数为media_id, title, description, music_url, hq_music_url
被动回复图文消息 : replyNewsMessage, 参数为media_id, title, description, picurl, url元组的List
将消息传递给微信客服平台 : redirectToKF
将消息传递给指定客户 : redirectToSpecifiedKF, 参数items为需要转发的客服Email列表

事件监听

官方文档 :https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Receiving_event_pushes.html

微信公众号或者小程序会监听很多事件，例如，某位用户关注了公众号、点击了菜单或者扫描了二维码等，在LazyWeChat中可以使用WeChatMessager类中的方法来监听事件，例如想要在用户关注公众号之后推送给用户一段文件

app.UseLazyWeChat(msg =>
{
    msg.onSubscribeEvent((eventKey, ticket) =>
    {
    	msg.replyTextMessage("hello world");
    });
});

如下为目前LazyWeChat可以监听的事件的介绍

关注公众号事件

备注 : 关注公众号事件本身不携带任何参数，但是当用户在未关注公众号的情况下触发扫描二维码事件，即会触发携带参数eventKey和ticket的关注公众号事件

app.UseLazyWeChat(msg =>
{
    msg.onSubscribeEvent((eventKey, ticket) =>
    {
    });
});

取消关注事件

app.UseLazyWeChat(msg =>
{
    msg.onUnsubscribeEvent(() =>
    {
    });
});

二维码扫描事件

备注 : 在用户未关注公众号之前扫描二维码会触发关注公众号事件

app.UseLazyWeChat(msg =>
{
    msg.onScanEvent((eventKey, ticket) =>
    {
    });
});

上报地理位置
- 官方文档 : https://developers.weixin.qq.com/doc/offiaccount/User_Management/Gets_a_users_location.html
- 需开启获取用户地理位置接口，可进入公众号平台开发-接口权限-用户管理中找到

app.UseLazyWeChat(msg =>
{
    msg.onLocationEvent((latitude, longitude, precision) =>
    {
    });
});

点击菜单拉取消息时的事件推送
- 需指定自定义菜单
- 菜单设置完成5分钟后，推送事件生效

app.UseLazyWeChat(msg =>
{    
    msg.onMenuClickEvent((eventKey) =>
    {
    });
});

模板消息发送后的推送事件

app.UseLazyWeChat(msg =>
{    
    msg.onTemplateMessageSentEvent((msgID, status) =>
	{
	});
});

点击菜单跳转链接时的事件推送
- 需指定自定义菜单
- 菜单设置完成5分钟后，推送事件生效

客服消息

备注 : 消息被转发到客服平台之后，用户发送的消息将不会再被推送到公众号或者小程序的服务器地址上

公众号将消息转发至客服平台

微信公众平台客服功能登录 https://mpkf.weixin.qq.com/

官方文档 https://developers.weixin.qq.com/doc/offiaccount/Customer_Service/Forwarding_of_messages_to_service_center.html

登录微信公众平台, 选择"添加功能插件"

选择客服功能后，点击开通

进入客服功能后点击添加客服，按照提示添加即可

public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
    	app.UseDeveloperExceptionPage();
    }
    else
    {
    	app.UseExceptionHandler("/Home/Error");
    }
    app.UseStaticFiles();
    app.UseRouting();

    app.UseAuthorization();

    app.UseLazyWeChat(msg =>
    {
    	msg.redirectToKF();	//将消息转发至客服平台
    });

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

当消息被转到到mpkf.weixin.qq.com中后, 微信服务器会向公众号服务器地址post一条消息，如下

<xml>
    <ToUserName><![CDATA[gh_971898acbead]]></ToUserName>
    <FromUserName><![CDATA[oNDiC0d-r7Su5mYCU-mXFSXuhmtQ]]></FromUserName>
    <CreateTime>1596949057</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[kf_create_session]]></Event>
    <KfAccount><![CDATA[kf2001@xcdaoxiao]]></KfAccount>
    <Encrypt><![CDATA[x8aArU1GWqa8NUw932An7xqeQZSwePmuaQndaO8fTyWIGQ8x4ckHlE2DidffQocDF+1B6jxyweFAvuy0U0tredPDAa8d/f4mwZfg2un/HMh8uR/pU7yomru3s3TC35pFkXmZp9xkU3K3jKb0YFXB6wFv2LjbAWTNgcsr/0Y7//PEh6EyZ0GdeTPRWXkf0/eFDwZFAL4uelXlQ7tY0J0KWY2V5OLxM8Qaxj2Gnsx0kNSpxFc8ynj00Hr6eIwsSKY2O3nn1X9MCmeORuwqx99JPL/Yjpzd8GemEPK/ozhxjjpExLViVVGZlWsA3nFVLQ5iwgkEESQ80pu70tK/+4TihR3eernooM+d6mgyhQ+LxC0rC9HPNYvCszvmMkvEqo/rglvJj/0k7fKZfup8MTMFimo0bTuOWdRs0WX8liWUY93w5EpBQxfiJADmWP4R+UTllgsAGNq/gmOlveKajaB43g==]]></Encrypt>
</xml>

该消息中指定了接入客服的email

可使用如下方法再消息会话结束之后将消息转发到之前指定的客服

app.UseLazyWeChat(msg =>
{
	msg.redirectToSpecifiedKF(new List<string> { "kf2001@xcdaoxiao" });
});

公众号中回复客服消息
- 被动回复消息在客户发送消息之后的48小时被仅可以回复一条消息，但是客户消息却可以回复多条
- 在ConfigureServices方法中添加 services.AddLazyWeChat(), Namspace 为 LazyWeChat.OfficialAccount
```
public void ConfigureServices(IServiceCollection services)
{
    services.AddLazyWeChat();
}
```
- 在需要使用客服消息的地方添加依赖(ILazyMessager)，例如:
  - 在Configure或者Controller中添加 ILazyMessager lazyMessager
```
public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env,
    ILazyMessager lazyMessager)
{
    if (env.IsDevelopment())
    {
    	app.UseDeveloperExceptionPage();
    }
    else
    {
    	app.UseExceptionHandler("/Home/Error");
    }
    app.UseStaticFiles();
    app.UseRouting();
    app.UseAuthorization();

    app.UseLazyWeChat(msg =>
    {
        var message = new WeChatKFTextMessage();
        message.touser = msg.messageBody.FromUserName;
        message.text.content = "hello world";
        lazyMessager.SendKFMessage(message);
    });

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}
```
  - 公众号客服消息类型, 消息参数与说明请参考官方文档 https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Service_Center_messages.html
    - 文本消息 : WeChatKFTextMessage
    - 图片消息 : WeChatKFImageMessage
    - 语音消息 : WeChatKFVoiceMessage
    - 视频消息 : WeChatKFVideoMessage
    - 音乐消息 : WeChatKFMusicMessage
    - 外部图文消息 : WeChatKFExternalNewsMessage
    - 图文消息 : WeChatKFNewsMessage
    - 菜单消息 : WeChatKFMenuMessage
    - 卡券消息 : WeChatKFCardMessage
    - 小程序消息 : WeChatKFMiniMessage

小程序中回复客服消息

在ConfigureServices方法中添加 services.AddLazyMiniProgram(), Namspace 为 LazyWeChat.MiniProgram

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddLazyMiniProgram();
}

在需要使用客服消息的地方添加依赖(ILazyMiniBasic )，例如:
- 在Configure或者Controller中添加 ILazyMiniBasic lazyMiniBasic

public void Configure(IApplicationBuilder app, 
    IWebHostEnvironment env, 
    ILazyMiniBasic lazyMiniBasic)
{
    if (env.IsDevelopment())
    {
    	app.UseDeveloperExceptionPage();
    }
    app.UseStaticFiles();
    app.UseRouting();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
    	endpoints.MapControllers();
    });

    app.UseLazyWeChat(msg =>
    {
        var message = new MiniKFTextMessage();
        message.touser = msg.messageBody.FromUserName;
        message.text.content = "hello world";
        lazyMiniBasic.Send(message);
    });
}

小程序客服消息类型, 消息参数与说明请参考官方文档 https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-message/customerServiceMessage.send.html
- 文本消息 : MiniKFTextMessage
- 图片消息 : MiniKFImageMessage
- 图文链接 : MiniKFLinkMessage
- 小程序卡片 : MiniKFMiniMessage

小程序将消息转发至客服平台

以小程序账号登录微信公众平台后找到功能->客户, 点击添加，按照步骤添加客服

企业微信中的消息配置

通讯录服务器地址配置

企业ID (CorpID) : 登录到企业微信后台，选择"我的企业"，拉倒最下面，便可看到
通过API接口或第三方应用同步通讯录 : 对于添加成员、部门、打标签等操作可以通过API接口中完成

可点击设置接收事件服务器的具体配置，同微信公众平台的服务器配置一样，需要配置通讯录服务器URL地址、Token以及EncodingAESKey，如下图