> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/how-the-apps-work/screens/chat/new-group.md).

# New group chat

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). Platforms: web, iOS and Android. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/chat/new-group.md).
{% endhint %}

Create a custom chat group: its picture, name, description (web only) and members.

![New group chat](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-50983c336ebb4770b44237bf6e754de3c4477da8%2Fnew-group.png?alt=media)

* **Where:** web: the "+" beside the search box in [Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md), a dialog. iOS and Android: the "+" in Chats opens the create-chat sheet; picking two or more people opens the group form.
* **Who:** any signed-in user on a site with chat on; no role is checked. The creator becomes the group's only admin (`is_admin`, `is_creator`); the people added are members.
* **Feature:** [Chat](https://docs.snapfix.com/product/features/chat/chat.md)

On iOS and Android, picking one person in the sheet opens a direct [conversation](https://docs.snapfix.com/how-the-apps-work/screens/chat/conversation.md) instead, and picking a task group opens that task group's chat. Adding people later is in [Group info](https://docs.snapfix.com/how-the-apps-work/screens/chat/group-info.md).

## Layout

### Web

A dialog in three steps with a progress header ("Chat Group Details", "Members", "Preview"). The dialog title follows the step.

1. **Chat Group Details** ("Enter the basic information for your new group"): the group picture (a placeholder with an edit badge that opens the file picker), "Chat Group Name" with a red "\*", and "Chat Group Description (Optional)".
2. **Select Members** ("Choose members to add to your group"): "Selected Members (n)" as removable chips, a "Search by name" box, and "Available Users (n)" as a checkbox list with pictures and names.
3. **Preview** ("Review your group before creating"): the picture, name, description, and the members with you marked "(You)".

The footer has "Back" (on step 1 it closes the dialog), "Cancel", and "Next" (steps 1 and 2) or "Create Group" (step 3). "Next" stays off until the step is valid; "Create Group" is off and shows a spinner while the group is being made.

### iOS and Android

1. **Create-chat sheet:** "Create a New Chat" / "Start a 1:1 chat or a custom chat group (many users).", the tabs "Users" and "Task Groups" with search ("Search users"), and "Start Chat". On the task-group tab the text is "Start a chat group with all users from your task group.". The same sheet, in add mode, adds members from [Group info](https://docs.snapfix.com/how-the-apps-work/screens/chat/group-info.md).
2. **Group form** ("New Group"): a picture button (camera or gallery; Android crops it square), the name field ("Group Name"), the picked members, including you, as a strip you can remove people from ("Members : n" on iOS, "Members: n" on Android), and "Done" (iOS) or a create button (Android). iOS turns "Done" off, and Android hides the button, when only you are left.

## Inputs

| Field       | Type                      | Required                             | Default                   | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ------------------------- | ------------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Picture     | Image file                | No                                   | The default group picture | Web: the file type must start with `image/`, else "Please select an image file.". It uploads when the group is made; on failure the web shows "Failed to upload image. Please try again." and still makes the group, storing the local default path as its picture. iOS: when the upload returns nothing, the group is not made and no message shows.                                                                                                 |
| Name        | Text                      | Yes                                  | Empty                     | Web: 2 to 50 characters; the box stops at 50. The code has "Chat group name is required", "Chat group name must be at least 2 characters" and "Chat group name cannot exceed 50 characters", but live none of them showed: with one character "Next" just stayed off, also after the field lost focus. iOS and Android: any non-empty name, no length limit; empty shows "Please enter a group name." (iOS) or "Please enter a group name" (Android). |
| Description | Text                      | No                                   | Empty                     | Web only, up to 200 characters; the box stops at 200 ("Description cannot exceed 200 characters"). The apps make the group with no description.                                                                                                                                                                                                                                                                                                       |
| Members     | Checkbox list with search | Yes, at least one other person (web) | None                      | Web: the site's users except you, A to Z, including people who have never signed in; search matches name and username, 300 ms after typing stops. No match: "No users found matching your search."; nobody to pick: "No users available.". iOS and Android: two or more people picked in the sheet, so a new group has at least three people.                                                                                                         |

## Actions

| Action                                                      | Who                | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                  | API                                                                                                                      |
| ----------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| "Next" / "Back" / "Cancel" (web)                            | Anyone             | Moves between the steps, or closes without making anything.                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                                                                          |
| "Start Chat" (mobile sheet)                                 | Anyone             | One person: the direct chat. Two or more: the group form. A task group: that group's chat.                                                                                                                                                                                                                                                                                                                                                                    |                                                                                                                          |
| "Create Group" (web), "Done" (iOS), create button (Android) | Anyone, valid form | Uploads the picture, then writes the group: its record (name, picture, description), you as admin and creator, the members, a chat entry for each member, and the audit line "created this group" ("You created this group" for you). Members' lists show "… added you". The web opens the new chat about 0.7 seconds later; live, no toast showed. Web failure: "Failed to create group. Please try again." Android shows "Creating group..." while it runs. | Web picture: [`POST /v1/app/upload`](https://docs.snapfix.com/engineering-reference/api/files.md); the rest is Firestore |

## States

* **Loading:** "Create Group" is off while the group is made; the member list uses the users already loaded in [Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md). iOS shows a progress indicator while the picture uploads.
* **Empty:** "No users available." when nobody is left to pick; "No users found matching your search." for a search.
* **Error:** the web alerts above, and "Failed to load users. Please try again." when "+" cannot load the users ([Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md)); the dialog keeps what was entered.
* **No permission:** none; any signed-in user can make a group.
* **Offline (mobile):** no offline state of its own.

## Platform differences

| Topic                     | Web                                  | iOS                        | Android                 |
| ------------------------- | ------------------------------------ | -------------------------- | ----------------------- |
| Steps                     | details, members, preview            | sheet, then the group form | sheet, then "New Group" |
| Description               | optional, up to 200                  | none                       | none                    |
| Name length               | 2 to 50                              | not limited                | not limited             |
| Fewest people picked      | one other                            | two others                 | two others              |
| Failed picture upload     | group made with a default path       | group not made, no message | not checked             |
| Task groups in the picker | no; they are under "Groups" in Chats | yes                        | yes                     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/how-the-apps-work/screens/chat/new-group.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
