TAtalkjs
Conversations

List conversations

Lists all conversations ever created in your TalkJS application.

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}/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.

Query parameters

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.

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.

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.

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.

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.

Response

Conversations 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"
        ]
      }
    }
  ]
}

Changes

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