Documentation: Add last_message to chat docs.

[akkoma] / docs / API / chats.md

diff --git a/docs/API/chats.md b/docs/API/chats.md
index 39f493b47a7c30dae21228a993a8ec90dd41f92c..1f6175f771c93673d50b827b6c0cdd551f79376f 100644 (file)
--- a/docs/API/chats.md
+++ b/docs/API/chats.md
@@ -32,53 +32,62 @@ For this reasons, Chats are a new and different entity, both in the API as well
 
 ## API
 
-In general, the way to send a `ChatMessage` is to first create a `Chat`, then post a message to that `Chat`. The actors in the API are generally given by their ActivityPub id to make it easier to support later `Group` scenarios. 
+In general, the way to send a `ChatMessage` is to first create a `Chat`, then post a message to that `Chat`. `Group`s will later be supported by making them a sub-type of `Account`.
 
 This is the overview of using the API. The API is also documented via OpenAPI, so you can view it and play with it by pointing SwaggerUI or a similar OpenAPI tool to `https://yourinstance.tld/api/openapi`.
 
 ### Creating or getting a chat.
 
-To create or get an existing Chat for a certain recipient (identified by AP ID)
+To create or get an existing Chat for a certain recipient (identified by Account ID)
 you can call:
 
-`POST /api/v1/pleroma/chats/by-ap-id/{ap_id}`
+`POST /api/v1/pleroma/chats/by-account-id/{account_id}`
 
-The ap_id of the recipients needs to be www-form encoded, so 
+The account id is the normal FlakeId of the usre
 
 ```
-https://originalpatchou.li/user/lambda
+POST /api/v1/pleroma/chats/by-account-id/someflakeid
 ```
 
-would become
+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.
 
-```
-https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda
+Returned data:
+
+```json
+{
+  "account": {
+    "id": "someflakeid",
+    "username": "somenick",
+    ...
+  },
+  "id" : "1",
+  "unread" : 2,
+  "last_message" : {...} // The last message in that chat
+}
 ```
 
-The full call would then be
+### Marking a chat as read
 
-```
-POST /api/v1/pleroma/chats/by-ap-id/https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda
-```
+To set the `unread` count of a chat to 0, call
 
-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.
+`POST /api/v1/pleroma/chats/:id/read`
 
 Returned data:
 
 ```json
 {
-  "recipient" : "https://dontbulling.me/users/lain",
-  "recipient_account": {
+  "account": {
     "id": "someflakeid",
     "username": "somenick",
     ...
   },
   "id" : "1",
-  "unread" : 2
+  "unread" : 0
 }
 ```
 
+
 ### Getting a list of Chats
 
 `GET /api/v1/pleroma/chats`
@@ -91,14 +100,14 @@ Returned data:
 ```json
 [
    {
-      "recipient" : "https://dontbulling.me/users/lain",
-      "recipient_account": {
+      "account": {
         "id": "someflakeid",
         "username": "somenick",
         ...
       },
       "id" : "1",
-      "unread" : 2
+      "unread" : 2,
+      "last_message" : {...} // The last message in that chat
    }
 ]
 ```
@@ -113,14 +122,14 @@ 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:
 
 ```json
 [
   {
-    "actor": "https://dontbulling.me/users/lain",
+    "account_id": "someflakeid",
     "chat_id": "1",
     "content": "Check this out :firefox:",
     "created_at": "2020-04-21T15:11:46.000Z",
@@ -135,7 +144,7 @@ Returned data:
     "id": "13"
   },
   {
-    "actor": "https://dontbulling.me/users/lain",
+    "account_id": "someflakeid",
     "chat_id": "1",
     "content": "Whats' up?",
     "created_at": "2020-04-21T15:06:45.000Z",
@@ -153,6 +162,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.
@@ -161,7 +171,7 @@ Returned data:
 
 ```json
 {
-  "actor": "https://dontbulling.me/users/lain",
+  "account_id": "someflakeid",
   "chat_id": "1",
   "content": "Check this out :firefox:",
   "created_at": "2020-04-21T15:11:46.000Z",
@@ -190,7 +200,7 @@ There's a new `pleroma:chat_mention` notification, which has this form:
     "chat_id": "1",
     "id": "10",
     "content": "Hello",
-    "actor": "https://dontbulling.me/users/lain"
+    "account_id": "someflakeid"
   },
   "created_at": "somedate"
 }