RCS Create Template

POST Method

The Create Template API allows you to create a new RCS template that can be used in sending RCS messages.

Prerequisites

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
To send any RCS messages, you must configure the RCS channel in the Kaleyra platform. To configure the RCS channel in your account, please contact your local Kaleyra representative.

Base URL

https://rcs-api.<pod>.kaleyra.io/v1/<sid>

API Domain and Value

api_domain	Value
IN pod	`https://rcs-api.in.kaleyra.io`
NA pod	`https://rcs-api.na.kaleyra.io`

API Request to Create a Template

To create an RCS template, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/template endpoint with the following request method:

Request Format

The following is the request format to create an RCS template.

curl --location POST 'https://<api_domain>/v1/<sid>/rcs/template'\
--header 'Content-Type: <content_type>' \
--header 'api-key: <api-key>' \
--data-raw '{
    "agent_number": "<agent_number>",
    "template_type": "<template_type>",
    "template_name": "<template_name>",
    "text": "<text>",
    "status": "<status>",
    "contentMessage": {
        "suggestions": [
            {
                "action": {
                    "text": "<text>",
                    "postback_data": "<postback_data>",
                    "shareLocationAction": {}
                }
            },
            {
                "action": {
                    "text": "<text>",
                    "postback_data": "<postback_data>",
                    "dial_action": {
                        "phone_number": "<phone_number>"
                    }
                }
            }
        ]
    }
}

Sample Request Format

The following is the sample request format to create an RCS template:

curl --location POST 'https://rcs-api.in.kaleyra.io/v1/XXXXX6913850XXXX/rcs/template'\
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "agent_number": "116XX2",
    "template_type": "1",
    "template_name": "doc_test_demo",
    "text": "This is autogenerated test message from TATA communication.",
    "status": "CREATED",
    "contentMessage": {
        "suggestions": [
            {
                "action": {
                    "text": "Location",
                    "postback_data": "Location clicked",
                    "shareLocationAction": {}
                }
            },
            {
                "action": {
                    "text": "Contact us",
                    "postback_data": "Contact us clicked",
                    "dial_action": {
                        "phone_number": "+9177XXXXXX77"
                    }
                }
            }
        ]
    }
}

URL Parameters and Headers

The following is the list of parameters and headers to send the outgoing message request:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	XXXXX6913850XXXX	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/JSON	Yes
`api-key`	String	API key generated from kaleyra.io account.	XXXXX3b8497f58a94e84b671aca43XXXX	Yes

The following is the list of attributes to be used in the payload to create an RCS template:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`agent_number`	String	Agent Number of the agent under which template will be created.	116XX2	Yes
`template_type`	String	Type of template. The allowed values are 1, 3, 4, or 5. For more information on Template type, see the Template Type table.	1	Yes
`template_name`	String	Unique template name. A maximum of 20 characters including alphanumeric and underscore is supported. Space is not allowed.	doc_test_demo	Yes
`text`	String	Text message you want to send to the end users. A maximum of 2000 characters is supported.	This is autogenerated test message from TATA communication.	Conditional, when `template_type` is selected as 1.
`status`	String	Display the status of the template. You can view the following statuses: DRAFT (Only for Vi Template) CREATED SUBMITTEDFORAPPROVAL (Only for Vi Template) ACTIVE For more information on template statuses, see the Template Status table.	CREATED	Yes
`contentMessage`	JSON Object	The interactive content of the RCS messages.	See the specific table for details.	No

The following table describes the different attributes used for the <contentMessage> JSON object:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`suggestions`	JSON Object	Suggestion chip list.	See the specific table for details.	No

The following table describes the different attributes used for the <suggestions> JSON object:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`action`	JSON Object	Action item for the Suggestion chip list.	See the specific table for details.	No

The following table describes the different attributes used for the <action> JSON object:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`text`	String	Text message you want to display for the action.	Contact us	No
`postback_data`	String	Information that you want to receive back after an action is completed.	Contact us clicked	No
`shareLocationAction`	String	The action item to share the location in latitude and longitude.	Latitude - 28.6313 Longitude - 77.2073	No
`dial_action`	JSON Object	Dialing action you want to provide to your end users.	See the specific table for details.	No

The following table describes the different attributes used for the <dial_action> JSON object:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`phone_number`	String	Phone number to be added using which end users can contact you.	+9177XXXXXX77	No

Template Type

The following is the detailed description for template types supported by RCS:

Value	Data Type	Type	Required Payload Field	Mandatory?
1	String	Text	`text`	Conditional
3	Object	File	`file`	Conditional
4	Object	Rich Card (Standalone)	`rich_card`	Conditional
5	Object	Rich Card (Carousel)	`rich_card_carousel`	Conditional

Template Status

The following is the detailed description for template statues supported by RCS:

Status	Description	Supported by Region
DRAFT	You can save the template as draft. You can edit the templates in draft stage.	IN
CREATED	You can create the template. After the successful creation, the template is in CREATED status, and you can edit until it becomes ACTIVE, similar to the DRAFT status.	IN and US
SUBMITTEDFORAPPROVAL	After the successful creation, the template is in the status of submitted for approval. In this, status the template is forwarded to the carrier for the approval.	IN
ACTIVE	The template in active status can be used to send traffic in the RCS messages API.	IN and US

Sample Success Response

The following is a sample success response:

{
    "code": "RCS1102",
    "message": "RCS Template created successfully",
    "data": {
        "template_id": "a3XXXX95-aXX2-4XX6-8XXd-e5XXXXXXX14",
        "created_date": 1776231412478,
        "agent_number": "116XX2",
        "template_type": "1",
        "template_name": "doc_test_demo",
        "text": "This is autogenerated test message from TATA communication.",
        "status": "CREATED",
        "template_number": "MNXXXXXXEWDW"
    },
    "error": {}
}

The following is the additional response fields in success response with dynamic variable:

Field name	Type	Description	Example	Mandatory?
`template_id`	string	UUID string for the template.	a3XXXX95-aXX2-4XX6-8XXd-e5XXXXXXX14	Yes
`template_number`	string	Unique identification number for the template.	MMXXXXXXXX36	Yes

Sample Failure Response

The following are sample failure responses:

{
  "code": "RCS1104",
  "message": "RCS Channel is not enabled for this User.",
  "data": [],
  "error": {
    "error_code": "RCS_CHANNEL_DISABLED",
    "error_message": "RCS Channel is not enabled for this User."
  }
}

The following is the list of sample failure responses:

HTTP Status	Code	Message	Error Code	Error Message
405	RCS405	Method not allowed.	`METHOD_NOT_ALLOWED`	Method not allowed.
400	RCS601	RCS Channel is not enabled for this User.	`RCS_CHANNEL_DISABLED`	RCS Channel is not enabled for this User.
400	RCS701	Invalid JSON format passed.	`INVALID_JSON_PAYLOAD`	Invalid JSON format passed.
400	RCS1104	Required fields are missing.	`MISSING_REQUIRED_FIELDS`	Missing required fields: `agent_number`, `template_type`, or `template_name`.
400	RCS1104	Template Type and Value mismatch Error.	`INVALID_FIELD_VALUES`	`text` is required when `template_type` is `1`.
400	RCS1104	Template Type and Value mismatch Error.	`INVALID_FIELD_VALUES`	Invalid `template_type`: 99, Allowed values are: 1, 3, 4, or 5.
400	RCS1104	Maximum Allowed char limit exceeded.	`MAX_CHAR_LIMIT_EXCEEDED`	Field-specific details.
400	RCS1104	Invalid field values are passed.	`FIELD_VALUE_ERROR`	Invalid `template_type`: 99, Allowed values are: 1, 3, 4, or 5.
4xx	RCS1104	RCS Template creation Failed.	`PROV_ERROR`	Upstream error body.
500	RCS502	Internal Gateway Error.	`RCS_CHANNEL_INTERNAL_ERROR`	Internal Gateway Error.

Create Template with Dynamic variables

You can create templates using dynamic variables. When creating the template, dynamic variable shall be marked with the syntax {{variableName}}. When the template is used to send message to any given recipient, the dynamic variables are replaced with the actual values passed in the API call or in the Campaign wizard.

Sample Template with Dynamic Variable

The following is the sample request format to create a template with dynamic variables:

curl --location POST 'https://<api_domain>/v1/<sid>/rcs/template'\
--header 'Content-Type: <content_type>' \
--header 'api-key: <api-key>' \
--data-raw '{
    "agent_number": "<agent_number>",
    "template_type": "<template_type>",
    "template_name": "<template_name>",
    "rich_card_standalone": {
        "card_orientation": "<card_orientation>",
        "thumbnail_image_alignment": "<thumbnail_image_alignment>",
        "content": {
            "title": "<title>",
            "description": "<description>",
            "media": {
                "height": "height",
                "file": {
                    "file_url": "<file_url>",
                    "thumbnail_url": "<thumbnail_url>",
                    "content_description": "<content_description>"
                }
            },
            "suggestions": [
                {
                    "action": {
                        "text": "<text>",
                        "postback_data": "<postback_data>",
                        "open_url_action": {
                            "url": "<url>",
                            "application": "<application>",
                            "webview_view_mode": "webview_view_mode"
                        }
                    }
                }
            ]
        }
    }
}

Sample Success Response with Dynamic Variable

The following is a sample success response with dynamic variable

{
    "code": "RCS1102",
    "message": "RCS Template created successfully",
    "data": {
        "template_id": "d3XXXX08-dXXf-4XXd-9XXf-9dXXXXXXXX65",
        "created_date": 1773244087431,
        "agent_number": "101XX2",
        "template_type": "4",
        "template_name": "doc_test_demo_for_dynamic_varibales",
        "rich_card_standalone": {
            "card_orientation": "VERTICAL",
            "thumbnail_image_alignment": "LEFT",
            "content": {
                "title": "The title is : {{custermername}}",
                "description": "This is a reminder that your electricity bill for Consumer No: {{consumerno}} is due for payment. Bill Amount:{{billamount}} Due Date {{duedate}} Please make the payment on or before the due date to avoid late charges or service disruption\nPay {{paymentLink}}",
                "media": {
                    "height": "SHORT",
                    "file": {
                        "file_url": "https://demo.test.net/1752XXXX3172-TC_Banner_Image.jpg",
                        "thumbnail_url": "https://d2luXXXXf347r.demo.test.net/17XXXXXX53172-TC_Banner_Image.jpg",
                        "content_description": "Electric Bill"
                    }
                },
                "suggestions": [
                    {
                        "action": {
                            "text": "PAY NOW",
                            "postback_data": "PAYMENT",
                            "open_url_action": {
                                "url": "https://demo.test.in/en/homepage-quick-bill-payment/",
                                "application": "WEBVIEW",
                                "webview_view_mode": "FULL"
                            }
                        }
                    }
                ]
            }
        },
        "status": "CREATED",
        "template_number": "MMXXXXXXXX36",
        "placeholders": "[\n  \"custermername\",\n  \"consumerno\",\n  \"billamount\",\n  \"duedate\"\n]"
    },
    "error": {}
}

The following is the additional response fields in success response with dynamic variable:

Field name	Type	Description	Example	Mandatory?
`template_id`	string	UUID string for the template.	d3XXXX08-dXXf-4XXd-9XXf-9dXXXXXXXX65	Yes
`template_number`	string	Unique identification number for the template.	MMXXXXXXXX36	Yes
`placeholders`	string	The string contains the list of dynamic variables.	`{{custermername}}`	Yes

Updated about 3 hours ago