================================================           💬 WEBSOCKET CHAT CONNECTOR
================================================

📋 QUICK START GUIDE
--------------------------------------------------

▶ STEP 1: Add the Chat Element
 • Drag the 'WebSocket Chat' element onto your page.
 • Set the element's height to "100%" or a fixed pixel value.
   (Note: Avoid "Auto" height for best scrolling results).

▶ STEP 2: Configure Properties
 Provide the following required Dynamic Data:
 • websocket_server  -> wss://your-domain.com
 • current_user_id   -> Current User's Unique ID
 • current_user_name -> Current User's Name
 • room_id           -> Unique Conversation ID

▶ STEP 3: Add Message Input
 1. Add a standard Bubble Text Input.
 2. Add a Button labeled "Send".
 3. Workflow for Button:
    Action: Plugins -> WebSocket Chat -> Send Message
    Value: Input's value.
 4. Action: Reset relevant inputs.

▶ STEP 4: Test!
 • Preview your page and check the status bar for "Connected".


📡 WEB-SOCKET SERVER PROTOCOL
--------------------------------------------------

[ CLIENT TO SERVER ]

 // 1. Get History (Sent on Connection)
 {
   "action": "get_history",
   "user_id": "user123",
   "room": "room456",
   "limit": 50
 }

 // 2. Send Message (Sent on Button Click)
 {
   "action": "send_message",
   "text": "Hello!",
   "user_id": "user123",
   "sender": "John Doe",
   "room": "room456",
   "timestamp": "2026-01-11T22:38:04Z"
 }


[ SERVER TO CLIENT ]

 // 1. History Response
 {
   "type": "history",
   "messages": [
      { "id": "1", "text": "Hi", "sender": "Jane", "sender_id": "u7" }
   ]
 }

 // 2. New Message Broadcast
 {
   "type": "message",
   "id": "msg_003",
   "text": "New alert!",
   "sender": "Jane Smith",
   "sender_id": "user789"
 }


✨ CUSTOM UI MODE (BETA)
--------------------------------------------------
Build your own chat interface using Bubble Repeating Groups.

👉 STEP 1: Toggle Mode
  • Set 'show_built_in_ui' to "no".

👉 STEP 2: Access the Data Stream
  • Use the state 'messages_json'. This updates in real-time.
  • Structure: Array of objects [{id, text, sender, etc}].

👉 STEP 3: Build the UI
  • Option A: Listen for the 'message_received' event.
  • Option B: Parse 'messages_json' into a Repeating Group.

👉 STEP 4: Alignment Logic
  • Conditional: When This Cell's sender_id is Current User's ID
    -> Align Right / Color: Blue
  • Conditional: When This Cell's sender_id is NOT Current User's ID
    -> Align Left / Color: Gray


⚠️ TROUBLESHOOTING
--------------------------------------------------

🚫 Status: "Connection Error"
  • Verify your server is running.
  • Check that you are using 'wss://' for SSL sites.
  • Ensure your firewall port is open.

🌑 Messages Not Showing
  • Check that 'room_id' on the server matches the plugin 'room_id'.
  • Ensure IDs are being sent as Strings, not Numbers.

🔄 Alignment is Inverted
  • Ensure 'sender_id' matches the 'current_user_id' exactly.


🏆 BEST PRACTICES
--------------------------------------------------
🔒 SECURITY: Always use wss:// for production.
⚡ PERFORMANCE: Keep history_limit between 50 and 100.
🎮 UX: Show the 'connection_status' state to your users.


==============================================
Try it out in the editor:

https://bubble.io/page?id=chat-demo-16170&app_type=mobile&tab=Design&name=Home&elements=bTHDZ