Describe & update app callbacks

api-reference/lifecycle-hooks/audio-chunk.mdx

@@ -0,0 +1,16 @@
+---
+title: "audio_chunk"
+---
+
+Hook to react to an incoming audio chunk from the user's microphone.
+
+## Usage
+
+```python
+import chainlit
+
+
+@chainlit.on_audio_chunk
+async def on_audio_chunk(chunk: chainlit.InputAudioChunk):
+    pass
+```

api-reference/lifecycle-hooks/on-audio-end.mdx → api-reference/lifecycle-hooks/audio-end.mdx

@@ -1,5 +1,5 @@
 ---
-title: "on_audio_end"
+title: "audio_end"
 ---
 
 Hook to react to the end of an audio recording coming from the user's microphone.

api-reference/lifecycle-hooks/audio-start.mdx

@@ -0,0 +1,17 @@
+---
+title: "audio_start"
+---
+
+Hook to react to the end of an audio recording coming from the user's microphone.
+
+## Usage
+
+```python
+from io import BytesIO
+import chainlit as cl
+
+
+@cl.on_audio_end
+async def on_audio_end():
+    pass
+```

api-reference/lifecycle-hooks/header-auth-callback.mdx

@@ -0,0 +1,4 @@
+---
+title: "header_auth_callback"
+url: "/authentication/header"
+---

api-reference/lifecycle-hooks/oauth-callback.mdx

@@ -0,0 +1,4 @@
+---
+title: "oauth_callback"
+url: "/authentication/oauth"
+---

api-reference/lifecycle-hooks/on-app-shutdown.mdx

@@ -0,0 +1,21 @@
+---
+title: "on_app_shutdown"
+---
+
+Hook to run code when the Chainlit application shuts down.
+
+Useful for cleaning up resources, closing connections, saving state, etc.
+
+The function can be synchronous or asynchronous.
+
+## Usage
+
+```python Code Example
+import chainlit
+
+
+@chainlit.on_app_shutdown
+async def on_app_shutdown():
+    print("Application is shutting down!")
+    # Clean up resources here
+```

api-reference/lifecycle-hooks/on-app-startup.mdx

@@ -0,0 +1,21 @@
+---
+title: "on_app_startup"
+---
+
+Hook to run code when the Chainlit application starts.
+
+Useful for initializing resources, loading models, setting up database connections, etc.
+
+The function can be synchronous or asynchronous.
+
+## Usage
+
+```python Code Example
+import chainlit
+
+
+@chainlit.on_app_startup
+async def startup():
+    print("Application is starting!")
+    # Initialize resources here
+```

api-reference/lifecycle-hooks/on-chat-resume.mdx

@@ -14,13 +14,22 @@ This decorator will automatically:
   Only JSON serializable fields of the user session will be saved and restored.
 </Warning>
 
+## Parameters
+
+<ParamField path="thread" type="ThreadDict">
+  The persisted chat to resume.
+</ParamField>
+
 ## Usage
 
-At minimum, you will need to use the `@cl.on_chat_resume` decorator to resume conversations.
+At minimum, you will need to use the `@chainlit.on_chat_resume` decorator to resume conversations.
 
 ```python
-@cl.on_chat_resume
-async def on_chat_resume(thread):
+import chainlit
+from chainlit import ThreadDict
+
+@chainlit.on_chat_resume
+async def on_chat_resume(thread: ThreadDict):
     pass
 ```
 
@@ -34,9 +43,3 @@ However, if you are using a Langchain agent for instance, you will need to reins
 >
   Practical example of how to resume a chat with context.
 </Card>
-
-## Parameters
-
-<ParamField path="thread" type="ThreadDict">
-  The persisted chat to resume.
-</ParamField>

api-reference/lifecycle-hooks/on-chat-start.mdx

@@ -7,11 +7,12 @@ Hook to react to the user websocket connection event.
 ## Usage
 
 ```python Code Example
-from chainlit import AskUserMessage, Message, on_chat_start
+import chainlit
+from chainlit import AskUserMessage, Message
 
 
-@on_chat_start
-async def main():
+@chainlit.on_chat_start
+async def on_chat_start():
     res = await AskUserMessage(content="What is your name?", timeout=30).send()
     if res:
         await Message(

api-reference/lifecycle-hooks/on-logout.mdx

@@ -18,10 +18,10 @@ Decorator to react to a user logging out. Useful to clear cookies or other user
 ```python
 from fastapi import Request, Response
 
-import chainlit as cl
+import chainlit
 
 
-@cl.on_logout
+@chainlit.on_logout
 def main(request: Request, response: Response):
     response.delete_cookie("my_cookie")
 ```

api-reference/lifecycle-hooks/on-message.mdx

@@ -7,17 +7,17 @@ The decorated function is called every time a new message is received.
 
 ## Parameters
 
-<ParamField path="message" type="cl.Message">
+<ParamField path="message" type="chainlit.Message">
   The message coming from the UI.
 </ParamField>
 
 ## Usage
 
 ```python
-import chainlit as cl
+import chainlit
 
-@cl.on_message
-def main(message: cl.Message):
+@chainlit.on_message
+def on_message(message: chainlit.Message):
   content = message.content
   # do something
 ```

api-reference/lifecycle-hooks/on-window-message.mdx

@@ -0,0 +1,4 @@
+---
+title: "on_window_message"
+url: "/api-reference/window-message#on-window-message"
+---

api-reference/lifecycle-hooks/password-auth-callback.mdx

@@ -0,0 +1,4 @@
+---
+title: "password_auth_callback"
+url: "/authentication/password"
+---

api-reference/lifecycle-hooks/send-window-message.mdx

@@ -0,0 +1,4 @@
+---
+title: "send_window_message"
+url: "/api-reference/window-message#send-window-message"
+---

api-reference/window-message.mdx

@@ -4,39 +4,44 @@ title: "Window Messaging"
 
 # on_window_message
 
-Decorator to react to messages coming from the Web App's parent window.
+Decorator to react to JavaScript [window message events](https://developer.mozilla.org/en-US/docs/Web/API/Window/message_event) coming from the Web App's parent window.
 The decorated function is called every time a new window message is received.
 
 ## Parameters
 
-<ParamField path="message" type="str">
-  The message coming from the Web App's parent window.
+<ParamField path="data" type="typing.Any">
+  Window message event data coming from the Web App's parent window.
 </ParamField>
 
 ## Usage
 
-```python
-import chainlit as cl
+```python Code Example
+from typing import Any
 
-@cl.on_window_message
-def main(message: str):
-  # do something
+import chainlit
+
+
+@chainlit.on_window_message
+async def on_window_message(message: Any):
+    print(message) # can be a string, dict, TypedDict, etc.
 ```
 
 # send_window_message
 
-Function to send messages to the Web App's parent window.
+Function to send messages to the Web App's parent window via a [window.postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) method.
 
 ## Parameters
 
-<ParamField path="message" type="str">
-  The message to send to the Web App's parent window.
+<ParamField path="data" type="typing.Any">
+  The data to send with the event to the Web App's parent window.
 </ParamField>
 
 ## Usage
 
-```python
-@cl.on_message
-async def message():
-  await cl.send_window_message("Server: Hello from Chainlit")
+```python Code Example
+import chainlit
+
+
+# can be a string, dict, TypedDict, etc
+chainlit.send_window_message({ "greeting": "Hello World!" })
 ```

authentication/oauth.mdx

@@ -211,7 +211,8 @@ def oauth_callback(
   provider_id: str,
   token: str,
   raw_user_data: Dict[str, str],
-  default_user: cl.User,
+  default_app_user: cl.User,
+  id_token: Optional[str]
 ) -> Optional[cl.User]:
   return default_user
 ```
@@ -228,7 +229,8 @@ def oauth_callback(
   provider_id: str,
   token: str,
   raw_user_data: Dict[str, str],
-  default_user: cl.User,
+  default_app_user: cl.User,
+  id_token: Optional[str]
 ) -> Optional[cl.User]:
   if provider_id == "google":
     if raw_user_data["hd"] == "example.org":

authentication/password.mdx

@@ -18,7 +18,7 @@ from typing import Optional
 import chainlit as cl
 
 @cl.password_auth_callback
-def auth_callback(username: str, password: str):
+def auth_callback(username: str, password: str) -> Optional[cl.User]:
     # Fetch the user matching username from your database
     # and compare the hashed password with the value stored in the database
     if (username, password) == ("admin", "admin"):

concepts/chat-lifecycle.mdx → concepts/app-lifecycle.mdx

@@ -1,5 +1,5 @@
 ---
-title: Chat Life Cycle
+title: App Lifecycle
 ---
 
 Whenever a user connects to your Chainlit app, a new chat session is created. A chat session goes through a life cycle of events, which you can respond to by defining hooks.

concepts/user-session.mdx

@@ -2,7 +2,7 @@
 title: User Session
 ---
 
-The user session is designed to persist data in memory through the [life cycle](/concepts/chat-lifecycle) of a chat session. Each user session is unique to a user and a given chat session.
+The user session is designed to persist data in memory through the [life cycle](/concepts/app-lifecycle) of a chat session. Each user session is unique to a user and a given chat session.
 
 ## Why use the user session?
 
@@ -60,21 +60,25 @@ The following keys are reserved for chat session related data:
 <ParamField path="id" type="str">
   The session id.
 </ParamField>
+
 <ParamField path="user" type="cl.User">
   Only set if you are enabled [Authentication](/authentication). Contains the
   user object of the user that started this chat session.
 </ParamField>
+
 <ParamField path="chat_profile" type="str">
   Only relevant if you are using the [Chat
   Profiles](/advanced-features/chat-profiles) feature. Contains the chat profile
   selected by this user.
 </ParamField>
+
 <ParamField path="chat_settings" type="Dict">
   Only relevant if you are using the [Chat
   Settings](/advanced-features/chat-settings) feature. Contains the chat
   settings given by this user.
 </ParamField>
+
 <ParamField path="env" type="Dict" default="{}">
-  Only relevant if you are using the [user_env](/backend/config/project) config.
+  Only relevant if you are using the [user\_env](/backend/config/project) config.
   Contains the environment variables given by this user.
 </ParamField>