Event Interfaces and Handlers

An app can listen for specific events and respond according to your requirements. You can implement an event interface to listen to an event and handle its payload. Apps-Engine provides various event interfaces. Typically, each interface contains methods that will be called before or after a Rocket.Chat event. Here, we will learn some concepts about event interfaces and handlers in Rocket.Chat.

Event interfaces

Event interfaces are the mechanism by which apps can connect to the events on Rocket.Chat. For instance, when a message is sent, when a room or channel is created, or when a file is uploaded, the app can take some actions. For each of these events, the app needs to use the respective interfaces to connect to the events.

Let's consider an example: an app implements the post-room creation interface with the PostRoomCreate method. This tells Apps-Engine that the app wants to connect to that event. Whenever a room is created, Apps-Engine executes this method in the app.

You need to define the method's parameters and the actions you want the app to perform. Typically, there are two fundamental methods for each interface:

• A method to check: This signals the Apps-Engine whether the event handler should be executed.

• A method to execute the defined actions: This is the event handler.

We will deprecate check* methods and won't add check* methods to event interfaces anymore. Avoid using them as much as possible.

Nomenclature

• For interfaces: ‘ I’ is prefixed to the event name.

• For the two interface methods:

  • ‘check’ is prefixed to the method that’s called to check whether the event has occurred.

  • ‘execute’ is prefixed to the method that defines the actions the app must perform when the event occurs.

For example, for the event PreRoomCreatePrevent, the corresponding nomenclature looks like this:

• Interface: IPreRoomCreatePrevent

• Check method: checkPreRoomCreatePrevent

• Execute method: executePreRoomCreatePrevent

This is the basic structure followed for most event interfaces supported by Rocket.Chat.

Event handlers

There are various ways to handle an event. When an event occurs, there are pre-handlers and post-handlers. The set of pre-handlers is executed before the event is completed. The set of post-handlers is executed when the event is completed. We recommend using pre-handlers to modify, extend, or change the data used for the event. If you want to listen for an event without modifying anything, use the post-handlers.

Here is an explanation of the handlers:

• Prevent: Determines whether the event should be prevented or not.

• Extend: Allows extending the data without being destructive of the data (adding an attachment to a message, for example).

• Modify: Allows destructive changes to the data (for example, changing any data).

• IPreEvent: Handlers that are called before an event happens.

• IPostEvent: Handlers that are called after an event happens.

In the main class of your app, the class name extends App. This tells the Apps-Engine that App is the main class. To use events, the app must implement the event interfaces, and this is done by using the keyword implements and the name of the events, comma-separated.

In the following sections, you will find the event interfaces supported by Rocket.Chat. The event interfaces are grouped based on the events, such as email, livechat, messages, rooms, users, and so on. You will also find examples of how these interfaces can be implemented.

You can find the supported interfaces and the methods on the TypeScript definition page.