---
url: https://talkjs.com/docs/REST_API/User_Presence
---

# User presence

Check which users are online and what they're doing.

Ask a question Copy for LLM [View as Markdown](/docs/REST_API/User_Presence.md)
You can programmatically check the online status and current activity of users on your app.

POST /v1/{appId}/presences

## Getting a list of online users

This lists all currently online users in your TalkJS application.

The response has a `data` field with a map of `User` objects with only a `widgets` field.

POST /v1/{appId}/presences

Payload Structure Response Structure Example Response

```typescript
{
  includeBackgroundSessions?: boolean,
  selectedConversationId?: string | null,
  hasFocus?: boolean,
  isTyping?: boolean,
  userIds?: string[]
}
```

### About background and widget sessions

If you create a TalkJS session on every page, which we recommend, then we internally store one background session for this user. In addition we also record one session for each visible TalkJS UI widget (an Inbox, a Chatbox or a popup widget).
By default we do not return users with only a background session. You can change this behaviour by passing the `includeBackgroundSessions` option.

### Available options

##### selectedConversationId

*(optional)*: string Filter users online in the given 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 not filter on currently selected conversations.

##### hasFocus

*(optional)*: boolean When set to `true`: only return users who are currently watching the TalkJS UI.
When set to `false`: only return users who are not watching the TalkJS UI.
Omit this field to get all users regardless of hasFocus.

##### isTyping

*(optional)*: boolean Only return users who are currently typing in a conversation.
Omit this field to get all users regardless of isTyping.

##### includeBackgroundSessions

*(optional)*: boolean Controls the filtering based on visibility of sessions.
The following values are accepted:

- `false` (default): Only return users who have a visible TalkJS UI widget.
- `true`: Return all online users. Users without a visible TalkJS UI widget will be returned with an empty `widgets` field.

##### userIds

*(optional)*: string[] Only show sessions for the given users. This is limited to a maximum of 1000 per request.

Omit this option to not filter on userIds.

### Examples

#### Get all users from conversation 987654

POST /v1/{appId}/presences

Example Payload Example Response

```typescript
{
  selectedConversationId: "987654"
}
```

#### Get sessions for users 1234, 5678 and 9012

POST /v1/{appId}/presences

Example Payload Example Response

```typescript
{
  userIds: ["1234", "5678", "9012"]
}
```

#### Get sessions for users that are typing in conversation 987654

POST /v1/{appId}/presences

Example Payload Example Response

```typescript
{
    selectedConversationId: "987654",
    isTyping: true
}
```

#### List users who are online but not in any conversation right now.

POST /v1/{appId}/presences

Example Payload Example Response

```typescript
{
  selectedConversationId: null
}
```

## Deprecated Legacy presence API

`{userId}` is your internal unique identifier for the user.

GET /v1/{appId}/users/{userId}/sessions

Response Structure

```typescript
[
  {
    "isTyping": boolean,
    "currentConversationId": string | null
  },
  ...
]
```

If you create a TalkJS session on every page, which we recommend, then you may see multiple session objects in the response: one for the TalkJS background session, and one for each visible TalkJS UI (an Inbox, a Chatbox or a popup widget).

### Examples

#### User 6789 is offline:

```typescript
// request:
GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions

// response:
[]
```

#### User 6789 is logged into your site, but not looking at a TalkJS UI:

```typescript
// request:
GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions

// response:
[
  {
    "isTyping": false,
    "currentConversationId": null
  }
]
```

#### User 6789 is logged into your site and looking at conversation 1234 in the Inbox, currently busy typing a message:

```typescript
// request:
GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions

// response:
[
  {
    "isTyping": false,
    "currentConversationId": null
  },
  {
    "isTyping": true,
    "currentConversationId": "1234"
  }
]
```