TAtalkjs
Users

List conversations a user is part of

Lists all conversations that a user is a part of.

The response contains user-specific fields to indicate whether a user has any unread messages in a conversation (isUnread), and a counter for unread messages (unreadMessageCount).

You can filter results with optional provided filters, or create your own custom filters.

Filter by custom filters

You can create a custom filter in the required JSON structure using your preferred programming language. The filter interface is the same as the JavaScript SDK's Conversation filter. URLencode the JSON formatted filter to use your custom filter.

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();
get/v1/{appId}/users/{userId}/conversations

Request

Path parameters

appIdstring required
Example:abcd1234

A unique identifier of your TalkJS app. You can find your app ID on the Settings page of your dashboard.

userIdstring required
Example:alice

A unique identifier of a user.

Query parameters

orderBy'lastActivity' | 'createdAt'
Example:createdAt

Optional parameter to control the sorting order of conversations.

You can sort conversations either based on the timestamp of their last activity (lastActivity), or the timestamp of their date of creation (createdAt). Ordering conversations by their creation date can be useful if you want stable sorting.

orderDirection'DESC' | 'ASC'
Example:ASC

Optional parameter to control the sorting order of conversations. You can sort conversations either in descending (DESC) or ascending (ASC) order.

startingAfterstring
Example:c10

An optional object ID that identifies a place in the record list, to allow you to paginate through a list of results.

By default, all records are sorted in descending order based on their createdAt property, which is a timestamp of a record's insertion date.

limitinteger
Example:25

An optional parameter to specify the number of conversations that should be returned.

offsetTsinteger
Example:1521522849308

An optional timestamp to offset results with. Using OffsetTs can be useful combined with lastActivity sorting, since conversations can move to the front of the results list when new messages are sent.

lastMessageAfterinteger
Example:1521522849308

Optional filter to return only conversations where the last message was sent after a certain timestamp. The timestamp should be a Unix timestamp expressed in milliseconds.

lastMessageBeforeinteger
Example:1521522849308

Optional filter to return only conversations where the last message was sent before a certain timestamp. The timestamp should be a Unix timestamp expressed in milliseconds.

unreadsOnlyboolean
Example:true

Optional filter to return only conversations that contain messages the user hasn't read yet.

Response

Conversations for a user listed successfully.

Example response

{
  "data": [
    {
      "id": "1629972494",
      "participants": {
        "alice": {
          "access": "ReadWrite",
          "notify": "MentionsOnly"
        },
        "zayneb": {
          "access": "ReadWrite",
          "notify": true
        }
      },
      "subject": "Studio headphones",
      "custom": {
        "productId": "454545"
      },
      "createdAt": 1525249255419,
      "topicId": "customer_support",
      "photoUrl": "https://example.com/productpictures/012345.jpg",
      "welcomeMessages": [
        "Hello there!",
        "I'm currently out of town, leave a message and I'll respond ASAP :)"
      ],
      "lastMessage": {
        "id": "msg_123ABcdefghiJKlmNOpqRS",
        "type": "UserMessage",
        "origin": "web",
        "location": [
          51.44442681184582,
          5.4733118103642395
        ],
        "text": "Hi, how are you?",
        "custom": {
          "priority": "high"
        },
        "attachment": {
          "dimensions": {
            "height": 1125,
            "width": 516
          },
          "size": 51552,
          "url": "https://example.com/attachment.jpg"
        },
        "conversationId": "0123456789",
        "createdAt": 1697711905431,
        "senderId": "alice",
        "editedAt": 1629972494633,
        "referencedMessageId": "msg_012ABcdefghiJKlmNOpqRS",
        "readBy": [
          "zayneb"
        ]
      },
      "isUnread": true,
      "unreadMessageCount": 2
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.