GITBOOK-1137: Apps-Engine Event Interfaces

SUMMARY.md

@@ -94,7 +94,7 @@
 * [App Development Lifecycle](apps-engine/understanding-app-lifecycle.md)
   * [Lifecycle of a Rocket.Chat App](apps-engine/understanding-app-lifecycle/lifecycle-of-a-running-app.md)
 * [App Configuration](apps-engine/app-configuration.md)
-* [Event Interfaces](apps-engine/fundamentals-of-apps/event-interfaces.md)
+* [Event Interfaces and Handlers](apps-engine/fundamentals-of-apps/event-interfaces.md)
   * [Email - Event Interfaces](apps-engine/event-interfaces/email-event-interfaces.md)
   * [Livechat - Event Interfaces](apps-engine/event-interfaces/livechat-event-interfaces.md)
   * [Message - Event Interfaces](apps-engine/event-interfaces/message-event-interfaces.md)

apps-engine/event-interfaces/email-event-interfaces.md

@@ -1,5 +1,5 @@
 # Email - Event Interfaces
 
-The table below contains all of the email-related events, as well as the purpose of each event. If you want to execute actions based on email events, you may use any of the events mentioned below as an event interface.
+The table below contains the email-related events, as well as the purpose of each event. If you want to execute actions based on email events, you can use any of the events mentioned below as an event interface.
 
-<table><thead><tr><th width="250.5">Interface</th><th>Purpose</th></tr></thead><tbody><tr><td><code>IPreEmailSent</code></td><td><p>Event interface that allows apps to register as a handler of the IPreEmailSent event.</p><p></p><p>This event is triggered before the mailer sends an email.</p><p></p><p>To prevent the email from being sent, you can throw an error with a message specifying the reason for rejection.</p></td></tr></tbody></table>
+<table><thead><tr><th width="250.5">Interface</th><th>Description</th></tr></thead><tbody><tr><td><code>IPreEmailSent</code></td><td><p>The event interface allows apps to register as a handler of the <code>IPreEmailSent</code> event.</p><p></p><p>This event is triggered before the mailer sends an email.</p><p></p><p>To prevent the email from being sent, you can throw an error with a message specifying the reason for rejection.</p></td></tr></tbody></table>

apps-engine/event-interfaces/livechat-event-interfaces.md

@@ -1,13 +1,5 @@
 # Livechat - Event Interfaces
 
-The table below contains all of the livechat-related events, as well as the purpose of each event. If you want to execute actions based on livechat events, you may use any of the events mentioned below as an event interface. 
+The table below contains the livechat-related events, as well as the purpose of each event. If you want to execute actions based on livechat events, you can use any of the events mentioned below as an event interface. 
 
-| Interface                      | Purpose                                                    |
-| ------------------------------ | ---------------------------------------------------------- |
-| `IPostLivechatAgentAssigned`   | Handler called after the assignment of a livechat agent.   |
-| `IPostLivechatAgentUnassigned` | Handler called after the unassignment of a livechat agent. |
-| `IPostLivechatGuestSaved`      | Handler called after the guest info gets saved.            |
-| `IPostLivechatRoomClosed`      | Handler called after a livechat room is closed.            |
-| `IPostLivechatRoomSaved`       | Handler called after the room info gets saved.             |
-| `IPostLivechatRoomStarted`     | Handler called after a livechat room starts.               |
-| `IPostLivechatRoomTransferred` | Handler called after a livechat room gets transferred.     |
+<table><thead><tr><th width="336">Interface</th><th>Description</th></tr></thead><tbody><tr><td><code>IPostLivechatAgentAssigned</code></td><td>The handler called after the assignment of a livechat agent.</td></tr><tr><td><code>IPostLivechatAgentUnassigned</code></td><td>The handler called after the livechat agent is unassigned.</td></tr><tr><td><code>IPostLivechatGuestSaved</code></td><td>The handler called after the guest's information is saved.</td></tr><tr><td><code>IPostLivechatRoomClosed</code></td><td>The handler called after a livechat room is closed.</td></tr><tr><td><code>IPostLivechatRoomSaved</code></td><td>The handler called after the room information is saved.</td></tr><tr><td><code>IPostLivechatRoomStarted</code></td><td>The handler called after a livechat room starts. </td></tr><tr><td><code>IPostLivechatRoomTransferred</code></td><td>The handler called after a livechat room is transferred. </td></tr></tbody></table>

apps-engine/event-interfaces/message-event-interfaces.md

@@ -1,6 +1,5 @@
 # Message - Event Interfaces
 
-The table below contains all of the message-related events, as well as the purpose of each event. If you want to execute actions based on message events, you may use any of the events mentioned below as an event interface.
-
-<table><thead><tr><th width="313.5">Interface</th><th>Purpose</th></tr></thead><tbody><tr><td><code>IPostMessageDeleted</code></td><td>Handler for after a message is deleted.</td></tr><tr><td><code>IPostMessageFollowed</code></td><td>Handler for after a message has been followed or unfollowed. </td></tr><tr><td><code>IPostMessagePinned</code></td><td>Handler for after a message has been pinned or unpinned.</td></tr><tr><td><code>IPostMessageReacted</code></td><td>Handler for after a message gets a reaction or a reaction got removed. </td></tr><tr><td><code>IPostMessageReported</code></td><td>Handler for after a message is reported. </td></tr><tr><td><code>IPostMessageSent</code></td><td>Handler for after a message is sent.</td></tr><tr><td><code>IPostMessageSentToBot</code></td><td>Handler for after a DM is sent to a bot.</td></tr><tr><td><code>IPostMessageStarred</code></td><td>Handler for after a message has been starred or unstarred. </td></tr><tr><td><code>IPostMessageUpdated</code></td><td>Handler for after a message is updated.</td></tr><tr><td><code>IPreMessageDeletePrevent</code></td><td>Handler which is called to determine whether a user is allowed to delete a message or not. </td></tr><tr><td><code>IPreMessageSentExtend</code></td><td>Handler called when an app wants to enrich a message.</td></tr><tr><td><code>IPreMessageSentModify</code></td><td>Handler called when an app wants to modify a message. </td></tr><tr><td><code>IPreMessageSentPrevent</code></td><td>Handler which is called to determine whether a user is allowed to send a message or not.</td></tr><tr><td><code>IPreMessageUpdatedExtend</code></td><td>Handler called when an app wants to enrich a message update.</td></tr><tr><td><code>IPreMessageUpdatedModify</code></td><td>​​Handler called when an app wants to modify a message update. </td></tr><tr><td><code>IPreMessageUpdatedPrevent</code></td><td>Handler which is called to determine whether a user is allowed to update a message or not.</td></tr></tbody></table>
+The table below contains the message-related events, as well as the purpose of each event. If you want to execute actions based on message events, you can use any of the events mentioned below as an event interface.
 
+<table><thead><tr><th width="297.5">Interface</th><th>Description</th></tr></thead><tbody><tr><td><code>IPostMessageDeleted</code></td><td>The handler after a message is deleted.</td></tr><tr><td><code>IPostMessageFollowed</code></td><td>The handler after a message has been followed or unfollowed. </td></tr><tr><td><code>IPostMessagePinned</code></td><td>The handler after a message is pinned or unpinned.</td></tr><tr><td><code>IPostMessageReacted</code></td><td>The handler after a message gets a reaction or a reaction is removed. </td></tr><tr><td><code>IPostMessageReported</code></td><td>The handler after a message is reported. </td></tr><tr><td><code>IPostMessageSent</code></td><td>The handler after a message is sent.</td></tr><tr><td><code>IPostMessageSentToBot</code></td><td>The handler after a DM is sent to a bot.</td></tr><tr><td><code>IPostMessageStarred</code></td><td>The handler after a message has been starred or unstarred. </td></tr><tr><td><code>IPostMessageUpdated</code></td><td>The handler after a message is updated.</td></tr><tr><td><code>IPreMessageDeletePrevent</code></td><td>The handler used to determine whether a user is allowed to delete a message or not. </td></tr><tr><td><code>IPreMessageSentExtend</code></td><td>The handler called when an app wants to extend a message.</td></tr><tr><td><code>IPreMessageSentModify</code></td><td>The handler called when an app wants to modify a message. </td></tr><tr><td><code>IPreMessageSentPrevent</code></td><td>The handler which is called to determine whether a user is allowed to send a message or not.</td></tr><tr><td><code>IPreMessageUpdatedExtend</code></td><td>The handler called when an app wants to extend a message update.</td></tr><tr><td><code>IPreMessageUpdatedModify</code></td><td>​​The handler called when an app wants to modify a message update. </td></tr><tr><td><code>IPreMessageUpdatedPrevent</code></td><td>The handler which is called to determine whether a user is allowed to update a message or not.</td></tr></tbody></table>

apps-engine/event-interfaces/room-event-interfaces.md

@@ -1,5 +1,5 @@
 # Room - Event Interfaces
 
-The table below contains all of the room-related events, as well as the purpose of each event. If you want to execute actions based on room events, you may use any of the events mentioned below as an event interface.
+The table below contains the room-related events, as well as the purpose of each event. If you want to execute actions based on room events, you can use any of the events mentioned below as an event interface.
 
-<table><thead><tr><th width="289.5">Interface</th><th>Purpose</th></tr></thead><tbody><tr><td><code>IPostRoomCreate</code></td><td>Handler for after a room is created.</td></tr><tr><td><code>IPostRoomCreate</code></td><td>Handler for after a room is deleted.</td></tr><tr><td><code>IPostRoomUserJoined</code></td><td><p>Event interface that allows an app to register as a handler of the `IPostRoomUserJoined`event. This event is triggered after a user successfully joins a room. This event does not allow an app to prevent any action from happening. For that, see its "pre-counterpart(s)":</p><p>- IPreRoomUserJoined</p></td></tr><tr><td><code>IPostRoomUserLeave</code></td><td><p>Event interface that allows an app to register as a handler of the `IPostRoomUserLeave`event. This event is triggered after a user successfully leaves a room. This event does not allow an app to prevent any action from happening. For that, see its "pre counterpart(s)":</p><p>- IPreRoomUserLeave</p></td></tr><tr><td><code>IPreRoomCreateExtend</code></td><td>Handler called when an app wants to enrich a room.</td></tr><tr><td><code>IPreRoomCreateModify</code></td><td>​​Handler called when an app wants to modify a room. </td></tr><tr><td><code>IPreRoomCreatePrevent</code></td><td>Handler called when an app wants to prevent the creation of a room. </td></tr><tr><td><code>IPreRoomDeletePrevent</code></td><td>Handler called when an app wants to prevent the deletion of a room. </td></tr><tr><td><code>IPreRoomUserJoined</code></td><td><p>Event interface that allows an app to register as a handler of the `IPreRoomUserJoined`event. This event is triggered prior to a user successfully</p><p>joining a room. To prevent the user from executing such an action, an app should throw the `UserNotAllowedException`. This event is not triggered before a room has been created. For that, check the `IPreRoomCreate` event.</p></td></tr><tr><td><code>IPreRoomUserLeave</code></td><td><p>Event interface that allows an app to register as a handler of the `IPreRoomUserLeave`event. This event is triggered prior to a user successfully</p><p>leaving a room. To prevent the user from executing such an action, an app should throw the `UserNotAllowedException`. This event is not triggered before a room has been created. For that, check the `IPreRoomCreate` event. </p></td></tr></tbody></table>
+<table><thead><tr><th width="281.5">Interface</th><th>Description</th></tr></thead><tbody><tr><td><code>IPostRoomCreate</code></td><td>Handler after a room is created.</td></tr><tr><td><code>IPostRoomCreate</code></td><td>Handler after a room is deleted.</td></tr><tr><td><code>IPostRoomUserJoined</code></td><td><p>Event interface that allows an app to register as a handler of the <code>IPostRoomUserJoined</code> event. </p><p></p><p>This event is triggered after a user successfully joins a room. This event does not allow an app to prevent any action from happening. For that, see the  <code>IPreRoomUserJoined</code> interface.</p></td></tr><tr><td><code>IPostRoomUserLeave</code></td><td><p>Event interface that allows an app to register as a handler of the <code>IPostRoomUserLeave</code> event. </p><p></p><p>This event is triggered after a user successfully leaves a room. This event does not allow an app to prevent any action from happening. For that, see the <code>IPreRoomUserLeave</code> interface.</p></td></tr><tr><td><code>IPreRoomCreateExtend</code></td><td>Handler called when an app wants to extend a room.</td></tr><tr><td><code>IPreRoomCreateModify</code></td><td>​​Handler called when an app wants to modify a room. </td></tr><tr><td><code>IPreRoomCreatePrevent</code></td><td>Handler called when an app wants to prevent the creation of a room. </td></tr><tr><td><code>IPreRoomDeletePrevent</code></td><td>Handler called when an app wants to prevent the deletion of a room. </td></tr><tr><td><code>IPreRoomUserJoined</code></td><td><p>Event interface that allows an app to register as a handler of the <code>IPreRoomUserJoined</code> event. </p><p></p><p>This event is triggered prior to a user successfully</p><p>joining a room. To prevent the user from executing such an action, an app should throw the <code>UserNotAllowedException</code>. This event is not triggered before a room has been created. For that, check the <code>IPreRoomCreate</code> event.</p></td></tr><tr><td><code>IPreRoomUserLeave</code></td><td><p>Event interface that allows an app to register as a handler of the <code>IPreRoomUserLeave</code> event. </p><p></p><p>This event is triggered prior to a user successfully</p><p>leaving a room. To prevent the user from executing such an action, an app should throw the <code>UserNotAllowedException</code>. This event is not triggered before a room has been created. For that, check the <code>IPreRoomCreate</code> event. </p></td></tr></tbody></table>

apps-engine/event-interfaces/settings-event-interfaces.md

@@ -1,5 +1,5 @@
 # Settings - Event Interfaces
 
-The table below contains all of the settings-related events, as well as the purpose of each event. If you want to execute actions based on settings events, you may use any of the events mentioned below as an event interface. 
+The table below contains the settings-related events, as well as the purpose of each event. If you want to execute actions based on settings events, you can use any of the events mentioned below as an event interface. 
 
-<table><thead><tr><th width="261.5">Interface</th><th>Purpose</th></tr></thead><tbody><tr><td><code>ISetting</code></td><td>Interface that represents a setting and fetches details of the setting such as ID, type, value, and so on.</td></tr><tr><td><code>ISettingUpdateContext</code></td><td>The context of execution for the event - ISettingUpdate. </td></tr><tr><td><code>SettingType</code></td><td>Interface that represents the setting type and fetches details on the type of setting configured for the app. </td></tr></tbody></table>
+<table><thead><tr><th width="261.5">Interface</th><th>Description</th></tr></thead><tbody><tr><td><code>ISetting</code></td><td>Interface that represents a setting and fetches details of the setting such as ID, type, value, and so on.</td></tr><tr><td><code>ISettingUpdateContext</code></td><td>The context of execution for the event - <code>ISettingUpdate</code>. </td></tr><tr><td><code>SettingType</code></td><td>Interface that represents the setting type and fetches details of the type of setting configured for the app. </td></tr></tbody></table>

apps-engine/event-interfaces/uploads-event-interfaces.md

@@ -1,5 +1,5 @@
 # Uploads - Event Interfaces
 
-The table below contains all of the upload-related events, as well as the purpose of each event. If you want to execute actions based on upload events, you may use any of the events mentioned below as an event interface. 
+The table below contains the upload-related events, as well as the purpose of each event. If you want to execute actions based on upload events, you can use any of the events mentioned below as an event interface. 
 
-<table><thead><tr><th width="265.5">Interface</th><th>Purpose</th></tr></thead><tbody><tr><td><code>IPreFileUpload</code></td><td><p>Event interface that allows an app to register as a handler of the `IPreFileUpload` event. This event is triggered prior to an upload successfully</p><p>being saved to the database, but *after* all its contents have been retrieved by Rocket.Chat. To prevent the upload from completing, an app should throw a `FileUploadNotAllowedException` with a message specifying the reason for rejection.</p></td></tr></tbody></table>
+<table><thead><tr><th width="238.5">Interface</th><th>Description</th></tr></thead><tbody><tr><td><code>IPreFileUpload</code></td><td><p>Event interface that allows an app to register as a handler of the <code>IPreFileUpload</code> event. </p><p></p><p>This event is triggered prior to an upload successfully being saved to the database, but only after all its contents have been retrieved by Rocket.Chat. To prevent the upload from completing, an app should throw a <code>FileUploadNotAllowedException</code> with a message specifying the reason for rejection.</p></td></tr></tbody></table>