> ## 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)

<img src="https://mintcdn.com/velt/vGgIoGfoceFP8dEI/images/presence/inactivity.png?fit=max&auto=format&n=vGgIoGfoceFP8dEI&q=85&s=b108868f28bb7f92b263def2967173e3" alt="" width="1280" height="720" data-path="images/presence/inactivity.png" />

<Tabs>
  <Tab title="React / Next.js">
    ```js theme={null}
    <VeltPresence inactivityTime={30000} />
    ```

    Using API:

    ```js theme={null}
    const presenceElement = client.getPresenceElement();
    presenceElement.setInactivityTime(30000);
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-presence inactivity-time="30000"></velt-presence>
    ```

    Using API:

    ```js theme={null}
    const presenceElement = Velt.getPresenceElement();
    presenceElement.setInactivityTime(30000);
    ```
  </Tab>
</Tabs>

#### 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`.

<img src="https://mintcdn.com/velt/vGgIoGfoceFP8dEI/images/presence/Presence_Max_Users.png?fit=max&auto=format&n=vGgIoGfoceFP8dEI&q=85&s=22a59f6d4fa9e38f6d7dc9225c8a7ef8" alt="" width="1280" height="720" data-path="images/presence/Presence_Max_Users.png" />

<Tabs>
  <Tab title="React / Next.js">
    ```js theme={null}
    <VeltPresence maxUsers={3} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-presence max-users="3"></velt-presence>
    ```
  </Tab>
</Tabs>

#### 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)

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    <VeltPresence offlineInactivityTime={600000} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-presence offline-inactivity-time="600000"></velt-presence>
    ```
  </Tab>
</Tabs>

#### self

* Whether to include yourself in the list of `Presence` users.
* Default: `true`

<img src="https://mintcdn.com/velt/vGgIoGfoceFP8dEI/images/presence/self.png?fit=max&auto=format&n=vGgIoGfoceFP8dEI&q=85&s=b2d5ec5876759d9736b0251513b03162" alt="" width="1280" height="720" data-path="images/presence/self.png" />

<Tabs>
  <Tab title="React / Next.js">
    ```js theme={null}
    <VeltPresence self={false} />
    ```

    API Method:

    ```jsx theme={null}
    const presenceElement = client.getPresenceElement();
    presenceElement.enableSelf();
    presenceElement.disableSelf();
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-presence self="false"></velt-presence>
    ```

    API Method:

    ```jsx theme={null}
    const presenceElement = Velt.getPresenceElement();
    presenceElement.enableSelf();
    presenceElement.disableSelf();
    ```
  </Tab>
</Tabs>

#### locationId

* Renders the Presence avatar if any user is active on the given `locationId`.
  <img src="https://mintcdn.com/velt/vGgIoGfoceFP8dEI/images/presence/Location.png?fit=max&auto=format&n=vGgIoGfoceFP8dEI&q=85&s=58567fb631747c51848723c522909312" alt="" width="1280" height="720" data-path="images/presence/Location.png" />

<Tabs>
  <Tab title="React / Next.js">
    ```js theme={null}
    <VeltPresence locationId={"YOUR_LOCATION_ID"} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```html theme={null}
    <velt-presence location-id="YOUR_LOCATION_ID"></velt-presence>
    ```
  </Tab>
</Tabs>

# Data

#### getData

* Subscribe to presence data.
* **Params:** [`PresenceRequestQuery`](/api-reference/sdk/models/data-models#presencerequestquery) (optional)
* **Returns:** [`Observable<GetPresenceDataResponse>`](/api-reference/sdk/models/data-models#getpresencedataresponse)

<Tabs>
  <Tab title="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>

  <Tab title="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);
    });
    ```
  </Tab>
</Tabs>

# Programmatic User Management

<Info>
  You can also manage users server-side using the [Presence REST APIs](/api-reference/rest-apis/v2/presence/add-presence).
</Info>

#### [addUser()](/api-reference/sdk/api/api-methods#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`](/api-reference/sdk/models/data-models#presenceuser)`>, localOnly?: boolean }`
* **Returns:** `void`

<Tabs>
  <Tab title="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>

  <Tab title="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 });
    ```
  </Tab>
</Tabs>

#### [removeUser()](/api-reference/sdk/api/api-methods#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`](/api-reference/sdk/models/data-models#presenceuser)`>, localOnly?: boolean }`
* **Returns:** `void`

<Tabs>
  <Tab title="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>

  <Tab title="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 });
    ```
  </Tab>
</Tabs>

# 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](/api-reference/sdk/models/data-models#presenceuserstatechangeevent) |

<Tabs>
  <Tab title="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>

  <Tab title="Other Frameworks">
    ```ts theme={null}
    const presenceElement = Velt.getPresenceElement();
    presenceElement.on("userStateChange").subscribe((data) => {
        console.log("userStateChange", data);
    });
    ```
  </Tab>
</Tabs>

#### onPresenceUserClick

* This event is triggered when a user clicks on a presence avatar.

<img src="https://mintcdn.com/velt/vGgIoGfoceFP8dEI/images/presence/onPresenceUserClick.png?fit=max&auto=format&n=vGgIoGfoceFP8dEI&q=85&s=efd8efdb886dc478f12bd498238d7a1f" alt="" width="1280" height="720" data-path="images/presence/onPresenceUserClick.png" />

<Tabs>
  <Tab title="React / Next.js">
    ```jsx theme={null}
    const onPresenceUserClickEvent = (user) => {
      console.log("Clicked presence user: ", user);
    }
    	
    <VeltPresence onPresenceUserClick={(user) => onPresenceUserClickEvent(user)} />
    ```
  </Tab>

  <Tab title="Other Frameworks">
    ```jsx theme={null}
    const presenceTag = document.querySelector('velt-presence');
    	presenceTag.addEventListener('onPresenceUserClick', (event) => {
    		console.log("Clicked presence user: ", event.detail);
    });
    ```
  </Tab>
</Tabs>

# 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](/api-reference/rest-apis/v2/presence/add-presence) — add one or more users to the presence list for a document.
* [Update Presence](/api-reference/rest-apis/v2/presence/update-presence) — update presence data (name, email, status) for existing users on a document.
* [Delete Presence](/api-reference/rest-apis/v2/presence/delete-presence) — remove one or more users from the presence list for a document.