Merge branch 'develop' of git.pleroma.social:pleroma/pleroma into remake-remodel-dms

[akkoma] / docs / API / chats.md

diff --git a/docs/API/chats.md b/docs/API/chats.md
index 24c4b4d06a7fe340f09e398797b7dec138ae344e..ad36961aef3be69eb5aba6430816636e2fd26767 100644 (file)
--- a/docs/API/chats.md
+++ b/docs/API/chats.md
@@ -43,12 +43,17 @@ you can call:
 
 `POST /api/v1/pleroma/chats/by-account-id/{account_id}`
 
-The account id is the normal FlakeId of the usre
-
+The account id is the normal FlakeId of the user
 ```
 POST /api/v1/pleroma/chats/by-account-id/someflakeid
 ```
 
+If you already have the id of a chat, you can also use
+
+```
+GET /api/v1/pleroma/chats/:id
+```
+
 There will only ever be ONE Chat for you and a given recipient, so this call
 will return the same Chat if you already have one with that user.
 
@@ -62,10 +67,32 @@ Returned data:
     ...
   },
   "id" : "1",
-  "unread" : 2
+  "unread" : 2,
+  "last_message" : {...} // The last message in that chat
+}
+```
+
+### Marking a chat as read
+
+To set the `unread` count of a chat to 0, call
+
+`POST /api/v1/pleroma/chats/:id/read`
+
+Returned data:
+
+```json
+{
+  "account": {
+    "id": "someflakeid",
+    "username": "somenick",
+    ...
+  },
+  "id" : "1",
+  "unread" : 0
 }
 ```
 
+
 ### Getting a list of Chats
 
 `GET /api/v1/pleroma/chats`
@@ -84,7 +111,8 @@ Returned data:
         ...
       },
       "id" : "1",
-      "unread" : 2
+      "unread" : 2,
+      "last_message" : {...} // The last message in that chat
    }
 ]
 ```
@@ -99,7 +127,7 @@ For a given Chat id, you can get the associated messages with
 `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
+pagination options are implemented.
 
 Returned data:
 
@@ -139,6 +167,7 @@ Posting a chat message for given Chat id works like this:
 
 Parameters:
 - content: The text content of the message
+- media_id: The id of an upload that will be attached to the message.
 
 Currently, no formatting beyond basic escaping and emoji is implemented, as well as no
 attachments. This will most probably change.
@@ -163,6 +192,14 @@ Returned data:
 }
 ```
 
+### Deleting a chat message
+
+Deleting a chat message for given Chat id works like this:
+
+`DELETE /api/v1/pleroma/chats/{chat_id}/messages/{message_id}`
+
+Returned data is the deleted message.
+
 ### Notifications
 
 There's a new `pleroma:chat_mention` notification, which has this form: