---
title: "Batch update users (chat API) (v2)"
method: PATCH
path: "/v2/chats/users"
tags: ["Chats"]
---

# Batch update users (chat API) (v2)

`PATCH /v2/chats/users`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/chats/users`
- Auth: HTTP bearer

**Auth**: User JWT

Batch update chat user fields (firstName / lastName / username /
profileImage / email).

Auth model: User JWT with `appUsers.update` Acl, or B2B Server JWT
targeting the token's own app.

Lookup: each item must include `uuid` OR `xmppUsername`. The
`xmppUsername` (when supplied) MUST start with `<reqUser.appId>_`
(the calling token's app id). This strict prefix check is intentional
and catches a common SDK foot-gun: wrappers that double-prefix the
xmppUsername (e.g. `<appId>_<appId>_<id>`). When acting on a CHILD
app from a parent-app token, the prefix can never match this route's
expectation - prefer the path-explicit
`PATCH /v2/apps/{appId}/chats/users` (tenant-actor auth) instead.

Per-user statuses (in `results[]` / `details[]`):
  - `updated`     - row updated, fresh `user` snapshot returned
  - `not-found`   - no user matched `{uuid|xmppUsername, appId}`
  - `skipped`     - no updatable fields present in the item
  - `invalid`     - payload-shape rejection (e.g. xmppUsername
                    prefix mismatch, email already in use by
                    another user in this app)

The HTTP status is always 200 when the request itself was well-
formed; clients MUST inspect each item's `status` to know if an
individual user actually changed.

## Request body

- object
  - `users` object[], required: Array of user-record patches. Each item must include `uuid` OR `xmppUsername` to identify the target user; any remaining keys (`firstName`, `lastName`, `username`, `profileImage`, `email`) are applied. The endpoint returns per-item status under `results[]` so a single bad row never fails the whole batch.
    - `uuid` string
    - `xmppUsername` string
    - `firstName` string
    - `lastName` string
    - `username` string
    - `profileImage` string: URL
    - `email` string, email: Validated against the deployment's EMAIL_TLD_VALIDATION policy (off | icann | list); trim/lowercase normalized server-side. Pass an empty string to clear the email. Returns `status: 'invalid'` if the new value is already used by another user in the same appId.

## Response `200`

```
{ ok: true, summary, results, details }
```
See description above for the per-user `status` values you must
inspect to know if individual rows actually changed.

- ChatUsersPatchBatchResponse
  - `ok` boolean, required
  - `summary` BatchSummary, required
    - `requested` integer, required: How many items the client requested to process.
    - `byStatus` object, required
  - `results` ChatUsersPatchBatchDetail[], required
    - `uuid` string, nullable
    - `xmppUsername` string, nullable
    - `status` string
    - `reason` string, nullable
    - `user` UserPublic
      - `_id` string
      - `uuid` string, nullable
      - `xmppUsername` string
      - `email` string, nullable
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `username` string, nullable
      - `profileImage` string, nullable
      - `profilePicture` string, nullable
      - `description` string, nullable
      - `tags` string[], nullable
  - `details` ChatUsersPatchBatchDetail[], required
    - `uuid` string, nullable
    - `xmppUsername` string, nullable
    - `status` string
    - `reason` string, nullable
    - `user` UserPublic
      - `_id` string
      - `uuid` string, nullable
      - `xmppUsername` string
      - `email` string, nullable
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `username` string, nullable
      - `profileImage` string, nullable
      - `profilePicture` string, nullable
      - `description` string, nullable
      - `tags` string[], nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)