Users
All resource URLs include an {appId}, which you can find in the Dashboard.
{userId} is your internal unique identifier for the user.
Before you start sending messages, you need to synchronize participants of the conversation.
{"name": string,"email": Array<string>,"welcomeMessage": string,"photoUrl": string,"role": string,"phone": Array<string>,"custom": Map<string, string>,"pushTokens": Map<string, true | null> | null}
{"name": "Alice","welcomeMessage": "Hi there, how are you? :-)","photoUrl": "https://demo.talkjs.com/img/alice.jpg","role": "buyer","phone": ["+1123456789"],"custom": {"country": "ca"}"pushTokens": {"fcm:MY_TOKEN_ID": true}}
pushTokens is an object that has the keys in the format:
"provider:token_id"
Where provider is either fcm for Android (Firebase Cloud Messaging), or apns for iOS (Apple Push Notification Service).
the value for each key can be either true for registering the device for push notifications, or null for unregistering the device.
Setting pushTokens to null unregisters all the previously registered devices.
After you successfully create or update a user, you can fetch it back with a GET REST call.
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;pushTokens: { [token_id: string]: true | null } | null;};
{"availabilityText": null,"createdAt": 1623926680918,"custom": {},"id": "123456789","locale": "en-US","name": "Alice","phone": null,"photoUrl": "https://demo.talkjs.com/marketplace_demo/img/alice.jpg","role": "default","welcomeMessage": "Hey there! How are you? :-)""pushTokens": {"apns:MY_TOKEN_ID": true}}
This lists all conversations the user is a part of.
The response is structured the same as when listing all conversations.
{"data": Array<Conversation>}
{"data": [{"createdAt": 1623926680929,"custom": {},"id": "87d70908d90cee5d12bd","lastMessage": {"attachment": null,"conversationId": "87d70908d90cee5d12bd","createdAt": 1630326385720,"custom": {},"id": "msg_7HtvCJLjdZoRsYE2nCXp2n","location": null,"origin": "web","readBy": ["123456789"],"senderId": "432156789","text": "it","type": "UserMessage"},"participants": {"87d70908d90cee5d12bd""123456789": {"access": "ReadWrite","notify": true},"432156789": {"access": "ReadWrite","notify": true}},"photoUrl": null,"subject": "Random conversation","topicId": null,"welcomeMessages": null},{...}]}
Ordering is available since API version 2021-02-09
Default order in versions before 2021-02-09 is createdAt DESC and cannot be changed
By default, conversations are returned in the order of the last activity in them, latest first. You can change the order by using orderBy and orderDirection query parameters. Conversations can either be sorted by creation date or by the last activity in the conversation. Ordering conversations by the creation date can be useful when you want stable sorting.
The following values are accepted in the orderBy query parameter:
lastActivity(default): sort by last activity timestampcreatedAt: sort by date of creation
The following values are accepted in the orderDirection query parameter:
DESC(default): descending orderASC: ascending order
Conversations can be paginated, as any other listing handle.
Using startingAfter requires passing in a conversation ID, whereby results will start with the conversation right after the selected one in the current sort order. It works with all currently supported sorting options.
Another option is to use offsetTs which accepts a timestamp and offsets the results according to the sort order. This might be more useful when used in conjunction with lastActivity sorting since conversations can move to the front of the list as new messages come, and using one of the conversations as a pointer can yield unexpected results.
offsetTs is available since API version 2021-02-09
If you want to filter a user's conversations you have the following options:
It is possible to filter conversations by when the last message was sent to the conversation using the lastMessageBefore and lastMessageAfter filters.
lastMessageBefore and lastMessageAfter should be Unix timestamps expressed in milliseconds.
You can pass unreadsOnly=true to only list conversations that contain messages the user hasn't read yet.
TalkJS also supports filtering by custom and access 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
accesslevel filter supports a set of basic equals operators (==,!=) for three access levels:ReadWrite,ReadandNone. 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
customfields filter supports the following operators:==,!=,exists,!exists.
You can use your favorite programming language to generate the filter in the required JSON structure.
// fetches a conversation which has a custom field { "category": "shoes" } and the user can read and write inconst 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();
GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?unreadsOnly=trueGET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageBefore=1521522849308GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageAfter=1421522849732GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?lastMessageBefore=1521522849308&lastMessageAfter=1421522849732GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?unreadsOnly=true&lastMessageBefore=1521522849308&lastMessageAfter=1421522849732GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&startingAfter=c_84726GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&startingAfter=c_84726&lastMessageBefore=1521522849308GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&offsetTs=1521522849308GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&sortBy=lastActivity+DESC
You can list all users ever created in your TalkJS application. The response has a data field with an array of User objects as described above.
{"data": Array<User>}
{"data": [{"name": "Alice","welcomeMessage": "Hi there, how are you? :-)","photoUrl": "https://demo.talkjs.com/img/alice.jpg","role": "buyer","phone": ["+1123456789"],"custom": {"country": "ca"}},{...}]}
Similarly to other list requests, pagination and limits are applicable to listing users.
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}/usersGET https://api.talkjs.com/v1/{appId}/users?limit=50GET https://api.talkjs.com/v1/{appId}/users?limit=50&startingAfter=u_31GET https://api.talkjs.com/v1/{appId}/users?startingAfter=u_31GET https://api.talkjs.com/v1/{appId}/users?isOnline=true&limit=3GET https://api.talkjs.com/v1/{appId}/users?isOnline=false&limit=5&startingAfter=u_48
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.