How to use Fluid Chat Web:
Place the Element: Drag and drop the Fluid Chat Native element onto your page. Make it fill the desired height and width (it's fully responsive!).

Load your Data (Update Action/Fields): In the property editor, map your database "Messages" to the corresponding lists (Text, Images, Audios, Creator IDs, Timestamps, etc.). Ensure all lists are sorted the exact same way (usually by Creation Date).

Setup Mentions: Map your "Users" data to the three mention fields (mention_names_list, mention_ids_list, mention_avatars_list) so the @ dropdown knows who to display.

Handle Sending (Workflow): Create a workflow: When Fluid Chat Native's message_sent is triggered. Use the exposed states (draft_text, draft_image_base64, draft_audio_base64) to create a new Message in your database.´

📂 How to handle Files (The String Engine):
To keep your Bubble database incredibly lightweight, Fluid Chat uses a powerful "Nested String" architecture instead of clunky database relations.

Your database should have a single text field for files (e.g., Files_List) and another for file names (e.g., Files_Names).

When loading the chat, feed your list of messages into the plugin using the :formatted as text operator.

The Golden Rule: Separate different messages using ||. If a single message contains multiple uploaded files, separate those files using a comma ,.

Example Output for the Plugin: url1.pdf,url2.pdf || url3.docx || url4.zip,url5.pdf

⚙️ Workflow for Sending Files/Audio:
The plugin unifies ALL media (Voice Notes, PDFs, Images) into a single event: A message is sent.

Use the trigger: When Fluid Chat (Pro) A message is sent

Create your Message in the DB.

For your Files field, simply Add list = This Fluid Chat (Pro)'s uploaded_files_urls.

For your File Names field, Add list = This Fluid Chat (Pro)'s uploaded_files_names.

(Note: Voice notes recorded via the mic will automatically be outputted as a 1-item list in the file states!)

Handle Actions (Workflow): Create a workflow: When Fluid Chat Native's long_press_triggered. Check the state last_action (e.g., "delete", "edit") and modify the database item matching the selected_message_id.

How to upgrade to the new Smart Reactions System:
Good news! You do not need to change your database structure. Your Reactions field remains a standard Text field. The plugin will automatically handle backward compatibility for older messages.

To enable the new smart toggling, just update your Bubble Workflow:

Delete your old reaction workflow (the one triggered by long_press_triggered).

Create a NEW Workflow Trigger: * Select When Fluid Chat (Pro) A message reaction was toggled.

Add the Action: * Data (Things) -> Make changes to a thing.

Thing to change: Do a search for the Message where Unique ID = This Fluid Chat (Pro)'s selected_message_id.

Field to change: Set your Reactions text field = This Fluid Chat (Pro)'s updated_reactions_string.

That's it! The plugin's engine will instantly calculate the math (adding, removing, or swapping the user's emoji based on their ID) and hand you the perfect, formatted string to save!

Handle Notifications: Use the user_mentioned event and the mentioned_user_ids state to send push notifications or emails to users tagged in a message!


💬 Setting up the Reply System:

Database: Add a new text field in your Messages database called Reply To ID.

Saving: In your "Message Sent" workflow, save the plugin's draft_reply_to_id state into this new database field.

Displaying: Map the plugin's reply_to_id_list property to Search for Messages's Reply To ID. The plugin will automatically connect the dots and draw the reply blocks!


🖼️ Setting up Multi-Image Galleries (Crucial Step):
To support multiple images per message without messing up Bubble's list indexes, the images_list property is now a single Text field (not a list).

In your database, store multiple image URLs as a single text string, separated by commas (e.g., url1.jpg, url2.jpg).

In the plugin properties, map images_list using the :format as text operator on your Search for Messages:

Content to show: This Message's Images :each item's URL join with ","

Delimiter: ||

The plugin will read the commas to create the photo grids, and the || to separate messages!


💬 How to setup the "Is Typing..." Indicator

🗄️ Step 1: Database Setup
Instead of messing with your Messages table, create a lightweight bridge table.

Create a new Data Type called Typing_Status (or Chat_Member).

Add these 3 fields:

Conversation (Type: Your Conversation Data Type)

User (Type: User)

is_typing (Type: yes/no, Default: no)

⚡ Step 2: The Workflows
Use the plugin's exposed is_typing state to toggle this database field.

When User Starts Typing:

Event: Do when condition is true -> Fluid Chat Pro's is_typing is yes

Action: Make changes to a thing -> Search for Typing_Status (Where User = Current User & Conversation = Current Chat) -> Set is_typing = yes.

When User Stops Typing (or sends the message):

Event: Do when condition is true -> Fluid Chat Pro's is_typing is no

Action: Make changes to a thing -> Set is_typing = no.

🔌 Step 3: Plugin Configuration
Now, just tell the plugin when to show the animation on the other user's screen!

Go to the Show Typing Indicator property of the Fluid Chat Pro element.

Insert this dynamic expression:
Do a search for Typing_Status (Constraints: Conversation = Current Chat, User ≠ Current User, is_typing = yes) :count > 0


1. Setting Up Infinite Scroll (Lazy Loading)
To prevent loading thousands of messages at once, you must control how many items Bubble sends to the plugin.

Step 1: Create a Custom State on your page (e.g., Chat_Container, type: Number, default value: 20). Let's call it Loaded_Messages.

Step 2: In your Plugin's Data Source fields (Message Text, Images, etc.), use your standard Search for Messages but add the modifier: :items until Loaded_Messages.

Step 3: Go to your Workflows and add a new event: "When Fluid Chat - Load More Triggered".

Step 4: Add an action to this workflow: Set State -> Loaded_Messages = Loaded_Messages + 20.

Magic: The plugin will detect the new messages, prepend them to the top of the chat, and perfectly anchor the scroll position so the user's screen doesn't jump!

2. Setting Up System Messages

Use the new Is System Message List field. Pass a list of "yes/no" (boolean) matching your messages. If "yes", the text will render as a centered date/event divider instead of a standard chat bubble.



Instructions for Fluid Chat Mobile

📸 How to Setup Image & Camera Uploads
To achieve zero-lag image previews, handle the file selection natively before sending it to your database.

1. Camera Setup

Trigger: Add a workflow for When Fluid Chat camera_pressed.

Action: Add the Bubble native action Open camera. (Crucial: Turn ON "Optimize image size" to prevent mobile memory crashes).

Store Locally: Add a Set State action. Save the Result of step 1's URL (do not use :saved to Bubble Storage).

2. Gallery Setup

Trigger: Add a workflow for When Fluid Chat attachment_pressed.

Action: Add the Bubble native action Open camera library.

Store Locally: Add a Set State action. Save the Result of step 1's URL.

3. Passing Images to the Chat

In the element's property panel, find the incoming_attachment field.

Map this field to your custom state where you saved the URLs.

Important: If you are passing a list of multiple images, format the custom state using join with ||| so the plugin can parse them seamlessly.

🎙️ How to Setup Audio Recording & Uploads
The audio engine uses a 4-step relay system to guarantee performance and prevent Bubble timeout errors.

1. Start the Engine

Trigger: When Fluid Chat mic_pressed

Action: Element Action -> Start Recording

2. Cancel Recording (Trash Icon)

Trigger: When Fluid Chat cancel_mic_pressed

Action: Element Action -> Stop Recording (This discards the audio).

3. Upload the Audio

Trigger: When Fluid Chat send_audio (Triggers when the user hits the send button while recording).

Action: Element Action -> Upload to Bubble.

Endpoint: Provide your app's file upload URL (e.g., [https://your-app.bubbleapps.io/version-test/fileupload](https://your-app.bubbleapps.io/version-test/fileupload)).

4. Save to Database

Trigger: When Fluid Chat voice_upload_finished

Action: Create a new Thing (Message).

Save the audio file using the element's exposed state: Fluid Chat's uploaded_voice_url.

Save the audio length using: Fluid Chat's recording_duration.


Download the full guide in the Demo Page.