> 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/tasks/add-task.md).

# Add a Task

{% 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. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/tasks/add-task.md).
{% endhint %}

Start a new task on the web: name it, show it as large text, a photo, a video, a sketch or a voice note, choose its group when the page doesn't decide it, and add what the group requires. The new task then opens.

* **Where:** web, a dialog. It opens from:
  * "+" on the [Feed](https://docs.snapfix.com/how-the-apps-work/screens/tasks/feed.md), and the "+" in the feed's empty state;
  * "+" ("Create") on [Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md), and "+" on a room's or an area's task list ([Rooms and areas](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md#rooms-and-areas)). In an empty group list, the "+" inside "To add a task, click on the + button." does nothing;
  * "+" on an asset's task list ([Asset detail](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-detail.md));
  * "Create Task" on a photo or video in the task chat ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#chat-actions)) or on a checklist item's photo or video ([Checklist](https://docs.snapfix.com/how-the-apps-work/screens/checklists/checklist.md));
  * "Create a task" on a message in a group chat ([Chat conversation](https://docs.snapfix.com/how-the-apps-work/screens/chat/conversation.md)).
* **Who:** the "+" shows to everyone on the feed, on an asset's task list, and on room and area lists (on a multi-site, room and area lists show it to site admins only). On a group's list it needs "Create New Task". Once the group is known, the dialog checks the user's permissions there ([Alerts](#alerts)).
* **Feature:** [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md)

iOS and Android create tasks with the [Camera](https://docs.snapfix.com/how-the-apps-work/screens/tasks/camera.md) and [Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md) instead. The housekeeping timeline has its own create dialog ([Timeline](https://docs.snapfix.com/how-the-apps-work/screens/housekeeping/timeline.md)). The same dialog also adds assets to an asset register, as "Add an Asset" with "Asset name"; that use belongs to the [Asset list](https://docs.snapfix.com/how-the-apps-work/screens/assets/asset-list.md).

![Add a Task, opened from the feed](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-1e43698453413f0a853f61328ae0052c690f810b%2Fadd-task.png?alt=media)

## Layout

1. **Header:** "Add a Task" and a close button. The close button hides while the task is being saved. Escape and clicks outside don't close the dialog.
2. **Creator:** the user's picture (or initials) and name.
3. **"Task name":** one line, placeholder "Task name". While it holds Snapfix AI's suggestion, it carries the badge "Snapfix Recommends". Hidden while the voice tool is on.
4. **Tool area**, by tool:
   * **Large text** (the default): a text box with the counter "0 / 50".
   * **Photo:** "Drag and drop an image here", "OR", "Choose an image". A picked photo shows with the buttons "Crop" and "Sketch". When Snapfix AI can't name the photo: "Snapfix couldn’t make a recommendation from this photo. Upload clearer image if you’d like a suggestion."
   * **Video:** "Drag and drop a video here", "OR", "Choose a video". A picked video shows in a player.
   * **Voice:** a countdown from 3, then the recording time and a button that deletes the recording and starts again.
   * **Sketch:** a blank page with "Sketch".
5. **Footer:** the tool buttons, photo and video, then microphone, pen and "T" (large text); a tick marks the active one. On the right, "Save", or "Next" while the group isn't known.

Started from a photo or video in a task chat or a checklist, the dialog offers only the matching tool, with that photo or video already in it. Started from a group chat, it opens on the photo tool with the message's photo, or with a picture of the message.

**Group step.** "Next" turns the dialog into "Add task to a Group": "Search Groups", then the groups as a radio list with image, name and address, 20 at a time sorted by name, more on scroll. Archived groups show but can't be picked. With Snapfix AI on and a photo, the suggested group moves to the top with an AI badge and is picked unless the user picks one first. The footer holds only "Save"; nothing leads back to the first step, and closing drops everything. A voice recording keeps running during this step, so the note also holds whatever is said while choosing.

## Inputs

| Field            | Type                | Required                  | Default                                                                                                                               | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------- | ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Task name"      | Text, one line      | Yes                       | Empty. From a group chat: the message's first 250 characters, line breaks as spaces. From a checklist photo or video: the item's name | Up to 255 characters; spaces only count as empty. While it's empty, "Save" and "Next" stay disabled. With Snapfix AI on, picking a photo while the name is empty fills in a suggested name, translated when the site translates. With the large-text tool on, typing here also changes the large text.                                                                                                                                                |
| Large text ("T") | Text, up to 5 lines | Yes, as the name          | Empty; coming back to "T" shows the name                                                                                              | Up to 50 characters. Typing here replaces "Task name" with the text, trimmed, with line breaks as spaces. The task's large text is the name, not the box: line breaks are lost, and a name longer than 50 characters becomes the large text, while the box stops following it at 50.                                                                                                                                                                  |
| Photo            | Image file          | Yes, with the photo tool  | None; or the chat's or checklist's photo                                                                                              | JPEG, PNG or GIF up to 20 MB. A larger file gets "Max file size is 20"; other file types dropped on the area are ignored without a message. Resized to at most 1,600 px, as JPEG, before upload. "Crop" (confirmed with "Save") and "Sketch" (draw on the photo) change it. No button removes it. In a group with "Block Photos from Gallery", the photo and video tools are greyed out, but only when the group is known before the photo is picked. |
| Video            | Video file          | Yes, with the video tool  | None; or the task chat's or checklist's video                                                                                         | Any video type up to 40 MB ("Max file size is 40"). Its first frame becomes the task image. A video the browser can't play makes "Save" do nothing. Greyed out together with the photo tool in a blocking group. No button removes it.                                                                                                                                                                                                                |
| Sketch           | Drawing             | Yes, with the sketch tool | A blank page                                                                                                                          | "Sketch" opens the drawing tools; the drawing becomes the task image.                                                                                                                                                                                                                                                                                                                                                                                 |
| Voice note       | Recording           | Yes, with the voice tool  | -                                                                                                                                     | Asks for the microphone, counts down from 3, then records with no time limit. "Save" works after one second of recording. A refused microphone, a recording error or a failed upload shows a key such as "TASKS.PROVIDE\_MICROPHONE\_PERMISSION" instead of a message. The task is named "Voice Task : Nov 11 14:30", in English, with the browser's time.                                                                                            |
| Group            | One group           | Yes                       | The list's group; none from the feed, room and area lists, chats, checklists and asset task lists                                     | See the group step under [Layout](#layout).                                                                                                                                                                                                                                                                                                                                                                                                           |

## Actions

| Action       | Who                                                | What happens                                                                                                                                                                                                           | API                                                                                                 |
| ------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Pick a tool  | Anyone                                             | Shows that tool. A photo, video or sketch picked with one tool stays chosen under the others, so "Save" can be enabled over an empty area and send the earlier file.                                                   | -                                                                                                   |
| "Next"       | Anyone, once the name (and the tool's file) is set | Opens the group step. With Snapfix AI on and a photo, asks for the best group.                                                                                                                                         | [`POST /v1/app/tasks/suggestions/group`](https://docs.snapfix.com/engineering-reference/api/ai.md)  |
| Pick a group | Anyone                                             | Loads the group and checks the user's permissions there ([Alerts](#alerts)). A refused group stays marked in the list but isn't taken: "Save" stays disabled, or saves into the group picked before.                   | [`GET /v1/app/businesses/{uuid}`](https://docs.snapfix.com/engineering-reference/api/groups.md)     |
| "Save"       | Anyone, with a group                               | Stops and uploads a voice recording, asks for what the group requires ([Required details](#required-details)), then creates the task ([What "Save" sends](#what-save-sends)). The button shows progress, then success. | [`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks) |
| Close        | Anyone, while not saving                           | Closes the dialog; nothing is kept.                                                                                                                                                                                    | -                                                                                                   |

### What "Save" sends

1. Voice notes only: the recording goes to `POST /v1/app/upload/voice`, which also returns a transcript ([Files API](https://docs.snapfix.com/engineering-reference/api/files.md)).
2. [`POST /v1/app/tasks`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasks) with the group, the name as `title`, the name again as `largeTitle` for large-text and voice tasks, and the photo or sketch as `file` (for a video, its first frame). `jobType` is 206 for large text, 203 for a photo or a sketch, 204 for a video, 208 or 209 from a group chat (photo or other message), 210 from a checklist and 211 from a task chat. Voice tasks add `voiceFileUrl`, `voiceDuration` and `transcriptValueAi`, and the server makes them type 41. A task from an asset's list adds `assetUuid`; one from a group chat adds `chatId` and `messageId`. When Snapfix AI suggested the name or the group, `aiTitle`, `aiTitleSuggestion`, `aiBusinessUuid` and `aiBusinessSuggestion` record it.
3. Then, all at once:

   * a video goes into the task chat ([`POST /v1/app/chat/file`](https://docs.snapfix.com/engineering-reference/api/chat.md));
   * tags through [`POST /v1/app/tasks/tag/multi`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptaskstagmulti), after creating the tags Snapfix AI made up ([`POST /v1/app/businesses/{uuid}/tags/multiple`](https://docs.snapfix.com/engineering-reference/api/tags.md)), including the ones the user unticked;
   * assets through [`POST /v1/app/tasks/asset-link`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksasset-link), assignees through [`POST /v1/app/tasks/assign/multi`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksassignmulti);
   * the room and the area through [`POST /v1/app/tasks/room-add`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksroom-add) and [`POST /v1/app/tasks/area-add`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksarea-add). A task started from a room's or an area's list always gets that room or area.

   Values Snapfix AI suggested are added first, marked as suggested, then corrected to the user's choice, with [`room-remove`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksroom-remove) and [`area-remove`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-v1apptasksarea-remove) where needed. All of this runs after the task exists, and the API doesn't check the group's requirements itself.
4. With housekeeping on, a task with an assignee and a room goes onto the housekeeping timeline ([`POST /v1/app/housekeeping/bulk-reassignment`](https://docs.snapfix.com/engineering-reference/api/housekeeping.md)).

A large-text task in a group without requirements sends only `POST /v1/app/tasks`.

### After saving

* 1.5 seconds after success, the dialog closes and the new task opens in [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md): `/group/:id/task/:taskId`, or `/room/:id/task/:taskId` and `/area/:id/task/:taskId` when started from a room's or an area's list. With Snapfix AI on and a photo, the task page then asks for more suggestions.
* From a group chat or an asset's task list, the dialog closes and the task doesn't open. The chat gets a "Task created from Chat" reply that links the task, and the asset's list reloads. With Snapfix AI on, both then ask it for suggestions in the background. From a checklist photo or video, all open dialogs close as the task opens.
* The new task is red, its creator follows it, and its chat starts with the "task created" card, which shows the group's name for red, such as "New tasks". It goes to the top of the list that "Previous" and "Next" walk through.

## States

* **Loading:** while saving, "Save" shows progress, the name can't be edited and the close button is hidden. In the group step, a spinner shows while groups load; while a picked group loads, the search and the list are disabled.
* **Empty:** the group step shows "No data available" when the user has no groups.
* **Error:** the API's message in an alert ([shared behavior](https://docs.snapfix.com/how-the-apps-work/shared.md)); the dialog stays open with what was entered. When the task fails after a voice upload, "Save" keeps spinning, so the note can only be recorded again after closing. When a request that follows the task's creation fails, its error shows, but the task opens without that tag, user, room, area or asset.
* **No permission:** see [Alerts](#alerts).
* **Offline:** the web needs a connection; requests fail with the shared error message.

## Dialogs and sheets

### Required details

"Save" opens one dialog per requirement of the group, one after the other. What a group can require: [Tag your task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#tag-your-task).

* **Tags:** "Add Required Tags": the mandatory tag folders, each marked "\*", with "Search" and a checkbox per tag. Tags Snapfix AI suggests carry its badge, and tags it made up show "New tag created by AI" (only when the site lets users manage tags). "CANCEL" and "SAVE"; "SAVE" stays disabled until each required folder has a tag. Folders without tags don't count.
* **Assets:** the [Assets](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#assets) dialog; "Save" with none: "You must add one or more assets."
* **Assignees:** the [Assigned to](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#assigned-to-followed-by) dialog; "Save" with none: "You must add one or more users."
* **Room, area, or either:** the [Rooms and areas](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#rooms-and-areas) dialog, showing only what's needed; "SAVE" stays disabled until it's chosen. A requirement counts only when the site has rooms or areas, checked with a one-item [`POST /v1/app/rooms/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md) and [`POST /v1/app/areas/list`](https://docs.snapfix.com/engineering-reference/api/rooms.md). When the group requires both and the site has only one kind, neither is asked. A task started from a room's or an area's list already has that one.

Closing any of these stops the save without a message; the dialog stays as it was, and "Save" starts over. With Snapfix AI on and a photo, these dialogs show its suggestions.

### Alerts

* Without "Create New Task" in the group: "You don't have the necessary permissions".
* In a group that requires an assignee, without "Assign Users": "To create a task, you need to assign a user to it. However, you do not have permission to assign users. Please contact your administrator for assistance." Started from a task chat or a checklist, the alert shows the key "ONLY\_EN.undefined\_NO\_ASSIGN\_USER\_PERMISSION" instead.
* When the page gave the group, either alert closes the dialog. In the group step, the group isn't taken.
* The code also has "Please enter a title", "Your input exceeds the maximum allowed length" and "Please select a media or sketch.", but "Save" and "Next" are disabled in those cases, so they don't show.


---

# 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/tasks/add-task.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.
