Skip to main content
Version: 2.0

Create Template

Overview​

The first message sent by an Enterprise to its customer must be whitelisted on the RCS platform by submitting template details.
There are three types of templates that can be created:

Text Template​

  • Can have a maximum of 2,500 characters.
  • Supports up to 11 interactive buttons, including:
    • Quick Reply
    • Dial a Number
    • Open a URL
    • Location (Lat/Long or Query)
    • Share Location
    • Calendar Event

Rich Card Standalone Template​

  • Includes an image or video, a title, and a description.
  • Supports up to 4 interactive buttons (same types as above).
  • Can include up to 10 Rich Cards.
  • Each card may contain media, title, description, and buttons.
  • API Endpoints: - /v2/rcs/<appId>/templates
  • Authentication: - This API requires Bearer token authentication. See Authentication for more details.
  • Method: - POST
  • Payload: - The payload must be passed in the body as a JSON object. Refer to CreateTemplatePayload

CreateTemplatePayload​

Key Features​

  • name: Unique Name of the template.
  • type: Type of template rich_card, text_message or carousel. See TemplateType for more details.
  • component (union field): See MessageContent for more details.

JSON Representation​

{
  "name": string,
  "type": enum (TemplateType),
  "component": {
    object (MessageContent)
  }
}

See MessageContent and TemplateType for more details.

Field Details​

Field
namestring

Name of the template.

Must be unique. Only lowercase letters, numbers, and underscores are allowed.
Maximum length: 20 characters.
typeenum (TemplateType)

Type of the template.
componentobject (MessageContent)

The content of the message template.

TemplateType​

Enums
text_messagePlain text template.
rich_cardSingle rich card template.
carouselCarousel of rich cards.

TemplateStatus​

Enums
approvedTemplate is approved.
pendingTemplate approval is pending.
rejectedTemplate is rejected.
expiredTemplate is expired.

MessageContent​

Depending on the type field, this object represents one of the following:

PlainText​

JSON Representation​

{
  "text": string,
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}

See Suggestion for more details.

Fields​

Field
textstring

Text encoded in UTF-8. Maximum 3072 characters.
suggestions[]object (Suggestion)

A list of suggested replies and suggested actions that appear as a list of suggestion chips following the associated agent message. Maximum 11 suggestions.

The chips only display when the associated agent message is the most recent message within the conversation (including both agent and user messages). The user can tap a suggested reply to send the text reply back to the agent or tap a suggested action to initiate a native action on the device. Maximum 11 suggestions.

Code Samples​

curl -X POST "https://api.aclwhatsapp.com/access-api/v2/rcs/<APP_ID>/templates" 
-H "Authorization: Bearer <YOUR_TOKEN>" 
-H "Content-Type: application/json" 
-d '{
    "name": "text_message_example",
    "type": "text_message",
    "component": {
        "text": "Hi [custom_param1b], \n This is a test template for testing [custom_param2b]. \n Thanks",
        "suggestions": [
            {
                "reply": {
                    "text": "Sug Butn Reply 1",
                    "postbackData": "text_message_example"
                }
            },
            {
                "action": {
                    "text": "Sug Butn DaN 2",
                    "postbackData": "text_message_example",
                    "dialAction": {
                        "phoneNumber": "+918010921481"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn OaU 3",
                    "postbackData": "text_message_example",
                    "openUrlAction": {
                        "url": "https://sinch.com/[custom_param1u]",
                        "application": "BROWSER"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn OaU 4",
                    "postbackData": "text_message_example",
                    "openUrlAction": {
                        "url": "https://sinch.com/[custom_param2u]",
                        "application": "WEBVIEW",
                        "webviewViewMode": "FULL",
                        "description": "This is a variation"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn OaU 5",
                    "postbackData": "text_message_example",
                    "openUrlAction": {
                        "url": "https://sinch.com/[custom_param3u]",
                        "application": "WEBVIEW",
                        "webviewViewMode": "HALF",
                        "description": "This is a variation"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn OaU 6",
                    "postbackData": "text_message_example",
                    "openUrlAction": {
                        "url": "https://sinch.com/[custom_param4u]",
                        "application": "WEBVIEW",
                        "webviewViewMode": "TALL",
                        "description": "This is a variation"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn VLLL 7",
                    "postbackData": "text_message_example",
                    "viewLocationAction": {
                        "latLong": {
                            "latitude": "33.22",
                            "longitude": "24.24"
                        },
                        "label": "Noida, Sector 132"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn VLQ 8",
                    "postbackData": "text_message_example",
                    "viewLocationAction": {
                        "query": "Share your Location"
                    }
                }
            },
            {
                "action": {
                    "text": "Sug Butn SL 9 Noida",
                    "postbackData": "text_message_example",
                    "shareLocationAction": {}
                }
            },
            {
                "action": {
                    "text": "Sug Butn CCE 10",
                    "postbackData": "text_message_example",
                    "createCalendarEventAction": {
                        "description": "Test Event Description",
                        "startTime": "2025-08-14T06:30:00Z",
                        "endTime": "2025-08-14T06:30:00Z",
                        "title": "Test Event Title"
                    }
                }
            },
            {
                "reply": {
                    "text": "Sug Butn Reply 11",
                    "postbackData": "text_message_example"
                }
            }
        ]
    }
}'

RichCard​

RichCardStandAlone​

JSON Representation​

{
  "richCard": {
    "standaloneCard" : {
      "cardOrientation": enum (CardOrientation),
      "thumbnailImageAlignment": enum (ThumbnailImageAlignment),
      "cardContent": {
        object (CardContent)
      }
    }
  }
}

See CardOrientation, ThumbnailImageAlignment and CardContent for more details.

Fields​

Field
richCard.standaloneCardobject

Standalone card.
richCard.standaloneCard.cardOrientationenum (CardOrientation)

Orientation of the card.
richCard.standaloneCard.thumbnailImageAlignmentenum (ThumbnailImageAlignment)

Image preview alignment for standalone cards with horizontal layout.
richCard.standaloneCard.cardContentobject (CardContent)

Card content.

CardOrientation​

Enums
HORIZONTALHorizontal layout.

If a horizontal rich card's object(CardContent) contains the media field, it must also include at least a title, description, or suggestions[] field.
VERTICALVertical layout.

ThumbnailImageAlignment​

Enums
LEFTFile preview is left-aligned.
RIGHTFile preview is right-aligned.

CardContent​

JSON Representation​
{
  "title": string,
  "description": string,
  "media": {
    "height": enum (MediaHeight),
    "contentInfo": {
      "fileUrl": string,
      "thumbnailUrl": string,
      "forceRefresh": boolean
    }
  },
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}

See MediaHeight and Suggestion for more details.

Fields​
Field
titlestring

(Optional) Title of the card. Maximum 200 characters.
descriptionstring

(Optional) Description of the card. Maximum 2000 characters.
mediaobject

(Optional) Media (image, GIF, video, PDF) to include in the card.
media.heightenum (MediaHeight)

(Optional) The height of the media within a rich card with a vertical layout. For a standalone card with horizontal layout, height is not customizable, and this field is ignored.
media.contentInfoobject

Information about a file, including the URL of the file and the URL of the file’s thumbnail.

The platform serves content from a cache, but an agent can force the platform to fetch a new version of the content and refresh the cache.
media.contentInfo.fileUrlstring

Publicly reachable URL of the file. The platform determines the MIME type of the file from the content-type field in the HTTP headers when the platform fetches the file. The content-type field must be present and accurate in the HTTP response from the URL. Recommended maximum file size of 100 MB.

Note: redirects in file URLs are not supported.
media.contentInfo.thumbnailUrlobject (CardContent)

(Optional, for image, audio and video files only) Publicly reachable URL of the thumbnail. Maximum size of 100 kB.

If you don't provide a thumbnail URL, the platform displays a blank placeholder thumbnail until the user's device downloads the file. Depending on the user's setting, the file may not download automatically and may require the user to tap a download button.

Note: redirects in file URLs are not supported.
media.contentInfo.forceRefreshboolean

If set, the platform fetches the file and thumbnail from the specified URLs, even if the platform has cached copies of the file (and/or of the thumbnail).
suggestions[]object (Suggestion)

(Optional) List of suggestions to include in the card. Maximum 4 suggestions.
MediaHeight​
Enums
SHORT112 DP.
MEDIUM168 DP.
TALL264 DP. Not available for rich card carousels when the card width is set to small.
Sample API payload​
Media: IMAGE and cardOrientation: HORIZONTAL​
{
    "name": "rich_card_example",
    "type": "rich_card",
    "component": {
        "richCard": {
            "standaloneCard": {
                "cardOrientation": "HORIZONTAL",
                "thumbnailImageAlignment": "LEFT",
                "cardContent": {
                    "title": "Welcome to Sinch Engage",
                    "description": "A single, powerful platform for SMS & WhatsApp — made for conversion.",
                    "media": {
                        "contentInfo": {
                            "fileUrl": "https://sinch.com/assets/banner.jpg",
                            "thumbnailUrl": "https://sinch.com/assets/thumb.jpg"
                        },
                        "height": "MEDIUM"
                    },
                    "suggestions": [
                        {
                            "reply": {
                                "text": "Sug Butn Reply 1",
                                "postbackData": "rich_card_example"
                            }
                        },
                        {
                            "action": {
                                "text": "Sug Butn DaN 2",
                                "postbackData": "rich_card_example",
                                "dialAction": {
                                    "phoneNumber": "+918010921481"
                                }
                            }
                        },
                        {
                            "action": {
                                "text": "Sug Butn OaU 3",
                                "postbackData": "rich_card_example",
                                "openUrlAction": {
                                    "url": "https://sinch.com/[custom_param1u]",
                                    "application": "BROWSER"
                                }
                            }
                        },
                        {
                            "action": {
                                "text": "Sug Butn OaU 4",
                                "postbackData": "rich_card_example",
                                "openUrlAction": {
                                    "url": "https://sinch.com/[custom_param2u]",
                                    "application": "WEBVIEW",
                                    "webviewViewMode": "FULL",
                                    "description": "This is a variation"
                                }
                            }
                        }
                    ]
                }
            }
        }
    }
}
Media: VIDEO and cardOrientation: VERTICAL​
{
    "name": "rich_card_example",
    "type": "rich_card",
    "component": {
        "richCard": {
            "standaloneCard": {
                "cardOrientation": "VERTICAL",
                "thumbnailImageAlignment": "RIGHT",
                "cardContent": {
                    "title": "Welcome to Sinch Engage",
                    "description": "A single, powerful platform for SMS & WhatsApp — made for conversion.",
                    "media": {
                        "contentInfo": {
                            "fileUrl": "https://freetestdata.com/wp-content/uploads/2022/02/Free_Test_Data_1MB_MP4.mp4",
                            "thumbnailUrl": "https://sinch.com/assets/thumb.jpg"
                        },
                        "height": "SHORT"
                    },
                    "suggestions": [
                        {
                            "action": {
                                "text": "Sug Butn VLLL 1",
                                "postbackData": "rich_card_example",
                                "viewLocationAction": {
                                    "latLong": {
                                        "latitude": "33.22",
                                        "longitude": "24.24"
                                    },
                                    "label": "Noida, Sector 132"
                                }
                            }
                        },
                        {
                            "action": {
                                "text": "Sug Butn VLQ 2",
                                "postbackData": "rich_card_example",
                                "viewLocationAction": {
                                    "query": "Share your Location"
                                }
                            }
                        },
                        {
                            "action": {
                                "text": "Sug Butn SL 3 Noida",
                                "postbackData": "rich_card_example",
                                "shareLocationAction": {}
                            }
                        },
                        {
                            "action": {
                                "text": "Sug Butn CCE 4",
                                "postbackData": "rich_card_example",
                                "createCalendarEventAction": {
                                    "description": "Test Event Description",
                                    "startTime": "2025-08-14T06:30:00Z",
                                    "endTime": "2025-08-14T06:30:00Z",
                                    "title": "Test Event Title"
                                }
                            }
                        }
                    ]
                }
            }
        }
    }
}

RichCardCarousel​

JSON Representation​

{
  "richCard": {
    "carouselCard" : {
      "cardWidth": enum (CardWidth),
      "cardContents": [
        {
          object (CardContent)
        }
      ]
    }
  }
}

See CardWidth and CardContent for more details

Fields​

Field
richCard.carouselCardobject

Carousel of cards.
richCard.carouselCard.cardWidthenum (CardWidth)

The width of the cards in the carousel.
richCard.carouselCard.cardWidthenum (CardWidth)

The width of the cards in the carousel.
richCard.carouselCard.cardContents[]object (CardContent)

The list of contents for each card in the carousel. A carousel can have a minimum of 2 cards and a maximum 10 cards.

CardWidth​

Enums
SMALL120 DP. Note that tall media cannot be used.
MEDIUM232 DP.

Sample API payload​

{
    "name": "carousel_example",
    "type": "carousel",
    "component": {
        "richCard": {
            "carouselCard": {
                "cardWidth": "MEDIUM",
                "cardContents": [
                    {
                        "title": "Card 1: Sinch Engage SMS",
                        "description": "Send SMS campaigns that drive engagement and conversion.",
                        "media": {
                            "contentInfo": {
                                "fileUrl": "https://sinch.com/assets/sms_card.jpg"
                            },
                            "height": "TALL"
                        },
                        "suggestions": [
                            {
                                "reply": {
                                    "text": "Sug Butn Reply 1",
                                    "postbackData": "carousel_example"
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn DaN 2",
                                    "postbackData": "carousel_example",
                                    "dialAction": {
                                        "phoneNumber": "+918010921481"
                                    }
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn OaU 3",
                                    "postbackData": "carousel_example",
                                    "openUrlAction": {
                                        "url": "https://sinch.com/[custom_param1u]",
                                        "application": "BROWSER"
                                    }
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn OaU 4",
                                    "postbackData": "carousel_example",
                                    "openUrlAction": {
                                        "url": "https://sinch.com/[custom_param2u]",
                                        "application": "WEBVIEW",
                                        "webviewViewMode": "FULL",
                                        "description": "This is a variation"
                                    }
                                }
                            }
                        ]
                    },
                    {
                        "title": "Card:2 Sinch Engage WhatsApp",
                        "description": "Create personalized WhatsApp campaigns to boost customer interactions.",
                        "media": {
                            "contentInfo": {
                                "fileUrl": "https://freetestdata.com/wp-content/uploads/2022/02/Free_Test_Data_1MB_MP4.mp4",
                                "thumbnailUrl": "https://sinch.com/assets/thumb.jpg"
                            },
                            "height": "MEDIUM"
                        },
                        "suggestions": [
                            {
                                "action": {
                                    "text": "Sug Butn OaU 5",
                                    "postbackData": "carousel_example",
                                    "openUrlAction": {
                                        "url": "https://sinch.com/[custom_param3u]",
                                        "application": "WEBVIEW",
                                        "webviewViewMode": "HALF",
                                        "description": "This is a variation"
                                    }
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn OaU 6",
                                    "postbackData": "carousel_example",
                                    "openUrlAction": {
                                        "url": "https://sinch.com/[custom_param4u]",
                                        "application": "WEBVIEW",
                                        "webviewViewMode": "TALL",
                                        "description": "This is a variation"
                                    }
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn VLLL 7",
                                    "postbackData": "carousel_example",
                                    "viewLocationAction": {
                                        "latLong": {
                                            "latitude": "33.22",
                                            "longitude": "24.24"
                                        },
                                        "label": "Noida, Sector 132"
                                    }
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn VLQ 8",
                                    "postbackData": "carousel_example",
                                    "viewLocationAction": {
                                        "query": "Share your Location"
                                    }
                                }
                            }
                        ]
                    },
                    {
                        "title": "Card 3: Sinch Engage Analytics",
                        "description": "Track your campaign performance in real-time to optimize conversions.",
                        "media": {
                            "contentInfo": {
                                "fileUrl": "https://sinch.com/assets/analytics_card.jpg"
                            },
                            "height": "SHORT"
                        },
                        "suggestions": [
                            {
                                "action": {
                                    "text": "Sug Butn SL 9 Noida",
                                    "postbackData": "carousel_example",
                                    "shareLocationAction": {}
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn CCE 10",
                                    "postbackData": "carousel_example",
                                    "createCalendarEventAction": {
                                        "description": "Test Event Description",
                                        "startTime": "2025-08-14T06:30:00Z",
                                        "endTime": "2025-08-14T06:30:00Z",
                                        "title": "Test Event Title"
                                    }
                                }
                            },
                            {
                                "reply": {
                                    "text": "Sug Butn Reply 11",
                                    "postbackData": "carousel_example"
                                }
                            },
                            {
                                "action": {
                                    "text": "Sug Butn DaN 12",
                                    "postbackData": "carousel_example",
                                    "dialAction": {
                                        "phoneNumber": "+918010921481"
                                    }
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Suggestions​

A Suggestion is either a SuggestedReply or a SuggestedAction.

SuggestedReply​

JSON Representation​

{
  "reply": {
    "text": string,
    "postbackData": string
  }
}

Fields​

Field
reply.textstring

Text that is shown in the suggested reply and sent back to the agent when the user taps it. Maximum 25 characters.
reply.postbackDatastring

The base64-encoded payload that the agent receives in a user event when the user taps the suggested reply.

SuggestedAction​

JSON Representation​

{
  "action": {
    "text": string,
    "postbackData": string,
    "fallbackUrl": string,

    // Union field action can be only one of the following:
    "dialAction": {
      "phoneNumber": string
    },
    "viewLocationAction": {
      "latLong": {
        "latitude": string,
        "longitude": string
      },
      "label": string,
      "query": string
    },
    "createCalendarEventAction": {
      "startTime": string,
      "endTime": string,
      "title": string,
      "description": string
    },
    "openUrlAction": {
      "url": string,
      "application": enum (OpenUrlApplication),
      "webviewViewMode": enum (WebviewViewMode),
      "description": string
    },
    "shareLocationAction": {
      // This type has no fields.
    }
    // End of list of possible types for union field action.
  }
}

Fields​

Field
action.textstring

Text that is shown in the suggested action. Maximum 25 characters.
action.postbackDatastring

Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
action.fallbackUrlstring

(Optional) Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows. Must be a valid URI as defined in RFC 3986. Maximum 2048 characters.
Union field action. The native action initiated on the device when the user taps the suggested action action can be only one of the following:
action.dialActionobject

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

The phone number in E.164 format, for example, +12223334444.
action.viewLocationActionobject

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.
action.viewLocationAction.latLongobject

(Optional) The latitude and longitude of the specified location.
action.viewLocationAction.latLong.latitudestring

The latitude in degrees. It must be in the range [-90.0, +90.0].
action.viewLocationAction.latLong.longitudestring

The longitude in degrees. It must be in the range [-180.0, +180.0].
action.viewLocationAction.labelstring

(Optional) The label of the pin dropped at latLong.
action.viewLocationAction.querystring

(Optional, only supported on Android Messages clients) Rather than specify a latLong (and optionally, a label), the agent can instead specify a query string. For default map apps that support search functionality (including Google Maps), tapping this suggested action results in a location search centered around the user's current location. If the query is sufficiently specific, then agents can use it to select any location in the world.

For instance, setting the query string to "Growing Tree Bank" will show all Growing Tree Bank locations in the user's vicinity. Setting the query string to "1600 Amphitheater Parkway, Mountain View, CA 94043" will select that specific address, regardless of the user's location.
action.createCalendarEventActionobject

Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
action.createCalendarEventAction.startTimestring (Timestamp format)

Event start time.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: 2014-10-02T15:01:23Z, 2014-10-02T15:01:23.045123456Z or 2014-10-02T15:01:23+05:30.
action.createCalendarEventAction.endTimestring (Timestamp format)

Event end time.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: 2014-10-02T15:01:23Z, 2014-10-02T15:01:23.045123456Z or 2014-10-02T15:01:23+05:30.
action.createCalendarEventAction.titlestring

Event title. Maximum 100 characters.
action.createCalendarEventAction.descriptionstring

Event description. Maximum 500 characters.
action.openUrlActionobject

Opens the user's default web browser app to the given URL. If the user has an app installed that is registered as the default handler for the URL, then this app will be opened instead, and its icon will be used in the suggested action UI.
action.openUrlAction.urlstring

The URL to open. Effective November 1, 2025, the URL scheme must be https:// or http://. API requests using any other schemes (e.g., tel:, mailto:, sms:) will be rejected with a 400 Bad Request error after this date. The URL must be a valid URI as defined in RFC 3986. Maximum 2048 characters.
action.openUrlAction.applicationenum (OpenUrlApplication)

URL open application, browser or webview. To check whether a user's device supports webview mode, run a capability check first. See the documentation for details: https://developers.google.com/business-communications/rcs-business-messaging/guides/build/capabilities.
action.openUrlAction.webviewViewModeenum (WebviewViewMode)

View mode for webview
action.openUrlAction.descriptionstring

Accessibility description for webview.

OpenUrlApplication​

Enums
BROWSERUse browser to open URL.
WEBVIEWOpen URL in an integrated web view window

WebviewViewMode​

Enums
FULLRequires a full screen overlay with the Chatbot conversation labelled within the status bar.
HALFRequires a half screen overlay.
TALLRequires a three-quarters screen overlay.

Responses​

StatusMeaningDescriptionSchema
201CreatedThe response body contains a newly created instance of Template.TemplateCreated
400Bad RequestInvalid Query or Body Parameters.BadRequest
401UnauthorizedMissing or invalid Authorization header.None
403ForbiddenThe provided token does not have access to this resource.None
429Too Many RequestsRate limit exceeded. Retry after the time specified in Retry-After header.None
500Internal Server ErrorSomething Went wrong wile processing your request.InternalServerError
502Bad GatewayThe upstream service failed to respond correctly.None
503Service UnavailableThe API is temporarily unavailable, often due to maintenance or overload.None
504Gateway TimeoutThe server did not receive a timely response from the upstream service.None

TemplateCreated​

JSON Representation​

{
  "component": {
    object (MessageContent)
  },
  "name": string,
  "type": enum (TemplateType),
  "status": enum (TemplateStatus)
}

See MessageContent, TemplateType and TemplateStatus for more details.

Fields​

Fields
componentobject (MessageContent)

The content of the message template.
namestring

Name of the template.
typeenum (TemplateType)

Type of the template.
statusenum (TemplateStatus)

Approval status of the template.

BadRequest​

JSON Representation​

{
  "error": {
    "code": 400,
    "message": string
  }
}

Fields​

Fields
error.code400
error.messagestring

The message detailing what parameter from the Body and Query is invalid.

InternalServerError​

JSON Representation​

{
  "error": {
    "message": "Something went wrong.",
    "code": 500
  }
}

Fields​

Fields
error.code500
error.messageSomething went wrong.