创建模板

域名

https://api.incsapp.com

请求路由

/external/templates/rcs

请求方式

POST

请求头

Content-Type: application/json
certification-code: f484bd42-4a0c-39d....

请求参数

请求参数列表

参数名	类型	必填	描述
name	string	是	模板名称。最大长度 25，只能包含字母数字字符和下划线。例如：test_template
type	string	是	模板类型，必须是text,richcard,carousel中的一种，参考：模板类型说明
content	object	是	模板内容，参考：模板内容（content）说明和请求示例

模板类型说明

支持的模板类型（type）包括：
- 文本消息 (text) - 文本消息模板支持包含建议回复或操作的简单文本消息。文本消息最多可包含 11 个建议项。
- 独立富卡片 (richcard) - 独立富卡片模板允许包含一张富卡片：图片、GIF 或视频，并附带建议回复和操作。该模板中的富卡片最多可包含 4 个建议项。
- 富卡片轮播 (carousel) - 富卡片轮播模板支持包含至少两张富卡片的轮播展示，其中每张卡片均带有建议回复和操作。富卡片轮播模板最多允许展示 10 张卡片，且每张卡片最多可包含 4 个建议项。

创建包含媒体内容的模板时，请参阅媒体指南

模板内容（content）说明和请求示例

1. 文本消息模板（text）

content 参数内容说明：

参数	类型	必填	描述	备注
textMessage	string	是	带有自定义变量的模板消息。自定义变量用方括号 [variable_name] 表示。最大长度 2500。	例如：Dear [name], it is time to grab a big deal.
suggestions	array	否	包含建议相关数据的数组	参考：参考：建议内容（suggestions）说明和示例

请求示例

 {
     "name": "test_template",
     "type": "text",
     "content": {
         "textMessage": "Dear [name], your order [order_id] has been shipped.",
         "suggestions": [
             {
                 "suggestionType": "reply",
                 "text": "Track Order",
                 "postbackData": "track_order_[order_id]"
             },
             {
                 "suggestionType": "url_action",
                 "text": "View Details",
                 "postbackData": "view_details",
                 "url": "https://brand.com/orders/[order_id]"
             }
         ]
     }
 }

2. 富媒体卡片独立模板（richcard）

content 参数内容说明：

参数类型必填描述备注

richCard object 是包含富媒体卡片配置的对象内容见下述richCard 参数内容说明

参数	类型	必填	描述	备注
richCard	object	是	包含富媒体卡片配置的对象	内容见下述richCard 参数内容说明

richCard 参数内容说明：

参数	类型	必填	描述	备注
cardOrientation	string	是	卡片方向：VERTICAL 或 HORIZONTAL
cardHeight	string	是	卡片高度：SHORT 或 MEDIUM（仅当 cardOrientation 为 VERTICAL 时适用）
title	string	否	卡片标题。最大长度 200。
description	string	否	卡片描述。最大长度 2000。
mediaUrl	string	是	媒体文件的公共 URL
thumbnailUrl	string	否	视频缩略图的公共 URL	当媒体为视频时必填
suggestions	array	否	建议数组，最多 4 个	参考：参考：建议内容（suggestions）说明和示例

* 请求示例
  ```json
  {
      "name": "promo_richcard_url",
      "type": "richcard",
      "content": {
          "richCard": {
              "cardOrientation": "VERTICAL",
              "cardHeight": "MEDIUM",
              "title": "Special Offer",
              "description": "Limited time offer!",
              "mediaUrl": "https://cdn.brand.com/images/promo.jpg",
              "suggestions": [
                  {
                      "suggestionType": "reply",
                      "text": "Learn More",
                      "postbackData": "learn_more"
                  }
              ]
          }
      }
  }
  ```

3. 富媒体卡片轮播模板（carousel）

content 参数内容说明：

参数类型必填描述备注

carousel object 是轮播配置对象见下述carousel 参数内容说明

参数	类型	必填	描述	备注
carousel	object	是	轮播配置对象	见下述carousel 参数内容说明

carousel 参数内容说明：

参数	类型	必填	描述	备注
cardWidth	string	是	卡片宽度：SMALL 或 MEDIUM
cardHeight	string	是	卡片高度：SHORT 或 MEDIUM
cards	array	是	卡片数组，最少 2 个，最多 10 个	见下述cards 参数内容说明

cards 参数内容说明：

参数	类型	必填	描述	备注
title	string	否	卡片标题。最大长度 200。
description	string	否	卡片描述。最大长度 2000。
mediaUrl	string	否	媒体 URL
thumbnailUrl	string	否	缩略图 URL	视频时必填
suggestions	array	否	建议数组，每个卡片最多 4 个	参考：建议内容（suggestions）说明和示例

* 请求示例
  ```json
  {
      "name": "product_carousel_url",
      "type": "carousel",
      "content": {
          "carousel": {
              "cardWidth": "MEDIUM",
              "cardHeight": "SHORT",
              "cards": [
                  {
                      "title": "Item 1",
                      "description": "Description for item 1",
                      "mediaUrl": "https://cdn.brand.com/item1.jpg",
                      "suggestions": [
                          {
                              "suggestionType": "reply",
                              "text": "Select",
                              "postbackData": "select_1"
                          }
                      ]
                  },
                  {
                      "title": "Item 2",
                      "description": "Description for item 2",
                      "mediaUrl": "https://cdn.brand.com/item2.jpg",
                      "suggestions": [
                          {
                              "suggestionType": "reply",
                              "text": "Select",
                              "postbackData": "select_2"
                          }
                      ]
                  }
              ]
          }
      }
  }
  ```

建议内容（suggestions）说明和示例

所有建议类型都包含以下通用参数：

参数必填描述备注

suggestionType 是建议类型

text 是建议显示文本。最大长度 25。

postbackData 是回传数据。最大长度 120。

参数	必填	描述
suggestionType	是	建议类型
text	是	建议显示文本。最大长度 25。
postbackData	是	回传数据。最大长度 120。

1. 回复建议

用于简单的快速回复按钮。

{
    "suggestionType": "reply",
    "text": "Yes",
    "postbackData": "user_confirmed_yes"
}

2. URL 动作 - 浏览器

在浏览器中打开 URL。

参数	必填	描述
suggestionType	是	设置为 "url_action"
url	是	要打开的有效公共 URL

{
    "suggestionType": "url_action",
    "text": "Visit Website",
    "postbackData": "visit_website",
    "url": "https://brand.com"
}

3. 拨号动作

拨打电话号码。

参数	必填	描述
suggestionType	是	设置为 "dialer_action"
phoneNumber	是	国际格式的有效电话号码

{
    "suggestionType": "dialer_action",
    "text": "Call Us",
    "postbackData": "call_support",
    "phoneNumber": "+6281234567890"
}

4. 查看位置

在地图中显示特定位置。

参数	必填	描述
suggestionType	是	设置为 "view_location"
latitude	是	纬度
longitude	是	经度
label	否	位置标签

{
    "suggestionType": "view_location",
    "text": "View Store",
    "postbackData": "view_store_location",
    "latitude": -6.2088,
    "longitude": 106.8456,
    "label": "Brand Store Jakarta"
}

5. 查询位置

搜索附近的位置。

参数	必填	描述
suggestionType	是	设置为 "query_location"
query	是	搜索查询字符串

{
    "suggestionType": "query_location",
    "text": "Find Nearby",
    "postbackData": "find_nearby_stores",
    "query": "Brand Store near me"
}

6. 分享位置

请求用户分享其当前位置。

{
    "suggestionType": "share_location",
    "text": "Share Location",
    "postbackData": "user_shared_location"
}

7. 日历事件

在用户日历中创建事件。

参数	必填	描述
suggestionType	是	设置为 "calendar_event"
title	是	事件标题
description	否	事件描述
startTime	是	开始时间（ISO 8601 格式）
endTime	是	结束时间（ISO 8601 格式）

{
    "suggestionType": "calendar_event",
    "text": "Add to Calendar",
    "postbackData": "add_event",
    "title": "Product Launch Event",
    "description": "Join us for the exciting product launch",
    "startTime": "2024-05-01T10:00:00+07:00",
    "endTime": "2024-05-01T12:00:00+07:00"
}

8. URL 动作 - WebView

在应用内 WebView 中打开 URL。

参数	必填	描述
suggestionType	是	设置为 "webview_action"
url	是	要在 WebView 中打开的 URL
viewMode	否	视图模式：FULL、HALF、TALL
description	否	WebView 的可访问性描述

{
    "suggestionType": "webview_action",
    "text": "Open Form",
    "postbackData": "open_webview_form",
    "url": "https://brand.com/form",
    "viewMode": "FULL",
    "description": "Registration form"
}

媒体指南

富媒体卡片和富媒体卡片轮播中的媒体应遵循以下指南。

图片：

消息类型	卡片方向	卡片高度	卡片宽度	图片宽高比	图片最佳分辨率(px)	图片最大文件大小	支持的图片格式
富媒体卡片	VERTICAL	SHORT	-	3:1	1440×480	2MB	JPEG, JPG, PNG, GIF
	VERTICAL	MEDIUM	-	2:1	1440×720
	HORIZONTAL	-	-	3:4	768×1024
轮播	NA	SHORT	SMALL	8:5	1160×720	1MB
		SHORT	MEDIUM	5:2	1840×720
		MEDIUM	SMALL	1:1	770×720
		MEDIUM	MEDIUM	16:9	1280×720

视频和缩略图：

消息类型	卡片方向	卡片高度	卡片宽度	视频最大文件大小	支持的视频格式	缩略图宽高比	缩略图最佳分辨率(px)	缩略图文件大小	支持的缩略图格式
富媒体卡片	VERTICAL	SHORT	-	10MB	MP4, M4V, MPEG, WEBM, H263, M4P	3:1	770×257	最小: 40KB, 最大: 100KB	JPEG, JPG, PNG
	VERTICAL	MEDIUM	-			7:3	770×335
	HORIZONTAL	-	-			25:33	250×330
轮播	NA	SHORT	SMALL	5MB		8:5	718×448
		SHORT	MEDIUM			5:2	1140×448
		MEDIUM	SMALL			1:1	480×448
		MEDIUM	MEDIUM			16:9	796×448

在富媒体卡片消息中使用图片/视频时，请参考 Google 最佳实践（富媒体卡片部分）

响应

成功响应示例

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "template_id": "2217676094281515152",
        "name": "api_5_text",
        "type": "text",
        "status": "PENDING",
        "content": {
            "textMessage": "Dear [name], time to use rcs api",
            "suggestions": [
                {
                    "suggestionType": "reply",
                    "text": "Join us",
                    "postbackData": "click_reply"
                }
            ]
        },
        "created_time": 1767609428,
        "updated_time": 1767609428,
        "status_updated_time": 0
    },
    "error": {}
}

模板状态说明：

获取模板状态请需要回调设置

状态	描述
PENDING	模板正在等待审核
APPROVED	模板已批准，可以使用
REJECTED	模板已被拒绝
DISABLED	模板已被禁用
ENABLED	模板已从禁用或暂停状态重新激活
SUSPENDED	模板已被暂停

失败响应示例

{
    "status": "error",
    "code": 400,
    "message": "type require",
    "data": {},
    "error": {}
}