Template Creation

Request

API domain

Domain

https://api.incsapp.com

Request

API route

Route

/external/templates/rcs

Request method

Method

POST

Request headers

Headers

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

Request parameters

Parameters

Parameter	Type	Mandatory	Description	Remarks
name	string	Yes	Template name. Max length 25 and should contain only alphanumeric chars, underscore.	e.g: test_template
type	string	Yes	Template type. Must be one of text, richcard, or carousel. See: Template Type.	e.g: text
category	string	Yes	Categorization of message content. See: Template Category	e.g: TRANSACTION
content	object	Yes	Template content. See: Template Content

Template Type

Supported types of templates are:

Text Message - The Text Message template supports simple text messages with suggested replies or actions. Text messages can contain up to 11 suggestions.
Rich Card standalone - The Rich Card Stand-alone template allows for the inclusion of a rich card: image, gif or video along with suggested replies and actions. A maximum of 4 suggestions can be included with the rich card in this template.
Rich Card carousel - The Rich Card Carousel template supports carousels with a minimum of two rich cards, with each featuring suggested replies and actions. the Rich Card Carousel template allows you to present up to 10 cards in the carousel with each card having up to 4 suggestions.

Template Category

Mandatory for multi-use agents. Allowed values:

PROMOTION – default for promotional agents.
TRANSACTION – default for transactional agents.
AUTHENTICATION – default for OTP agents.

Template Content

1. Text Message Template (text)

content payload

Parameter	Type	Mandatory	Description	Remarks
textMessage	string	Yes	Template message with custom variables. Custom variables are mentioned in square brackets [variable_name]. Max length 2500.	e.g: Dear [name], it is time to grab a big deal.
suggestions	array	No	Object with suggestions related data. See: Suggestion Types

Sample Request

      {
          "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. Rich Card Standalone (richcard)

content payload

Parameter	Type	Mandatory	Description	Remarks
orientation	string	Yes	Card orientation (VERTICAL/HORIZONTAL)	e.g VERTICAL
alignment	string	No	In case of HORIZONTAL orientation alignment should be (LEFT,RIGHT)	e.g: LEFT
height	string	No	Applicable only for VERTICAL orientation.Card Height (SHORT,MEDIUM)	e.g MEDIUM
standaloneCard	object	Yes	Rich card Object with below details

standaloneCard details

Parameter	Type	Mandatory	Description	Remarks
cardTitle	string	Yes	Card title. Max length 200 including variables if any.
cardDescription	string	No	Card description. Max length 2000 including variables if any.
mediaUrl	string	Yes	Valid publicly accessible URL. Max length 2048. Custom variables are allowed post domain/public IP only. Refer Media guidelines for accepted size/aspect ratio	Eg. https://brand.com/final.mp4 Eg. https://brand.com/[media]
thumbnailUrl	string	No	Valid publicly accessible URL.Custom variables are not allowed. Max length 2048.	Eg. https://brand.com/final.jpeg
suggestions	array	No	Object with suggestions related data	See: Suggestion Types

Sample Request

      {
          "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. Rich Card Carousel (carousel)

content payload

Parameter	Type	Mandatory	Description	Remarks
width	string	Yes	Card width (SMALL/MEDIUM)	e.g: SHORT
height	string	Yes	Card height (SHORT/MEDIUM)	e.g: MEDIUM
carouselCard	array	Yes	Carousel List Object with below details

carouselCard details

Parameter	Type	Mandatory	Description	Remarks
cardTitle	string	Yes	Card title. Max length 200 including variables if any.
cardDescription	string	No	Card description. Max length 2000 including variables if any
mediaUrl	string	Yes	Valid publicly accessible URL. Max length 2048. Custom variables are allowed post domain/public IP only. Refer Media guidelines for accepted size/aspect ratio	Eg. https://brand.com/final.mp4 Eg. https://brand.com/[media]
thumbnailUrl	string	No	Valid publicly accessible URL.Custom variables are not allowed. Max length 2048.	Eg. https://brand.com/final.jpeg
suggestions	array	No	Object with suggestions related data	See: Suggestion Types

Sample Request

      {
          "name": "test_carousel",
          "type": "carousel",
          "category": "PROMOTION",
          "content": {
              "height": "SHORT",
              "width": "MEDIUM",
              "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"
                          }
                      ]
                  }
              ]
          }
      }

Suggestion Types

This section is to describe details about different types of suggestions and their formats

The below two fields are common in all suggestions.：

Parameter	Type	Mandatory	Description	Remarks
text	string	Yes	Suggestion text. Max length is 25 including variables if any.
postbackData	string	Yes	Suggestion postback data Max length is 120 including variables if any.

1. Reply suggestion

Suggested replies help users respond to your agent in ways that it can easily respond to. When tapped, sends the text reply back to the agent.

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

2. Suggestion Action

When tapped, initiates the corresponding native action on the device

2.1. Url Action - Browser

The Open URL action lets you guide users to a web page specified by your agent. By default, the web page opens in the user's browser. If a user has a default app configured for the web page, that app will open instead. In that case, the icon on the suggested action button will be the app's icon.

Parameter	Description	Value
suggestionType	url_action	url_action
url	Valid public URL with/without variables	e.g: https://brand.com

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

2.2. Dialer Action

Opens the user's default dialer app with the agent-specified phone number filled in.

Parameter	Description	Value
suggestionType	dialer_action	dialer_action
phoneNumber	Valid Phone Number to dial in International format or custom variable.	e.g: +919702012345 or [dial_number]

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

2.3. View Locatio

Opens the user's default map app and selects the agent-specified location or searches around the user's location given an agent-specified query.

Parameter	Description	Value
suggestionType	view_location	view_location
latitude	Valid latitude within the range -90 to 90	e.g: -34.34555
longitude	Valid latitude within the range -180 to 180	e.g: 12.54654
label	Label to display

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

2.4. Query Location

Opens default maps app on the device and searches the query text around the user location given an agent-specified query. Only supported on Android Messages clients.

Parameter	Description	Value
suggestionType	query_location	query_location
query	Valid location name to search	e.g: Tajmahal

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

Opens the RCS app's location chooser so the user can pick a location to send to the agent.

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

2.6. Calendar Event

Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.

Parameter	Description	Value
suggestionType	calendar_event	calendar_event
title	Tile of the event. Max length 2048.
description	Description of the event. Max length 2048.
startTime	Start time of the event in YYYY-MM-DD HH:mm:ss format in local time zone	e.g: 2024-04-23 10:33:11
endTime	End time of the event in YYYY-MM-DD HH:mm:ss format in local time zone	e.g: 2024-04-23 18:33:11

{
    "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"
}

2.7. Url Action – WebView

The Open URL with webview action loads the specified web page inside the messaging app with the rendering engine of your default browser. This allows the user to interact with the web page without leaving the RBM conversation. If the user's device doesn't support webviews, the web page opens in the user's browser instead.

Parameter	Description	Value
suggestionType	url_action	url_action
application	WEBVIEW	WEBVIEW
webviewViewMode	FULL: The web page takes up the full screen. HALF: The web page takes up half of the screen. TALL: The web page takes up three quarters of the screen.	FULL
url	Valid public URL with/without variables	e.g: https://brand.com
description	Accessbility description for webview.

{
    "suggestionType": "url_action",
    "text": "Open Form",
    "postbackData": "open_webview_form",
    "application": "WEBVIEW",
    "url": "https://brand.com/form",
    "webviewViewMode": "FULL",
    "description": "Registration form"
}

Media guidelines

The media provided in Rich card and Rich card carousel should follow below guidelines.

Image:

Message Type	Card Orientation	Card Height	Card Width	Image Aspect ratio	Image Optimal Resolution(px)	Image Max file size	Accepted Image formats
Rich Card	VERTICAL	SHORT	-	3:1	1440×480	2MB	JPEG, JPG, PNG, GIF
Rich Card	VERTICAL	MEDIUM	-	2:1	1440×720	2MB
Rich Card	HORIZONTAL	-	-	3:4	768×1024	2MB
Carousel	NA	SHORT	SMALL	8:5	1160×720	1MB
Carousel	NA	SHORT	MEDIUM	5:2	1840×720	1MB
Carousel	NA	MEDIUM	SMALL	1:1	770×720	1MB
Carousel	NA	MEDIUM	MEDIUM	16:9	1280×720	1MB

Video & Thumbnail:

Message Type	Card Orientation	Card Height	Card Width	Video Max file size	Video Accepted Formats	THUMBNAIL Aspect ratio	THUMBNAIL Optimal Resolution(px)	THUMBNAIL File Size	THUMBNAIL Accepted Formats
Rich Card	VERTICAL	SHORT	-	10MB	MP4, M4V, MPEG, WEBM, H263, M4P	3:1	770×257	MIN: 40KB MAX: 100KB	JPEG, JPG, PNG
Rich Card	VERTICAL	MEDIUM	-	10MB		7:3	770×335
Rich Card	HORIZONTAL	-	-	10MB		25:33	250×330
Carousel	NA	SHORT	SMALL	5MB		8:5	718×448
Carousel	NA	SHORT	MEDIUM	5MB		5:2	1140×448
Carousel	NA	MEDIUM	SMALL	5MB		1:1	480×448
Carousel	NA	MEDIUM	MEDIUM	5MB		16:9	796×448

Refer to Google best practices(Rich Cards section) while using images/video in rich cards messages.

Response

Template Status

Status	Description
PENDING	Template is pending review.
APPROVED	Template has been approved and is ready to use.
REJECTED	Template has been rejected.
DISABLED	Template has been disabled.
ENABLED	Template has been re-enabled from a DISABLED or SUSPENDED status.
SUSPENDED	Template has been suspended.

Response

Sample Successful Response

{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "template_id": "2217676094281515152",
        "name": "api_5_text",
        "type": "text",
        "category": "PROMOTION",
        "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": {}
}

Sample Error Response

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

Template Creation

Request

API domain

Request

API route

Request method

Method

Request headers

Headers

Request parameters

Parameters

Template Type

Template Category

Template Content

1. Text Message Template (text)

2. Rich Card Standalone (richcard)

3. Rich Card Carousel (carousel)

Suggestion Types

1. Reply suggestion

2. Suggestion Action

2.1. Url Action - Browser

2.2. Dialer Action

2.3. View Locatio

2.4. Query Location

2.5. Share Location

2.6. Calendar Event

2.7. Url Action – WebView

Media guidelines

Image:

Video & Thumbnail:

Response

Template Status

Response

Sample Successful Response

Sample Error Response