> ## Documentation Index
> Fetch the complete documentation index at: https://onextel-09023014.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# RCS Templates

> Create RCS message templates and fetch existing templates from the OneXtel Omni platform.

RCS templates are reusable message definitions — text, media, or rich cards — that you submit
for approval and later reference by name (or `templateCode`) when sending messages. This page
covers the two template-management endpoints: **create** and **fetch**.

## Create Template

**apikey** `string` *required*

Your OneXtel API key.

**accept** `string` *required*

Must be `application/json`.

**Endpoint:** `POST https://api.onexaura.com/rcs/templates`

This endpoint accepts a `multipart/form-data` request. Template metadata is passed as a JSON
string in the `data` field, alongside separate form fields for sender profile and media upload.

### cURL

```bash theme={null}
curl --location 'https://api.onexaura.com/rcs/templates' \
--header 'accept: application/json' \
--header 'apikey: <api_key>' \
--form 'data="{
    \"name\": \"<template_name>\",
    \"type\": \"text_message\",
    \"textMessageContent\": \"<template_content>\"
}"' \
--form 'sender_profile_name="<sender_profile_name>"' \
--form 'update_by="<update_by>"' \
--form 'message_type="<message_type>"' \
--form 'multimedia_files=@"<Path of the media>"'
```

### Form fields

**data** `string` *required*

JSON string (see below) describing the template — `name`, `type`, content fields, and
optional `suggestions`.

**sender\_profile\_name** `string` *required*

The RCS sender profile the template belongs to.

**update\_by** `string` *required*

Identifier of the user/system submitting the template.

**message\_type** `string` *required*

RCS template category (e.g. Promotional, Transactional).

**multimedia\_files** `file`

Media file to attach, for template types that include media (image, video, or document).

### Fields inside `data`

**name** `string` *required*

Unique template name. Must be alphanumeric with underscores only.

**type** `string` *required*

Template type. One of `text_message`, `text_message_with_media`, `rich_card`, `carousel`.

**suggestions** `array`

Array of interactive action (button) objects. Optional — can be empty or omitted for basic
text messages.

### Field constraints

> [!NOTE]
>
> These are the technical limits. Templates are also reviewed against content rules — category
> alignment, brand visibility, and a minimum 70% static text ratio. See
> [template guidelines](/guides/rcs-platform/template-guidelines).

Templates are rejected outright if any of these limits is exceeded, so validate before
submitting rather than after.

| Field | Constraint |
| - | - |
| `name` | Max 20 characters. Alphanumeric and underscore (`_`) only |
| `textMessageContent` | Max 2500 characters, **including** variables |
| `cardTitle` | Max 200 characters, including variables |
| `cardDescription` | Max 2000 characters, including variables |
| `displayText` | Max 25 characters, including variables |
| `postback` | Max 120 characters, including variables |
| `phoneNumber` | Must be a valid phone number |
| `url` | Must be a valid URL |
| `mediaUrl`, `thumbnailUrl`, `documentUrl` | Must be publicly accessible |
| Media and document files | Under 100 MB |

> [!WARNING]
>
> Character limits count **variables as written**, not as resolved. A `cardTitle` of
> `Hi [customer_first_name]` costs 24 characters against the 200 limit regardless of what the
> variable expands to — but a `displayText` built the same way can exceed 25 easily.

**Suggestion limits** depend on the template type:

| Template type | Maximum suggestions |
| - | - |
| Text message | 11 |
| Text message with media or PDF | 11 |
| Rich card standalone | 4 |
| Carousel (per card) | 4 |

**File name matching.** When you upload a file rather than supplying a URL, the uploaded file's
name must exactly match the `fileName`, `thumbnailFileName`, or `documentFileName` you declare
in `data`. A mismatch fails the upload. Videos additionally require a `thumbnailFileName`.

### Suggestions object

Each entry in `suggestions` is one interactive button. `suggestionType` determines which other
fields are required.

**suggestionType** `string` *required*

Type of suggestion. Supported values: `reply`, `dialer_action`, `url_action`,
`view_location_latlong`, `view_location_query`, `share_location`, `calendar_event`.

**displayText** `string` *required*

The button text shown to the user.

**postback** `string` *required*

Data sent back to the bot when the user interacts with the suggestion. Used for internal
logic/tracking.

**url** `string`

URL to open when the user taps the suggestion. Required when `suggestionType` is
`url_action`.

**phoneNumber** `string`

Phone number to call when the user taps the suggestion. Required when `suggestionType` is
`dialer_action`.

**label** `string`

Label for the map location (e.g. "Our Store"). Required when `suggestionType` is
`view_location_latlong`.

**latitude** `string`

Latitude coordinate for the map view. Required when `suggestionType` is
`view_location_latlong`.

**longitude** `string`

Longitude coordinate for the map view. Required when `suggestionType` is
`view_location_latlong`.

**query** `string`

The query string to search (e.g. "nearest ATM"). Required when `suggestionType` is
`view_location_query`.

**title** `string`

Title of the calendar event. Required when `suggestionType` is `calendar_event`.

**description** `string`

Description or notes for the calendar event. Required when `suggestionType` is
`calendar_event`.

**startTime** `string`

Event start time, ISO or `yyyy-MM-dd HH:mm:ss` format. Required when `suggestionType` is
`calendar_event`.

**endTime** `string`

Event end time, ISO or `yyyy-MM-dd HH:mm:ss` format. Required when `suggestionType` is
`calendar_event`.

**timeZone** `string`

Time zone of the event (e.g. "Asia/Kolkata"). Required when `suggestionType` is
`calendar_event`.

### Minimum required fields per suggestion type

| Suggestion Type | Minimum Required Fields | Purpose |
| - | - | - |
| `reply` | `suggestionType`, `displayText`, `postback` | Creates quick reply buttons for user response. |
| `dialer_action` | `suggestionType`, `displayText`, `postback`, `phoneNumber` | Opens the phone dialer to call a given number. |
| `url_action` | `suggestionType`, `displayText`, `postback`, `url` | Opens a web URL in the browser. |
| `view_location_latlong` | `suggestionType`, `displayText`, `postback`, `label`, `latitude`, `longitude` | Displays a specific latitude/longitude on the map. |
| `view_location_query` | `suggestionType`, `displayText`, `postback`, `query` | Searches for a location query on the map. |
| `share_location` | `suggestionType`, `displayText`, `postback` | Allows users to share their current location. |
| `calendar_event` | `suggestionType`, `postback`, `title`, `description`, `startTime`, `endTime`, `timeZone` | Adds a calendar event to the user's device. |

> [!NOTE]
>
> Include `displayText` in every suggestion, including `calendar_event`.

### Template type: Text Message

**name** `string` *required*

Unique template name. Alphanumeric with underscores only.

**type** `string` *required*

Always `"text_message"`.

**textMessageContent** `string` *required*

The actual message body. Can include placeholders (e.g. `[name]`, `[otp]`).

```json Text Template theme={null}
{
  "name": "<template_name>",
  "type": "text_message",
  "suggestions": [],
  "textMessageContent": "This is a text message with [custom_param]."
}
```

Suggestion-specific variants of the text template (reply, dialer, URL, location, calendar) all
use the same `type: "text_message"` shape, adding one `suggestions` entry per action:

```json Reply Action theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "postback": "<postback>",
      "displayText": "<display text>",
      "suggestionType": "reply"
    },
    {
      "postback": "<postback>",
      "displayText": "<display text2>",
      "suggestionType": "reply"
    }
  ],
  "textMessageContent": "<text_message_content>"
}
```

```json Dialer Action theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "postback": "<postback>",
      "displayText": "<display text>",
      "phoneNumber": "<phone_number>",
      "suggestionType": "dialer_action"
    }
  ],
  "textMessageContent": "<text_message_content>"
}
```

```json URL Action theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "url": "<url>",
      "postback": "<postback>",
      "displayText": "<display text>",
      "suggestionType": "url_action"
    }
  ],
  "textMessageContent": "<text_message_content>"
}
```

```json View Location theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "label": "<label>",
      "latitude": "<latitude>",
      "longitude": "<longitude>",
      "postback": "<postback>",
      "displayText": "<display text>",
      "suggestionType": "view_location_latlong"
    }
  ],
  "textMessageContent": "<TextMessageContent>"
}
```

```json Location Query theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "query": "<query>",
      "postback": "<postback>",
      "displayText": "<display text>",
      "suggestionType": "view_location_query"
    }
  ],
  "textMessageContent": "<TextMessageContent>"
}
```

```json Share Location theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "postback": "<postback>",
      "displayText": "<display text>",
      "suggestionType": "share_location"
    }
  ],
  "textMessageContent": "<TextMessageContent>"
}
```

```json Calendar Event theme={null}
{
  "name": "<Template_name>",
  "type": "text_message",
  "suggestions": [
    {
      "title": "<title>",
      "endTime": "<endtime>",
      "postback": "<postback>",
      "displayText": "<display text>",
      "timeZone": "<timezone>",
      "startTime": "start_time",
      "description": "<description>",
      "suggestionType": "calendar_event"
    }
  ],
  "textMessageContent": "<TextMessageContent>"
}
```

### Template type: Text Message with Media

**type** `string` *required*

Always `"text_message_with_media"`.

**documentUrl** `string` *required*

URL of the media file to attach. Supported formats usually include images (`.jpg`, `.png`),
videos (`.mp4`), and documents (`.pdf`, `.docx`). The file should be publicly accessible or
hosted via an approved CDN.

**messageOrder** `string` *required*

Determines display order of media and text. Accepted values: `media_at_top` (media displayed
above text) or `text_message_at_top` (text displayed above media).

**textMessageContent** `string` *required*

Message body shown with the media. Supports placeholders like `[custom_param]`.

```json theme={null}
{
  "name": "<Template_name>",
  "type": "text_message_with_media",
  "documentUrl": "<media_url>",
  "messageOrder": "media_at_top",
  "textMessageContent": "<TextMessageContent>"
}
```

### Template type: Rich Card Standalone

**name** `string` *required*

Unique identifier or name for the rich card template.

**type** `string` *required*

Must be `"rich_card"`.

**orientation** `string` *required*

Defines the layout of card components. Supported values: `VERTICAL` or `HORIZONTAL`.

**height** `string` *required*

Card height. Applies to `VERTICAL` orientation only. Supported values: `SHORT_HEIGHT`,
`MEDIUM_HEIGHT`, `TALL_HEIGHT`.

**alignment** `string` *required*

Card alignment. Applies to `HORIZONTAL` orientation only. Supported values: `LEFT` or
`RIGHT`.

**standAlone** `object` *required*

An object that defines media, text, and actions for this single rich card. See fields below.

> [!NOTE]
>
> `height` and `alignment` are mutually exclusive and driven by `orientation` — a `VERTICAL` card
> takes `height`, a `HORIZONTAL` card takes `alignment`. Set `orientation` first.

**Parameters inside `standAlone`:**

**mediaUrl** `string` *required*

Publicly accessible URL to the card's media (image, video, or document).

**fileName** `string`

Name of the file that has been uploaded.

**cardTitle** `string` *required*

Title text shown on the card.

**cardDescription** `string` *required*

Description or message text for the card. Can include placeholders like `[custom_param]`.

**suggestions** `array`

Optional list of interactive buttons (see Suggestions Object above). Can be left empty (`[]`)
if no actions are required.

```json theme={null}
{
  "name": "rich_card_promo",
  "type": "rich_card",
  "height": "SHORT_HEIGHT",
  "standAlone": {
    "mediaUrl": "<document_url>",
    "cardTitle": "<card_title>",
    "suggestions": [],
    "cardDescription": "<card_description>"
  },
  "orientation": "VERTICAL"
}
```

### Template type: Rich Card Carousel

**name** `string` *required*

Template name, e.g. `"richCardCarouselP"`.

**type** `string` *required*

Always `"carousel"`.

**width** `string` *required*

Carousel card width. One of `MEDIUM_WIDTH`, `SMALL_WIDTH`, or `SHORT_WIDTH`.

**height** `string` *required*

Carousel card height. One of `SHORT_HEIGHT`, `MEDIUM_HEIGHT`, or `TALL_HEIGHT`.

**carouselList** `array` *required*

Array of carousel card objects — see fields below.

**templateState** `string`

Template state — `"Create"` or `"Submit"`.

**Parameters inside each `carouselList` entry:**

**mediaUrl** `string` *required*

Image/video URL used in the card.

**fileName** `string`

File name, e.g. `"marketing.png"`.

**cardTitle** `string` *required*

Title of the carousel card, e.g. `"New York Store"`.

**cardDescription** `string` *required*

Description shown below the title, e.g. `"Visit us in NYC and grab exciting deals!"`.

**suggestions** `array`

Array of suggested actions. Can be empty (`[]`).

```json theme={null}
{
  "name": "<Template_name>",
  "type": "carousel",
  "width": "MEDIUM_WIDTH",
  "height": "SHORT_HEIGHT",
  "carouselList": [
    {
      "mediaUrl": "<media_url>",
      "cardTitle": "<card_title>",
      "suggestions": [],
      "cardDescription": "<card_description>"
    },
    {
      "mediaUrl": "<media_url>",
      "cardTitle": "<card_title>",
      "suggestions": [],
      "cardDescription": "<card_description>"
    }
  ]
}
```

***

## Fetch Template

**apikey** `string` *required*

Your OneXtel API key.

**Content-Type** `string` *required*

Must be `application/json`.

**Endpoint:** `POST https://api.onexaura.com/oapi/templates/fetch`

### cURL

```bash theme={null}
curl --location 'https://api.onexaura.com/oapi/templates/fetch' \
--header 'accept: application/json' \
--header 'apikey: <api_key>' \
--header 'Content-Type: application/json' \
--data '{
    "channel": "RCS",
    "senderProfile": "<sender_profile>",
    "messageType": "Promotional",
    "pageNo": 1,
    "limit": 100
}'
```

### Request body

**channel** `string` *required*

Messaging channel. Must be `"RCS"`.

**senderProfile** `string` *required*

RCS sender profile identifier from which templates are fetched.

**messageType** `string` *required*

RCS template category: `Promotional`, `Transactional`, or `OTP`.

**status** `string`

Filters templates based on approval status: `Approved`, `Pending`, or `Rejected`.

**createdDate** `string`

Filters templates by creation timestamp, local datetime format `YYYY-MM-DDTHH:mm:ss`.

**templateName** `string`

RCS template name to filter by.

**pageNo** `integer` *required*

Page number for pagination. Must be a non-negative integer.

**limit** `integer` *required*

Number of records to return per page.

### Sample request

```json theme={null}
{
  "channel": "rcs",
  "senderProfile": "Rcssenderprofile",
  "messageType": "Promotional",
  "status": "approved",
  "createdDate": "2025-06-23 12:02:28",
  "templateName": "jiocarouseltest01",
  "pageNo": 0,
  "limit": 1
}
```

### Response

```json theme={null}
{
  "page_details": {
    "pageNo": 0,
    "limit": 1
  },
  "data": [
    {
      "name": "jiocarouseltest01",
      "type": "carousel",
      "width": "MEDIUM_WIDTH",
      "height": "SHORT_HEIGHT",
      "carouselList": [
        {
          "fileName": "temp.png",
          "mediaUrl": "https://example.com/media/laptop.jpeg",
          "cardTitle": "title - [c1-var1]",
          "suggestions": [
            {
              "postback": "postback - [c1-pd1]",
              "displayText": "text - [c1-s1]",
              "suggestionType": "reply"
            },
            {
              "url": "https://www.onextel.com/",
              "postback": "postback - [c1-pd2]",
              "application": "Webview-Tall",
              "displayText": "url - [c1-s2]",
              "suggestionType": "url_action"
            }
          ],
          "thumbnailUrl": "",
          "cardDescription": "desc - [c1-var2]",
          "thumbnailFileName": ""
        },
        {
          "fileName": "temp.png",
          "mediaUrl": "https://example.com/media/offer.jpeg",
          "cardTitle": "titile - [c2-t2]",
          "suggestions": [
            {
              "postback": "postback - [c2-pd2]",
              "displayText": "suggestion - [c2-s1]",
              "suggestionType": "reply"
            }
          ],
          "thumbnailUrl": "",
          "cardDescription": "desc - [c2-d2]",
          "thumbnailFileName": ""
        }
      ],
      "templateState": "Create",
      "created_on": "2025-08-26T12:27:21.684",
      "updated_on": "2025-08-26T12:31:22.536",
      "status": "Approved",
      "category": "Carousel"
    }
  ]
}
```

**page\_details** `object`

Pagination metadata echoing the requested `pageNo` and `limit`.

**data** `array`

Array of matching template objects. Each object's shape mirrors the create-template payload
for its `type` (`text_message`, `text_message_with_media`, `rich_card`, or `carousel`), plus:

**template metadata fields**

**templateState** `string`

Template state, e.g. `Create`.

**created\_on** `string`

Creation timestamp (ISO 8601).

**updated\_on** `string`

Last update timestamp (ISO 8601).

**status** `string`

Approval status: `Approved`, `Pending`, or `Rejected`.

**category** `string`

Template category, e.g. `Carousel`.

## Next steps

Once a template is `Approved`, reference its name as `templateCode` when sending a message —
see [Send a template message](/api-reference/rcs/send-template-message).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.