docs: Update docs for async event handlers

Author: tjtanjin

docs/api/events.md

@@ -51,7 +51,9 @@ Events emitted by the chatbot provide the following **details** accessible via `
 | currPath  | `string` | Represents the current path of the user.                        |
 | prevPath  | `string` | Represents the previous path of the user.                       |
 
-In addition, all events also contain **event-specific data** that are accessible via `event.data`. You may manipulate the data directly which will be reflected in the result of the event (e.g. modifying the content of a `RcbPreMessageInjectEvent` will modify the message sent).
+In addition, chatbot events are also initialized with **an empty promises array**, accessible via `event.promises`. This caters for use cases where event handlers are **async and require promises to be resolved before proceeding** with the chatbot logic. Push promises into `event.promises` to preserve the chatbot flow logic.
+
+Lastly, all events also contain **event-specific data** that are accessible via `event.data`. You may manipulate the data directly which will be reflected in the result of the event (e.g. modifying the content of a `RcbPreMessageInjectEvent` will modify the message sent). For an example on how to use events, you may take a look at the [**custom events**](/docs/examples/custom_events) example.
 
 Below is a detailed description of each event and how to use them.
 

docs/api/hooks.md

@@ -112,7 +112,7 @@ The `useAudio` hook allows you to track and manage the chatbot's audio functiona
 | Name           | Type       | Description                                            |
 | -------------- | ---------- | ------------------------------------------------------ |
 | audioToggledOn | `boolean ` | Indicates if the chatbot audio is currently on or off. |
-| toggleAudio    | `function` | Toggles the chatbot audio on or off.                   |
+| toggleAudio    | `async function` | Toggles the chatbot audio on or off.                   |
 
 #### Code Example
 ```jsx
@@ -184,7 +184,7 @@ The `useChatWindow` hook allows you to track and manage the chatbot's window sta
 | Name                | Type       | Description                                              |
 | ------------------- | ---------- | -------------------------------------------------------- |
 | isChatWindowOpen    | `boolean`  | Indicates if the chat window is currently open or close. |
-| toggleChatWindow    | `function` | Toggles the chat window open or close.                   |
+| toggleChatWindow    | `async function` | Toggles the chat window open or close.                   |
 
 #### Code Example
 ```jsx
@@ -300,7 +300,7 @@ The `useNotifications` hook allows you to track and manage the chatbot's notific
 | Name                   | Type       | Description                                                    |
 | ---------------------- | ---------- | -------------------------------------------------------------- |
 | notificationsToggledOn | `boolean ` | Indicates if the chatbot notifications is currently on or off. |
-| toggleNotifications    | `function` | Toggles the chatbot notifications on or off.                   |
+| toggleNotifications    | `async function` | Toggles the chatbot notifications on or off.                   |
 | playNotificationSound  | `function` | Plays the notification sound.                                  |
 
 #### Code Example
@@ -426,7 +426,7 @@ The `useTextArea` hook allows you to track and manage the chatbot's text area fi
 | textAreaSensitiveMode        | `boolean`   | Indicates if the text area is in sensitive mode.         |
 | toggleTextAreaSensitiveMode  | `function`  | Toggles the text area sensitive mode.                    |
 | getTextAreaValue             | `function`  | Retrieves the string value inside the text area.         |
-| setTextAreaValue             | `function`  | Sets the value inside the text area, identical to `params.setTextAreaValue` detailed [**here**](/docs/api/params#settextareavalue).                     |
+| setTextAreaValue             | `async function`  | Sets the value inside the text area, identical to `params.setTextAreaValue` detailed [**here**](/docs/api/params#settextareavalue).                     |
 | focusTextArea                | `function`  | Focuses on the text area.                                |
 
 #### Code Example
@@ -456,8 +456,8 @@ The `useToasts` hook allows you to track and manage the chatbot's toasts.
 #### Return Values
 | Name                         | Type        | Description                                              |
 | ---------------------------- | ----------- | -------------------------------------------------------- |
-| showToast     | `function`  | Shows a toast in chat, identical to `params.showToast` detailed [**here**](/docs/api/params#showtoast).    |
-| dismissToast  | `function`  | Dismisses a toast from chat, identical to `params.dismissToast` detailed [**here**](/docs/api/params#dismisstoast).                  |
+| showToast     | `async function`  | Shows a toast in chat, identical to `params.showToast` detailed [**here**](/docs/api/params#showtoast).    |
+| dismissToast  | `async function`  | Dismisses a toast from chat, identical to `params.dismissToast` detailed [**here**](/docs/api/params#dismisstoast).                  |
 | toasts        | `Array<Toast>`     | Array containing all toasts currently shown in the chatbot                 |
 | replaceToasts | `function`  | Directly replaces the current toasts with provided toasts.  |
 
@@ -489,7 +489,7 @@ The `useVoice` hook allows you to track and manage the chatbot's voice functiona
 | Name           | Type       | Description                                            |
 | -------------- | ---------- | ------------------------------------------------------ |
 | voiceToggledOn | `boolean ` | Indicates if the chatbot voice is currently on or off. |
-| toggleVoice    | `function` | Toggles the chatbot voice on or off.                   |
+| toggleVoice    | `async function` | Toggles the chatbot voice on or off.                   |
 
 #### Code Example
 ```jsx

docs/api/params.md

@@ -18,20 +18,20 @@ The following table provides details about the parameters available for attribut
 | userInput       | `string`            | All Attributes    | Represents the user's input in the chat.                                                                                          |
 | currPath        | `string`            | All Attributes    | Represents the current path in the chat (can be null if conversation flow has not started).                                                 |
 | prevPath        | `string`            | All Attributes    | Represents the previous path in the chat (can be null if no previous path exists).                                                 |
-| goToPath        | `function`          | All Attributes    | A utility function for navigating to another block.                                                                                |
+| goToPath        | `async function`          | All Attributes    | A utility function for navigating to another block.                                                                                |
 | injectMessage   | `async function`    | All Attributes    | A utility function to inject a message into the chat.   |
 | streamMessage   | `async function`    | All Attributes    | Streams a message into the chat. You can refer to the [**Real-Time Streaming**](/docs/examples/real_time_stream) example.          |
 | endStreamMessage   | `async function`    | All Attributes    | Ends an existing message stream. You can refer to the [**Real-Time Streaming**](/docs/examples/real_time_stream) example.          |
 | removeMessage   | `async function`    | All Attributes    | Removes a message from the chat by message id.          |
-| setTextAreaValue| `function`          | All Attributes    | Sets a value directly within the text area.                                                                                        |
-| showToast       | `function`          | All Attributes    | Shows a toast that is dismissed after a duration or on user click.                                                                                                          |
-| dismissToast       | `function`          | All Attributes    | Dismisses a toast by toast id.                                                                                                          |
-| openChat        | `function`          | All Attributes    | Opens or closes the chat component.                                                                                               |
+| setTextAreaValue| `async function`          | All Attributes    | Sets a value directly within the text area.                                                                                        |
+| showToast       | `async function`          | All Attributes    | Shows a toast that is dismissed after a duration or on user click.                                                                                                          |
+| dismissToast       | `async function`          | All Attributes    | Dismisses a toast by toast id.                                                                                                          |
+| openChat        | `async function`          | All Attributes    | Opens or closes the chat component.                                                                                               |
 | files           | `FileList`          | Only `file` Attribute | Represents the files uploaded by the user.                                                                                        |
 
 :::caution Caution
 
-If you are using `params.injectMessage`, `params.streamMessage`, `params.endStreamMessage` or `params.removeMessage`, do remember that they are `async` and that without using `await`, behavior may be unexpected (e.g. multiple messages sent at once). This is a common pitfall!
+If you are using functions from `params`, do remember that they are `async` and that without using `await`, behaviors may be unexpected (e.g. multiple messages sent at once). This is a common pitfall!
 
 :::
 
@@ -216,16 +216,16 @@ start: {
 Sets a value inside the input text area.
 
 #### Type
-`function`
+`async function`
 
 #### Parameters
 - `value` (required): a `string` value to set inside the input text area.
 
 #### Code Example
 ```jsx
 start: {
-  message: (params) => {
-    params.setTextAreaValue("This is the new input text area value!");
+  message: async (params) => {
+    await params.setTextAreaValue("This is the new input text area value!");
   }
 }
 ```
@@ -236,7 +236,7 @@ start: {
 Shows a toast that lasts for a duration (if specified).
 
 #### Type
-`function`
+`async function`
 
 #### Parameters
 - `content` (required): a `string` value representing the toast content to show.
@@ -245,8 +245,8 @@ Shows a toast that lasts for a duration (if specified).
 #### Code Example
 ```jsx
 start: {
-  message: (params) => {
-    params.showToast("Hello there, I last for 3 seconds!", 3000);
+  message: async (params) => {
+    await params.showToast("Hello there, I last for 3 seconds!", 3000);
   }
 }
 ```
@@ -257,16 +257,16 @@ start: {
 Dismisses a toast with the given toast id.
 
 #### Type
-`function`
+`async function`
 
 #### Parameters
 - `id` (required): a `string` value representing the id of the toast to remove.
 
 #### Code Example
 ```jsx
 start: {
-  message: (params) => {
-    params.dismissToast("fb8bf309-2a33-4683-955c-9e915768dadf");
+  message: async (params) => {
+    await params.dismissToast("fb8bf309-2a33-4683-955c-9e915768dadf");
   }
 }
 ```
@@ -277,16 +277,16 @@ start: {
 Sets the chat window to be open or close.
 
 #### Type
-`function`
+`async function`
 
 #### Parameters
 - `isOpen` (required): a `boolean` indicating if chat window should be set open.
 
 #### Code Example
 ```jsx
 start: {
-  message: (params) => {
-    params.openChat(true);
+  message: async (params) => {
+    await params.openChat(true);
   }
 }
 ```
@@ -305,8 +305,8 @@ List of files uploaded by the user (only present in the [**file attribute**](/do
 #### Code Example
 ```jsx
 start: {
-  message: (params) => {
-    params.openChat(true);
+  file: (params) => {
+    console.log(params.files);
   }
 }
 ```

docs/examples/custom_events.md

@@ -26,15 +26,29 @@ const MyChatBot = () => {
 	};
 
 	React.useEffect(() => {
+		// synchronous function
 		const handleUserSubmitText = (event: RcbUserSubmitTextEvent) => {
 			if (event.data.inputText.toLowerCase().includes("hello")) {
 				event.preventDefault();
 			}
 		};
 
+		// asynchronous function
+		const handleToggleNotifications = async (event: RcbToggleNotificationsEvent) => {
+			// simulates an async call with a 1 second delay
+			const mockApiCall = new Promise((resolve) => setTimeout(() => {
+				resolve("Notifications toggled successfully!");
+			}, 1000));
+
+			// collect promises for eventual resolution before chatbot logic proceeds
+			event.promises.push(mockApiCall);
+		}
+
 		window.addEventListener("rcb-user-submit-text", handleUserSubmitText);
+		window.addEventListener("rcb-toggle-notifications", handleToggleNotifications);
 		return () => {
 			window.removeEventListener("rcb-user-submit-text", handleUserSubmitText);
+			window.removeEventListener("rcb-toggle-notifications", handleToggleNotifications);
 		};
 	}, []);