Users
Monday, November 23, 2020 2:06 AMTable of Contents
All resource URLs include an {appId}
, which you can find in the Dashboard.
Path: | /v1/{appId}/users/{userId} |
Methods: | GET, PUT |
{userId}
is your internal unique identifier for the user.
Creating or updating a user
Before you start sending messages, you need to synchronize participants of the conversation.
PUT https://api.talkjs.com/v1/{appId}/users/{userId}
{
"name": string,
"email": Array<string>,
"welcomeMessage": string,
"photoUrl": string,
"role": string,
"phone": Array<string>,
"custom": Map<string, string>
}
Example payload:
{
"name": "Alice",
"email": ["[email protected]"],
"welcomeMessage": "Hi there, how are you? :-)",
"photoUrl": "https://demo.talkjs.com/img/alice.jpg",
"role": "buyer",
"phone": ["+1123456789"],
"custom": {
"country": "ca"
}
}
Getting created users
After you successfully create or update a user, you can fetch it back with a GET REST call.
GET https://api.talkjs.com/v1/{appId}/users/{userId}
The interface for this resource is the following:
type UserId = string;
type UnixMilliseconds = number;
type User = {
id: UserId;
name: string;
welcomeMessage?: string;
photoUrl?: string;
headerPhotoUrl?: string;
role?: string;
email?: string[] | null;
phone?: string[] | null;
custom?: {[name: string]: string };
availabilityText?: string;
locale?: string;
createdAt: UnixMilliseconds;
};
Listing conversations a user is a part of
This lists all conversations the user is a part of.
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations
The response is structured the same as when listing all conversations.
Filters
If you want to filter a user's conversations you have the following options:
-
Filter by the last message's timestamp
It is possible to filter conversations by when the last message was sent to the conversation using the
lastMessageBefore
andlastMessageAfter
filters.lastMessageBefore
andlastMessageAfter
should be Unix timestamps expressed in milliseconds. -
Only return unreads
You can pass
unreadsOnly=true
to only list conversations that contain messages the user hasn't read yet. -
Filter by
custom
andaccess
fields.TalkJS also supports filtering by
custom
andaccess
fields. The filter interface is precisely the same as the JavaScript SDK's Conversation Filter, except that only the operations listed below are supported. In order to use the filter you need to URLencoded the JSON formatted filter.-
the
access
level filter supports a set of basic equals operators (==
,!=
) for three access levels:ReadWrite
,Read
andNone
. For example:- Fetch only conversations that the user is currently still a part of: { access: ["!=", "None"]}
- Fetch only conversations that the user is able to write in: { access: ["==", "ReadWrite"]}
- Fetch only conversations that the user is only able to read but not write in: { access: ["==", "Read"]}
-
the
custom
fields filter supports the following operators:==
,!=
,exists
,!exists
.
You can use your favorite programming language to generate the filter in the required JSON structure.
-
NodeJS example:
// fetches a conversation which has a custom field { "category": "shoes" } and the user can read and write in
const filter = {custom: {category: ["==", "shoes"], access: ["==", "ReadWrite"]}};
const encodedFilter = encodeURIComponent(JSON.stringify(filter));
const res = await fetch(`https://api.talkjs.com/v1/${appId}/users/${userId}/conversations?filter=${encodedFilter}`);
const conversations = await res.json();
Limits and pagination
Similarly to other list requests, pagination and limits are applicable to listing a user's conversations.
Examples
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?unreadsOnly=true
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageBefore=1521522849308
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageBefore=1521522849308&lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?unreadsOnly=true&lastMessageBefore=1521522849308&lastMessageAfter=1421522849732
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&startingAfter=c_84726
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&startingAfter=c_84726&lastMessageBefore=1521522849308
Listing all users in the application
You can list all users ever created in your TalkJS application. The structure of the response is explained here.
GET https://api.talkjs.com/v1/{appId}/users
Limits and pagination
Similarly to other list requests, pagination and limits are applicable to listing users.
Filters
TalkJS supports a limited set of filters for getting user information.
In order to only list users that are online or offline, you have to pass the isOnline
parameter to the query string:
GET https://api.talkjs.com/v1/{appId}/users?isOnline=true
GET https://api.talkjs.com/v1/{appId}/users?isOnline=false
Examples
GET https://api.talkjs.com/v1/{appId}/users
GET https://api.talkjs.com/v1/{appId}/users?limit=50
GET https://api.talkjs.com/v1/{appId}/users?limit=50&startingAfter=u_31
GET https://api.talkjs.com/v1/{appId}/users?startingAfter=u_31
GET https://api.talkjs.com/v1/{appId}/users?isOnline=true&limit=3
GET https://api.talkjs.com/v1/{appId}/users?isOnline=false&limit=5&startingAfter=u_48
Deleting users
TalkJS currently does not have a way to delete user data. Instead, we suggest you use our edit endpoints to remove any personally identifiable information (PII) associated with the user. We have created a script that you can use to automate this process which can be found in our GitHub examples repository.