CreateRCSTemplate - 创建模板

前提条件

已通过 UpgradeToRCSSignature 接口将文本短信签名升级为 5G 消息签名。

使用说明

模板创建提交后需要审核，审核通过后才可用于消息发送。创建成功后返回的 TemplateCode，可作为 SendRCS 接口和 SendRCSReply 接口的入参发送消息。模板变量规则 TemplateRule 需与模板内容中的变量一一对应。

QPS 限制

本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用将会被限流，这可能会影响您的业务，请合理调用。

TemplateContent 富媒体模板 JSON 结构

当 TemplateFormat 为 RICH_MEDIA 时，TemplateContent 字段存储 JSON 结构，包含 Cards 数组和 Layout 对象。

悬浮菜单格式说明：卡片内嵌菜单 CardMenu 与外层悬浮菜单 TemplateMenu 均遵循同一悬浮菜单格式，即 GSMA RCS 标准的 suggestions 语法。必须以 suggestions 为根字段，值为 reply 或 action 数组，例如{"suggestions":[...]}。

{
  "Cards": [
    {
      "MediaCode": "ASSET_1721932656000a1b2c3",
      "Title": "卡片标题",
      "Description": "卡片描述信息",
      "CardMenu": {
        "suggestions": [
          {
            "reply": {
              "displayText": "查看详情",
              "postback": { "data": "uuid-1" }
            }
          }
        ]
      }
    }
  ],
  "Layout": {
    "CardOrientation": "VERTICAL"
  }
}

字段说明

字段	类型	必填	说明
Cards	Array	是	卡片数组，最多 6 张卡片
Cards[].MediaCode	String	是	素材编码 assetCode，可为常量或变量${mediaVar}，通过 CreateRCSAsset 接口上传素材后获取
Cards[].Title	String	是	卡片标题，不超过 150 Bytes，1 个中文字符占 3 Bytes
Cards[].Description	String	是	卡片描述，不超过 1000 Bytes
Cards[].CardMenu	Object	否	卡片内嵌悬浮菜单，格式为{"suggestions":[...]}，与外层悬浮菜单格式一致，suggestions 个数不超过 4 个。支持 MENU_ANY 全变量，值为${var}且需独占整个字段值
Layout	Object	是	布局配置
Layout.CardOrientation	String	是	卡片方向。取值 VERTICAL 表示垂直单列，HORIZONTAL 表示水平轮播

注意：Card.Height、Layout.CardWidth、Layout.ImageAlignment 由系统自动填充默认值，无需传递。

当 TemplateFormat 为 PLAIN_TEXT 时，TemplateContent 为字符串格式，变量以${变量名}占位，例如尊敬的用户${username}，您的账号${account}今日已达到发送量上限。纯文本模板内容不超过 200 字符。

模板变量类型与使用场景

变量类型	使用位置约束	是否允许拼接常量或其他变量	是否需要白名单	发送时传值内容
ANY	纯文本模板的 TemplateContent，富媒体模板的 Card.Title、Card.Description	允许	不需要	任意文本
MEDIA	富媒体模板的 Card.MediaCode，必须独占整个值	不允许	不需要	素材编码 assetCode
RCS_ANY	富媒体模板的 TemplateContent，必须独占整个值，即 TemplateContent 取值为${var}	不允许	需要	完整的富媒体 JSON 字符串
MENU_ANY	TemplateMenu 或卡片内 CardMenu，必须独占整个值，即 TemplateMenu 取值为${var}	不允许	需要，与模板全变量共享白名单	完整的悬浮菜单 JSON 字符串，含 suggestions 根字段，即{"suggestions":[...]}

约束说明：

• MEDIA、RCS_ANY、MENU_ANY 均为独占型变量，不允许与常量或其他变量拼接，否则创建模板报错 isv.INVALID_PARAMETERS，即变量类型使用不合法。

• 悬浮菜单内部字段如 displayText 不支持卹独设置变量。如需动态菜单内容，请使用 MENU_ANY 全变量，在发送时传入完整菜单 JSON。

创建模板示例

以下示例均通过 CreateRCSTemplate 接口创建模板。创建成功后返回 TemplateCode，可用于后续通过 SendRCS 接口发送消息。

示例 1：单卡片模板，常量素材，无变量

适用场景：素材和文案固定不变，如产品公告、固定通知。

{
  "TemplateName": "产品推荐模板",
  "RelatedSignNames": "阿里云",
  "TemplateType": 1,
  "TemplateFormat": "RICH_MEDIA",
  "TemplateContent": "{\n  \"Cards\": [\n    {\n      \"MediaCode\": \"ASSET_1721932656000a1b2c3\",\n      \"Title\": \"阿里云产品推荐\",\n      \"Description\": \"云服务器 ECS 限时优惠，立即选购！\",\n      \"CardMenu\": {\n        \"suggestions\": [\n          {\n            \"reply\": {\n              \"displayText\": \"了解详情\",\n              \"postback\": {\"data\": \"uuid-detail\"}\n            }\n          },\n          {\n            \"action\": {\n              \"displayText\": \"立即购买\",\n              \"postback\": {\"data\": \"uuid-buy\"},\n              \"urlAction\": {\n                \"openUrl\": {\n                  \"url\": \"https://www.aliyun.com/product/ecs\",\n                  \"application\": \"browser\"\n                }\n              }\n            }\n          }\n        ]\n      }\n    }\n  ],\n  \"Layout\": {\n    \"CardOrientation\": \"VERTICAL\"\n  }\n}",
  "TemplateRule": "{}",
  "TemplateMenu": "{\"suggestions\":[{\"reply\":{\"displayText\":\"返回首页\",\"postback\":{\"data\":\"uuid-home\"}}}]}"
}

示例 2：多卡片轮播模板，含 MEDIA 和 ANY 变量

适用场景：需要动态替换素材和文案，如商品推荐、活动轮播。

{
  "TemplateName": "商品轮播模板",
  "RelatedSignNames": "阿里云",
  "TemplateType": 1,
  "TemplateFormat": "RICH_MEDIA",
  "TemplateContent": "{\n  \"Cards\": [\n    {\n      \"MediaCode\": \"${mediaCode1}\",\n      \"Title\": \"${title1}\",\n      \"Description\": \"${desc1}\"\n    },\n    {\n      \"MediaCode\": \"${mediaCode2}\",\n      \"Title\": \"${title2}\",\n      \"Description\": \"${desc2}\"\n    }\n  ],\n  \"Layout\": {\n    \"CardOrientation\": \"HORIZONTAL\"\n  }\n}",
  "TemplateRule": "{\n  \"mediaCode1\": \"MEDIA\",\n  \"title1\": \"ANY\",\n  \"desc1\": \"ANY\",\n  \"mediaCode2\": \"MEDIA\",\n  \"title2\": \"ANY\",\n  \"desc2\": \"ANY\"\n}",
  "TemplateMenu": ""
}

变量类型说明：MEDIA 类型变量对应素材编码 assetCode，ANY 类型变量对应任意文本。

示例 3：全变量模板，RCS_ANY 模式

适用场景：模板结构完全由发送时决定，灵活度最高。需 PID 在白名单中。

{
  "TemplateName": "全变量富媒体模板",
  "RelatedSignNames": "阿里云",
  "TemplateType": 1,
  "TemplateFormat": "RICH_MEDIA",
  "TemplateContent": "${Content}",
  "TemplateRule": "{\n  \"Content\": \"RCS_ANY\"\n}",
  "TemplateMenu": ""
}

注意：RCS_ANY 变量不允许通过拼接常量或其他变量，必须独占整个 TemplateContent。

示例 4：悬浮菜单全变量模板，MENU_ANY 模式

适用场景：悬浮菜单内容如按钮文字、交互动作、按钮个数等需要在发送时动态指定，如千人千面的回复类交互。需 PID 在白名单中，与模板全变量共享白名单。

{
  "TemplateName": "菜单变量模板",
  "RelatedSignNames": "阿里云",
  "TemplateType": 1,
  "TemplateFormat": "RICH_MEDIA",
  "TemplateContent": "{\n  \"Cards\": [\n    {\n      \"MediaCode\": \"ASSET_1721932656000abc\",\n      \"Title\": \"活动通知\",\n      \"Description\": \"点击查看最新活动\"\n    }\n  ],\n  \"Layout\": {\n    \"CardOrientation\": \"VERTICAL\"\n  }\n}",
  "TemplateRule": "{\n  \"menu\": \"MENU_ANY\"\n}",
  "TemplateMenu": "${menu}"
}

注意：

• MENU_ANY 变量必须独占整个 TemplateMenu 或卡片内 CardMenu 的值，不允许拼接常量或其他变量。

• 如果菜单内容固定、无需动态替换，直接在 TemplateMenu 中传入完整菜单 JSON 即可，参见示例 1，无需使用变量。

示例 5：卡片内嵌多种 Action 的模板

适用场景：卡片内需要多种交互方式，包括快捷回复、打开网页、拨打电话、获取位置。

{
  "TemplateName": "综合服务模板",
  "RelatedSignNames": "阿里云",
  "TemplateType": 1,
  "TemplateFormat": "RICH_MEDIA",
  "TemplateContent": "{\n  \"Cards\": [\n    {\n      \"MediaCode\": \"ASSET_1721932656000abc\",\n      \"Title\": \"服务中心\",\n      \"Description\": \"请选择您需要的服务\",\n      \"CardMenu\": {\n        \"suggestions\": [\n          {\n            \"reply\": {\n              \"displayText\": \"确认订购\",\n              \"postback\": {\"data\": \"uuid-confirm\"}\n            }\n          },\n          {\n            \"action\": {\n              \"displayText\": \"访问官网\",\n              \"postback\": {\"data\": \"uuid-visit\"},\n              \"urlAction\": {\n                \"openUrl\": {\n                  \"url\": \"https://www.aliyun.com\",\n                  \"application\": \"browser\"\n                }\n              }\n            }\n          },\n          {\n            \"action\": {\n              \"displayText\": \"拨打客服\",\n              \"postback\": {\"data\": \"uuid-call\"},\n              \"dialerAction\": {\n                \"dialPhoneNumber\": {\"phoneNumber\": \"+8610086\"}\n              }\n            }\n          },\n          {\n            \"action\": {\n              \"displayText\": \"发送位置\",\n              \"postback\": {\"data\": \"uuid-location\"},\n              \"mapAction\": {\n                \"requestLocationPush\": {}\n              }\n            }\n          }\n        ]\n      }\n    }\n  ],\n  \"Layout\": {\n    \"CardOrientation\": \"VERTICAL\"\n  }\n}",
  "TemplateRule": "{}",
  "TemplateMenu": ""
}

TemplateMenu 悬浮菜单语法说明

悬浮菜单是附加在消息下方的交互按钮组，用户可点击进行快捷回复或触发操作。以下 Action 类型同时适用于外层悬浮菜单 TemplateMenu 和卡片内嵌菜单 CardMenu.suggestions。

结构约束

根对象必须包含 suggestions 字段，缺少该字段属于格式不合规。其值为数组，每一项为 reply 或 action。格式遵循 GSMA RCS 标准的 chatbot suggestions 语法。

约束	说明
根字段	必须为 suggestions
元素类型	每项为 reply 或 action 之一
数量限制	外层悬浮菜单 1~10 个，卡片内嵌菜单不超过 4 个
displayText	每个按钮最多 25 字符

reply 建议回复

用户点击后，向平台发送一条预设的回复消息。

字段	类型	必填	说明
displayText	string	是	按钮显示文字，1~25 字符
postback.data	string	是	回传给平台的业务数据，最长 2000 字符，需全局唯一，建议使用 UUID

action-urlAction 打开网页

字段	类型	必填	说明
displayText	string	是	按钮显示文字，1~25 字符
postback.data	string	是	回传给平台的业务数据
urlAction.openUrl.url	string	是	目标网址，支持 http、https 及 App Deep Link，如 weixin://
urlAction.openUrl.application	string	是	取值 browser 表示系统浏览器，webview 表示应用内嵌浏览器

action-dialerAction 拨打电话

字段	类型	必填	说明
displayText	string	是	按钮显示文字，1~25 字符
postback.data	string	是	回传给平台的业务数据
dialerAction.dialPhoneNumber.phoneNumber	string	是	电话号码，如+8613800138000 或 10086

action-mapAction 获取地理位置

用户点击后请求获取当前位置信息，用户授权后平台回调上行消息携带经纬度。

字段	类型	必填	说明
displayText	string	是	按钮显示文字，1~25 字符
postback.data	string	是	回传给平台的业务数据
mapAction.requestLocationPush	object	是	传入空对象即可，表示请求获取位置

说明：requestLocationPush 与 showLocation 互斥，二者只能选其一。

action-mapAction showLocation 展示地图位置

在地图上展示指定位置。

{
  "action": {
    "displayText": "查看门店位置",
    "postback": { "data": "f7e5b2c4-1a8d-6c6e-dh90-5e6f7a8b9012" },
    "mapAction": {
      "showLocation": {
        "location": {
          "latitude": 30.274,
          "longitude": 120.155,
          "label": "阿里云西溪园区",
          "query": "杭州市余杭区文一西路 969 号"
        },
        "fallbackUrl": "https://maps.example.com/?lat=30.274&lng=120.155"
      }
    }
  }
}

字段	类型	必填	说明
displayText	string	是	按钮显示文字，1~25 字符
postback.data	string	是	回传给平台的业务数据
mapAction.showLocation.location	object	是	位置信息
location.latitude	number	条件必填	纬度，与 query 二选一
location.longitude	number	条件必填	经度，与 query 二选一
location.label	string	否	位置标签
location.query	string	条件必填	地址查询字符串，与 latitude 加 longitude 二选一
mapAction.showLocation.fallbackUrl	string	否	备用 URL，当地图不可用时使用

说明：location 中 latitude 加 longitude 与 query 必须提供其中一种，不能同时为空。

悬浮菜单完整示例

{
  "suggestions": [
    {
      "reply": {
        "displayText": "查看套餐",
        "postback": { "data": "c5d6e7f8-a9b0-1234-c567-890123456789" }
      }
    },
    {
      "action": {
        "displayText": "拨打客服",
        "postback": { "data": "d6e7f8a9-b0c1-2345-d678-901234567890" },
        "dialerAction": {
          "dialPhoneNumber": { "phoneNumber": "10086" }
        }
      }
    },
    {
      "action": {
        "displayText": "访问官网",
        "postback": { "data": "e7f8a9b0-c1d2-3456-e789-012345678901" },
        "urlAction": {
          "openUrl": {
            "url": "https://www.example.com",
            "application": "browser"
          }
        }
      }
    }
  ]
}

用户点击菜单后的上行回执

用户点击悬浮菜单中的某一项时，客户端会向平台回传一条 response 消息，其中包含 reply 或 action 之一，字段内容与下行定义完全对应。平台根据 postback.data 的值执行对应业务逻辑。

{
  "response": {
    "reply": {
      "displayText": "查看套餐",
      "postback": { "data": "c5d6e7f8-a9b0-1234-c567-890123456789" }
    }
  }
}

返回示例

创建成功后返回模板 Code，可用于后续通过 SendRCS 接口发送消息：

{
  "Code": "OK",
  "RequestId": "A90E4451-FED7-49D2-87C8-00700A8C4D0D",
  "Success": true,
  "Data": {
    "TemplateCode": "RCS_SMS_1721932656000xyz"
  }
}