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

# Chat conversation

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

One site, group or direct chat: messages with photos and voice notes, replies, reactions, forwards and edits, and turning a message into a task.

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

* **Where:** web `/chat/:id?chatID=` (with `messageID` to jump to one message; both are cleared after the chat opens), a chat picked in [Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md) or [Chat contacts](https://docs.snapfix.com/how-the-apps-work/screens/chat/contacts.md). iOS and Android: a chat in Chats, a chat notification, a contact in Chat contacts, a mention or avatar in another chat, or a task group chosen in the "+" sheet.
* **Who:** the members of the chat. Any member who can still post can send, reply, react, forward, copy and create a task from a message. The sender can edit and delete their own messages; on iOS and Android a group admin can also delete other people's messages, and on the web nobody can. People who left or were removed cannot send (see [States](#states)).
* **Feature:** [Chat](https://docs.snapfix.com/product/features/chat/chat.md). Messages inside a task are on [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#task-chat), with the task chat API.

Messages are stored in Firestore ([Where the data lives](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md#where-the-data-lives)). Pushes after a message, a mention or a reaction go through [`POST /v1/app/notification/send`](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend).

## Layout

**Web**, the right column of [Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md), top to bottom:

1. **Header:** the picture (initials in a direct chat), the name, and an info button that opens [Group info](https://docs.snapfix.com/how-the-apps-work/screens/chat/group-info.md), [Contact info](https://docs.snapfix.com/how-the-apps-work/screens/chat/contact-info.md) or the site's info panel. A task-group or custom group name is translated; a direct chat and the site chat are not.
2. **Messages**, newest at the bottom, 20 at a time; scrolling to the top loads older ones with a spinner, and new ones arrive live. A sticky day label sits on each day: "Today", "Yesterday", the weekday name for the last six days, then the date. A button to jump to the newest message shows while you are scrolled up, with the number of messages that arrived meanwhile.
3. **Message box**, unless the custom group is deleted or you are marked deleted in it: a "+" button ("Photo" and "Record a voice message"), a text box with the placeholder "Type a message...", and a send button. A reply chip with a ✕ sits above the box while you reply, and a preview for a pasted picture.

**iOS and Android:** one full screen with the same header and a back button, the message list (iOS loads 30 at a time, Android 50) and a composer with camera and voice buttons, a text box ("Type Message" on iOS, "Add a message" on Android) and a send button. A long press opens the reactions and the message actions; a swipe replies.

**Each message** shows:

* The sender's picture and name on other people's messages.
* The text with links and @mentions highlighted, a photo (with its caption), a voice note with its length, or an audit line as a card in the middle ("You created this group", "Task created from Chat" with "View Task").
* A quoted reply when there is one; clicking the quote scrolls to the original and highlights it.
* "Forwarded" on forwarded messages, "Edited" when the text changed after sending.
* The time. On the web a text message shows "HH:mm" and a photo message the short 12-hour time, so one screen mixes "19:21" and "6:53 PM".
* Read ticks on your own messages ([Read receipts](#read-receipts)).
* Reactions under the bubble: up to three emoji and the total count. Clicking them lists who reacted with what, filtered by "All" or by emoji, with "Click to remove" on your own. The chip stays under a message after the message is deleted.
* A deleted message keeps its place: "⊘ You deleted this message" for your own, "⊘ Message has been deleted" for other people's. The chat list shows "You: Deleted this message" for the same event.
* Received text that the site translates offers "Translating...", then "See original" or "Show translation".

On the web, message text and audit lines are set as HTML without escaping.

A welcome card tops the chat once every message is loaded, and an empty chat (so it shows briefly while a long chat loads):

| Chat            | Text                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Site chat       | "Welcome to Group Chat. Perfect for company communication and announcements."                                             |
| Task-group chat | "Welcome to your Group Chat. This Group Chat is synced to your Group.", or "… synced to your Snapfix Group." with no name |
| Custom group    | "Welcome to your Group Chat."                                                                                             |
| Direct chat     | "Welcome to your 1:1 Chat."                                                                                               |

## Inputs

| Field      | Type                | Required                                  | Default                                 | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------- | ------------------- | ----------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Message    | Text, several lines | Yes, unless a photo or voice note is sent | Empty, or the draft saved for this chat | Web: Enter sends, Shift+Enter adds a line, Escape cancels a reply. Send stays off while the box is empty. The web has a 5,000-character check on the box, but the box never feeds it, so any length is sent; live, a 5,144-character message went out in full. Whether the apps limit a group message is not known.                                                                                      |
| Mention    | "@" and a name      | No                                        | None                                    | Typing "@" opens "Mention a user" with the chat's members (picture, name and "@username"); arrow keys and Enter pick one, and no match shows "No users found". The sent text shows "@Name", and the person gets a push ([Push notifications](#push-notifications)). On the web, Escape closes the whole conversation, also while this list is open.                                                      |
| Photo      | Image file          | Yes, to send a photo                      | None                                    | Web: "+" then "Photo" opens "Upload image" with a crop step and a caption; a pasted image also works, with "Pasted image preview" and the text in the box as its caption. iOS: the camera screen in chat mode, with a caption. Android: camera or gallery, with a caption; in a multi-pick, a video over 40 MB is skipped with "Snapfix allows video size up to 40 MB. Please choose video up to 40 MB". |
| Voice note | Recording           | Yes, to send one                          | None                                    | Web: "+" then "Record a voice message"; the dialog says "Tap to record" and "Tap to stop", and "Send voice message" sends. The web has no time limit. Without microphone permission the web shows the raw key "TASKS.PROVIDE\_MICROPHONE\_PERMISSION". iOS and Android: hold the voice button, "Slide To Cancel"; recording stops at 10 minutes.                                                         |
| Edit       | Text                | Yes                                       | The current text                        | Web dialog "Edit message", placeholder "Enter message": "Message is required" when empty, "Message cannot exceed 5000 characters" above 5,000, and "Confirm" stays off. The box itself stops at 5,000 characters, so the second message cannot appear by typing. iOS and Android: a sheet "Edit Message" with "Update"; empty text is not saved.                                                         |

## Actions

| Action                     | Who                                               | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | API                                                                                                                                                                          |
| -------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send text                  | Any member who can post                           | Adds the message, updates every member's chat entry (last message, unread count) and clears the draft. The web clears the box before sending; a failed send is only logged, so the text is lost. On iOS, a group message sent before the group's details load shows on screen but is not saved.                                                                                                                                                                              | Firestore; push: [`POST /v1/app/notification/send`](https://docs.snapfix.com/engineering-reference/api/chat.md#post-v1appnotificationsend)                                   |
| Send photo                 | Any member who can post                           | Uploads the photo, then adds an `image` message with the caption.                                                                                                                                                                                                                                                                                                                                                                                                            | [`POST /v1/app/upload`](https://docs.snapfix.com/engineering-reference/api/files.md) on the web and iOS, `POST /v1/app/upload/image` on Android; then Firestore and push     |
| Send voice note            | Any member who can post                           | Uploads the recording, then adds a `voice` message whose text is the length, such as "00:12". The web also stores the transcript and summary the upload returns.                                                                                                                                                                                                                                                                                                             | Web and Android: `POST /v1/app/upload/voice` ([Files API](https://docs.snapfix.com/engineering-reference/api/files.md)); iOS: `POST /v1/app/upload`; then Firestore and push |
| Reply                      | Any member, on a message that is not deleted      | Sends a new message that points to the quoted one.                                                                                                                                                                                                                                                                                                                                                                                                                           | Firestore and push                                                                                                                                                           |
| React                      | Any member, on a message that is not deleted      | Six emoji: 👍, 🙌, 🔎, 🛠️, 👌 and 🚥. One reaction per person per message; picking another, or the same one again, replaces yours. The chat list line becomes "Reacted 👍 to "…"". The author gets a push, unless you react to your own message.                                                                                                                                                                                                                            | Firestore (reactions subcollection); push as above                                                                                                                           |
| Remove your reaction (web) | The person who reacted                            | "Click to remove" in the reactions list soft-deletes your reaction. Whether it works live is not settled: every chat on the QA site includes real people, so the merge did not react                                                                                                                                                                                                                                                                                         | Firestore                                                                                                                                                                    |
| Copy                       | Any member                                        | Web: text messages only ("Copy Text"), toast "Message copied to clipboard". iOS also copies a photo, toast "Message copied to clipboard.". Android copies text and photo captions, toast "Message copied to clipboard".                                                                                                                                                                                                                                                      |                                                                                                                                                                              |
| Forward                    | Any member, on a message that is not deleted      | Opens "Forward message to". Each chosen chat or person gets a copy marked "Forwarded", with you as sender and without the quote and mentions; a direct chat is created when needed. The web then shows "Message forwarded to N recipients" (fixed English).                                                                                                                                                                                                                  | Firestore, once per target                                                                                                                                                   |
| Edit                       | The sender, text messages only                    | Saves the new text and the edit time; the message shows "Edited". The web also writes the new text as the chat list line for every member, even when an older message was edited. iOS and Android also clear the read receipts \[[ASK-45](https://github.com/snapfix/docs/blob/main/ASK.md#ask-45-should-editing-a-chat-message-clear-its-read-receipts)]. A failed edit on the web shows the fixed English "Failed to edit message".                                        | Firestore                                                                                                                                                                    |
| Delete                     | The sender; on iOS and Android also a group admin | Web: asks first ([Delete message](#delete-message)), then sets `is_deleted` and shows the toast "Message has been deleted". iOS and Android delete at once. The text stays in the database \[[ASK-46](https://github.com/snapfix/docs/blob/main/ASK.md#ask-46-what-happens-to-a-deleted-messages-text-and-to-a-deleted-groups-data)]. If it was the last message, the chat list line updates. A failed delete on the web shows the fixed English "Failed to delete message". | Firestore                                                                                                                                                                    |
| "Create a task"            | Any member, on text and photo messages            | Web: opens [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md) with the first 250 characters of the text as the name (line breaks become spaces) and the photo, or a picture of the message. After saving, the chat gets a "Task created from Chat" card. The apps open their own task screens.                                                                                                                                               | [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md), then Firestore                                                                                     |
| "View Task"                | Any member, on a "Task created from Chat" card    | Web: opens the task in a new tab, remembering the chat and message. Failure: "Failed to retrieve task details" or "Task details not found".                                                                                                                                                                                                                                                                                                                                  | [Tasks API](https://docs.snapfix.com/engineering-reference/api/tasks.md)                                                                                                     |
| "Info"                     | The sender                                        | Opens [Message info](https://docs.snapfix.com/how-the-apps-work/screens/chat/message-info.md).                                                                                                                                                                                                                                                                                                                                                                               |                                                                                                                                                                              |
| Tap a mention or avatar    | Any member                                        | Opens the direct chat with that person, creating it if needed.                                                                                                                                                                                                                                                                                                                                                                                                               | Firestore                                                                                                                                                                    |
| Tap a photo                | Any member                                        | Web: opens it in a new browser tab.                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                                                                                                                                                              |
| Save a draft               | Any member                                        | Keeps unsent text for this chat. The web saves it when the box loses focus or another chat is picked; iOS when you go back.                                                                                                                                                                                                                                                                                                                                                  | Firestore (`draft_message`)                                                                                                                                                  |
| Read messages              | Automatic, while the chat is open                 | Adds your read time to each message from someone else (`read_by`) and marks the chat read.                                                                                                                                                                                                                                                                                                                                                                                   | Firestore                                                                                                                                                                    |
| Translate                  | Any member, when the site translates              | Shows received text in your language, with the toggle above.                                                                                                                                                                                                                                                                                                                                                                                                                 | [`POST /v1/app/translations/batch`](https://docs.snapfix.com/engineering-reference/api/reference.md)                                                                         |

### Push notifications

A new message pushes to every member who has not muted or archived the chat, except the sender. The push text is the message text, "📷 Photo" for a photo without a caption, or "🎤 Voice message(00:12)" for a voice note. The route accepts any receivers and any title and text from a signed-in user.

* A message with @mentions pushes "Mentioned you - " to the people mentioned. iOS also pushes the normal message to everyone else; the web pushes only to the people mentioned.
* On the web, the receiver list of a custom group still includes people who left or were removed, so they get the new message's text. iOS and Android leave them out.
* A reaction pushes the author of the message, never yourself.

### Read receipts

Your own messages show sent, delivered or read. In a direct chat the web shows read once the other person has read the message, and delivered before that. In a group it shows read when every other member has read it, delivered when at least one has, and sent before that. On the web a custom group or the site chat has no member list for this, so its messages never get past delivered, while [Message info](https://docs.snapfix.com/how-the-apps-work/screens/chat/message-info.md) can list readers. iOS and Android show read when every member has read.

## States

* **Loading:** the newest messages appear as they arrive; older pages show a spinner at the top. The welcome card can show briefly first.
* **Empty:** the day label for today, the welcome card and the message box. Web with no chat selected: "Select a chat to start messaging".
* **Error:** send and listen failures are written to the console. The only error toasts are the edit and delete failures above, "Failed to remove reaction", and the "View Task" failures. A task-group chat the user can no longer open (403 or 404) leaves the list with "You no longer have access to this group." ([Chats](https://docs.snapfix.com/how-the-apps-work/screens/chat/chats.md)).
* **No permission:** in a deleted custom group, "This group has been deleted. You can no longer send messages." replaces the message box. If you are marked deleted in a custom group, the web hides the box and shows nothing in its place. Android closes the chat when its group is deleted. iOS goes back to the start when the group is deleted or you are marked deleted in it (ios @ aa31967ac8, `SnapFix/Chat/ChatVC/ChatViewModel.swift:395-400`, `:269-270`).
* **Offline (mobile):** no offline state of its own. Android says "You must be connected to the Internet to carry out this task. Please connect and try again." when a voice note cannot download.

## Dialogs and sheets

### Message menu

On the web, the menu opens from a button on each message, next to the reaction button. On iOS and Android it opens with a long press, together with the reactions.

| Item            | Web                         | iOS                                          | Android                                                    |
| --------------- | --------------------------- | -------------------------------------------- | ---------------------------------------------------------- |
| Reply           | All messages                | All messages                                 | Other people's messages (and swipe)                        |
| Forward         | All messages                | All messages                                 | Other people's messages                                    |
| Copy            | Text messages ("Copy Text") | Text and photos                              | Text, and photos with a caption                            |
| Edit            | Your text messages          | Your text messages                           | Your text messages                                         |
| "Create a task" | Text and photos             | Text and photos                              | Text and photos, not voice                                 |
| "Info"          | Your messages               | Your messages                                | Your messages                                              |
| Delete          | Your messages               | Your messages; any message for a group admin | Your messages; other people's in a group for a group admin |

### Delete message

Web: "Delete Message" with "Are you sure you want to delete this message?", "Cancel" and "Delete". The text is passed as HTML through the shared alert, which live shows raw markup (`<\/div>`, `<\/p>`) and a broken warning image in the profile and planner delete dialogs; one agent saw the same here

### Forward message

Web: "Forward message to", a search box, the tabs "Groups" (group chats only) and "Users" (site users), checkboxes, "Cancel" and "Forward". An empty tab shows "No data available". iOS and Android use their own sheet of groups and people.

### Edit message

See [Inputs](#inputs).

### Voice note

Web: "Record a voice message", described under [Inputs](#inputs).

## Platform differences

| Topic                         | Web               | iOS                                                                                                                                | Android                                                                                                                            |
| ----------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Page size                     | 20                | 30                                                                                                                                 | 50                                                                                                                                 |
| Delete confirmation           | yes               | no                                                                                                                                 | no                                                                                                                                 |
| Delete someone else's message | never             | group admin                                                                                                                        | group admin, in a group                                                                                                            |
| Copy a photo                  | no                | copies the image                                                                                                                   | copies the caption                                                                                                                 |
| Voice transcript              | stored, not shown | "Transcribe" when a transcript exists                                                                                              | "View transcript", sheet "Transcript"                                                                                              |
| Read receipts after an edit   | kept              | cleared \[[ASK-45](https://github.com/snapfix/docs/blob/main/ASK.md#ask-45-should-editing-a-chat-message-clear-its-read-receipts)] | cleared \[[ASK-45](https://github.com/snapfix/docs/blob/main/ASK.md#ask-45-should-editing-a-chat-message-clear-its-read-receipts)] |
| Photo upload                  | `upload`          | `upload`                                                                                                                           | `upload/image`                                                                                                                     |
| Composer when you have left   | hidden, no text   | chat closes                                                                                                                        | chat closes when the group is deleted                                                                                              |


---

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