X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;f=docs%2FAPI%2Fchats.md;h=9857aac672224e44aed52d73ea826d4eeded1561;hb=37e8e8bf8ef560bc42d8b470c25e6022b369590b;hp=39f493b47a7c30dae21228a993a8ec90dd41f92c;hpb=e62f8542a1933ba71dfd236741ad3afc76b89f22;p=akkoma

diff --git a/docs/API/chats.md b/docs/API/chats.md
index 39f493b47..9857aac67 100644
--- a/docs/API/chats.md
+++ b/docs/API/chats.md
@@ -32,53 +32,83 @@ 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}`
-
-The ap_id of the recipients needs to be www-form encoded, so 
+`POST /api/v1/pleroma/chats/by-account-id/:account_id`
 
+The account id is the normal FlakeId of the user
 ```
-https://originalpatchou.li/user/lambda
+POST /api/v1/pleroma/chats/by-account-id/someflakeid
 ```
 
-would become
+If you already have the id of a chat, you can also use
 
 ```
-https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda
+GET /api/v1/pleroma/chats/:id
 ```
 
-The full call would then be
+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/by-ap-id/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
+  "updated_at": "2020-04-21T15:11:46.000Z"
+}
 ```
 
-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.
+### Marking a chat as read
+
+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`
+
+
+Parameters:
+- last_read_id: Given this id, all chat messages until this one will be marked as read. Required.
+
 
 Returned data:
 
 ```json
 {
-  "recipient" : "https://dontbulling.me/users/lain",
-  "recipient_account": {
+  "account": {
     "id": "someflakeid",
     "username": "somenick",
     ...
   },
   "id" : "1",
-  "unread" : 2
+  "unread" : 0,
+  "updated_at": "2020-04-21T15:11:46.000Z"
 }
 ```
 
+### 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
 
 `GET /api/v1/pleroma/chats`
@@ -91,36 +121,37 @@ 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
+      "updated_at": "2020-04-21T15:11:46.000Z"
    }
 ]
 ```
 
 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
 
-`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
+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",
@@ -132,36 +163,41 @@ Returned data:
         "visible_in_picker": false
       }
     ],
-    "id": "13"
+    "id": "13",
+    "unread": true
   },
   {
-    "actor": "https://dontbulling.me/users/lain",
+    "account_id": "someflakeid",
     "chat_id": "1",
     "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:
 
-`POST /api/v1/pleroma/chats/{id}/messages`
+`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:
 
 ```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",
@@ -173,13 +209,22 @@ Returned data:
       "visible_in_picker": false
     }
   ],
-  "id": "13"
+  "id": "13",
+  "unread": false
 }
 ```
 
+### 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:
+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
 {
@@ -190,8 +235,17 @@ 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",
+    "unread": false
   },
   "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.