Start Conversation
A combined user picker and action button for starting or continuing conversations. Pick one or more users from a searchable list, then tap the button at the bottom — it automatically shows Start Conversation or Continue Conversation depending on whether a matching conversation already exists.
Overview
The Start Conversation component replaces the old "Chat User Picker + Conversation Action Button" two-component setup with a single, self-contained component. It handles user selection, conversation detection, group name/image entry, and action routing all in one place.
Props
Top-Level
Logged In User ID
Number
The current user's ID. This user is always included in the selected IDs output and shown as "(You)" in the list.
Users
List
The collection of users to display in the picker.
Find Existing Conversations
List
A filtered Conversations collection. When this list has any results, the button shows "Continue Conversation" instead of "Start Conversation". Filter this to conversations where the ConversationKey equals the component's Selected User IDs output.
Start Conversation Action
Action
Fires when starting a new 1-on-1 conversation, or a group conversation without an image. Group Name is available as Magic Text.
Start Group Conversation (With Image) Action
Action
Fires when starting a group conversation where the user picked a group image. Group Name and Group Image are available as Magic Text.
Advanced Options (Hidden Outputs)
These are available as Magic Text throughout your app via the form value system:
Selected User IDs
Text
Comma-separated, sorted list of selected user IDs (including the logged-in user). Use this to filter conversations and as the ConversationKey when creating new conversations.
Selected Count
Number
Number of users currently selected (not including the logged-in user).
User 2 ID
Number
The ID of the first selected user (for 1-on-1 conversations).
User 2 Name
Text
The name of the first selected user.
User 2 Image URL
Text
The avatar URL of the first selected user.
Child Components
User Fields
Bind each column from your Users collection to the picker rows.
User ID
The user's database ID (required for selection to work)
Name
Displayed as the primary name in each row
Avatar URL
User's profile image
Line 2
Optional second line of text (e.g. email, username)
Line 3
Optional third line of text (e.g. user ID, role)
When Selected
Action that fires when this user is selected
When Deselected
Action that fires when this user is deselected
Continue Conversation Setup
Bind conversation data for the Continue Conversation flow.
Conversations
The conversations list (same as "Find Existing Conversations" — bind to the same filtered collection)
Conversation ID
The conversation's database ID
Continue Conversation Action
Action that fires when the user taps "Continue Conversation" — use this to navigate to the conversation screen
Button Style
Customize the Start/Continue button appearance.
Start Label
"Start Conversation"
Button text when no existing conversation
Continue Label
"Continue Conversation"
Button text when existing conversation found
Active Color
#007AFF
Button background when enabled
Text Color
#FFFFFF
Button label color
Disabled Outline Color
#CCCCCC
Border color when no users selected
Disabled Text Color
#CCCCCC
Text color when no users selected
Font Size
16
Button label font size
Font Weight
Semi Bold
Button label weight
Border Radius
8
Button corner radius
Button Height
50
Button height in pixels
Group Name Prompt
Customize the popup that appears when starting a group conversation.
Input Placeholder
"Group name..."
Placeholder text in the name field
Popup Background
#FFFFFF
Background color of the popup card
Name Style / Line 2 Style / Line 3 Style
Font size, weight, and color for each text row in the user list.
Toggle
Customize the selection indicator on each user row.
Size
26
Toggle diameter in pixels
Active Color
#007AFF
Fill color when selected
Inactive Color
#CCCCCC
Border color when unselected
Checkmark Color
#FFFFFF
Icon color when selected
Show Selected Icon
true
Show an icon inside the toggle when selected
Selected Icon
check
Material icon name for selected state
Show Unselected Icon
false
Show an icon when unselected
Shape
Circle
Circle, Square, or Rounded Square
Styling
Control the list layout and spacing.
List Background
#FFFFFF
Background color of each row
Selected Row Background
#E8F4FD
Background color of selected rows
Divider Color
#EEEEEE
Color of the row separator lines
Show Divider
true
Toggle row dividers on/off
Avatar Size
48
Profile image size in pixels
Row Height
72
Height of each user row
Users Per Page
20
Number of users to show before a "Load More" button
Load More Color
#007AFF
Color of the "Load More" text
Search Bar
Customize the search field at the top of the list.
Placeholder
"Search users..."
Search input placeholder
Background Color
#F0F0F0
Search field background
Text Color
#333333
Search input text
Border Radius
8
Search field corner radius
Show Search Icon
true
Show the search icon inside the field
Search Icon
search
Material icon for the search field
Sticky While Scrolling
true
Keep the search bar pinned at the top while the list scrolls
How It Works
User Selection
Tapping a user row toggles their selection on/off.
The logged-in user (matched by Logged In User ID) always appears in the list but cannot be deselected — they are always included in the Selected User IDs output.
Selected rows are highlighted with the Selected Row Background color.
Button Logic
0 users selected
Disabled
—
1 user selected, no existing conversation
Start Conversation
onStartConversation (no arguments)
1 user selected, existing conversation found
Continue Conversation
onContinue from Continue Conversation Setup
2+ users selected, no existing conversation
Start Conversation
Prompts for group name/image, then onStartConversation(groupName) or onStartGroupConversation(groupName, groupImage)
2+ users selected, existing conversation found
Continue Conversation
onContinue from Continue Conversation Setup
Conversation Detection
Filter the Find Existing Conversations list by ConversationKey = [Selected User IDs]. When that filtered list returns any results, the button automatically switches to "Continue Conversation".
Group Conversations
When 2+ users are selected and no existing conversation is found, tapping the button opens a group name prompt. The user can:
Type a group name
Optionally tap the avatar area to pick a group image
Tap Start to confirm
If a group image was picked →
onStartGroupConversation(name, image)firesIf no image →
onStartConversation(name)fires
Group Name and Group Image are available as Magic Text inside both action triggers.
Selected User IDs Format
The output is a sorted, comma-separated string of numeric IDs including the logged-in user, e.g.: "16,17,21". Sorting ensures the same conversation is always found regardless of the order users were selected — use this as your ConversationKey field in the Conversations collection.
Setup Guide
Conversation Detection
Find Existing Conversations → Conversations filtered where:
ConversationKey = [Start Conversation > Selected User IDs]Continue Conversation Setup > Conversations → Same filtered collection
Continue Conversation Setup > Conversation ID → Conversation > ID
Continue Conversation Setup > Continue Conversation Action → Navigate to the Conversation screen, passing the Conversation ID
Start Conversation Action
For 1-on-1 conversations:
Create a new Conversation record with
ConversationKey = [Selected User IDs]Navigate to the Conversation screen
For group conversations (use the Start Conversation Action trigger, not "With Image"):
Create a new Conversation record with
ConversationKey = [Selected User IDs],GroupName = [Group Name]Navigate to the Conversation screen
Tips
Search is client-side — it filters the already-loaded users list by name. For very large user bases, pre-filter your Users collection to a relevant subset.
Users Per Page controls pagination. Increase it if you want fewer "Load More" taps; decrease it for better initial load performance.
Sticky While Scrolling keeps the search bar pinned. Turn it off if you prefer the search bar to scroll with the list.
The component's height in the builder matches what you see in the preview — drag the bottom handle to fill the screen for the best appearance.
Was this helpful?