---
title: "List online users"
method: POST
path: "/v1/{appId}/presences"
tags: ["User presence"]
---

# List online users

`POST /v1/{appId}/presences`

## Request

- Base URL: `https://api.talkjs.com`
- URL: `https://api.talkjs.com/v1/{appId}/presences`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
- TypeScript: <https://skmtc.dev/talkjs/apis/talkjs-api/docs/v1/:appId/presences/post.ts> (a function with typed inputs; its response is checked against the schema)

Lists online users. 

You can programmatically check the online status and current activity of users on your app.

If you create a TalkJS session on every page—which we recommend—then TalkJS internally stores two sessions: one background session for each user, and one session for each active [TalkJS chat UI widget](https://talkjs.com/docs/Features/Chat_UI_Modes/). 

By default, we don't return users with only a background session. You can change this behavior by passing the `includeBackgroundSessions` option.

## Path parameters

- `appId` string, required

## Request body

- OnlineUserListCreateData: Requirements for the list of online users to be created.
  - `includeBackgroundSessions` boolean: Filter users based on whether they have their TalkJS session in the background or not. The following values are accepted: - **false**: Only return users who have a TalkJS UI widget in the foreground. - **true**: Return all online users. Users who has their TalkJS UI widget in the background are returned with an empty `widgets` field.
  - `selectedConversationId` string, nullable: Filter users who are online in the selected conversation. Requires passing in a `conversationID`. You can pass an explicit `null` value to filter users who are online but have no conversation selected. Omit this field to return online users in all conversations, regardless of whether a conversation is selected.
  - `hasFocus` boolean: Filter users based on whether they have the TalkJS UI in focus or not. Omit this field to get all online users, regardless of whether they have the TalkJS UI in focus.
  - `isTyping` boolean: Only return users who are currently typing in a conversation. Omit this field to get all users, regardless of whether they're typing.
  - `userIds` string[]: Only show sessions for users with the given user IDs. Omit this option to not filter on user ID.

## Response `200`

Online users listed successfully.

- OnlineUserList: Online users.
  - `data` object: A data object that wraps online users.

## Other responses

- `400`: Bad request
- `401`: Authorization information is missing or invalid.
- `404`: Resource not found
- `415`: Unsupported media type
- `429`: Too many requests
- `500`: Internal server error

---

[API](https://skmtc.dev/talkjs/apis/talkjs-api.md) - [All operations](https://skmtc.dev/talkjs/apis/talkjs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talkjs/apis/talkjs-api/revisions/9d4acc9cfa43?raw)