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

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

Record a voice note that becomes a new task.

* **Where:** iOS and Android: "+" menu, "Create a new Voice Task" (Android "Create a New Voice Task"), on Home and inside a group; iOS also in rooms and areas. A sheet on both platforms.
* **Who:** members of at least one task group on the current site (the "+" menu offers it only then; inside a group, iOS also needs the right to create tasks there). Android does not offer it while asset registers are showing.
* **Feature:** [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md)

Group tasks also have a hold-to-record button that creates voice tasks inside the group ([Group tasks](https://docs.snapfix.com/how-the-apps-work/screens/tasks/group-tasks.md)). This doc covers the "+" menu sheet, mainly as opened from Home.

## Layout

* **Header:** the title "Create a new Voice Task" (Android "Create a New Voice Task") and a close button.
* **Recording panel:** a microphone icon and a countdown, "3", "2", "1"; then the elapsed time ("00:00", Android "00 : 00"), an animation, and a cancel button.
* **Send button:** below the panel. It is disabled during the countdown; Android keeps it disabled for one more second.

## Inputs

| Field     | Type                         | Required | Default                              | Rules and messages                                                                                                                        |
| --------- | ---------------------------- | -------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Recording | audio, AAC in an `.m4a` file | yes      | starts by itself after the countdown | At most 10 minutes; at 10 minutes the app sends it as if Send was tapped. iOS records mono at 12 kHz. There is no playback before sending |

## Actions

| Action                           | Who         | What happens                                                                                                                                                              | API       |
| -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Open the sheet                   | as above    | Checks the microphone, counts down from 3 and starts recording                                                                                                            | none      |
| Send                             | anyone here | Stops recording and creates the task (below). On iOS a recording shorter than one second does nothing, and the sheet stays open with the timer stopped until it is closed | see below |
| Close or cancel                  | anyone here | Stops recording and closes the sheet; nothing is kept. Android deletes the file                                                                                           | none      |
| Tap outside the sheet            | anyone here | Android: nothing; the sheet cannot be dismissed that way or dragged. iOS: closes the sheet but keeps recording                                                            | none      |
| App goes to the background (iOS) | anyone here | Drops the recording and closes the sheet. Android does not react                                                                                                          | none      |

**After Send, from Home**

| Step | iOS                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Android                                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | When the current group requires tags or asks to confirm the location, those steps come first; from Home there is usually no current group, so they are skipped                                                                                                                                                                                                                                                                                       | Closes the sheet and opens [Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md) as a sheet. Cancelling it drops the recording                                                                                                                                                                                                                             |
| 2    | Online: shows "Snapfix is creating your new voice task" and uploads the recording to [`?action=upload_voice_task_file`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-actionupload_voice_task_file) (multipart field `uploaded_file`). An answer containing "token has expired" ends the flow with no task and no message. Any other failure, or no connection, goes on without the upload, and the recording is then never uploaded | [Tag your task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#tag-your-task) when the chosen group requires it. When the group requires an assignee and the user may not assign, the alert "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." stops the flow     |
| 3    | Opens [Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md); backing out drops the task                                                                                                                                                                                                                                                                                                                      | [Set the task location](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#set-the-task-location) when the group asks for it                                                                                                                                                                                                                                                   |
| 4    | [Tag your task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#tag-your-task) and [Set the task location](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#set-the-task-location) for the chosen group, then saves the task and opens it                                                                                                                                                               | Saves the task. Online: shows "Snapfix is creating your new voice task" and uploads the recording to [`?action=upload_voice_task_file`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-actionupload_voice_task_file); on failure or offline, queues it for [`?action=save_document`](https://docs.snapfix.com/engineering-reference/api/files.md). Then opens the task in its group |

Inside a group the task goes straight into that group: the same tag, location and upload steps run, then the new task opens. There iOS keeps a recording it could not upload and sends it later through [`?action=save_document`](https://docs.snapfix.com/engineering-reference/api/files.md). iOS in a room or area first asks for the group in a sheet ([Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md)) and then links the room or area to the task.

**What the task gets**

* **Name and large text:** "Voice task : " plus the date and time, for example "Voice task : Nov 11 17:22" ("Voice asset : …" in asset registers on iOS). The same text is the task's large text (`fLargeTextTitle`), shown in place of a photo.
* **Type:** `enum_JobType` 41, voice task (44 in asset registers) ([`enum_JobType`](https://docs.snapfix.com/engineering-reference/db/tables/enum_jobtype.md)).
* **Chat:** the "Created task" item, then the voice message with the recording's length.
* **AI fields:** the upload answer is meant to carry an AI title, image and transcript, which would replace the name and image and fill `transcript_value_ai`, `title_gen_ai` and `image_gen_ai`. The server has that step switched off, so it always answers with empty values and voice tasks keep the date name \[[ASK-15](https://github.com/snapfix/docs/blob/main/ASK.md#ask-15-is-snapfix-ai-for-voice-tasks-switched-off-on-purpose)].

## States

* **Loading:** the countdown, then "Snapfix is creating your new voice task" while the recording uploads (only online).
* **Empty:** none.
* **Error:** see the upload step above; there is no error message on either platform.
* **No permission:** iOS asks for the microphone the first time ("We need to access your microphone to capture audio for the purposes of sending video and voice messages, and creating voice tasks. You can proceed without granting the permissions, but you will not be able to use these features."). When refused, it shows the same text as an alert with "GO TO SETTINGS" and "Cancel", and the sheet stays open without recording. Android asks for the microphone, and storage on Android 12 and older. A refusal closes the sheet; after an earlier refusal it first explains "To record voice message allow Snapfix to access your microphone and your device storage." with "Continue" and "Not now"; once the system stops asking it shows "To create voice task allow Snapfix to access your microphone and your device storage. Tap on Go to settings > permission and allow permissions." with "Go to settings" and "Not now".
* **Offline (mobile):** recording works. Android saves the task and uploads the recording later; iOS from Home saves the task but loses the recording.

## Platform differences

* iOS uploads the recording before the group is chosen; Android after the task is saved.
* Android keeps the recording when the upload fails and uploads it later; iOS from Home does not, and gives up silently on an expired session.
* The iOS sheet can be closed by tapping outside it while recording continues; Android's cannot.
* iOS drops the recording when the app goes to the background; Android does not react.
* Android disables Send for the first second of recording; iOS accepts it and does nothing.
* Android's voice flow skips the plan's task limit check that iOS runs when the group is chosen.


---

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