TAtalkjs
User presence

List online users

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.

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

post/v1/{appId}/presences

Request

Path parameters

appIdstring required
Example:abcd1234

A unique identifier of your TalkJS app. You can find your app ID on the Settings page of your dashboard.

Request body

includeBackgroundSessionsboolean

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.
selectedConversationIdstring 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.

hasFocusboolean

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.

isTypingboolean

Only return users who are currently typing in a conversation. Omit this field to get all users, regardless of whether they're typing.

userIdsstring[]

Only show sessions for users with the given user IDs. Omit this option to not filter on user ID.

Example request

{
  "includeBackgroundSessions": true,
  "selectedConversationId": "0123456789",
  "hasFocus": true,
  "isTyping": true,
  "userIds": [
    "alice",
    "sebastian"
  ]
}

Response

Online users listed successfully.

dataobject

A data object that wraps online users.

Example response

{
  "data": {
    "alice": {
      "status": "online",
      "backgroundSessions": [
        {
          "custom": {
            "priority": "high"
          },
          "selectedConversationId": "0123456789abcdef",
          "isTyping": false,
          "hasFocus": true,
          "sessionId": "0123456789-0123456789-abcde-abcde"
        }
      ],
      "widgets": [
        {
          "custom": {
            "priority": "high"
          },
          "selectedConversationId": "0123456789abcdef",
          "isTyping": false,
          "hasFocus": true,
          "sessionId": "0123456789-0123456789-abcde-abcde"
        }
      ]
    },
    "sebastian": {
      "status": "online",
      "backgroundSessions": [
        {
          "custom": {
            "priority": "high"
          },
          "selectedConversationId": "0123456789abcdef",
          "isTyping": false,
          "hasFocus": true,
          "sessionId": "0123456789-0123456789-abcde-abcde"
        }
      ],
      "widgets": [
        {
          "custom": {
            "priority": "high"
          },
          "selectedConversationId": "0123456789abcdef",
          "isTyping": false,
          "hasFocus": false,
          "sessionId": "0123456789-0123456789-abcde-abcde"
        }
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.