Implementing the Command Suggestion Handler

What are suggestion handlers?

Suggestion handlers provide a user with choices to select before executing the command. The click to execute field works in relation to the suggestion handlers, i.e you can specify the maximum number of suggestions a user can select from the suggestion list before they execute the command. When the click to execute option is enabled for any command, a user can also make multiple selections from the list of suggestions shown. When the click to execute option is not enabled, then the user can select a maximum of 10 suggestions from the list. The table below shows the list of attributes received upon triggering the suggestion handler, most important of them being selections.

Note:

Maximum number of suggestions that can be specified in the Click to Execute option is 10.

For example, in the below-given image, the command will be executed once the user selects one suggestion from the list since the option entered here reads - 'Execute the command on selecting  suggestion(s).'  

 

Command Click to Execute option

Attribute NameDescription
argumentsWhole string present after the command name.
chatChat details in which the command is executed.
userDetails of the user executing the command.
optionsAttributes that help in reforming the command output according to the requirement.
mentionsDetails of the user/channel/bot mentioned.
attachmentsAn array of deluge file objects.
selectionsSelections made by the user from the suggestions provided.
locationDetails of the current location of the user.

Sample Suggestion Code:

Customise your suggestions by giving a title, description, image or personalize it further by creating different combinations from them. Take a look at the sample suggestion object given below. This sample code will be available when you click on Edit Suggestion Code option. 


List = List();
entry = Map();
entry.put("title","Suggestion Title");
list.add(entry);
entry.put("description", "Suggestion description");
entry.put("imageurl", "Insert image URL");
return list;

Rendering a response:

When the user selects an option or a list of options from the suggestions provided, they are passed to the selections and function arguments in the command execution code. The execution code is executed to render the response. The selections attribute will contain the array of selected objects from the suggestions list provided. 

Types of suggestions:

The suggestions provided to a command can have a title, an image, a description, combinations of a title, description and image or any way you wish to structure your suggestion. 

Command Suggestion List Limit:

A maximum number of 50 suggestions can be shown in the command suggestions list. 

Example:

The /cliqhelp command will get you a list of help documents as suggestions. Selecting a document shown in the suggestion list and clicking enter will direct you to the respective page! Take a look at our sample syntax given below.




//Sample Execution Code - /cliqhelp

message = Map();
if(selections.size() >0 )
{
	details = selections.get(0).toMap();
	if(details.get("title").containsIgnoreCase("User Guide"))
	{
message.put("text", "Take a look at our [User Guide](https://www.zoho.com/cliq/help/)");
	}
	else if(details.get("title").containsIgnoreCase("Platform Guide"))
	{
		message.put("text", "Take a look at our [Platform Guide](https://www.zoho.com/cliq/help/developers.html)");
	}
	else 
	{
message.put("text", "Take a look at our [Rest API Document](https://www.zoho.com/cliq/help/restapi/)");
	}

}
card=Map();
card.put("theme","prompt");
message.put("card",card);
return message;

//Sample Suggestion Code

list = List();
entry = Map();
entry.put("title","User Guide");
entry.put("imageurl","https://www.zoho.com/cliq/help/restapi/images/cliq_icon.png");
list.add(entry);
entry1 = Map();
entry1.put("title","Platform Guide");
entry1.put("imageurl","https://www.zoho.com/cliq/help/restapi/images/cliq_icon.png");
list.add(entry1);
entry2 = Map();
entry2.put("title","Rest API Document");
entry2.put("imageurl","https://www.zoho.com/cliq/help/restapi/images/cliq_icon.png");
list.add(entry2);
return list;

Command Suggestion Handler

Suggestions List using Command Suggestion Handler

Command Suggestions Selection and Response

 

Related Articles:

Slash Command Series: Command Suggestions - The power of choosing!

Take a look at how to share files from Zoho Docs easily with the /zdocs command