Bot Participation Handler

The bot participation handler can be used to add a bot to a channel. The participation handler essentially allows the bot to read, understand and participate in channel conversations. You can configure the bot to do either of the following actions or both, listen and respond to the channel messages and perform a corresponding action or directly send messages in the channel without any prompting. Here're a few examples of how the participation handler can be put to good use. 

• A help desk bot can be added as a participant in different support channels. The bot can listen to messages, look for support tickets being discussed and can share information about the support ticket right inside the channel. The bot can also take note of the messages and add them as comments to the respective tickets. 
• How about having a project bot that sends in daily project updates, pulls up task data when there's a discussion going on and simply keeps tabs on the project's progress?

Participation handler attributes

The list of attributes that are passed when the participation handler is triggered is given below. 

The operation attribute

The operation attribute is of the type, string and denotes the type of operation that is performed in the channel where the bot has been added. You can use this attribute to configure the bot's response based on different operation values. The list of operations for which the bot's participation handler is triggered are: 

Note:

• Along with the above operation the developer can get the current thread details from chat Dre object and the user who performed the action from user object.
• Message returned via participation handler on thread_closed operation will be skipped.
• thread_closed and thread_reopened operation will be sent only to the bots currently following the thread.

The data attribute 

The data map can have the following keys based on the operation: 

Transient Messages

Transient Messages are temporary messages which will only be visible to the participant of a channel who adds or removes a bot from the channel. One can opt to post the message publicly or just close the message. If neither option is selected the message will automatically disappear when you close the channel. 

The bot can be equipped to post temporary messages in a channel whenever its being added to or removed from that particular channel using the bot participation handler.

Example :

The below sample syntax shows different temporary messages being posted when the bot is added to or removed from a channel.

// Sample Syntax for Transient Message

response = Map();
if(operation == "removed")
{
	response.put("type","transient_message");
	response.put("text","Bot removed");
}
else if(operation == "added")
{
	response.put("type","transient_message");
	response.put("text","Bot added");
}
return response;

Configuring the bot's channel participation

A bot's channel participation can be configured from the bot's edit configurations page. You can choose to allow any user to add your bot to any channel. To do so, 

1) In the Create bot page, enable the "Allow users to add this bot to any channel" option.  Once done, there're 2 simple bot participation configurations:

• Listen to messages - Your bot can listen and respond to messages in the channel
• Send messages - Your bot can only send messages to the channel without any relative prompting from the user

You can choose either or both options based on the bot's purpose. 

2) Click on Save and head over to the bot's edit handlers page.

3) Click on the Edit Code option provided for the Participation Handler.

4) Add your code and click on save.

How to add a bot to a channel 

To add a bot as a channel participant,

1. Open the channel where you'd like to add the bot
2. Then, click on the channel participants info right below the channel heading. 
3. Click on the Add participants option

​

4. Search for the bot and then click Add

​

5. Once you select the bot you'd like to add, a confirmation prompt is displayed with all the actions and permissions the bot can perform in the channel. Click on Add bots to the channel to add the bot as a participant. 

Example 

Let's take a sample user scenario to understand how the bot participation handler works. Consider a channel with all your customer support executives to discuss current customer tickets, feedback and more. We'll create a Support Bot, that'll help executives tackle customer requests and tickets in the channel. Whenever a channel participant shares an email in the channel, the bot immediately checks and pulls up any open, ongoing tickets from the respective email ID in Zoho Desk. In case a user wants more details about a specific ticket ID, then the user can ask the bot to bring more information on the specific ticket. This way the bot keeps everyone in the channel informed about the ongoing ticket status. Take a look at the bot's participation handler code given below.

Prerequisites to use this code snippet:

• Create a connection in Cliq with Zoho Desk with the following scopes: Desk.search.READ, Desk.tickets.READ and use the connection name in the invoke URL task.
•  Zoho Desk API used: Search across modules API

response = Map();
username = user.get("first_name");
if(operation.contains("message_sent"))
{
	info "here";
	text = data.get("message").get("text").toList(" ");
	for each textItem in text
	{
	emailID = textItem.matches("^([\s\S]*)?([\w\-\.\+\'\/]*)@((?!zoho\w).*[\w\-\.]+)(\.[a-zA-Z]{2,22}(\.[a-zA-Z]{2}){0,2})([\s\S]*)?$");
if(emailID)
	{
getTickets = invokeUrl [
    url : "https://desk.zoho.com/api/v1/tickets/search?email="+textItem.trim()
    type : GET
    connection : //Give your connection name
];
info getTickets;
tickets = getTickets.get("data");
rows = List();
for each ticket in tickets
{
row = Map();
row.put("Ticket No",ticket.get("ticketNumber"));
row.put("Subject",ticket.get("subject"));
row.put("Status",ticket.get("statusType"));
rows.add(row);
}
response = {"text":"Here's the list of tickets that "+textItem.trim()+" has raised!","card":{"theme":"modern-inline","title":"Ticket Raised"},"slides":{{"type":"table","title":"","data":{"headers":{"Ticket No","Subject","Status"},"rows":rows}}}};
	}
}
}
return response;

The image illustrates how the Support Bot helps customer executives. Whenever a message is posted with an email ID, the Support Bot looks for tickets associated with that email ID in Zoho Desk and posts it directly in the channel.