# Folded threads API Proposal

## New Endpoints

### GET /api/v4/users/{user_id}/threads?page=0&pageSize=30
Retrive list of threads that user is following
Optional request parameters (in query string):

* page - zero based index of result page to display (default: 0)
* pageSize - amount of items per page (default: 30)
* extended - include participants details in response (default: false)
* since - optional timestamp of the time when the thread list was fetched last (useful for fetching only threads that were modified, i.e. threads that were either deleted since that timestamp or reply count changes, etc)
* deleted - include deleted posts

Response format:

{
    "total": 1234,
    "unreadReplies": 0, // total unread replies across all threads
    "unreadMentions": 0, // total unread mentions across all threads
    "threads": [
        {
            "id": "xxxxx", // id of root post
            "reply_count": 5, // reply count
            "unreadReplies": 0, //  unread replies in this thread
            "unreadMentions": 0, //  unread mentions in this thread
            "last_reply_at": 12452736687, // when was the last reply
            "last_viewed_at": 1234895164, // when the thread was last opened
            "participants": [ // list of thread participants
               // just user id if 'extended' was set to false
               {"id": "xxxxxx"},
               // full user profile if 'extended' was set to true
               {"id": "xxxxxx", "first_name":"...", "last_name":"...", ... } 
            ],
            "post": {
               // all post fields of the root post
            }
        }
    ]
}

### PUT /api/v4/users/{user_id}/threads/{thread_id}/following

Start following the thread

### DELETE /api/v4/users/{user_id}/threads/{thread_id}/following

Stop following the thread

### PUT /api/v4/users/{user_id}/threads/{thread_id}/read

Mark thread as 'read'

### DELETE /api/v4/users/{user_id}/threads/{thread_id}/read

Mark thread as 'unread'

### PUT /api/v4/users/{user_id}/threads/read

Mark all threads as 'read'

### DELETE /api/v4/users/{user_id}/threads/read

Mark all threads as 'unread'

## Updated endpoints

All 'get posts' methods, i.e.:
`/api/v4/users/{user_id}/channels/{channel_id}/posts/unread`
`/api/v4/channels/{channel_id}/posts`
`/api/v4/posts/{post_id}/thread`

Will receive additional optional query parameter: `collapsedThreads=true`
Optionally, `extendedCollapsedThreads=true` can be provided to enrich `participants` array

In this mode, the output of these API calls will change, instead of returning all posts, only top-level posts will be returned, and for those posts that have replies (i.e. threads), additional fields will be added to the output:

* `participants` - array of user IDs (used to show avatars under the thread info in the channel): ``[{id:"zxxxx", id:"xcccvbs"}]`` or if `extendedCollapsedThreads` is set it will return the full user objects
* `reply_count` - amount of replies
* `followed` - if current user is following this thread
* `last_reply_at` - timestamp of last reply
* `unreadReplies` - unread replies in this thread
* `unreadMentions` - unread mentions in this thread

# Config

## ServiceSettings.CollapsedThreads

Defaults to 'disabled'.
Can also be 'default_on' or 'default_off' to set thread preference for users.
User can override via user preference: 'collapsed_threads_settings.collapsed_threads_enabled'

## ServiceSettings.ThreadAutoFollow
Defaults to 'true'.
Controls if the threads are autofollowed when:
1. Somebody replies to your post
2. You are mentioned in a thread
3. When someone replies to a root post you are mentioned in

# Websocket events

## New events

### thread_updated
issued when there is a change in a thread (new post). includes thread details in 'thread' field.

### thread_follow_changed
issued when a thread 'followed' state is changed
includes 'thread_id' and 'state' fields, 'state' is true/false indicating following/unfollowed

### thread_read_changed
issued when a thread 'read' state is changed
includes 'thread_id' and 'timestamp' fields, 'timestamp' indicates the time to which the thread was reset to.
if 'thread_id' is not included - even applies to ALL user threads

## Updated events

### posted/post_edited/post_deleted
Additional 'following' boolean will be added