--- url: https://talkjs.com/docs/REST_API/Users/ title: "Users | REST API | TalkJS Docs" --- For AI agents: Find a documentation index at https://talkjs.com/llms.txt (full content at https://talkjs.com/llms-full.txt). Get a markdown version of any page by appending .md to its URL path. # Users Create, update, and subscribe to user data. All resource URLs include an `{appId}`, which you can find on the **Settings** page of your [dashboard](https://talkjs.com/dashboard). GETPUT/v1/{appId}/users/{userId} `{userId}` is your internal unique identifier for the user. ## Create or update a user Before you start sending messages, you need to synchronize participants of the conversation. **Note:** To update user details, you only need to send the subset of fields you want to update. In that respect, even though you update a user with an HTTP `PUT` request method, the user update acts similar to an HTTP `PATCH` request method. PUT/v1/{appId}/users/{userId} Payload StructureExample Payload ```typescript type RequestBody = { name: string, email?: Array | null, welcomeMessage?: string | null, photoUrl?: string | null, locale?: string | null, role?: string | null, phone?: Array | null, custom?: Record | null, pushTokens?: Record, true | null> | null } ``` `pushTokens` is an object that has the keys in the format: ```js '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. ## Batch update users You can update multiple users with a single API call. PUT/v1/{appId}/users Payload StructureExample Payload ```typescript type RequestBody = { [userId: string]: { name: string, email?: Array | null, welcomeMessage?: string | null, photoUrl?: string | null, locale?: string | null, role?: string | null, phone?: Array | null, custom?: Record | null, pushTokens?: Record, true | null> | null } } ``` If all of the provided update objects are valid, a HTTP 200 status code is returned and all the updates are applied. If one or more update objects are invalid, none of the updates are applied (even if some of them were valid) and a HTTP 400 status code is returned in the response, along with an object that holds error messages for the invalid updates. Here's an example of an invalid payload and the generated response: PUT/v1/{appId}/users Example PayloadExample Response ```js { // Valid update object "alice": { "name": "Alice" }, // Invalid; required `name` property is missing "sebastian": {} } ``` In this case a `400 Bad Request` is returned and neither `alice` nor `sebastian` are updated. **Note:** Currently you can update a maximum of 100 users with a single API call. Attempting to update more will result in a `400 Bad Request` and no users will be updated. ## Get created users After you successfully create or update a user, you can fetch it back with a GET REST call. GET/v1/{appId}/users/{userId} Response StructureExample Response ```typescript type UserId = string; type UnixMilliseconds = number; type User = { id: UserId; name: string; welcomeMessage: string; photoUrl: 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; }; ``` ## List conversations a user is a part of This lists all conversations the user is a part of. The response is structured similarly to [the one when listing all conversations](https://talkjs.com/docs/REST_API/Conversations/#listing-all-conversations-in-the-application), but it contains additional, user specific fields. GET/v1/{appId}/users/{userId}/conversations Response StructureExample Response ```typescript type UsersConversation = { id: ConversationId; subject: string | null; photoUrl: string | null; welcomeMessages: string[] | null; custom: { [name: string]: string }; lastMessage: Message | null; unreadMessageCount: number; isUnread: boolean; participants: { [id: UserId]: { access: 'ReadWrite' | 'Read'; notify: boolean }; }; createdAt: UnixMilliseconds; }; type Response = { data: Array } ``` ### Ordering **Ordering is available since API version [`2021-02-09`](https://talkjs.com/docs/REST_API/Versions/#2021-02-09)** Default order in versions before [`2021-02-09`](https://talkjs.com/docs/REST_API/Versions/#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 timestamp - `createdAt`: sort by date of creation The following values are accepted in the `orderDirection` query parameter: - `DESC` (default): descending order - `ASC`: ascending order ### Pagination Conversations [can be paginated](https://talkjs.com/docs/REST_API/#listing), as any other list resource. You can request a maximum of 100 conversations in a single request. 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`](https://talkjs.com/docs/REST_API/Versions/#2021-02-09)** ### 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` and `lastMessageAfter` filters. `lastMessageBefore` and `lastMessageAfter` 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 filters TalkJS also supports filtering by various fields. The filter interface is precisely the same as the JavaScript SDK's [Conversation Filter](https://talkjs.com/docs/UI_Components/JavaScript/Classic/Other_Interfaces/#ConversationPredicate). In order to use the filter you need to URL-encode the JSON formatted filter. You can use your favorite programming language to generate the filter in the required JSON structure. #### NodeJS example ```typescript // 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(); ``` #### Examples ```typescript 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 GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&offsetTs=1521522849308 GET https://api.talkjs.com/v1/{appId}/users/{userId}/conversations?limit=5&sortBy=lastActivity+DESC ``` ## List all users in the application 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](https://talkjs.com/docs/REST_API/Users/#getting-created-users). GET/v1/{appId}/users Response StructureExample Response ```typescript { "data": Array } ``` ### Limits and pagination Similarly to other list requests, pagination and limits are applicable to [listing users](https://talkjs.com/docs/REST_API/#listing). You can request a maximum of 100 users in a single request. ### 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/v1/{appId}/users?isOnline=true GET/v1/{appId}/users?isOnline=false #### List users examples ```typescript 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 ``` ## Delete 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](https://github.com/talkjs/talkjs-examples/tree/master/rest-api/anonymizing-user).