Merge branch 'libmagic' into 'develop'

[akkoma] / docs / API / chats.md

diff --git a/docs/API/chats.md b/docs/API/chats.md
index 2e415e4dac1284deb0e9daea7d0df51470d60c0b..f50144c865997a9d6971d6fe17767f1de34a251d 100644 (file)
--- a/docs/API/chats.md
+++ b/docs/API/chats.md
@@ -41,7 +41,7 @@ This is the overview of using the API. The API is also documented via OpenAPI, s
 To create or get an existing Chat for a certain recipient (identified by Account ID)
 you can call:
 
 To create or get an existing Chat for a certain recipient (identified by Account ID)
 you can call:
 

-`POST /api/v1/pleroma/chats/by-account-id/{account_id}`
+`POST /api/v1/pleroma/chats/by-account-id/:account_id`

 
 The account id is the normal FlakeId of the user
 ```
 
 The account id is the normal FlakeId of the user
 ```


@@ -75,10 +75,15 @@ Returned data:
 
 ### Marking a chat as read
 
 
 ### Marking a chat as read
 

-To set the `unread` count of a chat to 0, call
+To mark a number of messages in a chat up to a certain message as read, you can use

 
 `POST /api/v1/pleroma/chats/:id/read`
 
 
 `POST /api/v1/pleroma/chats/:id/read`
 

+
+Parameters:
+- last_read_id: Given this id, all chat messages until this one will be marked as read. Required.
+
+

 Returned data:
 
 ```json
 Returned data:
 
 ```json


@@ -94,6 +99,15 @@ Returned data:
 }
 ```
 
 }
 ```
 

+### Marking a single chat message as read
+
+To set the `unread` property of a message to `false`
+
+`POST /api/v1/pleroma/chats/:id/messages/:message_id/read`
+
+Returned data:
+
+The modified chat message

 
 ### Getting a list of Chats
 
 
 ### Getting a list of Chats
 


@@ -102,6 +116,10 @@ Returned data:
 This will return a list of chats that you have been involved in, sorted by their
 last update (so new chats will be at the top).
 
 This will return a list of chats that you have been involved in, sorted by their
 last update (so new chats will be at the top).
 

+Parameters:
+
+- with_muted: Include chats from muted users (boolean).
+

 Returned data:
 
 ```json
 Returned data:
 
 ```json


@@ -121,13 +139,13 @@ Returned data:
 ```
 
 The recipient of messages that are sent to this chat is given by their AP ID.
 ```
 
 The recipient of messages that are sent to this chat is given by their AP ID.

-The usual pagination options are implemented.
+No pagination is implemented for now.

 
 ### Getting the messages for a Chat
 
 For a given Chat id, you can get the associated messages with
 
 
 ### Getting the messages for a Chat
 
 For a given Chat id, you can get the associated messages with
 

-`GET /api/v1/pleroma/chats/{id}/messages`
+`GET /api/v1/pleroma/chats/:id/messages`

 
 This will return all messages, sorted by most recent to least recent. The usual
 pagination options are implemented.
 
 This will return all messages, sorted by most recent to least recent. The usual
 pagination options are implemented.


@@ -149,7 +167,8 @@ Returned data:
         "visible_in_picker": false
       }
     ],
         "visible_in_picker": false
       }
     ],

-    "id": "13"
+    "id": "13",
+    "unread": true

   },
   {
     "account_id": "someflakeid",
   },
   {
     "account_id": "someflakeid",


@@ -157,16 +176,20 @@ Returned data:
     "content": "Whats' up?",
     "created_at": "2020-04-21T15:06:45.000Z",
     "emojis": [],
     "content": "Whats' up?",
     "created_at": "2020-04-21T15:06:45.000Z",
     "emojis": [],

-    "id": "12"
+    "id": "12",
+    "unread": false,
+    "idempotency_key": "75442486-0874-440c-9db1-a7006c25a31f"

   }
 ]
 ```
 
   }
 ]
 ```
 

+- idempotency_key: The copy of the `idempotency-key` HTTP request header that can be used for optimistic message sending. Included only during the first few minutes after the message creation.
+

 ### Posting a chat message
 
 Posting a chat message for given Chat id works like this:
 
 ### Posting a chat message
 
 Posting a chat message for given Chat id works like this:
 

-`POST /api/v1/pleroma/chats/{id}/messages`
+`POST /api/v1/pleroma/chats/:id/messages`

 
 Parameters:
 - content: The text content of the message. Optional if media is attached.
 
 Parameters:
 - content: The text content of the message. Optional if media is attached.


@@ -190,7 +213,8 @@ Returned data:
       "visible_in_picker": false
     }
   ],
       "visible_in_picker": false
     }
   ],

-  "id": "13"
+  "id": "13",
+  "unread": false

 }
 ```
 
 }
 ```
 


@@ -198,13 +222,13 @@ Returned data:
 
 Deleting a chat message for given Chat id works like this:
 
 
 Deleting a chat message for given Chat id works like this:
 

-`DELETE /api/v1/pleroma/chats/{chat_id}/messages/{message_id}`
+`DELETE /api/v1/pleroma/chats/:chat_id/messages/:message_id`

 
 Returned data is the deleted message.
 
 ### Notifications
 
 
 Returned data is the deleted message.
 
 ### Notifications
 

-There's a new `pleroma:chat_mention` notification, which has this form:
+There's a new `pleroma:chat_mention` notification, which has this form. It is not given out in the notifications endpoint by default, you need to explicitly request it with `include_types[]=pleroma:chat_mention`:

 
 ```json
 {
 
 ```json
 {


@@ -215,8 +239,17 @@ There's a new `pleroma:chat_mention` notification, which has this form:
     "chat_id": "1",
     "id": "10",
     "content": "Hello",
     "chat_id": "1",
     "id": "10",
     "content": "Hello",

-    "account_id": "someflakeid"
+    "account_id": "someflakeid",
+    "unread": false

   },
   "created_at": "somedate"
 }
 ```
   },
   "created_at": "somedate"
 }
 ```

+
+### Streaming
+
+There is an additional `user:pleroma_chat` stream. Incoming chat messages will make the current chat be sent to this `user` stream. The `event` of an incoming chat message is `pleroma:chat_update`. The payload is the updated chat with the incoming chat message in the `last_message` field.
+
+### Web Push
+
+If you want to receive push messages for this type, you'll need to add the `pleroma:chat_mention` type to your alerts in the push subscription.