> 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/engineering-reference/api/chat.md).

# Chat API

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

Chat messages, files, reactions and transcripts.

The endpoints below work on a **task's** chat: each message is a row of [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) with its task. The chat tab's one-to-one and group chats are not stored by any Snapfix API: the web and the apps read and write them directly in Firestore, per site (`web_app_v2:src/app/services/chat/chat-firebase/chat-firebase.service.ts`); the [Chat screens](https://docs.snapfix.com/how-the-apps-work/screens/chat.md) describe them. This group covers only their Firebase sign-in token and their pushes. The route classes under `v1/App` are empty and run the `v1_0` methods.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`
* **Auth:** api\_php\_live\_v2: user token (authpy access JWT in `Authorization: Bearer`). The message, file and delete endpoints check the caller's access to the task ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). The list and reaction endpoints check no access to the task, and the notification endpoint checks nothing about its receivers. php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]); the actions use the user ID in the request, not the token's user, and don't check that the user may act on the task, group or row they name. Shared rules: [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors) and [API conventions](https://docs.snapfix.com/engineering-reference/api.md).
* **Used by:** web\_app\_v2, iOS, Android, snapfix\_ai\_agent (Simon, the AI assistant); 22 of the 32 endpoints have no known caller. The web's endpoint list also names `chat/transcripts`, and the iOS and Android endpoint lists name the generic chat table actions. No code calls them \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].

| Method | Path                                                                 | Service            | Purpose                                                           |
| ------ | -------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------- |
| POST   | [`/v1/app/chat`](#post-v1appchat)                                    | api\_php\_live\_v2 | Send a text message in a task's chat                              |
| POST   | [`/v1/app/chat/file`](#post-v1appchatfile)                           | api\_php\_live\_v2 | Send a photo, video or document in a task's chat                  |
| POST   | [`/v1/app/chat/list`](#post-v1appchatlist)                           | api\_php\_live\_v2 | List a task's chat                                                |
| GET    | `/v1/app/chat/reaction`                                              | api\_php\_live\_v2 | List a task's chat reactions (no caller)                          |
| POST   | [`/v1/app/chat/reaction`](#post-v1appchatreaction)                   | api\_php\_live\_v2 | Add, change or remove the caller's reaction to a chat message     |
| GET    | [`/v1/app/chat/token`](#get-v1appchattoken)                          | api\_php\_live\_v2 | Get a Firebase custom token for the chat tab                      |
| POST   | `/v1/app/chat/transcripts`                                           | api\_php\_live\_v2 | Get voice message transcripts (no caller)                         |
| DELETE | [`/v1/app/chat/{uuid}`](#delete-v1appchatuuid)                       | api\_php\_live\_v2 | Delete a chat message                                             |
| POST   | [`/v1/app/notification/send`](#post-v1appnotificationsend)           | api\_php\_live\_v2 | Send a push notification to named users                           |
| ANY    | `?action=create_pri_chat_item_type`                                  | php-apis           | Create chat item types, generic table action (no caller)          |
| ANY    | `?action=create_pri_job_chat`                                        | php-apis           | Create task chat messages, generic table action (no caller)       |
| ANY    | `?action=delete_pri_chat_item_type`                                  | php-apis           | Delete chat item types, generic table action (no caller)          |
| ANY    | `?action=delete_pri_job_chat`                                        | php-apis           | Delete task chat messages, generic table action (no caller)       |
| ANY    | `?action=modify_pri_chat_item_type`                                  | php-apis           | Change chat item types, generic table action (no caller)          |
| ANY    | `?action=modify_pri_job_chat`                                        | php-apis           | Change task chat messages, generic table action (no caller)       |
| ANY    | `?action=read_pri_chat_item_type`                                    | php-apis           | Read chat item types by UUID, generic table action (no caller)    |
| ANY    | `?action=read_pri_job_chat`                                          | php-apis           | Read task chat messages by UUID, generic table action (no caller) |
| ANY    | `?action=read_pri_reaction`                                          | php-apis           | Read chat reactions (no caller)                                   |
| POST   | [`?action=read_transcripts`](#post-actionread_transcripts)           | php-apis           | Read voice message transcripts                                    |
| ANY    | `?action=save_pri_chat_item_type`                                    | php-apis           | Save chat item types, generic table action (no caller)            |
| POST   | [`?action=save_pri_job_chat`](#post-actionsave_pri_job_chat)         | php-apis           | Save task chat messages from the apps' sync                       |
| POST   | [`?action=save_pri_log_reaction`](#post-actionsave_pri_log_reaction) | php-apis           | Save chat reactions from the apps' sync                           |
| ANY    | `?action=webcust_delete_jobchat`                                     | php-apis web       | Delete a task chat message (no caller)                            |
| ANY    | `?action=webcust_jobchat_document`                                   | php-apis web       | Send a document in a task chat (no caller)                        |
| ANY    | `?action=webcust_jobchat_drawing`                                    | php-apis web       | Send a drawing in a task chat (no caller)                         |
| ANY    | `?action=webcust_jobchat_image`                                      | php-apis web       | Send an image in a task chat (no caller)                          |
| ANY    | `?action=webcust_jobchat_image_description`                          | php-apis web       | Send an image description in a task chat (no caller)              |
| ANY    | `?action=webcust_jobchat_text`                                       | php-apis web       | Send a text message in a task chat (no caller)                    |
| ANY    | `?action=webcust_jobchat_video`                                      | php-apis web       | Send a video in a task chat (no caller)                           |
| ANY    | `?action=webcust_list_jobchats`                                      | php-apis web       | List task chat messages (no caller)                               |
| ANY    | `?action=webcust_list_jobchats_v2`                                   | php-apis web       | List task chat messages (v2) (no caller)                          |
| ANY    | `?action=webcust_save_chat_reaction`                                 | php-apis web       | Save a chat reaction (no caller)                                  |

The three php-apis rows that have a caller show the method their callers send. Any method reaches a php-apis action. The other `ANY` rows have no caller, so they keep `ANY`.

## POST /v1/app/chat

Sends a text message to a task's chat.

* **Auth:** user token. The caller must be a current member of the task's group, or the call answers `404`. The caller must also see the task: a group admin, a member with the "view all tasks" permission, the task's creator, a follower or an assignee ([task permissions](https://docs.snapfix.com/engineering-reference/api/tasks.md#task-permissions)). The task must be editable: not locked, not archived, and inside its time range. Read-only members pass these checks \[[ASK-44](https://github.com/snapfix/docs/blob/main/ASK.md#ask-44-should-read-only-members-post-react-and-delete-chat-messages)].
* **Used by:** web (task chat). iOS and Android send their messages through [`save_pri_job_chat`](#post-actionsave_pri_job_chat).

**Request** (JSON or form data)

| Name               | In   | Type   | Required | Rules                                                                                                                                                                             |
| ------------------ | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`          | body | string | yes      | The task                                                                                                                                                                          |
| `text`             | body | string | yes      | The message. Blank text is refused. The server sets no length limit; the column holds up to about 64 KB. The web limits the box to 5,000 characters, and Android cuts longer text |
| `replyJobChatUuid` | body | string | no       | The message this one replies to. Not checked to exist or to be in the same task                                                                                                   |

**Response** `200` (trimmed)

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "400",
    "text": "Leaking tap fixed in Room 101",
    "type": 1,
    "fileUrl": null,
    "thumbnailUrl": null,
    "active": null,
    "replyUuid": null,
    "createdTs": 1794387600000,
    "user": {
      "uuid": "300",
      "name": "Jane",
      "image": null,
      "username": "jane@example.com",
      "businessName": "Jane"
    }
  }
}
```

`data` is a [chat item object](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object) of type 1, without `reactions`. Its `active` is always `null`, because `tPri_JobChat` has no `fActive` column.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors), and:

* `403` "Access denied": the caller can't see the task.
* `400` "The task can not be updated": the task is locked, archived or outside its time range.
* `404` "Resource not found": the task doesn't exist, or the caller isn't a current member of its group.
* `422`: `jobUuid` or `text` is missing or blank, or `replyJobChatUuid` isn't a string.

**Side effects:**

* Adds a text row to [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) (type 1). The author is the caller, `fUserBusinessName` is the caller's first name, and `reply_uuid_tJobChat` holds the reply link.
* Touches the task and adds the caller's viewed rows for the task and its group ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)). The table's trigger adds one to the task's `job_chat_count`.
* Pushes to the task's people ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)): the title is the group and task names, and the body is the author's name and the text. The caller's own devices, and anyone who muted the group, get it silent. A silent refresh push to everyone goes out only when `VIA_QUEUE` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].
* The text is stored as sent, with no HTML removed. The web shows it as HTML.

## POST /v1/app/chat/file

Sends a photo, a video or a document to a task's chat.

* **Auth:** user token. The same checks as [POST /v1/app/chat](#post-v1appchat), and the same read-only gap \[[ASK-44](https://github.com/snapfix/docs/blob/main/ASK.md#ask-44-should-read-only-members-post-react-and-delete-chat-messages)].
* **Used by:** web (task chat attachments, task documents, and the video step after a task is created in "Add a Task").

**Request** (multipart form data)

| Name         | In   | Type    | Required | Rules                                                                                                                                                                                                                                                                                                        |
| ------------ | ---- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `jobUuid`    | body | string  | yes      | The task                                                                                                                                                                                                                                                                                                     |
| `file`       | body | file    | yes      | An image (jpg, jpeg, png, gif), a video (mp4, mov, avi, ogg) or a document (txt, doc, docx, xls, xlsx, pdf, md, epub, csv, json, eml, zip). Up to `FILE_MAX_SIZE` KB (default 102400). Audio is refused; voice notes go through the [Files API](https://docs.snapfix.com/engineering-reference/api/files.md) |
| `fileThumb`  | body | file    | no       | An image (jpg, jpeg, png, gif), up to 4096 KB. Stored as the thumbnail                                                                                                                                                                                                                                       |
| `isDocument` | body | integer | no       | 0 or 1. 1 stores the file as a document (type 36), whatever its type                                                                                                                                                                                                                                         |

The message type follows the file's MIME type as the client sends it: `image/*` is type 3, `video/*` is type 5, and anything else is type 36 (document). `isDocument` 1 overrides that and stores 36, but the push still uses the MIME category, so an image sent with `isDocument` 1 is stored as a document and announced as an image. `replyJobChatUuid` isn't among the validated fields, so a file message is never a reply.

**Response** `200`: a [chat item object](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object), as [POST /v1/app/chat](#post-v1appchat) returns, with `fileUrl` set and `thumbnailUrl` set when `fileThumb` was sent.

**Errors:** the same as [POST /v1/app/chat](#post-v1appchat), and `422` when the file is missing, too large or not an allowed type, or when the thumbnail isn't an image or is over 4096 KB.

**Side effects:**

* Stores the file and its thumbnail in the default file bucket, under `img/`, `vid/` or `doc/` by extension, with a random name.
* The row holds `fFileUrl`, `fFileUrlByte` (the size in bytes), `fThumbnailUrl`, and `fText` set to the original file name. The web shows the file name as text, not as HTML.
* Otherwise as [POST /v1/app/chat](#post-v1appchat): the task is touched, viewed rows are added, and the push is sent.

## POST /v1/app/chat/list

Lists a task's chat items (messages and audit lines), newest first, one page at a time.

* **Auth:** user token. The endpoint doesn't check the caller's access to the task or its group, so any signed-in user who knows a task's ID gets its chat. Simon (`snapfix_ai_agent`) calls [`GET /v1/app/tasks/{uuid}`](https://docs.snapfix.com/engineering-reference/api/tasks.md#get-v1apptasksuuid) first, which is its only access check on this path (snapfix\_ai\_agent @ 6b69151530, `src/agent/tools/resolve.py:99-115`).
* **Used by:** web (task chat and the task activity), snapfix\_ai\_agent (Simon's `task_messages` tool, `src/snapfix/tasks/__init__.py:348`).

**Request**

| Name            | In    | Type              | Required | Rules                                                                                                                                          |
| --------------- | ----- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `jobUuid`       | body  | string            | yes      | The task                                                                                                                                       |
| `chatItemTypes` | body  | array of integers | no       | [Chat item types](#chat-item-types) to return. Empty or absent: every type, without `reactions`. With types, each item carries its `reactions` |
| `limit`         | query | integer           | no       | Items per page, 25 by default, at least 0. No maximum                                                                                          |
| `offset`        | query | integer           | no       | Page number, from 1 by default                                                                                                                 |

`limit` and `offset` are read from the query string only. A value in the body is validated and then ignored.

**Response** `200`: `data` is one page.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "items": [
      {
        "uuid": "400",
        "text": "<b>Jane Smith</b> created Task",
        "type": 6,
        "createdTs": 1794387600000,
        "user": {
          "uuid": "300",
          "name": "Jane",
          "image": null,
          "username": "jane@example.com",
          "businessName": "Jane"
        },
        "reactions": []
      }
    ],
    "pagination": {
      "total": 42,
      "perPage": 25,
      "currentPage": 1,
      "lastPage": 2,
      "from": 1,
      "to": 25
    }
  }
}
```

* `items` are [chat item objects](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object), with the deleted messages left out. Each item's `user.username` is the author's username, usually their email address. Each reaction carries the reactor's email and mobile number.
* `text` is the message as stored. Audit lines are HTML, and the web shows text messages as HTML too.
* `reactions` is present only when `chatItemTypes` is sent. Its items are [chat reaction objects](#chat-reaction-object).

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors), and:

* `404` "Resource not found": `jobUuid` doesn't exist.
* `422`: a `chatItemTypes` value isn't a chat type, or `limit` or `offset` isn't a whole number of 0 or more.

A caller who can't see the task still gets `200`.

**Side effects:**

* Adds the caller's viewed rows for the task and its group on every call, also when the caller can't see the task. So a call marks the task as read.
* Each item's author, and each reaction's reactor, is loaded with its own query.
* The request log keeps the response when it is under about 100 KB.

## POST /v1/app/chat/reaction

Adds, changes or removes the caller's reaction to a chat item. Each user has one reaction per item; a new code replaces the previous one.

* **Auth:** user token. The endpoint checks neither membership nor access to the task. Any signed-in user can react to any chat item by its ID. The policy that limits reactions to group admins and members with the "create task" permission (`ChatPolicy::chatReaction`) is never called. The task must be editable. Read-only members pass this check \[[ASK-44](https://github.com/snapfix/docs/blob/main/ASK.md#ask-44-should-read-only-members-post-react-and-delete-chat-messages)].
* **Used by:** web (task chat reactions). Reactions in the chat tab's own chats live in Firestore.

**Request** (JSON)

| Name       | In   | Type           | Required | Rules                                                                                                                                         |
| ---------- | ---- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatUuid` | body | string         | yes      | The chat item                                                                                                                                 |
| `reaction` | body | string or null | no       | A [reaction code](#reaction-codes). `null` or absent removes the caller's reaction. The caller can't add a code they already have on the item |

**Response** `200`: a [chat reaction object](#chat-reaction-object) for the caller's reaction. After a removal, `reaction` is `null`.

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "uuid": "500",
    "jobChatUuid": "400",
    "reaction": "0X1F44D",
    "createdTs": 1794387600000,
    "modifiedTs": 1794387600000,
    "user": {
      "uuid": "300",
      "name": "Jane",
      "image": null,
      "username": "jane@example.com",
      "countryCode": 353,
      "mobile": 850000000
    }
  }
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors), and:

* `404` "Resource not found": the chat item doesn't exist.
* `400` "The task can not be updated": the task is locked, archived or outside its time range.
* `422`: `chatUuid` is missing, `reaction` isn't one of the six codes, or the caller already has that reaction on the item ("The reaction has already been taken.").

**Side effects:**

* Adds a row to [`tPri_Log_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobchat_reaction.md) (`action` 1 when a code is set, 0 when it is removed), and creates or updates the caller's row in [`tPri_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat_reaction.md). There is one row per user and chat item.
* Touches the task and adds the caller's viewed rows ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)).
* Adding a reaction sends a normal push about it (type 52) to the task's people whose settings allow it. Every call sends a silent update push (type 114, or the queue type when `VIA_QUEUE` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]) to the task's people.

## GET /v1/app/chat/token

Gets a Firebase custom token for the caller. The web and the apps sign in to Firebase with it, for the chat tab.

* **Auth:** user token. Any signed-in user.
* **Used by:** web (`firebase.service.ts`, sign-in to Firebase), iOS (`LoginSuccess.swift`), Android (`FirebaseTokenHelper.kt`).

**Request:** none.

**Response** `200`

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": {
    "token": "<Firebase custom token>"
  }
}
```

`token` is a Firebase custom token for the caller's user ID. Its `parents` claim lists the caller's sites: every site the caller has a link to in `tPri_UserParent` (the admin-only filter is commented out), plus the sites of their current task group and asset register memberships, without sites the caller has left (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/UserParentService.php:21-60`). Each site is written as `p_` followed by the site ID, for example `p_200`. The token names no groups or tasks; the Firebase rules that use the claim aren't in the repos \[[ASK-43](https://github.com/snapfix/docs/blob/main/ASK.md#ask-43-where-are-the-firebase-rules-that-guard-chat-data)].

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors). A Firebase failure gives the generic server error.

**Side effects:** none in the database.

## DELETE /v1/app/chat/{uuid}

Deletes a chat item.

* **Auth:** user token. The caller must be the item's author or an admin of the item's group. The author check doesn't need a current membership, so an author who has left the group can still delete their own items. Read-only members pass this check \[[ASK-44](https://github.com/snapfix/docs/blob/main/ASK.md#ask-44-should-read-only-members-post-react-and-delete-chat-messages)]. Who may delete differs by platform. iOS deletes through [`save_pri_job_chat`](#post-actionsave_pri_job_chat), which doesn't apply this rule.
* **Used by:** web (task chat message actions, and task documents).

**Request**

| Name   | In   | Type   | Required | Rules         |
| ------ | ---- | ------ | -------- | ------------- |
| `uuid` | path | string | yes      | The chat item |

**Response** `200`

```json
{
  "status": "success",
  "message": "messages.chat_deleted",
  "data": null
}
```

The message is a key, not text, because no text exists for it.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors), and:

* `403` "Access denied": the caller is neither the author nor an admin of the group.
* `404` "Resource not found": there is no such item, or it's already deleted.
* `400` "The task can not be updated": the task is locked, archived or outside its time range.

**Side effects:**

* Marks the item deleted (`fDeleted` 1, a soft delete). The item stops appearing in the chat list. No audit line is added.
* Touches the task and adds the caller's viewed rows ([common side effects](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-side-effects)).
* Sends a silent update push with type 30 (message delete) to the task's people. When `VIA_QUEUE` is on, the push uses the queue type \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. No visible push goes out.

## POST /v1/app/notification/send

Sends a push notification with a title and a text to the users it names. The web and the apps use it for the chat tab's Firebase chats: mentions, reactions and new messages. It doesn't cover task chat. The server forwards the body the client sends.

* **Auth:** user token. Any signed-in user can call it. It doesn't check that the caller shares a chat, a group or a site with the receivers. Compare, where apipy's push routes need no login at all.
* **Used by:** web (`chat-helper.service.ts`: mentions, reactions and new chat messages), iOS (`ChatNotification.swift`), Android (`FirebaseChatNotificationSender.kt`).

**Request** (JSON)

| Name                  | In   | Type             | Required | Rules                                                                                                       |
| --------------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `receivers`           | body | array of strings | yes      | The user IDs to notify                                                                                      |
| `notificationMsgData` | body | object           | yes      | `title`, `body` and `sound`, each a string and each required. The apps send `sound` "default"               |
| `notificationBody`    | body | object           | yes      | The data sent with the push, as given. The web sends chat fields such as `chatId`, `senderId` and `type` 97 |

Top-level keys that aren't listed, such as `isSilent` and `sender_user_uuid` (which clients send), are ignored. The server adds `withIosSettings: true` to `notificationMsgData`.

**Response** `200`: `data` is `null`, also when every receiver was dropped.

```json
{ "status": "success", "message": "Operation was successful", "data": null }
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors), and `422` when a field is missing or has the wrong type.

**Side effects:**

* Queues one visible push for the receivers' devices. The notification is `title` and `body`, and `notificationBody` goes with it as data.
* Skips receivers who have chat notifications off (`fFirebaseChatCreated` 0 in [`tPri_UserNotifSettings`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_usernotifsettings.md)), and devices with an app version below 600100037.
* Takes each receiver's devices from `firebase_user_device_token`, the newest row of each device, and sends to every one with a token. It applies no group mute and no sender rule, so a sender who is listed as a receiver gets the push too (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/TokenService.php:203-225`, `app/Services/UserDeviceService.php:10-35`).
* Writes one row per push job to [`tPri_Log_NotifAPIRequests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_notifapirequests.md).

## POST ?action=read\_transcripts

Reads the stored transcripts of voice messages.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action doesn't use the caller and checks no access to the chat items or their task.
* **Used by:** iOS (`MessagesVC+Transcript.swift`, for voice messages without a local transcript), Android (`JobViewModel.java`).

**Request** (JSON)

| Name             | In   | Type             | Required | Rules                                                                                                                                                       |
| ---------------- | ---- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `job_chat_uuids` | body | array of strings | yes      | The voice messages to read. Repeats are dropped. Each must exist, be a voice message (type 37) and not be deleted. Messages of different tasks may be mixed |

**Response** `200`

```json
{
  "result": true,
  "message": "success",
  "data": [
    { "job_chat_uuid": "401", "transcript": "Please check the tap in Room 101." },
    { "job_chat_uuid": "402", "transcript": null }
  ],
  "serverTs": 1794387599000
}
```

Every asked ID comes back. `transcript` is `null` when the message has no row in [`tPri_JobChat_VoiceTranscript`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat_voicetranscript.md) yet. `serverTs` is the server time in ms, minus 5 seconds, as on every php-apis answer.

**Errors:** these answer `200` with `result` false and a message, not an HTTP error:

* "Data cannot be blank!" for an empty body.
* "invalid params" when `job_chat_uuids` is missing or empty.
* "invalid jobchats" when an ID isn't an existing, undeleted voice message. Nothing is returned then.

**Side effects:** none. The action only reads.

## POST ?action=save\_pri\_job\_chat

Saves task chat rows from the apps' local databases, including audit lines. iOS sends up to 500 unsynced rows per call. On iOS, a deleted message is saved here too.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). No check that the caller may act on the task, group or row. The author and membership fields come from the rows, not from the token.
* **Used by:** iOS (`TaskManager.swift`, chat sync), Android (`SyncRepository.kt`, chat sync). The web doesn't call it.

**Request** (JSON)

```json
{
  "insert_data": [
    {
      "uuid": "400",
      "uuid_tJob": "123",
      "uuid_tBusiness": "200",
      "uuid_tUserBusiness": "500",
      "fUserBusinessName": "Jane",
      "uuid_tChatItemType": "1",
      "fText": "Leaking tap fixed in Room 101",
      "uuid_tUser_CreatedBy": "300",
      "fCreatedTs": 1794387600000
    }
  ]
}
```

| Name          | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------- | ---- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Rows of [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md), with the columns as stored (`uuid`, `uuid_tJob`, `uuid_tUserBusiness`, `uuid_tBusiness`, `fUserBusinessName`, `uuid_tChatItemType`, `fText`, `fFileUrl`, `fThumbnailUrl`, `fVisible`, `JobChatTs`, `reply_uuid_tJobChat`, the AI fields, `fDeleted`, the times and the user IDs). A row whose `uuid` exists is updated with the fields sent. Any other row is inserted |

The server fills `fServerTs`, and fills `fCreatedTs` and `fModifiedTs` when they are missing or 0, so a message written offline keeps its place in the chat.

**Response** `200`: the [save result object (php-apis)](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis).

```json
{
  "result": true,
  "message": "Please find the processed record count",
  "total_record_count": 1,
  "inserted_record_count": 1,
  "updated_record_count": 0,
  "insert_failed_record_count": 0,
  "update_failed_record_count": 0,
  "serverTs": 1794387599000
}
```

With `LEGACY_QUEUE_SUPPORT` on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], every row is reported as inserted.

**Errors:**

* `{"success": "0", "message": "Data cannot be blank!"}` for an empty body.
* A body without `insert_data` fails with an empty HTTP `500` on the direct path.
* A row that fails counts in `insert_failed_record_count` or `update_failed_record_count`, and `result` is false.

**Side effects:**

* Inserts or updates [`tPri_JobChat`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat.md) rows as sent. The text is stored without HTML removed. Field names reach the SQL as sent, and some JSON values run as SQL.
* For each row whose task exists and whose type isn't 28 (task access changed), sets the task's `fJobChatModifiedTs` and `fServerTs` (php-apis @ aee9175122, `htmlphp/api/snapfix/class/class.functions.php`, `updateJobTableTs`).
* Foreign-key checks are switched off for this table during the save. A row whose task doesn't exist is stored and counted as inserted. says the foreign key rejects such a row. On this path it doesn't.
* Each insert adds one to the task's `job_chat_count`, through the table's trigger.
* With `LEGACY_QUEUE_SUPPORT` on, the rows go to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) and are written after the response is sent.
* On iOS, deleting a message saves its row with `fDeleted` set to 1 (ios @ aa31967ac8, `SnapFix/MessagesVC/MessagesVC.swift:4755-4769`), so this action is also how iOS deletes messages. It doesn't apply the rule of [`DELETE /v1/app/chat/{uuid}`](#delete-v1appchatuuid).
* No push is sent; the apps send their own. The voice step that would ask Snapfix AI for a title and transcript after the answer is commented out \[[ASK-15](https://github.com/snapfix/docs/blob/main/ASK.md#ask-15-is-snapfix-ai-for-voice-tasks-switched-off-on-purpose)].

## POST ?action=save\_pri\_log\_reaction

Saves reaction changes from the apps' local databases.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The reaction's user comes from each row, not from the token. The chat item and its task aren't checked.
* **Used by:** iOS (`TaskManager.swift`, reaction sync), Android (`SyncRepository.kt`, reaction sync).

**Request** (JSON)

| Name          | In   | Type             | Required | Rules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insert_data` | body | array of objects | yes      | Reaction log rows. `uuid_tUser` and `uuid_tJobChat` are required. `uuid` is generated when missing. `reaction_character` is a reaction code, or `null` or empty to remove. `action` is 1 to add or 0 to remove; when missing on a new reaction, it follows `reaction_character`. `fCreatedTs` is set to now when missing. `uuid_tUser_CreatedBy` defaults to `uuid_tUser`. A row whose `uuid` is already in the log is skipped. The code isn't checked against the six reaction codes |

**Response** `200`: the [save result object (php-apis)](https://docs.snapfix.com/engineering-reference/api/tasks.md#save-result-object-php-apis), plus:

* `unprocessed_record_count`: rows skipped because they're already logged.
* `invalid_params_count`: rows without a user or a chat ID.
* `invalid_reaction_record_count`: removals with no reaction to remove. These still leave `result` true.

**Errors:**

* `{"success": "0", "message": "Data cannot be blank!"}` for an empty body.
* `200` with `result` false and "invalid params" when `insert_data` is missing or empty.
* `result` is false when a row fails to insert or update.

**Side effects:**

* Inserts each accepted row into [`tPri_Log_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_jobchat_reaction.md). The log is insert only.
* Creates or updates the user's row in [`tPri_JobChat_Reaction`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_jobchat_reaction.md). A removal sets `reaction_character` to `null`.
* With `LEGACY_QUEUE_SUPPORT` on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)], the rows go to [`tPri_Queue`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_queue.md) and are written after the response is sent.
* No push is sent, and the task isn't touched.

## Chat item types

The values of `type` on a [chat item object](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object), and of `chatItemTypes` on [POST /v1/app/chat/list](#post-v1appchatlist) (`app/Enums/ChatType.php`). Types 1 to 5, 36 and 37 are messages from a person; the others are audit lines the server or the apps write when something about the task changes.

| Type | Meaning                        |
| ---- | ------------------------------ |
| 1    | Text                           |
| 2    | Drawing                        |
| 3    | Image                          |
| 4    | Image with a description       |
| 5    | Video                          |
| 6    | Task created                   |
| 7    | Title changed                  |
| 8    | Location                       |
| 9    | Task image set                 |
| 10   | Checklist item added           |
| 11   | Checklist item checked         |
| 12   | Checklist item unchecked       |
| 14   | Tag added                      |
| 15   | Tag removed                    |
| 19   | Status changed                 |
| 21   | User selected                  |
| 22   | User unselected                |
| 25   | Notification created           |
| 26   | Checklist item removed         |
| 27   | Checklist item edited          |
| 28   | Task access changed            |
| 29   | Note                           |
| 30   | Message deleted                |
| 31   | Planned task                   |
| 32   | NFC read                       |
| 33   | Flag set                       |
| 34   | Flag removed                   |
| 36   | Document                       |
| 37   | Voice                          |
| 38   | Schedule added                 |
| 39   | Schedule updated               |
| 40   | Schedule cancelled             |
| 41   | All checklist items unchecked  |
| 42   | Signature                      |
| 43   | User unassigned                |
| 44   | User assigned                  |
| 45   | Cost added                     |
| 46   | Cost edited                    |
| 47   | Cost removed                   |
| 48   | Time added                     |
| 49   | Time edited                    |
| 50   | Time removed                   |
| 52   | Reaction notification          |
| 53   | Section added                  |
| 54   | Section updated                |
| 55   | Section deleted                |
| 56   | Reminder set                   |
| 57   | Reminder removed               |
| 58   | Reminder                       |
| 59   | Asset added                    |
| 60   | Asset removed                  |
| 61   | Task turned amber on its own   |
| 66   | Time range set                 |
| 67   | Time range updated             |
| 68   | Time range cleared             |
| 69   | Task copied                    |
| 70   | Task moved                     |
| 71   | Copied without messages        |
| 72   | Copied with messages           |
| 73   | Checklist completed            |
| 74   | Room added                     |
| 75   | Room removed                   |
| 76   | Checklist item renamed         |
| 77   | Due date set                   |
| 78   | Due date updated               |
| 79   | Due date cleared               |
| 81   | Task created from chat         |
| 82   | System added                   |
| 83   | System removed                 |
| 84   | Area added                     |
| 85   | Area removed                   |
| 86   | Sent for approval              |
| 87   | Approved                       |
| 88   | Rejected                       |
| 89   | Rejection note                 |
| 90   | Sent for approval, admins only |
| 91   | Snoozed                        |
| 98   | User added                     |

## Reaction codes

The only values [POST /v1/app/chat/reaction](#post-v1appchatreaction) stores (`app/Enums/Reactions.php`).

| Code      | Meaning           |
| --------- | ----------------- |
| `0X1F44D` | Thumbs up         |
| `0X1F64C` | Raised hands      |
| `0X1F50E` | Magnifying glass  |
| `0X1F6E0` | Hammer and wrench |
| `0X1F44C` | OK hand           |
| `0X1F6A5` | Traffic light     |

## Chat reaction object

A reaction to a chat item (`ChatReactionResource`). It's returned by [POST /v1/app/chat/reaction](#post-v1appchatreaction), and it's in the `reactions` of a [chat item object](https://docs.snapfix.com/engineering-reference/api/tasks.md#chat-item-object) when those are loaded.

| Field                     | Type           | Meaning                                                                                                                                                                                                    |
| ------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                    | string         | Reaction ID                                                                                                                                                                                                |
| `jobChatUuid`             | string         | The chat item                                                                                                                                                                                              |
| `reaction`                | string or null | A [reaction code](#reaction-codes); `null` after a removal                                                                                                                                                 |
| `createdTs`, `modifiedTs` | integer        | Epoch ms                                                                                                                                                                                                   |
| `user`                    | object or null | The reactor: `uuid`, `name`, `image`, `username` (usually their email address), `countryCode` and `mobile` (their phone number). `username`, `countryCode` and `mobile` are null when the account has 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/engineering-reference/api/chat.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.
