Docs: Document streaming differences

[akkoma] / docs / API / chats.md

diff --git a/docs/API/chats.md b/docs/API/chats.md
index 24c4b4d06a7fe340f09e398797b7dec138ae344e..2e415e4dac1284deb0e9daea7d0df51470d60c0b 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,34 @@ Returned data:
     ...
   },
   "id" : "1",
-  "unread" : 2
+  "unread" : 2,
+  "last_message" : {...}, // The last message in that chat
+  "updated_at": "2020-04-21T15:11:46.000Z"
+}
+```
+
+### 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,
+  "updated_at": "2020-04-21T15:11:46.000Z"
 }
 ```
 
+
 ### Getting a list of Chats
 
 `GET /api/v1/pleroma/chats`
@@ -84,7 +113,9 @@ Returned data:
         ...
       },
       "id" : "1",
-      "unread" : 2
+      "unread" : 2,
+      "last_message" : {...}, // The last message in that chat
+      "updated_at": "2020-04-21T15:11:46.000Z"
    }
 ]
 ```
@@ -99,7 +130,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:
 
@@ -138,10 +169,10 @@ Posting a chat message for given Chat id works like this:
 `POST /api/v1/pleroma/chats/{id}/messages`
 
 Parameters:
-- content: The text content of the message
+- content: The text content of the message. Optional if media is attached.
+- 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.
+Currently, no formatting beyond basic escaping and emoji is implemented.
 
 Returned data:
 
@@ -163,6 +194,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: