Bot Participation Handler

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. 

Expected values: added | removed | message_sent | message_edited | message_deleted 
Denotes the operation performed on the channel. Use this attribute to configure the bot's action based on the operation. 
dataMapDetails of the operation performed. The data object will show information based on the operation. 
userMapDetails of the user sending a message in the channel.
chatMapDetails of the channel in which the bot is added as a participant.
environmentMapDetails of the data center to which the user belongs.
accessMapDetails of the user's web client. 

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: 

Operation TypeDescription
addedWhen the bot has been added to the channel.
removedWhen the bot has been removed from the channel. 
message_sentWhen a new message (text, links, and attachments) is posted by a channel participant.
message_editedWhen a message is edited by a channel participant. 
message_deletedWhen a message is deleted by a channel participant. 

The data attribute 

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

Associated OperationKeyTypeDescription
added, removed, message_sent, message_edited, message_deletedtimetimestampRepresents the time at which the operation was performed. 
message_sent, message_edited, message_deletedmessageJSON ObjectRepresents the message object. 

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("text","Bot removed");
else if(operation == "added")
	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. 


  1. Adding a bot to a channel is associated with the channel's permission. Users can add a bot to a channel only if this permission set is enabled for their role. The same permission applies when any user tries to remove a bot from a channel. 
  2. Bots created for personal use (bot access level set as Personal) can also be added to a channel, provided the above-mentioned configuration is enabled. 
  3. You can add a maximum of 10 bots per channel.


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:

response = Map();
username = user.get("first_name");
	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]*)?$");
getTickets = invokeUrl [
    url : ""+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"));
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. 

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: