Send an RCS Template Message - OneXtel

Once an RCS template is created and approved (see RCS Templates), send it to a recipient by referencing its templateCode in a Send Message request. This is the same /oapi/send_sms endpoint used for non-template RCS messages — the message is routed by the shape of contentMessage. Endpoint: POST https://api.onexaura.com/oapi/send_sms

string

required

Your OneXtel API key.

string

required

Must be application/json.

cURL

curl --location 'https://api.onexaura.com/oapi/send_sms' \
--header 'apikey: <api_key>' \
--header 'Content-Type: application/json' \
--data '{
    "rcs": [
        {
            "sender": "<sender_bot_id>",
            "recipient": "<recipient_phone_number>",
            "messageType": "Transactional",
            "contentMessage": {
                "templateMessage": {
                    "templateCode": "SP_testing_demo",
                    "customParams": "{\"custom_param1\":\"Namaste\",\"custom_param2\":\"Name\"}"
                }
            },
            "custref1": "",
            "custref2": "",
            "custref3": "",
            "custref4": "",
            "custref5": ""
        }
    ],
    "prefix": "+91"
}'

Request body

array

required

Wrapper array of one or more message objects. Supports up to 500 objects per request (many-to-many use case).

string

Country code prefix applied to recipient numbers (e.g. +91). Optional.

string

Optional campaign identifier for reporting/tracking.

object

Optional object used only if links in the message body need shortening/tracking. See fields below.

Inside each `rcs` message object

string

required

Type of message: Promotional, Transactional, or OTP.

string

required

Recipient phone number, without prefix. Can also be an array to support a one-to-many use case, containing up to 500 numbers in a single request.

string

required

Sender bot ID or sender phone number.

object

required

Holds the message payload. For a template message, this contains a templateMessage object (documented below). contentMessage can alternatively hold text or richCard for non-template messages.

string

Time-to-live for the message (e.g. "1200s"). Only applicable in some transactional messages.

string

Optional absolute expiry timestamp for the message, ISO 8601 (e.g. "2024-10-02T15:01:23Z").

string

Optional custom reference field.

string

Optional custom reference field.

string

Optional custom reference field.

string

Optional custom reference field.

string

Optional custom reference field.

string

Optional custom reference field.

Inside `contentMessage.templateMessage`

string

required

Template identifier, matching the name used when the template was created (e.g. "my_template_otp").

string

A JSON string of key-value pairs replacing the template’s placeholder variables (e.g. [custom_param]). Not required for templates with no placeholders.

Optional `urlShortener` object

integer

1 = enable URL shortening, 0 = disable. Mandatory if URL shortening is required in the message body.

array

Array of URL-shortening definitions. Each entry defines longUrl, senderId/domain, and track_user.

Fields inside each urlDetails entry:

string

required

The original (full) URL you want to shortened. Mandatory if urlShortener.flag is set to 1.

string

The sender ID or bot ID associated with the message (matches your RCS sender). Send this field with the key senderId.

string

The domain used for the shortened URL.

boolean

Whether to enable user-level click tracking (e.g. true or 1). Default: disabled.

string

Optional expiry for the shortened URL.

Examples

Basic template reference

The minimal payload references an approved template by templateCode with no personalization:

{
  "rcs": [
    {
      "messageType": "Transactional/OTP/Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "update_related_temp"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Template with custom parameters

Use customParams to fill placeholders defined in the template’s textMessageContent, cardDescription, etc.:

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "My_template_demo",
          "customParams": "{\"custom_param\":\"John\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91",
  "urlShortener": {
    "flag": 0,
    "urlDetails": [
      {
        "longUrl": "",
        "senderId": "<sender_id>",
        "domain": " ",
        "track_user": 1
      }
    ]
  }
}

Text templates built with a specific action type (reply, dialer, URL, location, calendar) are sent the same way — only templateCode and customParams change to match the template’s placeholders:

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "text_with_reply_temp",
          "customParams": "{\"custom_param\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "text_with_dialertemp",
          "customParams": "{\"custom_param\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_customPa",
          "customParams": "{\"custom_param\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_query",
          "customParams": "{\"custom_param\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "text_shareLoc_temp",
          "customParams": "{\"custom_param\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "calendar_event",
          "customParams": "{\"custom_param\":\"Name\"},{\"custom_param2\":\"Thursday\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Send customParams as one JSON object.

Media template (with custom params or actions)

Templates of type text_message_with_media are sent identically — only templateCode (and optional customParams) differ per action type:

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "media_with_reply"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_dialeractio"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_URL_ACTION"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_LATLONG"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_EWLOC"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "template_SHARELOC"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Rich card standalone template

Promotional

{
  "rcs": [
    {
      "messageType": "Transactional/OTP/Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "rich_card_promo",
          "customParams": "{\"custom_param\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Additional rich-card-standalone action variants follow the same shape with a different templateCode — e.g. rich_card_replyac (reply), richCardDialerAction (dialer), rich_card_URL (URL), rich_card_location (location, also shown with expireTime), LocationQuery (location query), standAloneShLocation (share location), and richCardStandCalend (calendar event).

Rich card carousel template

{
  "rcs": [
    {
      "messageType": "Transactional/OTP/Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "richCardCarouselP"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Only custom parameters:

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "SP_carousel_temp",
          "customParams": "{\"custom_param\":\"Hi\",\"custom_param1\":\"Name\",\"custom_param2\":\"5000\",\"custom_param3\":\"Aug 30\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

With parameters in suggestions:

{
  "rcs": [
    {
      "messageType": "Transactional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "SP_testing_demo",
          "customParams": "{\"custom_param1\":\"Namaste\",\"custom_param2\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Calendar event in a carousel:

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_bot_Id>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "CarouselCalendarEve",
          "customParams": "{\"name\":\"Name\"}"
        }
      },
      "custref1": "",
      "custref2": "",
      "custref3": "",
      "custref4": "",
      "custref5": ""
    }
  ],
  "prefix": "+91"
}

Dynamic query with tracking (URL shortener + TTL)

{
  "rcs": [
    {
      "messageType": "Promotional",
      "recipient": "<recipient_phone_number>",
      "sender": "<sender_phone_number>",
      "contentMessage": {
        "templateMessage": {
          "templateCode": "<template_name>",
          "customParams": "{\"url\":\"<url>\"}"
        },
        "ttl": "10s"
      }
    }
  ],
  "prefix": "+91",
  "urlShortener": {
    "flag": 1
  }
}

Send ttl as a sibling of contentMessage, at the message-object level.

Response

[
  {
    "messageId": "33mXmXf0myfFe7lA1QpPcDJcVaH",
    "code": 200,
    "status": "success"
  }
]

string

Unique identifier for the submitted message. Use it to correlate delivery reports.

integer

Result code. 200 indicates the message was accepted.

string

Result status, e.g. success.