--- title: "List conversations" method: GET path: "/v1/{appId}/conversations" tags: ["Conversations"] --- # List conversations `GET /v1/{appId}/conversations` ## Request - Base URL: `https://api.talkjs.com` - URL: `https://api.talkjs.com/v1/{appId}/conversations` - Auth: one of: - HTTP bearer - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](https://talkjs.com/docs/Reference/JavaScript_Chat_SDK/Other_interfaces/#ConversationPredicate). URLencode the JSON formatted filter to use your custom filter. #### NodeJS example ```js // 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(); ``` ## Path parameters - `appId` string, required ## Query parameters - `startingAfter` string - `limit` integer - `orderBy` 'lastActivity' | 'createdAt' - `orderDirection` 'DESC' | 'ASC' - `offsetTs` integer - `lastMessageBefore` integer - `lastMessageAfter` integer ## Response `200` Conversations listed successfully. - ConversationsInApp: An object that wraps an array of conversations - `data` Conversation[]: An array with conversations that have been created in a TalkJS application. - `id` string: A unique identifier of a conversation. You determine the conversation ID yourself. For more information on setting a conversation ID, see: [Conversation ID](https://talkjs.com/docs/Reference/Concepts/Conversations/#the-conversation-id). - `participants` object: A participant is a user who is a member of a conversation. A participant can be @mentioned in a conversation, get notified of new activity, and is listed in the conversation's member list. - `access` 'Read' | 'ReadWrite' | 'None': A setting to control the type of access that a participant has to a conversation. Participants can have access to a conversation with one of three different types of access right: | Access | Result | | -- | -- | | `ReadWrite` | The participant has full access to the conversation. The participant can read messages from, and write messages to, other users, and can be listed in the conversation header. | | `Read` | The participant has read-only access to the conversation. The participant can read messages from other users, but not post messages themselves. The participant can be listed in the conversation header. | | `None` | The participant has no access to the conversation. The participant can't read messages from or write messages to the conversation, nor are they listed in the header of the conversation. When a participant's access to a conversation is withdrawn, they won't receive any new messages. However, they can still access the messages up to the point at which their access was removed. If a participant whose access to a conversation was removed at a later point gets their access back, then they can again read the entire conversation history, including all the messages that were sent while they didn't have access. - `notify` union: A setting to control if and when a participant should get notifications for unread messages when they meets the [conditions](https://talkjs.com/docs/Features/Notifications/#when-are-notifications-sent) for getting a notification. If you have enabled [mentions](https://talkjs.com/docs/Features/Message_Features/Mentions/) for your chat, you can set this notification property to `MentionsOnly` so that participants are only notified when they're mentioned. | Notifications | Result | | -- | -- | | `true` | The participant receives notifications. | | `false` | The participant **doesn't** receive notifications. | | `"MentionsOnly"` | The participant only receives notifications when they're mentioned in the conversation. | - boolean - string - `subject` string, nullable: An optional conversation subject that is displayed in the chat header. To delete any existing value, set this property to `null`. - `custom` object: Custom field for a conversation. To delete any existing value, set this property to `null`. - `createdAt` integer: Timestamp for when this conversation was edited, expressed as the number of milliseconds since the UNIX epoch (1970-1-1, 00:00:00 UTC). - `topicId` string: Identifier of the topic of this conversation. `topicId` is deprecated. Instead, use `id` to set a unique identifier of a conversation, and use `subject` to set the subject of a conversation. - `photoUrl` string, nullable: An optional URL to an image that is shown as the photo for the conversation in the chat header. - `welcomeMessages` string[]: An array of messages that are sent directly at the start of a conversation. Welcome messages set at conversation level appear as [system messages](https://talkjs.com/docs/Reference/Concepts/System_Messages/). - `lastMessage` Message: A message in a conversation. - `id` string: An automatically generated unique identifier of this message. - `type` 'UserMessage' | 'SystemMessage': Whether this message is a [message](https://talkjs.com/docs/Reference/Concepts/Messages/) sent by a user, or a [system message](https://talkjs.com/docs/Reference/Concepts/System_Messages/). - `origin` 'web' | 'rest' | 'email' | 'import': Indicates how this message was sent. Possible origin options are: - web browser or mobile WebView (`"web"`) - REST API (`"rest"`) - reply-to-email (`"email"`) - REST API import operation (`"import"`) - `location` number[]: An array of two numbers that represent the longitude and latitude of a location, respectively. `location` is only given if the message's type is a shared location. - `text` string, nullable: Text of a message body. `text` is only given if the message type is text. - `custom` object: A custom object with key-value pairs that you want to associate with a message. Both keys and values must be strings. You can access a custom property in for example API responses, webhook events, and themes. - `attachment` object, nullable: An object with the dimensions, location, and filesize (in bytes) of a file attached to this message. `attachment` is a read-only property that is only given if a message is a file transfer. - `dimensions` object: The dimensions of the attachment in pixels. - `height` integer: The height of the attachment, in pixels. - `width` integer: The width of the attachment, in pixels. - `size` integer: The size of the attached file, in bytes. - `url` string: The URL where the attachment is stored. - `conversationId` string: Unique ID of the conversation this message is part of. - `createdAt` number, nullable: The time at which the message was posted. For welcome messages the timestamp is always `nil`. - `senderId` string, nullable: A unique identifier of the user who sent the message. For asystem messages the sender is always `nil`. - `editedAt` integer: Timestamp when this message was edited, expressed as the number of milliseconds since the UNIX epoch (1970-1-1, 00:00:00 UTC). - `referencedMessageId` string, nullable: Unique identifier of the message that this message is replying to. Referencing a message can be done via TalkJS UI. - `readBy` unknown[], nullable: An array of user IDs of users who have read this message. **Note:** `readBy` is only used for conversations with at most 300 participants. For conversations with 301 or more participants, the `readBy` field will be empty. - unknown ## Other responses - `400`: Bad request - `401`: Authorization information is missing or invalid. - `404`: Resource not found - `429`: Too many requests - `500`: Internal server error --- [API](https://skmtc.dev/talkjs/apis/talkjs-api.md) - [All operations](https://skmtc.dev/talkjs/apis/talkjs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talkjs/apis/talkjs-api/revisions/9d4acc9cfa43?raw)