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

Payload Structure

Response Structure

Example Response


1{
2  includeBackgroundSessions?: boolean,
3  selectedConversationId?: string | null,
4  hasFocus?: boolean,
5  isTyping?: boolean,
6  userIds?: string[]
7}


1{
2  data: 
3    {userId}: {
4      status: string,
5      backgroundSessions: [{
6        selectedConversationId: string | null,
7        custom: Map<string, string>,
8        hasFocus: boolean,
9        isTyping: boolean,
10        sessionId: string
11      }],
12      widgets: [{
13        selectedConversationId: string | null,
14        custom: Map<string, string>,
15        hasFocus: boolean,
16        isTyping: boolean,
17        sessionId: string
18      }]
19    },
20}


1{
2  "data": {
3    "623b106653a97": {
4      "status": "online",
5      "backgroundSessions": [],
6      "widgets": [
7        {
8          "selectedConversationId": "987654",
9          "custom": {},
10          "hasFocus": true,
11          "isTyping": false,
12          "sessionId": "0123456789-0123456789-abcde-abcde"
13        }
14      ]
15    }
16  }
17}

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


1{
2  selectedConversationId: "987654"
3}


1{
2  "data": 
3    "623b106653a97": {
4      "widgets": [
5        {
6          "selectedConversationId": "987654",
7          "custom": {},
8          "hasFocus": true,
9          "isTyping": false
10        }
11      ]
12  }
13}

Get sessions for users 1234, 5678 and 9012

POST/v1/{appId}/presences

Example Payload

Example Response


1{
2  userIds: ["1234", "5678", "9012"]
3}


1{
2  "data": {
3    "5678": {
4      "widgets": [
5         {
6           "selectedConversationId": null,
7           "custom": {},
8           "hasFocus": false,
9           "isTyping": false
10         },
11         {
12           "selectedConversationId": "456789",
13           "custom": {},
14           "hasFocus": true,
15           "isTyping": false
16         }
17      ]
18    },
19    "9012": {
20      "widgets": [
21        {
22        "selectedConversationId": "987654",
23        "custom": {},
24        "hasFocus": true,
25        "isTyping": true
26        }
27      ]  
28    }
29  }  
30}

Get sessions for users that are typing in conversation 987654

POST/v1/{appId}/presences

Example Payload

Example Response


1{
2    selectedConversationId: "987654",
3    isTyping: true
4}


1{
2  "data": {
3      "5678": {
4      "widgets": [
5        {
6          "selectedConversationId": "987654",
7          "custom": {},
8          "hasFocus": true,
9          "isTyping": true
10        }
11      ]  
12    },
13    "9012": {
14      "widgets": [
15        {
16          "selectedConversationId": "987654",
17          "custom": {},
18          "hasFocus": true,
19          "isTyping": true
20        }
21      ]  
22    }
23  }
24}

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

POST/v1/{appId}/presences

Example Payload

Example Response


1{
2  selectedConversationId: null
3}


1{
2  "data": {
3    "5678" : {
4      "availabilityText": null,
5      "createdAt": 1643719013438,
6      "custom": {},
7      "email": [
8        "[email protected]"
9      ],
10      "locale": null,
11      "name": "Alice",
12      "phone": null,
13      "photoUrl": "http://localhost:50000/demo/img/alice.jpg",
14      "role": "booker",
15      "welcomeMessage": null,
16      "widgets": [
17        {
18          "selectedConversationId": null,
19          "custom": {},
20          "hasFocus": false,
21          "isTyping": false
22        }
23      ]  
24    }
25  }
26}

Deprecated Legacy presence API

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

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

Response Structure


1[
2  {
3    "isTyping": boolean,
4    "currentConversationId": string | null
5  },
6  ...
7]

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:


1// request:
2GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions
3
4// response:
5[]

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


1// request:
2GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions
3
4// response:
5[
6  {
7    "isTyping": false,
8    "currentConversationId": null
9  }
10]

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


1// request:
2GET https://api.talkjs.com/v1/YOUR_APP_ID/users/6789/sessions
3
4// response:
5[
6  {
7    "isTyping": false,
8    "currentConversationId": null
9  },
10  {
11    "isTyping": true,
12    "currentConversationId": "1234"
13  }
14]

User Presence

Getting a list of online users

About background and widget sessions

Available options

selectedConversationId

hasFocus

isTyping

includeBackgroundSessions

userIds

Examples

Get all users from conversation 987654

Get sessions for users 1234, 5678 and 9012

Get sessions for users that are typing in conversation 987654

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

Deprecated Legacy presence API

Examples

User 6789 is offline:

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

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