User Presence

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 an map of User objects with only a widgets field.

POST/v1/{appId}/presences
{
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
{
selectedConversationId: "987654"
}

Get sessions for users 1234, 5678 and 9012

POST/v1/{appId}/presences
{
userIds: ["1234", "5678", "9012"]
}

Get sessions for users that are typing in conversation 987654

POST/v1/{appId}/presences
{
selectedConversationId: "987654",
isTyping: true
}

List users with expanded information who are online but not in any conversation right now.

POST/v1/{appId}/presences
{
selectedConversationId: null,
expandUser: true
}

Deprecated Legacy presence API

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

GET/v1/{appId}/users/{userId}/sessions
[
{
"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:

// 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:

// 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:

// request:
GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions
// response:
[
{
"isTyping": false,
"currentConversationId": null
},
{
"isTyping": true,
"currentConversationId": "1234"
}
]