短信插件开发文档 | DM Hub API 文档

短信插件简介

发布版本：1.88

不同的客户的短信供应商可能都不同，DMHub支持通过插件形式发送短信。您可以通过插件满足系统现有所有功能，比如群发短信，自动流程发送短信，测试发送短信，发送验证码，以及发送明细管理，发送量发送速率管控等等。做到这些您的插件需要提供两个接口： 1.群发短信接口 2.发送验证码接口以及调用DMHub的发送短信回执接口以完成发送状态上报。

安全说明

由于DMHub可能是通过公网访问短信插件的接口，因此需要一定的安全校验。目前插件支持两种安全校验。

1.生成签名： DMHub在请求插件接口时会带有以下parameters

    POST ${url}/sms/batch?appId=${appId}&timestamp=${timestamp}&signature=${signature}

parameters说明

名称	类型	描述	实例
url	String	在短信插件平台中配置的插件服务地址	http://localhost:1234/
appId	String	在短信插件平台中配置的appId	cl001116d62
timestamp	String	当前时间，格式为yyyyMMddHHmmss，时间为UTC时间	20210308131501
signature	String	用于权限校验的签名，计算方法 org.apache.commons.codec.digest.DigestUtils.md5Hex("${appId}${appSecret}${timestamp}")，appSecret是在短信插件平台设置的密钥。插件在验证签名是否正确的同时需要验证timestamp是否过期。	832bf922568fdd7849b4dba6721973ee

2.阿里云api gateway：

该方式只需要在插件平台正确的配置阿里云网关的appKey和appSecret即可。详细请见阿里云网关

插件接口说明

1.群发短信接口

格式

POST ${url}/sms/batch

请求体

DMHub的短信有模版的概念，模版内以客户的属性或身份作为变量，通过模版+属性变量的方式来达到每个人收到的短信都可能不一样的效果。而有些客户认为的敏感信息是不会存储在DMHub 中，比如手机号码、家庭住址等等，而插件可以获取到这些敏感信息。这时候就需要在插件内部组装模版+变量。因此请求体分为两种：

1.当在插件平台勾选了 '在插件内拼装模版和变量'时:

{
 "templateId":5355,
 "templateText":"位于${attr.attr1@10!""}的客户${name@3!""}您好，欢迎体验DMHub！ 回TD退订",
 "batchId":"s5355-4",
 "audienceIdType":"mobile",
 "data":[
     {
         "attr":{
             "attr1@10":"上海市，乐山路"
         },
         "name@3":"Convertlab",
         "_audienceId":"199xxxx6782"
     },
     {
         "attr":{
             "attr1@10":"上海市，龙耀路"
         },
         "name@3":"Convertwork",
         "_audienceId":"133xxxx0592"
     }
  ]
}

参数说明

名称	类型	描述
templateId	Int	短信模版ID
templateText	String	模版内容
batchId	String	发送批次号
audienceIdType	String	触达ID类型，当为客户手机号时为mobile,当为手机号身份时为customerIdentity.mobile，诸如此类
data	List	参数列表
_audienceId	String	触达ID
attr	Map	客户自定义属性
name@3	String	客户姓名

2.未勾选 '在插件内拼装模版和变量'时

 {
  "templateId":5355,
  "templateText":"位于${attr.attr1@10!""}的客户${name@3!""}您好，欢迎体验DMHub！ 回TD退订",
  "batchId":"s5355-4",
  "audienceIdType":"mobile",
  "data":[
      {
          "smsMessage":"上海市，乐山路的客户Convertlab您好，欢迎体验DMHub！ 回TD退订",
          "_audienceId":"199xxxx6782"
      },
      {
          "smsMessage":"上海市，龙耀路的客户Convertwork您好，欢迎体验DMHub！ 回TD退订",
          "_audienceId":"133xxxx0592"
      }
   ]
}

参数说明

名称	类型	描述
templateId	Int	短信模版ID
templateText	String	模版内容
batchId	String	发送批次号
audienceIdType	String	触达ID类型，当为客户手机号时为mobile,当为手机号身份时为customerIdentity.mobile，诸如此类
smsMessage	String	每个客户的发送文本
_audienceId	String	触达ID

接口返回

插件内部发送短信最好是异步发送，通过一些消息组件做到降低接口延迟，提高并行度。

在接口处理成功时需要返回

{"code":"SUCCESS"}

在接口处理失败后需要按照标准错误格式返回，例如：

{"error":{"code":"400001","message":"invalid signature"}}

2.发送验证码接口

格式

POST ${url}/sms/verifyCode

请求体

{"mobile":"199xxxx6782","code":"123456"}

参数说明

名称	类型	描述
mobile	String	手机号码
code	String	验证码

发送状态回执

通常在发送短信时，接口调用成功并不意味着真的发送成功了，很可能由于退订、黑名单、手机关机、不在服务区等等因素导致一批中有部分手机号码发送失败。这时就需要通过状态回执的方式来通知各个号码的发送结果，详见发送短信状态回执。

系统通知

发布版本：2.5

系统通知短信可以支持通过插件发送，实现短信通道的定制。该功能的实现需要开启相应的功能开关。

短信通知接口

格式

POST ${url}/sms/plugin/send

请求体

发送系统通知需要您的插件具备模版类型。通知模版示例、模版类型和对应的变量请下载文件进行查看。模版下载

例如：租户即将到期通知 { "signature": "【Convertlab】" "name": "12", "tenantId": "10113", "dateEnd": "2022-03-10", "smsTemplateType": "TenantExpiring" }

参数说明

名称	类型	描述
signature	String	签名
name	String	租户名称
tenantId	int	租户Id
dateEnd	String	到期时间
smsTemplateType	String	模版类型