> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Customize Behavior
# Configuration
#### inactivityTime
* Configure when a user is considered inactive after being inactive.
* These are considered as inactive:
* no mouse movement
* no keyboard activity
* This is in milliseconds.
* This will set the following fields in the presence user object:
* `onlineStatus` to `away`
* `isUserIdle` to `true`
Note about tab focus:
* If a user's tab is unfocused, we immediately update following fields in the presence user object:
* `onlineStatus` to `away`
* `isTabAway` to `true`
Default: `300000` (5 min)
> [tab] React / Next.js
>
> ```js theme={null}
>
> ```
>
> Using API:
>
> ```js theme={null}
> const presenceElement = client.getPresenceElement();
> presenceElement.setInactivityTime(30000);
> ```
> [tab] Other Frameworks
>
> ```html theme={null}
>
> ```
>
> Using API:
>
> ```js theme={null}
> const presenceElement = Velt.getPresenceElement();
> presenceElement.setInactivityTime(30000);
> ```
#### maxUsers
* Set how many `Presence` avatars to display at a time.
* You can set this via the `maxUsers` attribute. Any extra avatars will be hidden and shown in an avatar which indicates the number of extra `Users`.
> [tab] React / Next.js
>
> ```js theme={null}
>
> ```
> [tab] Other Frameworks
>
> ```html theme={null}
>
> ```
#### offlineInactivityTime
* Configure when a user is considered offline if they do not take any action on the document within the specified timeframe.
* User is also marked offline if they lose internet connection.
* This is in milliseconds.
* This will set the `onlineStatus` field in the presence user object to `offline` if they are inactive for the given time.
Default: `600000` (10 min)
> [tab] React / Next.js
>
> ```jsx theme={null}
>
> ```
> [tab] Other Frameworks
>
> ```html theme={null}
>
> ```
#### self
* Whether to include yourself in the list of `Presence` users.
* Default: `true`
> [tab] React / Next.js
>
> ```js theme={null}
>
> ```
>
> API Method:
>
> ```jsx theme={null}
> const presenceElement = client.getPresenceElement();
> presenceElement.enableSelf();
> presenceElement.disableSelf();
> ```
> [tab] Other Frameworks
>
> ```html theme={null}
>
> ```
>
> API Method:
>
> ```jsx theme={null}
> const presenceElement = Velt.getPresenceElement();
> presenceElement.enableSelf();
> presenceElement.disableSelf();
> ```
#### locationId
* Renders the Presence avatar if any user is active on the given `locationId`.
> [tab] React / Next.js
>
> ```js theme={null}
>
> ```
> [tab] Other Frameworks
>
> ```html theme={null}
>
> ```
# Data
#### getData
* Subscribe to presence data.
* **Params:** [`PresenceRequestQuery`](https://velt.dev/docs/api-reference/sdk/models/data-models#presencerequestquery) (optional)
* **Returns:** [`Observable`](https://velt.dev/docs/api-reference/sdk/models/data-models#getpresencedataresponse)
> [tab] React / Next.js
>
> **Using Hook:**
>
> ```jsx theme={null}
> // Fetch users with status: online
> const presenceData = usePresenceData({ statuses: ['online'] });
>
> useEffect(() => {
> if (presenceData && presenceData.data) {
> console.log('Presence data (online users): ', presenceData.data);
> }
> }, [presenceData]);
>
> // Fetch all users (no query)
> const presenceData = usePresenceData();
> useEffect(() => {
> if (presenceData && presenceData.data) {
> console.log('Presence data (all users): ', presenceData.data);
> }
> }, [presenceData]);
> ```
>
> **Using API:**
>
> ```ts theme={null}
> const presenceElement = client.getPresenceElement();
> // Fetch online users
> presenceElement.getData({ statuses: ['online'] }).subscribe((response: GetPresenceDataResponse) => {
> console.log("Presence data (online users): ", response.data);
> });
>
> // Fetch all users (no query)
> presenceElement.getData().subscribe((response: GetPresenceDataResponse) => {
> console.log("Presence data (all users): ", response.data);
> });
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> const presenceElement = Velt.getPresenceElement();
> // Fetch online users
> presenceElement.getData({ statuses: ['online'] }).subscribe((response) => {
> console.log("Presence data (online users): ", response.data);
> });
>
> // Fetch all users (no query)
> presenceElement.getData().subscribe((response) => {
> console.log("Presence data (all users): ", response.data);
> });
> ```
# Programmatic User Management
> [!NOTE]
>
> You can also manage users server-side using the [Presence REST APIs](https://velt.dev/docs/api-reference/rest-apis/v2/presence/add-presence.md).
#### [addUser()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#adduser)
* Programmatically add a custom user (e.g., AI agent, bot, system account) to the presence list for the current document.
* Set `localOnly: true` to restrict the change to the current client without persisting to the database. Useful for showing local-only indicators such as AI agents visible only to the current user.
* **Params:** `{ user: Partial<`[`PresenceUser`](https://velt.dev/docs/api-reference/sdk/models/data-models#presenceuser)`>, localOnly?: boolean }`
* **Returns:** `void`
> [tab] React / Next.js
>
> ```js theme={null}
> const presenceElement = client.getPresenceElement();
>
> // Add a persistent custom user
> presenceElement.addUser({ user: { userId: 'ai-agent-1', name: 'AI Assistant' } });
>
> // Add a local-only user (not persisted to database)
> presenceElement.addUser({ user: { userId: 'local-bot', name: 'Local Bot' }, localOnly: true });
> ```
> [tab] Other Frameworks
>
> ```js theme={null}
> const presenceElement = Velt.getPresenceElement();
>
> // Add a persistent custom user
> presenceElement.addUser({ user: { userId: 'ai-agent-1', name: 'AI Assistant' } });
>
> // Add a local-only user (not persisted to database)
> presenceElement.addUser({ user: { userId: 'local-bot', name: 'Local Bot' }, localOnly: true });
> ```
#### [removeUser()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#removeuser)
* Programmatically remove a custom user from the presence list for the current document.
* Set `localOnly: true` to restrict the removal to the current client (matches the `localOnly` flag used when adding the user).
* **Params:** `{ user: Partial<`[`PresenceUser`](https://velt.dev/docs/api-reference/sdk/models/data-models#presenceuser)`>, localOnly?: boolean }`
* **Returns:** `void`
> [tab] React / Next.js
>
> ```js theme={null}
> const presenceElement = client.getPresenceElement();
>
> // Remove a persistent user
> presenceElement.removeUser({ user: { userId: 'ai-agent-1' } });
>
> // Remove a local-only user
> presenceElement.removeUser({ user: { userId: 'local-bot' }, localOnly: true });
> ```
> [tab] Other Frameworks
>
> ```js theme={null}
> const presenceElement = Velt.getPresenceElement();
>
> // Remove a persistent user
> presenceElement.removeUser({ user: { userId: 'ai-agent-1' } });
>
> // Remove a local-only user
> presenceElement.removeUser({ user: { userId: 'local-bot' }, localOnly: true });
> ```
# Event Subscription
#### on
* Subscribe to Presence Events. Here is the list of events you can subscribe to and the event objects you will receive.
| Event Type | Description | Event Object |
| - | - | - |
| `userStateChange` | Triggered when a user state changes to online, offline, or away | [PresenceUserStateChangeEvent](https://velt.dev/docs/api-reference/sdk/models/data-models.md#presenceuserstatechangeevent) |
> [tab] React / Next.js
>
> **Using Hook:**
>
> ```jsx theme={null}
> const userStateChangeEventData = usePresenceEventCallback('userStateChange');
>
> useEffect(() => {
> if (userStateChangeEventData) {
> console.log('userStateChange: ', userStateChangeEventData);
> }
> }, [userStateChangeEventData]);
> ```
>
> **Using API:**
>
> ```ts theme={null}
> const presenceElement = client.getPresenceElement();
> presenceElement.on("userStateChange").subscribe((data: PresenceUserStateChangeEvent) => {
> console.log("userStateChange", data);
> });
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> const presenceElement = Velt.getPresenceElement();
> presenceElement.on("userStateChange").subscribe((data) => {
> console.log("userStateChange", data);
> });
> ```
#### onPresenceUserClick
* This event is triggered when a user clicks on a presence avatar.
> [tab] React / Next.js
>
> ```jsx theme={null}
> const onPresenceUserClickEvent = (user) => {
> console.log("Clicked presence user: ", user);
> }
>
> onPresenceUserClickEvent(user)} />
> ```
> [tab] Other Frameworks
>
> ```jsx theme={null}
> const presenceTag = document.querySelector('velt-presence');
> presenceTag.addEventListener('onPresenceUserClick', (event) => {
> console.log("Clicked presence user: ", event.detail);
> });
> ```
# Backend REST APIs
Use these REST API endpoints for server-side management of presence records. A common use case is showing AI agents or bots as live participants while they work on a document — for example, surfacing an "AI Editor" avatar alongside human collaborators. Also useful for seeding presence state, removing stale users, or integrating with external session management systems.
* [Add Presence](https://velt.dev/docs/api-reference/rest-apis/v2/presence/add-presence.md) — add one or more users to the presence list for a document.
* [Update Presence](https://velt.dev/docs/api-reference/rest-apis/v2/presence/update-presence.md) — update presence data (name, email, status) for existing users on a document.
* [Delete Presence](https://velt.dev/docs/api-reference/rest-apis/v2/presence/delete-presence.md) — remove one or more users from the presence list for a document.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.