# Conversation Action Button

A smart three-state button that automatically adapts based on your user selection. It's disabled when no users are selected, shows **Start Conversation** when no matching conversation exists, and switches to **Continue Conversation** when one does — all without any conditional logic on your end.

***

## Before You Begin

* This component is designed to work alongside the [**Chat User Picker**](/component-basics/marketplace-components/chat-suite/start-conversation/chat-user-picker.md). The User Picker outputs a **Selected User IDs** value — this button reads it.
* Your **Conversations** collection should have a field (e.g., `participant_key`) that stores a sorted, comma-separated string of participant IDs. This is what the button uses to detect whether a conversation already exists.

***

## Getting Started

{% stepper %}
{% step %}

### Add the component

Add the **Conversation Action Button** to the same screen as your **Chat User Picker**.
{% endstep %}

{% step %}

### Bind the selected count

In the **Selected Count** field, bind to the **Chat User Picker**'s **Selected Count** Magic Text output. The button is disabled when this value is 1 or less (only the logged-in user is selected, nobody else chosen yet).
{% endstep %}

{% step %}

### Configure conversation matching

In the **Conversations** section, choose your Conversations collection and filter it where `participant_key` equals the **Chat User Picker**'s **Selected User IDs** Magic Text output. This is how the button detects an existing conversation.
{% endstep %}

{% step %}

### Map conversation fields

Open **Conversation Fields** and map **Conversation ID** to your conversation's ID field. Then set up the **Continue Conversation Action** — typically navigate to the conversation screen and pass the conversation ID.
{% endstep %}

{% step %}

### Set up the start action

Set up the **Start Conversation Action** — this fires when no matching conversation exists. Use it to create a new conversation record, add participant relationships, then navigate to the new conversation.
{% endstep %}
{% endstepper %}

***

## Settings

### Button Style

* **Start Text** — The label shown when no matching conversation exists. Defaults to "Start Conversation."
* **Continue Text** — The label shown when a matching conversation is found. Defaults to "Continue Conversation."
* **Active Color** — Background color of the button when active (start or continue state).
* **Disabled Outline Color** — The outline color when the button is disabled (no users selected yet).
* **Text Color** — Label color in the active state.
* **Disabled Text Color** — Label color in the disabled state.
* **Font Size** — Button label size in pixels (12–24, default: 16).
* **Font Weight** — Regular, Medium, Semi Bold, or Bold.
* **Border Radius** — Corner roundness of the button (0–24, default: 8).
* **Disabled Border Width** — The outline thickness when the button is in its disabled state (1–4px).

### Group Name (optional)

When a user starts a conversation with more than one other person, the button can prompt them to name the group first. Configure the popup with:

* **Group Name Placeholder** — Placeholder text inside the group name input.
* **Popup Background Color** — Background of the group name prompt.

The **Group Name** and **Group Image** are passed as arguments to the **Start Conversation Action** so you can save them to your database.

***

## Actions

* **Start Conversation Action** — Fires when the button is active and no existing conversation is found. Magic Text arguments: **Group Name** and **Group Image** (for group chats). Use this action to create a conversation record, add participants, then navigate to the conversation screen.
* **Continue Conversation Action** — Set inside **Conversation Fields**. Fires when a matching conversation is found. Typically navigates to the existing conversation and passes the conversation ID.

***

## How the Three States Work

| State                     | When                                            | Appearance                         |
| ------------------------- | ----------------------------------------------- | ---------------------------------- |
| **Disabled**              | Selected Count ≤ 1                              | Outlined, greyed out, not tappable |
| **Start Conversation**    | Selected Count > 1, no matching conversation    | Filled, active color               |
| **Continue Conversation** | Selected Count > 1, matching conversation found | Filled, active color               |

The component checks the Conversations list you provided. If the list has at least one record, it shows **Continue Conversation** and fires the continue action. If the list is empty, it shows **Start Conversation** and fires the start action.

***

## Tips

* Filter your Conversations collection as tightly as possible — `participant_key = Selected User IDs`. Since Selected User IDs is a sorted string, an exact match means you've found the right conversation (no duplicates).
* Wire **Start Conversation** to: (1) Create conversation, (2) Add participant relationships, (3) Navigate to conversation screen. Pass the new conversation ID via Magic Text.
* The button works for both 1-on-1 and group conversations — the group name prompt only appears when more than one other user is selected.

***

## Need Help?

Visit [forum.adalo.com](https://forum.adalo.com/) to ask questions or share what you've built.


---

# 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/conversation-action-button.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.