update for message api rework

Author: willydouhard

api-reference/action.mdx

@@ -4,7 +4,7 @@ title: "Action"
 
 The `Action` class is designed to create and manage actions to be sent and displayed in the chatbot user interface. Actions consist of buttons that the user can interact with, and these interactions trigger specific functionalities within your app.
 
-### Parameters
+### Attributes
 
 <ParamField path="name" type="str">
   Name of the action, this should be used in the action_callback
@@ -32,7 +32,7 @@ import chainlit as cl
 
 @cl.action_callback("action_button")
 def on_action(action):
-    cl.send_message(f"Executed {action.name}")
+    cl.Message(content=f"Executed {action.name}").send()
     # Optionally remove the action button from the chatbot user interface
     action.remove()
 
@@ -43,5 +43,5 @@ def start():
         cl.Action(name="action_button", value="example_value", description="Click me!")
     ]
 
-    cl.send_message(content="Interact with this action button:", actions=actions)
+    cl.Message(content="Interact with this action button:", actions=actions).send()
 ```

api-reference/ask/ask-for-file.mdx

@@ -1,14 +1,14 @@
 ---
-title: "ask_for_file"
+title: "AskFileMessage"
 ---
 
 Ask the user to upload a file before continuing.
 If the user does not answer in time (see timeout), a TimeoutError will be raised or None will be returned depending on raise_on_timeout.
 If a project ID is configured, the messages will be uploaded to the cloud storage.
 
-### Parameters
+### Attributes
 
-<ParamField path="title" type="str">
+<ParamField path="content" type="str">
   Text displayed above the upload button.
 </ParamField>
 <ParamField path="accept" type="List[str]">
@@ -33,20 +33,23 @@ If a project ID is configured, the messages will be uploaded to the cloud storag
 ### Usage
 
 ```python Code Example
-from chainlit import send_message, ask_for_file, on_chat_start
+import chainlit as cl
 
 
-@on_chat_start
-def main():
-    file = None  # Wait for the user to upload a file
-    while file == None:
-        file = ask_for_file(
-            title="Please upload a text file to begin!", accept=["text/plain"]
-        )
+@cl.on_chat_start
+def start():
+    file = None
 
-    # Decode bytes to text
+    # Wait for the user to upload a file
+    while file == None:
+        file = cl.AskFileMessage(
+            content="Please upload a text file to begin!", accept=["text/plain"]
+        ).send()
+    # Decode the file
     text = file.content.decode("utf-8")
 
-    send_message(f"`{file.name}` uploaded, you can now ask questions!")
-
+    # Let the user know that the system is ready
+    cl.Message(
+        content=f"`{file.name}` uploaded, it contains {len(text)} characters!"
+    ).send()
 ```

api-reference/ask/ask-for-input.mdx

@@ -1,12 +1,12 @@
 ---
-title: "ask_for_input"
+title: "AskUserMessage"
 ---
 
 Ask for the user input before continuing.
 If the user does not answer in time (see timeout), a TimeoutError will be raised or None will be returned depending on raise_on_timeout.
 If a project ID is configured, the messages will be uploaded to the cloud storage.
 
-### Parameters
+### Attributes
 
 <ParamField path="content" type="str">
   The content of the message.
@@ -31,14 +31,14 @@ If a project ID is configured, the messages will be uploaded to the cloud storag
 ### Usage
 
 ```python Code Example
-from chainlit import send_message, ask_for_input, on_chat_start
+import chainlit as cl
 
 
-@on_chat_start
+@cl.on_chat_start
 def main():
-    res = ask_for_input(content="What is your name?")
+    res = cl.AskUserMessage(content="What is your name?", timeout=10).send()
     if res:
-        send_message(
+        cl.Message(
             content=f"Your name is: {res['content']}",
-        )
+        ).send()
 ```

api-reference/elements/local-image.mdx

@@ -4,7 +4,7 @@ title: "Local Image"
 
 The `LocalImage` class is designed to create and handle local image elements to be sent and displayed in the chatbot user interface.
 
-### Parameters
+### Attributes
 
 <ParamField path="name" type="str">
   The name of the image to be displayed in the UI.
@@ -39,7 +39,7 @@ elements = [
   LocalImage(name="image1", display="inline", path="./image1.jpg")
 ]
 
-cl.send_message(content="Look at this local image!", elements=elements)
+cl.Message(content="Look at this local image!", elements=elements).send()
 ```
 
 ### Usage without scope

api-reference/elements/remote-image.mdx

@@ -4,7 +4,7 @@ title: "Remote Image"
 
 The `RemoteImage` class allows you to display an image hosted remotely in the chatbot UI. Instead of uploading a local image, this class takes a URL of an image hosted online, creates an image element and sends it to the UI.
 
-### Parameters
+### Attributes
 
 <ParamField path="name" type="str">
   The name of the image to be displayed in the UI.
@@ -34,7 +34,7 @@ elements = [
     cl.RemoteImage(name="remote_image", url=image_url, display="inline")
 ]
 
-cl.send_message(content="Look at this remote image!", elements=elements)
+cl.Message(content="Look at this remote image!", elements=elements).send()
 ```
 
 ### Usage without scope

api-reference/elements/text.mdx

@@ -4,7 +4,7 @@ title: "Text"
 
 The `Text` class allows you to display a text element in the chatbot UI. This class takes a string and creates a text element that can be sent to the UI.
 
-### Parameters
+### Attributes
 
 <ParamField path="name" type="str">
   The name of the text element to be displayed in the UI.
@@ -35,7 +35,7 @@ elements = [
     cl.Text(name="simple_text", text=text_content, display="inline")
 ]
 
-cl.send_message(content="Check out this text element!", elements=elements)
+cl.Message(content="Check out this text element!", elements=elements).send()
 ```
 
 ### Usage without scope

api-reference/langchain/langchain-postprocess.mdx

@@ -4,7 +4,7 @@ title: "langchain_postprocess"
 
 Useful to post process the response a LangChain object instantiated with [@langchain_factory](/api-reference/langchain/langchain-factory).
 The decorated function takes the raw output of the LangChain object as input.
-The response will NOT be automatically sent to the UI, you need to call [send_message](/api-reference/send-message).
+The response will NOT be automatically sent to the UI, you need to send a [Message](/api-reference/message).
 
 ### Parameters
 
@@ -30,5 +30,5 @@ def main():
 
 @cl.langchain_postprocess
 def postprocess(output: str):
-    cl.send_message("In the end it doesn't even matter.")
+    cl.Message(content="In the end it doesn't even matter.").send()
 ```

api-reference/langchain/langchain-run.mdx

@@ -5,7 +5,7 @@ title: "langchain_run"
 Useful to override the default behavior of the LangChain object instantiated with [@langchain_factory](/api-reference/langchain/langchain-factory).
 Use when your agent run method has custom parameters.
 Takes the LangChain agent and the user input as parameters.
-The response will NOT be automatically sent to the UI, you need to call [send_message](/api-reference/send-message).
+The response will NOT be automatically sent to the UI, you need to send a [Message](/api-reference/message).
 
 ### Parameters
 
@@ -35,5 +35,5 @@ def main():
 @cl.langchain_run
 def run(agent, input_str):
     res = agent("2+2")
-    cl.send_message(res["text"])
+    cl.Message(content=res["text"]).send()
 ```

api-reference/send-message.mdx renamed to api-reference/message.mdx

@@ -1,11 +1,10 @@
 ---
-title: "send_message"
+title: "Message"
 ---
 
-Send a message to the chatbot UI.
-If a project ID is configured, the message will be uploaded to the cloud storage.
+The `Message` class is designed to send, stream, edit or remove messages in the chatbot user interface.
 
-### Parameters
+### Attributes
 
 <ParamField path="content" type="str">
   The content of the message.
@@ -37,18 +36,60 @@ If a project ID is configured, the message will be uploaded to the cloud storage
   If positive, the message will be nested in the UI.
 </ParamField>
 
-### Returns
+### Send a message
 
-<ResponseField name="response" type="str" required>
-  The message ID.
-</ResponseField>
+```python Code Example
+import chainlit as cl
+
+
+@cl.on_message
+def main(message: str):
+    cl.Message(
+        content=f"Received: {message}",
+    ).send()
+```
 
-### Usage
+### Stream a message
 
 ```python Code Example
-from chainlit import send_message, on_message
+import chainlit as cl
 
-@on_message
-def main(message: str):
-  send_message(content=f"Received: {message}")
+token_list = ["the", "quick", "brown", "fox"]
+
+
+@cl.on_chat_start
+def main():
+    msg = cl.Message(content="")
+    for token in token_list:
+        msg.stream_token(token)
+
+    msg.send()
+```
+
+### Update a message
+
+```python Code Example
+import chainlit as cl
+
+
+@cl.on_chat_start
+def main():
+    msg = cl.Message(content="Hello!")
+    msg.send()
+    cl.sleep(2)
+    msg.update(content="Hello again!")
+```
+
+### Remove a message
+
+```python Code Example
+import chainlit as cl
+
+
+@cl.on_chat_start
+def main():
+    msg = cl.Message(content="Message 1")
+    msg.send()
+    cl.sleep(2)
+    msg.remove()
 ```

api-reference/on-chat-start.mdx

@@ -4,17 +4,17 @@ title: "on_chat_start"
 
 Hook to react to the user websocket connection event.
 
-<RequestExample>
+### Usage
+
 ```python Code Example
-from chainlit import send_message, ask_for_input, on_chat_start
+from chainlit import AskUserMessage, Message, on_chat_start
 
 
 @on_chat_start
 def main():
-    res = ask_for_input(content="What is your name?")
+    res = AskUserMessage(content="What is your name?", timeout=30).send()
     if res:
-        send_message(
-            content=f"Your name is: {res['content']}",
-        )
+        Message(
+            content=f"Your name is: {res['content']}.\nChainlit installation is working!\nYou can now start building your own chainlit apps!",
+        ).send()
 ```
-</RequestExample>