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 abeee698f03043b8647ff5319120c6b2b200d108..9857aac672224e44aed52d73ea826d4eeded1561 100644 (file)
--- a/docs/API/chats.md
+++ b/docs/API/chats.md
@@ -41,7 +41,7 @@ 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}`
+`POST /api/v1/pleroma/chats/by-account-id/:account_id`

 
 The account id is the normal FlakeId of the user
 ```
 
 The account id is the normal FlakeId of the user
 ```


@@ -75,10 +75,15 @@ Returned data:
 
 ### 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


@@ -130,13 +135,13 @@ Returned data:
 ```
 
 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.


@@ -168,16 +173,19 @@ Returned data:
     "created_at": "2020-04-21T15:06:45.000Z",
     "emojis": [],
     "id": "12",
     "created_at": "2020-04-21T15:06:45.000Z",
     "emojis": [],
     "id": "12",

-    "unread": false
+    "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:
 - content: The text content of the message. Optional if media is attached.
 
 Parameters:
 - content: The text content of the message. Optional if media is attached.


@@ -210,7 +218,7 @@ Returned data:
 
 Deleting a chat message for given Chat id works like this:
 
 
 Deleting a chat message for given Chat id works like this:
 

-`DELETE /api/v1/pleroma/chats/{chat_id}/messages/{message_id}`
+`DELETE /api/v1/pleroma/chats/:chat_id/messages/:message_id`

 
 Returned data is the deleted message.
 
 
 Returned data is the deleted message.