# 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

| Prop                                         | Type   | Description                                                                                                                                                                                                                                            |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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:

| Output            | Type   | Description                                                                                                                                                                    |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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.

| Prop            | Description                                             |
| --------------- | ------------------------------------------------------- |
| 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.

| Prop                         | Description                                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 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.

| Prop                   | Default                 | Description                                  |
| ---------------------- | ----------------------- | -------------------------------------------- |
| 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.

| Prop              | Default         | Description                        |
| ----------------- | --------------- | ---------------------------------- |
| 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.

| Prop                 | Default | Description                                  |
| -------------------- | ------- | -------------------------------------------- |
| 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.

| Prop                    | Default | Description                                         |
| ----------------------- | ------- | --------------------------------------------------- |
| 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.

| Prop                   | Default           | Description                                                  |
| ---------------------- | ----------------- | ------------------------------------------------------------ |
| 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

| Scenario                                       | Button Label          | Action Fired                                                                                                             |
| ---------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 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:

1. Type a group name
2. Optionally tap the avatar area to pick a group image
3. Tap **Start** to confirm

* If a group image was picked → `onStartGroupConversation(name, image)` fires
* If 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

{% stepper %}
{% step %}

#### Database Requirements

Your app needs:

* A **Users** collection with: ID, Name, Avatar URL (plus any other fields you want displayed)
* A **Conversations** collection with at minimum: ID, ConversationKey (Text)
* A **Messages** collection linked to Conversations
  {% endstep %}

{% step %}

#### Basic Wiring

1. **Logged In User ID** → Logged In User > ID
2. **Users** → All Users (filtered to exclude the logged-in user if desired)
3. **User Fields > User ID** → User > ID
4. **User Fields > Name** → User > Name
5. **User Fields > Avatar URL** → User > Avatar URL
   {% endstep %}

{% step %}

#### Conversation Detection

1. **Find Existing Conversations** → Conversations filtered where: `ConversationKey = [Start Conversation > Selected User IDs]`
2. **Continue Conversation Setup > Conversations** → Same filtered collection
3. **Continue Conversation Setup > Conversation ID** → Conversation > ID
4. **Continue Conversation Setup > Continue Conversation Action** → Navigate to the Conversation screen, passing the Conversation ID
   {% endstep %}

{% step %}

#### Start Conversation Action

For 1-on-1 conversations:

1. Create a new Conversation record with `ConversationKey = [Selected User IDs]`
2. Navigate to the Conversation screen

For group conversations (use the **Start Conversation Action** trigger, not "With Image"):

1. Create a new Conversation record with `ConversationKey = [Selected User IDs]`, `GroupName = [Group Name]`
2. Navigate to the Conversation screen
   {% endstep %}

{% step %}

#### Start Group Conversation (With Image) Action

When a user picks a group image during group setup:

1. Create a new Conversation record with `ConversationKey = [Selected User IDs]`, `GroupName = [Group Name]`, `GroupImage = [Group Image]`
2. Navigate to the Conversation screen
   {% endstep %}
   {% endstepper %}

***

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.adalo.com/component-basics/marketplace-components/chat-suite/start-conversation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.