> 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/chats.md).

# Chats

{% 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/chats.md).
{% endhint %}

The list of the site's chats: the site chat, task-group chats, custom groups and direct chats, with search, filters and a menu on each row.

![Chats](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-c08bfcc26fe15efb059b3bdcf12194008e5adcd4%2Fchats.png?alt=media)

* **Where:** web `/chat/:id` (`:id` is the site), side menu "Chat". The page title is "Messages" and the first tab is "Chats". iOS and Android: the chat icon in the bottom bar (its label is hidden; Android's hidden label is "CHAT").
* **Who:** any signed-in user on a site with chat on (`chatEnable`). The list has no role split; group actions depend on the group's admins ([Group info](https://docs.snapfix.com/how-the-apps-work/screens/chat/group-info.md)). With chat off, the web guard sends the user to `/fix`, and the page does the same when the site changes; the web side menu also hides "Chat" while a multi-site is selected. On iOS and Android the chat tab shows [My network](https://docs.snapfix.com/how-the-apps-work/screens/chat/my-network.md) instead. Where the per-site chat switch is set is not known \[[ASK-47](https://github.com/snapfix/docs/blob/main/ASK.md#ask-47-how-is-a-sites-chat-switched-off-and-who-should-be-able-to-do-it)].
* **Feature:** [Chat](https://docs.snapfix.com/product/features/chat/chat.md)

The "My Network" tab is [Chat contacts](https://docs.snapfix.com/how-the-apps-work/screens/chat/contacts.md). A row opens [Chat conversation](https://docs.snapfix.com/how-the-apps-work/screens/chat/conversation.md). Messages inside a task stay on [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#task-chat).

## Layout

**Web**, left column, top to bottom. The open conversation fills the column on the right; with none open it says "Select a chat to start messaging".

1. Title "Messages".
2. Tabs "Chats" and "My Network". The language file has "MY NETWORK"; the live app shows "My Network".
3. A "Search" box and a round "+" button, then the filter tabs "All", "My Chats", "Groups" and "Archived". "Archived" shows the number of archived chats that have unread messages. The same filter tabs stay on the "My Network" tab and change the shared filter, so the Chats list behind it changes too.
4. The chat list, newest activity first. Once the list has loaded, the first chat that is not archived opens by itself. A `chatID` query (and an optional `messageID`) opens that chat instead; both are then removed from the address.

**iOS:** a "CHATS" / "MY NETWORK" toggle with a "+" button, then the chips "All", "My Chats", "Group Chats", "My Network" and "Archived", and a search icon. "Archived" has a badge. Search replaces the chips with a "Search" field. The list has pull to refresh. The "My Network" chip lists the site's users inside this screen, next to the separate "MY NETWORK" page.

**Android:** the same chips, a search icon, and the list with pull to refresh. The "My Network" chip swaps the list for the site's users ([Chat contacts](https://docs.snapfix.com/how-the-apps-work/screens/chat/contacts.md)). The layout has a floating "+" that stays hidden; the working "+" is the app's top "+" while the chat tab is selected.

**Each row** shows the image (initials for a direct chat; an archive mark when the chat is archived), the name, the last-message line, a mute mark when the chat is muted and not archived, the unread count, the time, and a more button ("⋮" on the web). The open chat is highlighted.

* The name of a task-group chat or a custom group is translated. A direct chat and the site chat keep the name as stored. The site chat uses the site's current name and image.
* The last-message line shows a draft first: web "Draft:" and the text whenever a draft is stored; iOS and Android only while the unread count is 0. Otherwise it shows the sender ("You:" or the sender's full name) and the text. A voice message shows a microphone and "Voice message" when it has no text. A photo shows a camera and "Photo" when the text is empty or "Photo". An audit line (joins, leaves, removals) has no sender. Long lines end with an ellipsis.
* Lines seen live: "You: Reacted 👍 to "…"", "You created this group" and "You: Deleted this message".
* The web escapes this line before putting it in the page. Message bodies in the conversation are not escaped.
* The time is "HH:mm" today, "Yesterday", the weekday name within the last week, and "DD/MM/YYYY" after that.
* Unread count: web shows the count, or "999+" above 999, and hides it when you sent the last message. Android shows the count, or "99+" above 99, and an empty badge when the count is 0 but a message is newer than `last_seen_ts`. iOS shows the count, or nothing when it is 0.
* The bottom-bar or side-menu badge is the number of chats with unread messages, not counting archived chats (and, on the web, the open chat).

## Inputs

| Field             | Type                       | Required | Default | Rules and messages                                                                                                                                                                                                                                                                                                                       |
| ----------------- | -------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filter            | Tabs (web), chips (mobile) | No       | "All"   | "All": every chat that is not archived. "My Chats": direct chats and custom groups, not archived. "Groups" (mobile "Group Chats"): the site chat and task-group chats, not archived; custom groups are not in it. "Archived": archived chats only. "My Network" (mobile only): the site's users.                                         |
| Search ("Search") | Text                       | No       | Empty   | Matches the chat name; no validation. Web and iOS filter as you type. Android waits 250 ms. Android's search keeps archived chats inside "All", "My Chats" and "Group Chats", also when the field is cleared. Under the iOS "My Network" chip it matches user names. A search with no match shows "No chats found matching your search." |

## Actions

| Action                | Who             | What happens                                                                                                                                                                                                                                                                                                                                                                                      | API                                                                                                                                                                             |
| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the page         | Anyone, chat on | Signs in to Firestore, then listens to this user's chat entries for the site. If the site chat does not exist yet, the web creates it from the site name and image, with every user of the site. The web also loads the site's users for names and for [Chat contacts](https://docs.snapfix.com/how-the-apps-work/screens/chat/contacts.md).                                                      | [`GET /v1/app/chat/token`](https://docs.snapfix.com/engineering-reference/api/chat.md#get-v1appchattoken), [users](https://docs.snapfix.com/engineering-reference/api/users.md) |
| Open a chat           | Anyone          | Opens [Chat conversation](https://docs.snapfix.com/how-the-apps-work/screens/chat/conversation.md) and marks it read: unread count 0, last-seen time now. The web opens it beside the list; iOS and Android open it as its own screen. Opening a task-group chat on the web checks the group; on 403 or 404 the chat leaves the list and the web shows "You no longer have access to this group." | [`GET /v1/app/businesses/{uuid}`](https://docs.snapfix.com/engineering-reference/api/groups.md) for task groups                                                                 |
| "+" (web)             | Anyone          | Opens [New group chat](https://docs.snapfix.com/how-the-apps-work/screens/chat/new-group.md). The web makes groups only; a direct chat starts from [Chat contacts](https://docs.snapfix.com/how-the-apps-work/screens/chat/contacts.md). With no users loaded it loads them first; on failure an alert says "Failed to load users. Please try again."                                             | [users](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                            |
| "+" (iOS and Android) | Anyone          | Opens a sheet to pick people or a task group. One person opens a direct chat, two or more open [New group chat](https://docs.snapfix.com/how-the-apps-work/screens/chat/new-group.md), and a task group opens that group's chat.                                                                                                                                                                  | [users](https://docs.snapfix.com/engineering-reference/api/users.md)                                                                                                            |
| Row menu              | Anyone          | Web: the "⋮" button. Android: the more button or a long press. iOS: the row's menu button only; the long press is registered but does nothing.                                                                                                                                                                                                                                                    |                                                                                                                                                                                 |
| "Mark as unread"      | Anyone          | Sets `last_seen_ts` to one millisecond before the last message. Web toast "Chat marked as unread". On the web the row shows no badge afterwards, because the badge needs an unread count; only the side-menu total rises.                                                                                                                                                                         | Firestore only                                                                                                                                                                  |
| Mute or unmute        | Anyone          | Sets `mute_group` on the user's chat membership and chat entry. No push for that chat while muted. Web toasts "Chat muted successfully", "Group muted successfully", "Chat unmuted successfully" or "Group unmuted successfully".                                                                                                                                                                 | Firestore only                                                                                                                                                                  |
| Archive or unarchive  | Anyone          | Sets `is_archived` the same way; the chat moves to "Archived" for this user only. Web toasts "Chat archived successfully", "Group archived successfully", "Chat unarchived successfully" or "Group unarchived successfully".                                                                                                                                                                      | Firestore only                                                                                                                                                                  |
| "Group Info"          | Group rows      | Opens [Group info](https://docs.snapfix.com/how-the-apps-work/screens/chat/group-info.md). A deleted custom group offers only this item on the web.                                                                                                                                                                                                                                               |                                                                                                                                                                                 |
| "Delete Chat"         | Direct chats    | Deletes only this user's chat entry, with no confirmation. Web toast "Chat deleted successfully". The messages stay, so the chat comes back when someone writes again.                                                                                                                                                                                                                            | Firestore only                                                                                                                                                                  |
| "Leave Group"         | Custom groups   | See [Leave group](#leave-group). The site chat and task-group chats have no leave action.                                                                                                                                                                                                                                                                                                         | Firestore only                                                                                                                                                                  |
| Pull to refresh       | iOS, Android    | Reloads the chat entries and, on Android, the site's users. Each iOS refresh adds another Firestore listener and never removes it.                                                                                                                                                                                                                                                                |                                                                                                                                                                                 |
| Switch site           | Anyone          | Reloads the list for the new site. Web: `/chat/<site id>`, or `/fix` when that site has chat off.                                                                                                                                                                                                                                                                                                 |                                                                                                                                                                                 |

Sort order is newest activity first. The web uses the last message time. iOS uses the draft time whenever a draft is stored, even when a message arrived later. Android uses the draft time only when it is later than the last message.

### Leave group

Custom groups only.

* **Web** leaves at once, with no confirmation. It marks the user deleted in the group, writes the audit message `{user id} left the group`, sets the other members' chat entries to " left the group", and deletes the user's own entry. Toast "Successfully left the group". The only admin gets the alert "Cannot Leave Group" / "Each group requires at least one admin. Please assign another user as an admin before leaving the group." and stays. A deleted group: "Cannot leave a deleted group". Failure: "Failed to leave group".
* **iOS** asks "Leave this group?" / "By leaving this group, you will no longer receive messages from it, and it will be removed from your chat." with "Leave". The only admin gets the same admin sentence with "Ok" and stays. Confirming marks the user deleted and deletes the user's entry. It builds a "left" audit message but never sends it, unlike leaving from [Group info](https://docs.snapfix.com/how-the-apps-work/screens/chat/group-info.md).
* **Android** asks the same question in a sheet with "Leave". The only admin gets the same admin sentence and stays. While it runs: "Leaving group…".

### Where the data lives

Chat data is in Firestore, not in the SQL database; the web and the apps read and write it directly. Each site has its own Firestore area, named after the site ID with a `p_` prefix. The API has no endpoint to list, create or delete a site or group chat ([Chat API](https://docs.snapfix.com/engineering-reference/api/chat.md)).

| Item                           | What it holds                                                                                                                                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recent_chats/{person}/{chat}` | One entry per person per chat: the last message and its time, the sender, the unread count, the draft, the mute and archive flags, and whether the chat is a task group (`is_snapfix_group`)                        |
| `{chat}/messages/{message}`    | Each message: type (`text`, `image`, `voice`, `audit` or `task_audit`), text, file address, sender, reply, mentions, read times (`read_by`), and flags for deleted and forwarded. Reactions sit in a subcollection. |
| `{chat}/users/{person}`        | One member: admin flag, deleted flag (left or removed), mute and archive flags                                                                                                                                      |
| `{chat}/metadata/{group}`      | The group's name, picture, description and deleted flag                                                                                                                                                             |

* Chat IDs: a direct chat is the two user IDs joined by `_`, smaller first. A custom group uses its group ID, a task-group chat the task group's ID, and the site chat the site's ID.
* The web creates the site chat the first time anyone opens Chat, with the site's users at that time. A user who joins later has no site-chat entry on the web until someone sends a message there from the web, which writes an entry for every site user.
* Who may read or write chat data is decided by Firestore rules, which are in none of the repos \[[ASK-43](https://github.com/snapfix/docs/blob/main/ASK.md#ask-43-where-are-the-firebase-rules-that-guard-chat-data)]. The token from [`GET /v1/app/chat/token`](https://docs.snapfix.com/engineering-reference/api/chat.md#get-v1appchattoken) lists, as `p_{site ID}`, the sites of the task groups and asset registers the user belongs to.

## States

* **Loading:** web: skeleton rows. The language file has "Loading chats...", but nothing shows it. iOS and Android: the pull-to-refresh spinner until the first data arrives.
* **Empty:** web, by filter: "No recent chats found." ("All", or no chat at all), "You have no personal chats to show." ("My Chats"), "You are not in any groups." ("Groups"), "You have no archived chats." ("Archived"). A search with no match: "No chats found matching your search." iOS and Android show an empty list with no text.
* **Error:** web: a failed action shows its toast, such as "Failed to mark chat as unread", "Failed to update mute settings", "Failed to archive chat" (for any archive or unarchive failure), "Failed to delete chat", "Chat not found" or "User UUID not available", and the list does not change. A failed load stops the skeleton and is written to the console; the list then shows the empty-state text, as if there were no chats. A Firestore permission error on Android signs in again with a new token and retries.
* **Stale row:** live, the site chat's row shows a date and no last-message line. The date is later than the newest message in the conversation (16/10/2026 against 24/09/2026 on 2026-11-12)
* **No permission:** chat off, as in **Who**. With the testing flag on (it is on), the web does not drop chats the user has left or whose custom group was deleted elsewhere; it lists them in the pop-up "Chats Removed (Testing Only)".
* **Offline (mobile):** no offline state of its own. Android turns on Firestore's on-device cache, so the last list can show; iOS uses Firestore's defaults. What shows without a connection was not checked.

## Dialogs and sheets

### Chat menu

The row menu of each chat: a menu on the web, a bottom sheet on iOS and Android.

| Item                 | Direct chat | Custom group | Deleted custom group (web) | Site chat or task group |
| -------------------- | ----------- | ------------ | -------------------------- | ----------------------- |
| "Mark as unread"     | Yes         | Yes          | No                         | Yes                     |
| Mute or unmute       | Yes         | Yes          | No                         | Yes                     |
| Archive or unarchive | Yes         | Yes          | No                         | Yes                     |
| "Group Info"         | No          | Yes          | Yes                        | Yes                     |
| "Delete Chat"        | Yes         | No           | No                         | No                      |
| "Leave Group"        | No          | Yes          | No                         | No                      |

Labels: the web says "Mute Chat" / "Unmute Chat" and "Archive Chat" / "Unarchive Chat" on a direct chat, and "Mute Group" / "Unmute Group" and "Archive Group" / "Unarchive Group" on a group. Android uses the same mute labels and "Archive" / "Unarchive" for every row. iOS uses "Mute Chat" / "Unmute Chat" and "Archive" / "Unarchive" for every row.

### Chats Removed (Testing Only)

Web only. Lists the chats the membership check would drop, each with a reason, and a "Dismiss" button. The reasons show as raw keys (`CHAT.REASON_…`) or the English "Group deleted".

### Notification prompt (Android 13 and later)

After the system notification permission was refused: "Chat is live - don't miss a thing!", "Turn on notifications to get real-time updates and stay connected with your team.", "Turn on notifications" (opens the app's system settings, with the toast "Tap on Permissions and allow permissions.") and "Maybe later".

## Platform differences

| Topic                 | Web              | iOS                                       | Android                               |
| --------------------- | ---------------- | ----------------------------------------- | ------------------------------------- |
| Conversation          | beside the list  | its own screen                            | its own screen                        |
| First chat            | opens by itself  | not opened                                | not opened                            |
| Groups filter         | "Groups"         | "Group Chats"                             | "Group Chats"                         |
| Contacts              | "My Network" tab | "My Network" chip and a "MY NETWORK" page | "My Network" chip                     |
| "+"                   | new group dialog | sheet: people or a task group             | sheet: people or a task group         |
| Row menu              | "⋮"              | menu button only                          | more button or long press             |
| Draft in the sort     | ignored          | always, while a draft exists              | only when newer than the last message |
| Unread cap            | "999+"           | the full count                            | "99+"                                 |
| Mute label on a group | "Mute Group"     | "Mute Chat"                               | "Mute Group"                          |
| Leave confirmation    | none             | yes                                       | yes                                   |
| Multi-site            | menu item hidden | the selected site's chats                 | the selected site's chats             |


---

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