自定义通知发送插件（`CustomNotificationSender`）

自定义通知发送插件（插件类型 CustomNotificationSender，枚举值 3）是一种用于接管消息模板自定义渠道投递的服务端插件，可在消息通知触发时，把消息内容投递到任意外部系统（如企业微信群机器人、钉钉、飞书、Webhook 等）。

概述

自定义通知发送插件（自定义通知插件 / 通知发送插件 / CustomNotificationSender）属于 ChameleonPlugin 插件体系。消息模板中的每个自定义通知渠道都绑定一个该类型的插件（通过插件 Key 关联），消息触发时服务端会执行插件脚本，由脚本完成实际投递。

与内置通知渠道（系统消息 / 系统待办 / 邮件 / 短信）的边界：内置渠道由平台直接投递，无需插件；自定义渠道的投递方式完全由插件脚本决定，适合对接平台未内置的第三方系统。

tip

插件必须在「插件管理」中启用后才会被消息通知调度；插件被禁用或删除后，引用它的渠道将静默跳过（详见消息模板自定义渠道）。

配置项

在「开发中心 → 系统设置 → 插件」页面点击「添加」创建插件：

配置项	说明
名称	插件显示名称，必填；建议与渠道用途一致，会作为消息模板设置页的渠道选项
类型	必须选择「自定义通知发送（`CustomNotificationSender`）」
Key	插件唯一标识，必填；消息模板通过该 Key 关联渠道，创建后请勿随意修改
描述	插件说明，选填
脚本	C# 脚本，创建后通过「编辑脚本」维护
配置项	Key-Value 列表，选填；会合并进脚本参数 `context.DicParam`，供脚本读取

脚本说明

脚本入口与平台 C# 脚本组件一致，签名固定为 ExecuteAsync(ComponentContext context, ChameleonSDK sdk)。脚本负责完成对第三方系统的实际投递（如调用其 Web API），投递失败可抛出异常记录日志。

基本示例

using System;
using System.Linq;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Chameleon.Common;
using Chameleon.Common.Context;
using Chameleon.Common.Exceptions;
using Chameleon.Common.Models;
using Chameleon.Database;
using Chameleon.SDK;

public class ChameleonCSharpScript
{
    public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk)
    {
        var subject = context.DicParam.TryGetValue("Subject", out var s) ? s : "";
        var content = context.DicParam.TryGetValue("Content", out var c) ? c : "";

        // Deliver the message to a third-party system here
        sdk.Logger.LogInformation($"Sending custom notification: {subject}");

        return null;
    }
}

脚本参数

脚本通过 context.DicParam 获取消息上下文与插件配置：

参数	说明
`Subject`	消息主题（已在服务端完成占位符替换）
`Content`	消息内容（已在服务端完成占位符替换）
`Receiver`	接收人用户 ID
`Link`	消息跳转链接，可能为空
`BizDataId`	业务数据 ID，可能为空
`MetaObjectCode`	对象编码，可能为空
`Scene`	业务场景标识，可能为空
配置项 Key	插件「配置项」中定义的自定义键值；与上述键冲突时以消息上下文为准

context.Param 为原始的 CustomNotificationRequest 对象，可获取完整请求信息。

使用场景

将审批待办推送到企业微信群 / 钉钉群机器人
对接飞书 / 钉钉等第三方 IM 的应用消息接口
调用公司内部消息网关 Webhook
基于插件配置项实现多环境 Webhook 地址区分

下一步

消息模板自定义通知渠道 - 在消息模板中配置并使用该插件
消息模板总览 - 了解消息模板整体结构
插件总览 - 返回插件分类

属性明细

以下内容面向技术实现与 AI 检索。

插件属性表

属性名	类型	含义	取值/存储值
`Name`	string	插件名称	必填
`Type`	string	插件类型	`"CustomNotificationSender"`（枚举 `PluginTypeEnum.CustomNotificationSender = 3`）
`Key`	string	插件唯一标识，消息模板按此关联渠道	必填，同一插件内唯一
`Description`	string	描述	可空
`Version`	string	版本	可空
`Script`	string	C# 脚本全文	必填，入口 `ChameleonCSharpScript.ExecuteAsync(ComponentContext, ChameleonSDK)`
`Config`	string	配置项 JSON	可空，`{"key":"value"}` 字符串，经 `GetConfig()` 反序列化为 `Dictionary<string,string>`
`Enable`	bool	启用状态	`true` 启用 / `false` 禁用；仅启用的插件参与调度

存储示例

存储位置：插件定义（system_chameleonplugin）。

{
  "Name": "企业微信群机器人通知",
  "Type": "CustomNotificationSender",
  "Key": "wecom-bot-sender",
  "Description": "将消息推送到企业微信群机器人",
  "Enable": true,
  "Config": "{\"WebhookUrl\":\"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx\"}",
  "Script": "using System; ... public class ChameleonCSharpScript { public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk) { ... } }"
}

服务端执行逻辑

自定义通知由 NotificationService.SendCustomNotificationAsync（server/Chameleon.Domain/NotificationService.cs）执行，步骤如下：

消息通知触发时，NotificationService.NotifyAsync 将模板 Properties.CustomNotificationChannels 逐项转为 CustomNotificationRequest，并对 Subject / Content 完成占位符替换。
查询所有已启用的 CustomNotificationSender 类型插件，按 Key 建立映射。
对每条消息按 PluginKey 匹配插件；匹配成功后构造参数字典：先写入 Subject/Content/Receiver/Link/BizDataId/MetaObjectCode/Scene，再以 TryAdd 合并插件 Config（请求值优先）。
构造 ComponentContext { DicParam = parameters, Param = item }，通过 C# 脚本引擎执行插件 Script。
全部消息处理完成后，若存在失败则记录错误日志。

异常与校验

场景	行为
`PluginKey` 为空	跳过该条消息，记录 Warning 日志
插件被禁用或已删除	跳过该条消息，记录 Warning 日志，不影响其他渠道
插件脚本执行异常	捕获并计入失败数，最终记录 Error 日志；不影响其他渠道投递

概述​

配置项​

脚本说明​

基本示例​

脚本参数​

使用场景​

下一步​

属性明细​

插件属性表​

存储示例​

服务端执行逻辑​

异常与校验​

相关实现​

概述

配置项