RCS API - Suggestions

Suggestions are interactive components in a Message. Using suggestions, you can suggest a reply/response from the recipient or suggest an action from his end. The Actions are displayed as interactive elements in the Messaging App of user's phone. When user responds or takes suggested actions; an associated value is posted back to Business on Webhook.

JSON Structure shown below against each type of suggestion is for a Single Suggestion.

A Single Suggestion is used as an object in "suggesetions" array in JSON Payload to "Send Message" or in "Rich Card" definition.. A Single Message may have maximum of 4 suggestions, so "suggestions" is an array of suggestion-objects in the Payload.

Standard JSON Object

{
	"type": "{Type of suggestion}",
	"text": "{Plain text}",

    // Suggestion Type specific keys will appear

	"postback": "{Postback text}"
}

Payload Explanation

There are 2 types of suggestions, viz.

• Suggested Replies
• Suggested Actions

Suggested Replies

Suggested Replies guide recipients through conversations by providing responses / reactions that the app understands. The app sends suggested replies in suggestion chip lists or in rich cards.

When a user taps a suggested reply, app receives an event that contains the reply's text and postback data. Suggested action has a maximum of 25 characters.

Reply with Text Prompt

JSON Object

{
	"type": “reply”,
	"text": "{Plain text}",
	"postback": "{Postback text}"
}

Payload Explanation

Suggested Actions

Suggested actions guide users through conversations by leveraging the native functionality of their devices. Suggest users to dial a number, to open a location on a map, to share a location, to open a URL, or to create a calendar event. The app sends suggested replies in suggestion chip lists or in rich cards.

When a user taps a suggested action, the app receives an event that contains post back data.

Suggested replies have a maximum of 25 characters.

Open a URL

The Open URL action opens the user's web browser to the specified URL. If an app is registered as a default handler for the URL, the app opens instead.

JSON Object

{
	"type": "open_url",
	"text": "{Plain text}",
	"url": "{Suggested URL}",
	"postback": "{Postback text}"
}

Payload Explanation

Dial a Phone

The Dial action guides the user to dial a specified phone number. Phone numbers need to include a leading +, the country code, and the area code but shouldn't include separators. For example, +14155555555.

JSON Object

{
	"type": "dial",
	"text": "{Plain text}",
	"phone": "{Phone number}",
	"postback": "{Postback text}"
}

Payload Explanation

View a Location

The View location action helps to send Location Information to recipient that directs the users to view the location using default map app. You can also set a custom label for the pin that displays in the map app.

JSON Object

{
	"type": "view_location”",
	"text": "{Plain text}",
	"latitude": "{Latitude value}",
	"longitude": "{longitude value}",
	"label": "{display label on map}",
	"fallback": "{fallback to map url/apps}",
	"postback": "{Postback text}"
}

Payload Explanation

Request to share Location

The Share location action lets the user send a location. The location the user specifies is not necessarily the user's own location.

JSON Object

{
	"type": "share_location",
	"text": "{Plain text}",
	"postback": "{Postback text}"
}

Payload Explanation

Create Calendar Event

The Create Calendar Event action opens the user's calendar app and begins to create a new event with the specified information.

JSON Object

{
	"type": "create_calendar_event",
	"text": "{Plain text}",
	"title": "{Event Title}",
	"description": "{Event Description}"
	"start_time": "{Event Start Time}",
	"end_time": "{Event End Time}",
	"fallback": "{fallback to calendar apps}",
	"postback": "{Postback text}"
}

Payload Explanation

Postbacks on Webhook

When user reads RCS messages on the Messaging App of Mobile Devices, he see interactive elements against which he can take action or responds to the business. When he responds or takes suggested actions; an associated value is posted back to Business on Webhook.

Read more...

• Webhook Posts on Suggestions