---
source_url: https://www.pubnub.com/docs/chat/chat-sdk/build/features/users/updates
title: Manage user updates
updated_at: 2026-06-17T11:36:38.449Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Manage user updates

Update user details and receive real-time update events.

:::note Requires App Context
Enable [App Context](https://youtu.be/9UEoSlngpYI) in the [Admin Portal](https://admin.pubnub.com/) to store user data.
:::

## Update user details

Edit user metadata with `update()` or `updateUser()`.

* `update()` - call on a `User` object (no ID needed)
* `updateUser()` - call on a `Chat` object (requires user ID)

### Method signature

These methods take the following parameters:

* update() 1user.update({2 name?: string,3 externalId?: string,4 profileUrl?: string,5 email?: string,6 custom?: ObjectCustom,7 status?: string,8 type?: string9}): Promise<User>
* updateUser() 1chat.updateUser(2 id: string,3 {4 name?: string,5 externalId?: string,6 profileUrl?: string,7 email?: string,8 custom?: ObjectCustom,9 status?: string,10 type?: string11 }): Promise<User>

#### Input

| Parameter | Required in update() | Required in updateUser() | Description |
| --- | --- | --- | --- |
| id | string | Optional |  | No | Yes | [Unique user identifier](https://www.pubnub.com/docs/general/setup/users-and-devices#user-id-usage). |
| name | string | Optional |  | No | No | Display name for the user (must not be empty or consist only of whitespace characters). |
| externalId | string | Optional |  | No | No | User's identifier in an external system. You can use it to match `id` with a similar identifier from an external database. |
| profileUrl | string | Optional |  | No | No | URL of the user's profile picture. |
| email | string | Optional |  | No | No | User's email address. |
| custom | ObjectCustom | Optional |  | No | No | JSON providing custom data about the user. Values must be scalar only; arrays or objects are not supported. [Filtering App Context data](https://www.pubnub.com/docs/general/metadata/filtering) through the `custom` property is not recommended in SDKs. |
| status | string | Optional |  | No | No | Tag that lets you categorize your app users by their current state. The tag choice is entirely up to you and depends on your use case. For example, you can use `status` to mark users in your chat app as `invited`, `active`, or `archived`. |
| type | string | Optional |  | No | No | Tag that lets you categorize your app users by their functional roles. The tag choice is entirely up to you and depends on your use case. For example, you can use `type` to group users by their roles in your app, such as `moderator`, `player`, or `support-agent`. |

:::tip API limits
To learn about the maximum length of parameters used to set user metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-user-metadata).
:::

#### Output

| Type | Description |
| --- | --- |
| `Promise<User>` | Returned object containing the updated user metadata. |

#### Errors

Whenever the user ID is required, and you try to update the user without providing their ID, you will receive the `ID is required` error. If you try to edit a user that doesn't exist, you will receive the `User with this ID does not exist` error.

### Sample code

Change the link to the user's `support_agent_15` LinkedIn profile to `https://www.linkedin.com/mkelly_vp2`.

* update() 1// reference the "user" object2const user = await chat.getUser("support_agent_15")3// invoke the "update()" method on the "user" object4await user.update(5 {6 custom: {7 linkedInUrl: "https://www.linkedin.com/mkelly_vp2"8 }9 }10)
* updateUser() 1// reference the "chat" object and invoke the "updateUser()" method2const user = await chat.updateUser(3 "support_agent_15",4 {5 custom: {6 linkedInUrl: "https://www.linkedin.com/mkelly_vp2"7 }8 }9)

## Get user updates

Receive real-time updates when a [User object](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user) is edited or deleted using the event-driven methods introduced in chat-1-0-0:

* `onUpdated()` - fires when a user's metadata changes
* `onDeleted()` - fires when a user is deleted

Both methods accept a callback and return an unsubscribe function.

### Method signature

These methods take the following parameters:

* onUpdated() 1user.onUpdated(2 callback: (user: User) => void3): () => void
* onDeleted() 1user.onDeleted(2 callback: () => void3): () => void

#### Input

| Parameter | Description |
| --- | --- |
| `callback` *Type: n/aDefault: n/a | Callback function invoked when the user event occurs. |
| → `user`Type: `User`Default: n/a | The updated [User object](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user). Only passed to `onUpdated()`. |

#### Output

| Type | Description |
| --- | --- |
| `() => void` | Function you can call to stop listening to user events. |

### Sample code

Listen for updates and deletions on `support_agent_15`.

```ts
const user = await chat.getUser("support_agent_15")

const stopUpdated = user.onUpdated((updated) => {
    console.log("User updated:", updated)
})

const stopDeleted = user.onDeleted(() => {
    console.log("User was deleted")
})

// after some time...
stopUpdated()
stopDeleted()
```

## Get user updates (deprecated)

:::warning Deprecated
`streamUpdates()` is deprecated as of chat-1-0-0. Use [onUpdated()](#get-user-updates) and [onDeleted()](#get-user-updates) instead. `streamUpdatesOn()` remains supported.
:::

Receive updates when [User objects](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user) are edited or removed:

* `streamUpdates()` - monitors a single user
* `streamUpdatesOn()` - monitors multiple users

:::note Callback behavior
* `streamUpdates()`: returns updated `User` object (or `null` if deleted)
* `streamUpdatesOn()`: returns complete list of monitored users on any change
:::

### Method signature

These methods take the following parameters:

* streamUpdates() 1user.streamUpdates(2 callback: (user: User) => unknown3): () => void
* streamUpdatesOn() 1static User.streamUpdatesOn(2 users: User[],3 callback: (users: User[]) => unknown4): () => void

#### Input

| Parameter | Required in `streamUpdates()` | Required in `streamUpdatesOn()` | Description |
| --- | --- | --- | --- |
| `users`Type: `User[]`Default: n/a | No | Yes | Array of [User objects](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/user) for which you want to get updates. |
| `callback`Type: n/aDefault: n/a | Yes | Yes | Callback function passed as a parameter to both methods. It defines the custom behavior to be executed when detecting user metadata changes. |
| → `user`Type: `User`Default: n/a | Yes | No | Returned `User` object with the updated data. |
| → `users`Type: `User[]`Default: n/a | No | Yes | Returned array of `User` objects with the updated data. |

#### Output

| Type | Description |
| --- | --- |
| `() => void` | Function you can call to disconnect (unsubscribe) from the channel and stop receiving `objects` events. |

#### Errors

Whenever a list of `User` objects is required as a parameter, and you try to get updates on users without specifying their list, you will receive the `Cannot stream user updates on an empty list` error.

### Sample code

Get updates on `support_agent_15`.

* streamUpdates() 1const user = await chat.getUser("support_agent_15")2user.streamUpdates((user) => {3 // The callback receives the entire updated User object each time a change occurs.4 if (user) {5 console.log("Updated user: ", user)6 } else {7 console.log("User was deleted")8 }9})

Get updates on `support_agent_15` and `support-manager`.

* streamUpdatesOn() 1const agentUser = await chat.getUser("support_agent_15")2const managerUser = await chat.getUser("support-manager")3User.streamUpdatesOn([agentUser, managerUser], (users) => {4 // The callback receives the complete list of all users you're monitoring5 // each time any change occurs.6 console.log("Updated users: ", users)7})

### Other examples

Stop listening to updates on `support_agent_15`.

* streamUpdates() 1const user = await chat.getUser("support_agent_15")2const stopUpdates = user.streamUpdates(/* handle update callback */)3// after some time...4stopUpdates()

Stop listening to updates on `support_agent_15` and `support-manager`.

* streamUpdatesOn() 1const agentUser = await chat.getUser("support_agent_15")2const managerUser = await chat.getUser("support-manager")3const stopUpdates = User.streamUpdatesOn([agentUser, managerUser], /* handle update callback */)4// after some time...5stopUpdates()