> 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/product/features/ai/snapfix-recommends.md).

# Snapfix Recommends

{% 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)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/snapfix-recommends.md).
{% endhint %}

**Snapfix Recommends** is the AI help for creating **tasks**. From a photo or typed text it suggests a new task's **title** and **group**, and then its **tags**, **assignees**, **rooms** and **areas**. Each suggestion carries an AI badge and can be changed, so the person creating the task keeps the final say. Guests on a **QR form** get a suggested title and room, and tasks sent through the Open API and the Vendor API get the values their caller left out. A **site admin** switches it on for a site in the site details, and can stop the AI from making up new tags. It saves typing and gets tasks into the right group with consistent tags. It is a different feature from the [Snapfix AI](https://docs.snapfix.com/product/features/ai/snapfix-ai.md) chat.

## Rules

### Switching it on

* The site's switch is "Snapfix Recommended Task Field Suggestions" (`fAiSuggestionEnabled`), with "Restrict to My Tags" below it while it is on. Turning it off turns "Restrict to My Tags" off too ([Site details](https://docs.snapfix.com/how-the-apps-work/screens/console/site-details.md#inputs), [Site details feature](https://docs.snapfix.com/product/features/console/site-details.md)).
* It is off for a new site: every way of creating a site leaves it at its default, 0 ([`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md)).
* The web shows the switch on every site outside production. In production, and in the apps everywhere, it shows only where Firebase Remote Config allows it: every site, or the sites on a list. The only code that updates that list is a staff action that no client calls, so who turns the feature on for a customer is open \[[ASK-181](https://github.com/snapfix/docs/blob/main/ASK.md#ask-181-who-switches-snapfix-ai-and-snapfix-recommends-on-for-a-site)] ([Site details](https://docs.snapfix.com/how-the-apps-work/screens/console/site-details.md#web)).
* Each user also has "Enable AI Auto-Assign" in the site permissions, shown only while the site's switch is on. It decides whether assignees are suggested for the tasks that user creates ([Users](https://docs.snapfix.com/how-the-apps-work/screens/console/users.md#site-permissions-web)).
* The apps and the web ask for nothing while the switch is off. The AI service also refuses a site with the switch off, but only when the request names the site: titles reach it without one, so they skip the switch and the site's title style ([How the suggestion routes work](https://docs.snapfix.com/engineering-reference/api/ai.md#how-the-suggestion-routes-work)).

### Title and group

* The title is suggested while the name is empty, from the photo or the typed text. On the web it comes in "Add a Task". In the apps it comes once, for the photo of a new photo task outside asset registers, on the photo screen; videos, sketches, text and voice tasks get none. The badge reads "Snapfix Recommends" ("Snapflix Recommends" on iOS), and Android may replace the suggestion with a translation into the app's language ([Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md#ai-name-suggestion), [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md)).
* The title comes out in whatever language the model picks: iOS sends the app's language, and the server drops it \[[ASK-178](https://github.com/snapfix/docs/blob/main/ASK.md#ask-178-should-ai-titles-follow-the-users-language)].
* For a photo task, the suggested group moves to the top of the group list with a badge and is picked unless the person already picked one ([AI group suggestion](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#ai-group-suggestion)).
* Only groups the person may use are candidates: live groups where they are an admin or may create tasks ([`POST /v1/app/tasks/suggestions/group`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsgroup)).
* The task records whether its final title and group were the suggestions (`title_aiSuggested`, `business_aiSuggested`), and both apps log each suggestion and the person's choice ([`save_ai_job_log`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-actionsave_ai_job_log), [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md)).

### Tags, assignees, rooms and areas

* After a task is created, the task page on all three platforms asks for each kind the task still lacks and applies what comes back with AI badges; in the apps this needs the task's photo on the phone, or the photo's AI reference ([Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#users-tags-rooms-assets-and-compliance); ios @ aa31967ac8, `SnapFix/MessagesVC/MessagesVC+AISuggestion.swift:4-89`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/JobChatFragment.java:15695`).
* When the group requires details, the apps' "Tag your task" step marks the suggested tags, users, rooms and areas and lists them first. iOS gives text and sketch tasks no suggestions there ([Tag your task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#tag-your-task)).
* **Tags** come from the tag folders the group can use, an existing one when the AI is more than 70% sure. With "Restrict to My Tags" off, the AI may also propose a new tag ("New tag created by AI" on the web, "New Tags Created by AI" in the apps); the web adds it only for people with the "Manage Tags" permission (web\_app\_v2 @ 0989b8e685, `src/app/services/task/task-suggestion-helper/task-suggestion-helper.service.ts:69-71`, `:216`). A made-up tag stays in the group's folders after the person unticks it. How confident the AI must be before it makes one up depends on a server setting whose default and comment disagree \[[ASK-176](https://github.com/snapfix/docs/blob/main/ASK.md#ask-176-which-ai-suggestion-settings-and-logins-does-production-use)].
* **"Restrict to My Tags"** stops the AI from proposing new tags; it still picks from every tag in the group's folders, whoever created it. Its help text, "AI suggestions will only include tags you have created", says otherwise. The flag `fAiUseOnlyExistingTag` is 1 when it is on ([`POST /api/v1/ai-task/tag`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-tasktag)).
* **Assignees** are suggested only when the creator's "Enable AI Auto-Assign" is on, on all three platforms; the AI ranks the group's members and offers at most two. On the web the top one is assigned to the new task. The apps ask on the task page, and in "Tag your task" when the group requires an assignee ([`POST /v1/app/tasks/suggestions/assignees`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsassignees); android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/dialog/TagRequiredDialog.java:486`; ios @ aa31967ac8, `Models/UserParent.swift:167-169`, `SnapFix/TagRequire/TagRequiredVC.swift:385`).
* **Rooms and areas** are matched to the site's own live lists; the web applies the first suggested room and area when the task has none ([`POST /v1/app/tasks/suggestions/rooms`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsrooms), [areas](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsareas)).

### QR forms, Open API and Vendor API

* **QR forms:** the guest page suggests a title and a room after a photo. After the submit, the server asks for the room, area, tags and assignees and adds them to the task \[[ASK-186](https://github.com/snapfix/docs/blob/main/ASK.md#ask-186-should-the-ai-add-assignees-tags-rooms-and-areas-to-qr-form-tasks)]. Those calls share one rate limit across every customer. Details in [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md#ai-suggestions-on-the-form).
* **Open API and Vendor API:** on a site with the switch on, a task sent without a group goes to the group the AI picks, at 15% confidence or more \[[ASK-187](https://github.com/snapfix/docs/blob/main/ASK.md#ask-187-should-open-api-and-vendor-api-tasks-without-a-group-go-to-the-closest-group-at-15-confidence)]; the task is refused when the pick is not a group of that site. A queued job then fills in the tags, assignees, room and area the caller left out, from the title, the description and the text messages, never the photo. A value the caller sent is never changed ([Open API](https://docs.snapfix.com/product/features/integrations/open-api.md), [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md); api\_php\_live\_v2 @ ef3c4319f6, `app/Services/Suggestions/AiTaskCreationService.php:139-210`, `:536-562`). The caller's API key goes along to the AI service.

### Failures and limits

* A failed or empty suggestion is silent: the field stays as it is, and the task saves either way. Without a connection the apps skip the suggestions ([AI group suggestion](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#ai-group-suggestion), [Offline](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#offline)).
* A photo over 6 MB gets no suggestion and no message, though the API accepts far larger ones. The group route answers an empty result in another shape than the others.
* Each suggestion call can hold the API for 30 seconds while the AI answers, and every tag suggestion sends the group's whole tag catalogue to the model.
* A photo's AI reference lives 24 hours; after that the other suggestions get nothing ([How the suggestion routes work](https://docs.snapfix.com/engineering-reference/api/ai.md#how-the-suggestion-routes-work)). The reference is not tied to the site or user that made it.
* No plan limit applies.

### Data, privacy and access

* The suggestion routes check only that the caller is signed in. Nothing checks that the caller belongs to the site or group named in the request, so the answers can show another customer's staff, tags, rooms and areas.
* The photo, the text and the site's group and tag names go to OpenAI; for assignees, the candidates go as numbers with their workload. The apps never name the provider \[[ASK-177](https://github.com/snapfix/docs/blob/main/ASK.md#ask-177-do-the-customer-terms-cover-sending-task-text-photos-recordings-and-chats-to-ai-providers)].
* The API's log keeps each suggestion's request and answer, and the AI service's usage table keeps up to 500 characters of the task's text, with no retention.

## Flow

```mermaid
flowchart TD
  start["New task: photo or text"] --> sw{"Site switch on, and allowed by Remote Config?"}
  sw -- no --> manual["No suggestions; the person fills every field"]
  sw -- yes --> title["Title suggested while the name is empty"]
  title --> group["Group suggested, moved to the top and picked"]
  group --> pick{"Person picks another group?"}
  pick -- yes --> own["Their group kept"]
  pick -- no --> ai["Suggested group kept"]
  own --> details
  ai --> details["Tag your task, if the group requires details: suggestions listed first"]
  details --> saved["Task saved; suggestions and choices logged"]
  saved --> later["Task page: missing tags, rooms, areas and, with auto-assign, assignees filled in"]
```

## Platforms

| Capability                           | Web                                                         | iOS                                                      | Android                                                  |
| ------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- |
| Title from a photo                   | Yes, in "Add a Task"                                        | Yes, photo tasks only                                    | Yes, photo tasks only; may be replaced by a translation  |
| Group from a photo                   | Yes, moved to the top and picked                            | Yes                                                      | Yes                                                      |
| Tags, rooms and areas after creation | Yes, on the task page                                       | Yes, on the task page and in "Tag your task"             | Yes, on the task page and in "Tag your task"             |
| Assignees                            | With the creator's auto-assign switch; the top one assigned | With the switch, on the task page and in "Tag your task" | With the switch, on the task page and in "Tag your task" |
| New tags made up by the AI           | Only for people with "Manage Tags"                          | Yes, "New Tags Created by AI"                            | Yes, "New Tags Created by AI"                            |
| Site switch shown                    | Always outside production; by Remote Config in production   | By Remote Config                                         | By Remote Config                                         |
| Suggestion log                       | No                                                          | Yes                                                      | Yes                                                      |

## Screens

* [Add a Task](https://docs.snapfix.com/how-the-apps-work/screens/tasks/add-task.md): the web's title and group suggestions.
* [Photo edit and name](https://docs.snapfix.com/how-the-apps-work/screens/tasks/photo-edit.md): the title suggestion in the apps.
* [Add task to a group](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md): the group suggestion and "Tag your task" in the apps.
* [Task detail](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md): the suggestions after a task is created.
* [Site details](https://docs.snapfix.com/how-the-apps-work/screens/console/site-details.md): the site's switches.
* [Users](https://docs.snapfix.com/how-the-apps-work/screens/console/users.md): the "Enable AI Auto-Assign" switch.
* [QR form](https://docs.snapfix.com/how-the-apps-work/screens/qr/form.md): the guest title and room suggestions.

## API and data

* [How the suggestion routes work](https://docs.snapfix.com/engineering-reference/api/ai.md#how-the-suggestion-routes-work): the rules every suggestion route shares.
* App routes: [title](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionstitle), [group](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsgroup), [tags](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionstags), [assignees](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsassignees), [rooms](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsrooms) and [areas](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1apptaskssuggestionsareas). Guest routes for QR forms: [title](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1guestsuggestionstitle) and [rooms](https://docs.snapfix.com/engineering-reference/api/ai.md#post-v1guestsuggestionsrooms), and the others that the QR form's server step calls.
* The AI service behind them: [`/api/v1/ai-task/title`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-tasktitle), [group](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-taskgroup), [tag](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-tasktag), [assignee](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-taskassignee), [room](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-taskroom) and [area](https://docs.snapfix.com/engineering-reference/api/ai.md#post-apiv1ai-taskarea). Clients never call it directly.
* [`POST ?action=save_ai_job_log`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-actionsave_ai_job_log): the apps' suggestion log. The web saves the switches with [`PUT /v1/app/parents/{uuid}`](https://docs.snapfix.com/engineering-reference/api/console.md#put-v1appparentsuuid).
* Tables: [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) (`fAiSuggestionEnabled`, `fAiUseOnlyExistingTag`), [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) (`fAiAutoAssignEnabled`), [`tPri_Job`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_job.md) (`title_aiSuggested`, `business_aiSuggested`), [`log_ai_job`](https://docs.snapfix.com/engineering-reference/db/tables/log_ai_job.md) (suggestions and choices) and [`ai_token_usage`](https://docs.snapfix.com/engineering-reference/db/tables/ai_token_usage.md) (one row per AI call).

## Depends on

* [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md) and [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): the fields the suggestions fill.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md): the site's switches. [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the "Manage Tags" and "Enable AI Auto-Assign" permissions.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the groups a person may pick and the members who can be assigned.
* [Site tags](https://docs.snapfix.com/product/features/console/site-tags.md): the tag folders the AI picks from.
* [Rooms and areas](https://docs.snapfix.com/product/features/rooms/rooms-and-areas.md): the rooms and areas it matches.
* [Chat](https://docs.snapfix.com/product/features/chat/chat.md): "Create a task" from a message sends the messages around it for the title.
* [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md), [Open API](https://docs.snapfix.com/product/features/integrations/open-api.md) and [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md): the guest and server-side suggestions.
* Uploads: where a site switches on AI for images, voice, video or documents, each upload of that kind also goes to the AI provider, and waits for it ([Files API](https://docs.snapfix.com/engineering-reference/api/files.md)). Voice tasks get no AI title or transcript today \[[ASK-15](https://github.com/snapfix/docs/blob/main/ASK.md#ask-15-is-snapfix-ai-for-voice-tasks-switched-off-on-purpose)].
* Firebase Remote Config (which sites may show the switch) and OpenAI (the model).

## Edge cases

* **Switch off:** no suggestions anywhere, and the server skips its step for Open API and Vendor API tasks.
* **Android search:** a suggestion that arrives while the group search holds text can crash the group list.
* **Refused group pick on the web:** the earlier group stays, and "Save" uses it.
* **Offline (apps):** no suggestions; the task saves and uploads later.
* **Several sites:** suggestions use the selected site's switch, groups, tags, rooms and areas.
* **Time zones:** none.


---

# 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/product/features/ai/snapfix-recommends.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.
