# Submit a template for review

### Request
#### API Domain
* https://api.incsapp.com

#### API Route
* /external/templates/rcs

#### Method
* **POST**

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

#### 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](#type). |e.g: text|
|category|string|Yes| Categorization of message content. See: [Template Category](#category) |e.g: TRANSACTION |
|content|object|Yes|Template content. See: [Template Content](#template_content)

<a id="type"></a>
#### 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.

<a id="category"></a>
#### Template Category
**Mandatory for multi-use agents**. Allowed values: 
* **PROMOTION** – default for promotional agents.
* **TRANSACTION** – default for transactional agents.
* **AUTHENTICATION** – default for OTP agents.

<a id="template_content"></a>
#### 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](#suggestions) | |
     
   * Sample Request

```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. 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](#media) 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](#suggestions)  |
   * Sample Request
```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. 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](#media) 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](#suggestions)  |

  * Sample Request
```json
      {
          "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"
                          }
                      ]
                  }
              ]
          }
      }
```
<a id="suggestions"></a>
#### 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.

```json
{
    "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 |

```json
{
    "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] |

```json
{
    "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 |  |

```json
{
    "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  |

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

##### 2.5. Share Location

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

```json
{
    "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 |

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

##### 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. | |

```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>
#### 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.](https://developers.google.com/business-communications/rcs-business-messaging/guides/learn/best-practices)



### 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. |

#### Sample Successful Response
```json
{
    "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
```json
{
    "status": "error",
    "code": 400,
    "message": "type require",
    "data": {},
    "error": {}
}
```