# RCS Templates API

RCS Templates Manage API

# 创建模板

### 域名
* 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中的一种，参考：[**模板类型说明**](#type)
|category|string|是| 模板类别. 参考：[**模板类型说明**](#category)|
|content|object|是|模板内容，参考：[**模板内容（content）说明和请求示例**](#example)

<a id="type"></a>
#### 模板类型（type）说明

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

* **创建包含媒体内容的模板时，请参阅 [媒体指南](#media)**

<a id="category"></a>
#### 模板类别（category）说明
对于 **multi-use agents** 必填。 允许的值: 
* **PROMOTION** – promotional agents 的默认值.
* **TRANSACTION** – transactional agents 的默认值.
* **AUTHENTICATION** – OTP agents 的默认值.

<a id="example"></a>
#### 模板内容（content）说明和请求示例
##### 1. 文本消息模板（text）
   * **content** 参数内容说明：
      | 参数 | 类型 | 必填 | 描述 | 备注 |
      | --- | --- | --- | --- | --- |
      | textMessage | string | 是 | 带有自定义变量的模板消息。自定义变量用方括号 [variable_name] 表示。最大长度 2500。 | 例如：Dear [name], it is time to grab a big deal. |
      | suggestions | array | 否 | 包含建议相关数据的数组 |参考：[建议内容（suggestions）说明和示例](#suggestions) |
     
   * 请求示例

```json
      {
          "name": "test_template",
          "type": "text",
          "category": "PROMOTION",
          "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** 参数内容说明：
      | 参数 | 类型 | 必填 | 描述 | 备注 |
      | --- | --- | --- | --- | --- |
      | orientation | string | 是 | 卡片方向：VERTICAL 或 HORIZONTAL | |
      | alignment | string | 否 | 排列：当 orientation 为 HORIZONTAL 时，排列为：(LEFT, RIGHT) | |
      | height | string |  否 | 卡片高度：SHORT 或 MEDIUM（仅当 cardOrientation 为 VERTICAL 时适用） | |
      | standaloneCard | object | 是 | 包含富媒体卡片配置的对象 |内容见下述**standaloneCard** 参数内容说明 |
   * **standaloneCard** 参数内容说明：
      | 参数 | 类型 | 必填 | 描述 | 备注 |
      | --- | --- | --- | --- | --- |
      | cardTitle | string |  是 | 卡片标题。最大长度 200。 | |
      | cardDescription | string |  否 | 卡片描述。最大长度 2000。 | |
      | mediaUrl | string |  是 | 媒体文件的公共 URL | |
      | thumbnailUrl | string |  否 | 视频缩略图的公共 URL | 当媒体为视频时必填 |
      | suggestions | array |  否 | 建议数组 |参考：[建议内容（suggestions）说明和示例](#suggestions) |
   * 请求示例
```json
      {
          "name": "promo_richcard_url",
          "type": "richcard",
          "category": "PROMOTION",
          "content": {
              "orientation": "VERTICAL",
              "height": "SHORT",
              "standaloneCard": {
                  "cardTitle": "Keep calm & BAT on!",
                  "cardDescription": "Dear [name], time to participate in lucky draw and win prizes",
                  "mediaUrl": "https://brand.com/Ad.mp4",
                  "thumbnailUrl": "https://brand.com/Ad_snap.png",
                  "suggestions": [
                      {
                          "suggestionType": "reply",
                          "text": "Avail offer [offer_name]",
                          "postbackData": "offer_reply"
                      }
                  ]
              }
          }
      }
      
```
##### 3. 富媒体卡片轮播模板（carousel）
   * **content** 参数内容说明：
      | 参数 | 类型 | 必填 | 描述 | 备注 |
      | --- | --- | --- | --- | --- |
      | width | string | 是 | 卡片宽度：SMALL 或 MEDIUM | |
      | height | string |  是 | 卡片高度：SHORT 或 MEDIUM | |
      | carouselCard | array | 是 | 卡片数组，最少 2 个，最多 10 个 |见下述**carouselCard** 参数内容说明 |
   * **carouselCard** 数组对象参数内容说明：
      | 参数 | 类型 | 必填 | 描述 | 备注 |
      | --- | --- | --- | --- | --- |
      | cardTitle | string| 是 | 卡片标题。最大长度 200。 | |
      | cardDescription | string| 否 | 卡片描述。最大长度 2000。 | |
      | mediaUrl | string | 是 | 媒体 URL | |
      | thumbnailUrl | string | 否 | 缩略图 URL | |
      | suggestions | array | 否 | 建议数组，每个卡片最多 4 个 | 参考：[建议内容（suggestions）说明和示例](#suggestions) |

  * 请求示例
```json
      {
          "name": "test_carousel",
          "type": "carousel",
          "content": {
              "height": "SHORT",
              "width": "MEDIUM",
              "category": "PROMOTION",
              "carouselCard": [
                  {
                      "cardTitle": "New watches",
                      "cardDescription": "Dear [name] brand new watches for less price",
                      "mediaUrl": "https://brand.com/media/watches.mp4",
                      "thumbnailUrl": "https://brand.com/media/watches.jpeg",
                      "suggestions": [
                          {
                              "suggestionType": "url_action",
                              "url": "https://brand.com/",
                              "text": "Buy Now at [offer_name]",
                              "postbackData": "shop_url"
                          }
                      ]
                  },
                  {
                      "cardTitle": "New perfumes",
                      "cardDescription": "Dear [name], Choose from brand new perfumes.",
                      "mediaUrl": "https://brand.com/media/[image]",
                      "suggestions": [
                          {
                              "suggestionType": "dialer_action",
                              "phoneNumber": "+919702012345",
                              "text": "Call now to avail[offer_name]",
                              "postbackData": "call_click"
                          }
                      ]
                  }
              ]
          }
      }
```
<a id="suggestions"></a>
#### 建议内容（suggestions）说明和示例
* **所有建议类型都包含以下通用参数：**
  | 参数 | 必填 | 描述 | 备注 |
  | --- | --- | --- | --- |
  | suggestionType | 是 | 建议类型 | |
  | text | 是 | 建议显示文本。最大长度 25。 | |
  | postbackData | 是 | 回传数据。最大长度 120。 | |
##### 1. 回复建议

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

```json
{
    "suggestionType": "reply",
    "text": "Yes",
    "postbackData": "user_confirmed_yes"
}
```
##### 2. URL 动作 - 浏览器

在浏览器中打开 URL。

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

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

##### 3. 拨号动作

拨打电话号码。

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

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

##### 4. 查看位置

在地图中显示特定位置。

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

```json
{
    "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 | 是 | 搜索查询字符串 |

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

##### 6. 分享位置

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

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

##### 7. 日历事件

在用户日历中创建事件。

| 参数 | 必填 | 描述 |
| --- | --- | --- |
| suggestionType | 是 | 设置为 "calendar_event" |
| title | 是 | 事件标题 |
| description | 否 | 事件描述 |
| startTime | 是 | 开始时间（YYYY-MM-DD HH:mm:ss 格式） |
| endTime | 是 | 结束时间（YYYY-MM-DD HH:mm:ss 格式） |

```json
{
    "suggestionType": "calendar_event",
    "text": "Add to Calendar",
    "postbackData": "add_event",
    "title": "Product Launch Event",
    "description": "Join us for the exciting product launch",
    "startTime": "2024-04-23 10:33:11",
    "endTime": "2024-04-23 18:33:11"
}
```

##### 8. URL 动作 - WebView

在应用内 WebView 中打开 URL。

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

```json
{
    "suggestionType": "url_action",
    "text": "Open Form",
    "postbackData": "open_webview_form",
    "application": "WEBVIEW",
    "url": "https://brand.com/form",
    "webviewViewMode": "FULL",
    "description": "Registration form"
}
```
<a id="media"></a>
#### 媒体指南

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

##### 图片：

| 消息类型 | 卡片方向 | 卡片高度 | 卡片宽度 | 图片宽高比 | 图片最佳分辨率(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 最佳实践（富媒体卡片部分）](https://developers.google.com/business-communications/rcs-business-messaging/guides/learn/best-practices)


### 响应
#### 成功响应示例
```json
{
    "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 | 模板已被暂停 |


#### 失败响应示例
```json
{
    "status": "error",
    "code": 400,
    "message": "type require",
    "data": {},
    "error": {}
}
```

# 删除模板

### 域名
* https://api.incsapp.com

### 请求路由
* /external/templates/rcs/{template_id}

### 请求方式
* **DELETE**

### 请求头
* certification-code: f484bd42-4a0c-39d....

### 请求参数
* 无



### 响应
#### 成功响应示例
```json
{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {},
    "error": {}
}
```
#### 失败响应示例
```json
{
    "status": "error",
    "code": 404,
    "message": "The template is not found.",
    "data": {},
    "error": {}
}
```

# 获取模板详情

### 域名
* https://api.incsapp.com

### 请求路由
* /external/templates/rcs/{template_id}

### 请求方式
* **GET**

### 请求头
* certification-code: f484bd42-4a0c-39d....

### 请求参数
* 无



### 响应
#### 成功响应示例

```json
{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "template_id": "2217670951241515121",
        "name": "api_4_standalone_image",
        "type": "richcard",
        "category": "PROMOTION",
        "status": "APPROVED",
        "content": {
            "orientation": "VERTICAL",
            "height": "SHORT",
            "standaloneCard": {
                "cardTitle": "Keep calm & BAT on!",
                "cardDescription": "Dear [name], time to participate in lucky draw and win prizes",
                "mediaUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/videos/6943e9cea07d7.mp4",
                "thumbnailUrl": "",
                "suggestions": [
                    {
                        "suggestionType": "reply",
                        "text": "Avail offer [offer_name]",
                        "postbackData": "offer_reply"
                    }
                ]
            }
        },
        "created_time": 1767095125,
        "updated_time": 1767337727,
        "status_updated_time": 1767337724
    },
    "error": {}
}
```
#### 失败响应示例
```json
{
    "status": "error",
    "code": 400,
    "message": "The template is not found.",
    "data": {},
    "error": {}
}
```

# 获取模板列表

### 域名
* https://api.incsapp.com

### 请求路由
* /external/templates/rcs

### 请求方式
* **GET**

### 请求头
* certification-code: f484bd42-4a0c-39d....

### 请求参数
#### 请求参数列表

|参数名|类型| 必填| 描述|
|-|-|-|-|
|last_id|string|否|上一页的最后一条数据 template_id
|count|int|否|每页数据量，默认10，最大为100条

### 响应
#### 成功响应示例

```json
{
    "status": "success",
    "code": 200,
    "message": "",
    "data": [
        {
            "template_id": "2217670963801515124",
            "name": "api_4_carousel_image",
            "type": "carousel",
            "category": "PROMOTION",
            "status": "APPROVED",
            "content": {
                "height": "SHORT",
                "width": "MEDIUM",
                "carouselCard": [
                    {
                        "cardTitle": "New watches",
                        "cardDescription": "Dear [name] brand new watches for less price",
                        "mediaUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/images/eb9872d5-b1d3-4e97-8c86-75b0495fa8f1.png?x-oss-process=image/crop,w_1200,h_480,g_center",
                        "suggestions": [
                            {
                                "suggestionType": "url_action",
                                "url": "https://www.infin80linx.co.id",
                                "text": "Buy Now at [offer_1]",
                                "postbackData": "shop_url"
                            }
                        ]
                    },
                    {
                        "cardTitle": "New perfumes",
                        "cardDescription": "Dear [name], Choose from brand new perfumes.",
                        "mediaUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/images/eb9872d5-b1d3-4e97-8c86-75b0495fa8f1.png?x-oss-process=image/crop,w_1200,h_480,g_center",
                        "suggestions": [
                            {
                                "suggestionType": "dialer_action",
                                "phoneNumber": "+6281519140200",
                                "text": "Call now",
                                "postbackData": "call_click"
                            }
                        ]
                    }
                ]
            },
            "created_time": 1767096381,
            "updated_time": 1767337736,
            "status_updated_time": 1767337733
        },
        {
            "template_id": "2217670951241515121",
            "name": "api_4_standalone_image",
            "type": "richcard",
            "category": "PROMOTION",
            "status": "APPROVED",
            "content": {
                "orientation": "VERTICAL",
                "height": "SHORT",
                "standaloneCard": {
                    "cardTitle": "Keep calm & BAT on!",
                    "cardDescription": "Dear [name], time to participate in lucky draw and win prizes",
                    "mediaUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/videos/6943e9cea07d7.mp4",
                    "thumbnailUrl": "",
                    "suggestions": [
                        {
                            "suggestionType": "reply",
                            "text": "Avail offer [offer_name]",
                            "postbackData": "offer_reply"
                        }
                    ]
                }
            },
            "created_time": 1767095125,
            "updated_time": 1767337727,
            "status_updated_time": 1767337724
        },
        {
            "template_id": "2217670929841515117",
            "name": "api_3",
            "type": "text",
            "category": "PROMOTION",
            "status": "APPROVED",
            "content": {
                "textMessage": "text template with parameters [name] and suggestions",
                "suggestions": [
                    {
                        "suggestionType": "reply",
                        "text": "Need [service_name]?",
                        "postbackData": "click_reply"
                    },
                    {
                        "suggestionType": "url_action",
                        "url": "https://www.infin80linx.co.id/",
                        "text": "Visit our Website",
                        "postbackData": "url_click"
                    },
                    {
                        "suggestionType": "dialer_action",
                        "phoneNumber": "+6281519236680",
                        "text": "Call Now",
                        "postbackData": "call_now"
                    }
                ]
            },
            "created_time": 1767092985,
            "updated_time": 1767337721,
            "status_updated_time": 1767337718
        }
    ],
    "error": {}
}
```