Merge branch 'idempotency-key-optimistic-posting' into 'develop'

[akkoma] / docs / API / chats.md

diff --git a/docs/API/chats.md b/docs/API/chats.md
index 1f6175f771c93673d50b827b6c0cdd551f79376f..9857aac672224e44aed52d73ea826d4eeded1561 100644 (file)
--- a/docs/API/chats.md
+++ b/docs/API/chats.md
@@ -41,14 +41,19 @@ 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}`
-
-The account id is the normal FlakeId of the usre
+`POST /api/v1/pleroma/chats/by-account-id/:account_id`

 
 

+The account id is the normal FlakeId of the user

 ```
 POST /api/v1/pleroma/chats/by-account-id/someflakeid
 ```
 
 ```
 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.
 
 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.
 


@@ -63,16 +68,22 @@ Returned data:
   },
   "id" : "1",
   "unread" : 2,
   },
   "id" : "1",
   "unread" : 2,

-  "last_message" : {...} // The last message in that chat
+  "last_message" : {...}, // The last message in that chat
+  "updated_at": "2020-04-21T15:11:46.000Z"

 }
 ```
 
 ### 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


@@ -83,10 +94,20 @@ Returned data:
     ...
   },
   "id" : "1",
     ...
   },
   "id" : "1",

-  "unread" : 0
+  "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
 
 
 ### Getting a list of Chats
 


@@ -107,19 +128,20 @@ Returned data:
       },
       "id" : "1",
       "unread" : 2,
       },
       "id" : "1",
       "unread" : 2,

-      "last_message" : {...} // The last message in that chat
+      "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 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.


@@ -141,7 +163,8 @@ Returned data:
         "visible_in_picker": false
       }
     ],
         "visible_in_picker": false
       }
     ],

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

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


@@ -149,23 +172,26 @@ 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:
 
 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.
 
 - 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:
 
 
 Returned data:
 


@@ -183,13 +209,22 @@ Returned data:
       "visible_in_picker": false
     }
   ],
       "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
 
 ### 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
 {


@@ -200,8 +235,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.