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中的一种，参考： 模板类型说明 category string 是 模板类别. 参考： 模板类型说明 content object 是 模板内容，参考： 模板内容（content）说明和请求示例 模板类型（type）说明 支持的模板类型（type）包括： 文本消息 (text) - 文本消息模板支持包含建议回复或操作的简单文本消息。文本消息最多可包含 11 个建议项。 独立富卡片 (richcard) - 独立富卡片模板允许包含一张富卡片：图片、GIF 或视频，并附带建议回复和操作。该模板中的富卡片最多可包含 4 个建议项。 富卡片轮播 (carousel) - 富卡片轮播模板支持包含至少两张富卡片的轮播展示，其中每张卡片均带有建议回复和操作。富卡片轮播模板最多允许展示 10 张卡片，且每张卡片最多可包含 4 个建议项。 创建包含媒体内容的模板时，请参阅 媒体指南 模板类别（category）说明 对于 multi-use agents 必填。 允许的值: PROMOTION – promotional agents 的默认值. TRANSACTION – transactional agents 的默认值. AUTHENTICATION – OTP agents 的默认值. 模板内容（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", "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）说明和示例 请求示例 { "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）说明和示例 请求示例 { "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" } ] } ] } } 建议内容（suggestions）说明和示例 所有建议类型都包含以下通用参数： 参数 必填 描述 备注 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 是 开始时间（YYYY-MM-DD HH:mm:ss 格式） endTime 是 结束时间（YYYY-MM-DD HH:mm:ss 格式） { "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 的可访问性描述 { "suggestionType": "url_action", "text": "Open Form", "postbackData": "open_webview_form", "application": "WEBVIEW", "url": "https://brand.com/form", "webviewViewMode": "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": {} } 删除模板 域名 https://api.incsapp.com 请求路由 /external/templates/rcs/{template_id} 请求方式 DELETE 请求头 certification-code: f484bd42-4a0c-39d.... 请求参数 无 响应 成功响应示例 { "status": "success", "code": 200, "message": "", "data": {}, "error": {} } 失败响应示例 { "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.... 请求参数 无 响应 成功响应示例 { "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": {} } 失败响应示例 { "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条 响应 成功响应示例 { "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": {} }