RCS Suggestions Chips

RCS Suggestions allow you to use suggested replies and actions in your RCS messages. They can be included in various message types, such as Cards, Carousels, and Text messages, and are defined in the JSON payload of those messages as an array of suggestion objects.

These suggestion objects can be suggested replies, suggested actions, or a combination of both. The exact structure of the objects varies depending on the type of suggestion.

Suggestions

Suggestions are interactive UI elements rendered as buttons or 'chips' in supported RCS messaging apps. Each suggestion represents a quick reply or an action the user can tap. These chips appear below the main body of the message and disappear once the user interacts with them or when a newer message is received.

There are two types of suggestions:

  • Suggested Replies: Predefined user responses that trigger an inbound message of type reply to the URL defined for your Inbound Message Webhook.
  • Suggested Actions: Buttons that perform an action, for example to open URL or call a number, and trigger an inbound message of type button to the URL defined for your Inbound Message Webhook.

Note: You can also include a suggestions array in a rich card message. Since a carousel is a collection of cards, each card in a carousel may also contain its own suggestions array. See Rich Cards and Carousels for more information.

Suggested Replies

Use suggested replies when expecting a response that can be processed programmatically. Each reply includes:

  • text: Displayed on the chip.
  • postback_data: An identifier returned in the inbound reply message payload as the id parameter.

Here is an example of an RCS message of type text with two suggested replies:

{
   "to": "447700900000",
   "from": "Vonage",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello, world!",
   "suggestions": [
       {
           "type": "reply",
           "text": "Suggestion #1",
           "postback_data": "suggestion_1"
       },
       {
           "type": "reply",
           "text": "Suggestion #2",
           "postback_data": "suggestion_2"
       }
   ]
}

If the recipient tapped on one of the suggestions, this would trigger an inbound message of type reply; here, the value of id would vary depending on which suggestion chip the user selected:

{
  "to": "Vonage",
  "from": "447900000000",
  "channel": "rcs",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2024-02-08T10:12:44Z",
  "message_type": "reply",
  "reply": {
    "id": "suggestion_1",
    "title": "Suggestion #1"
  }
}

Suggested Actions

Suggested actions perform a function and return structured data via a button message. All actions require:

  • type: Defines the type of action
  • text: Chip label (max 25 characters)
  • postback_data: An identifier returned in the inbound button message payload as the payload parameter.

Most action types also require one or more additional parameters to support the specific action. Some types also have further optional parameters. These parameters are detailed in the descriptions for the specific types below:

Open a URL

This action object has a type of open_url and has the following additional properties:

  • url: The URL to be opened. Note: the only permitted schemes are http:// and https://; other schemes types such as tel, mailto, etc are not permitted.
  • description: An optional description of the URL for accessibility purposes.
  • url (String): this is the URL to be opened.

If this action chip is tapped, the recipient's device opens the specified URL either in the device's default browser or in an installed app (if an app is registered as a handler for the URL's domain).

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description"
   }
  ]
 }

Open an URL in Webview

This action object has a type of open_url_in_webview and has the following additional properties:

  • url: The URL to be opened. Note: the only permitted schemes are http:// and https://; other schemes types such as tel, mailto, etc are not permitted.
  • description: An optional description of the URL for accessibility purposes.
  • view_mode: The mode for displaying the URL in the webview window. Either FULL, TALL, or HALF.

If this action chip is tapped, the recipient's device opens the specified URL within the messaging app itself, with the size of the webpage within the app interface determined by the value of the view_mode parameter.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url_in_webview",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description",
     "view_mode": "FULL"
   }
  ]
 }

Dial a Number

This action object has a type of dial and has the following additional properties:

  • phone_number (String): this is the phone number to be dialled. It must be in E.164 format, include the country code, and be prepended by a +, for example +447900000000
  • fallback_url (String): this is a URL to be opened if it is not possible for the dial action to be initiated.

If this action chip is tapped, the recipient will be directed to call the phone number specified.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "dial",
     "text": "Call",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/contact/",
     "phone_number": "+15556667777"
   }
 ]
}

View a Location

This action object has a type of view_location and has the following additional properties:

  • latitude (String): The latitude in degrees. It must be in the range [-90.0, +90.0]
  • longitude (String): The longitude in degrees. It must be in the range [-180.0, +180.0].
  • pin_label (String): an optional property which adds a label to the pin displayed on the map.
  • fallback_url (String): this is a URL to be opened if it is not possible for the view location action to be initiated.

If this action chip is tapped, the recipient's device displays the specified location in the device's default map application.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "view_location",
     "text": "View map",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/maps/@37.4220188,-122.0844786,15z",
     "latitude": "37.4220188",
     "longitude": "-122.0844786",
     "pin_label": "Googleplex"
   }
 ]
}

Share a Location

This action object has a type of share_location and only has three required parameters: type, text, and postback_data.

If this action chip is tapped, the recipient's device opens the default location chooser so the recipient can pick a location to send back.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "share_location",
     "text": "Share your location",
     "postback_data": "postback_data_1234"
   }
 ]
}

Create a Calendar Event

This action object has a type of create_calendar_event and has the following additional properties:

  • start_time (String in Timestamp format): defines the event start time. A timestamp in RFC3339 UTC "Zulu" format, for example 2024-06-28T19:00:00Z
  • end_time (String in Timestamp format): defines the event end time. A timestamp in RFC3339 UTC "Zulu" format, for example 2024-06-28T19:00:00Z.
  • title (String): defines the title of the event.
  • description (String): defines the description of the event.
  • fallback_url (String): this is a URL to be opened if it is not possible for the create calendar event action to be initiated.

If this action chip is tapped, the recipient's device opens the default calendar app and starts creating a new calendar event with the data defined in the action object.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
         {
     "type": "create_calendar_event",
     "text": "Save to calendar",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/calendar",
     "start_time": "2020-06-30T19:00:00Z",
     "end_time": "2020-06-30T20:00:00Z",
     "title": "My calendar event",
     "description": "Description of the calendar event"
   }
 ]
}

Code Snippets

Below is a list of code snippets for sending message requests for different types of messages:

Further Reading