git.squeep.com Git - akkoma/blob - docs/API/chats.md

   1 # Chats
   2
   3 Chats are a way to represent an IM-style conversation between two actors. They are not the same as direct messages and they are not `Status`es, even though they have a lot in common.
   4
   5 ## Why Chats?
   6
   7 There are no 'visibility levels' in ActivityPub, their definition is purely a Mastodon convention. Direct Messaging between users on the fediverse has mostly been modeled by using ActivityPub addressing following Mastodon conventions on normal `Note` objects. In this case, a 'direct message' would be a message that has no followers addressed and also does not address the special public actor, but just the recipients in the `to` field. It would still be a `Note` and is presented with other `Note`s as a `Status` in the API.
   8
   9 This is an awkward setup for a few reasons:
  10
  11 - As DMs generally still follow the usual `Status` conventions, it is easy to accidentally pull somebody into a DM thread by mentioning them. (e.g. "I hate @badguy so much")
  12 - It is possible to go from a publicly addressed `Status` to a DM reply, back to public, then to a 'followers only' reply, and so on. This can be become very confusing, as it is unclear which user can see which part of the conversation.
  13 - The standard `Status` format of implicit addressing also leads to rather ugly results if you try to display the messages as a chat, because all the recipients are always mentioned by name in the message.
  14 - As direct messages are posted with the same api call (and usually same frontend component) as public messages, accidentally making a public message private or vice versa can happen easily. Client bugs can also lead to this, accidentally making private messages public.
  15
  16 As a measure to improve this situation, the `Conversation` concept and related Pleroma extensions were introduced. While it made it possible to work around a few of the issues, many of the problems remained and it didn't see much adoption because it was too complicated to use correctly.
  17
  18 ## Chats explained
  19 For this reasons, Chats are a new and different entity, both in the API as well as in ActivityPub. A quick overview:
  20
  21 - Chats are meant to represent an instant message conversation between two actors. For now these are only 1-on-1 conversations, but the other actor can be a group in the future.
  22 - Chat messages have the ActivityPub type `ChatMessage`. They are not `Note`s. Servers that don't understand them will just drop them.
  23 - The only addressing allowed in `ChatMessage`s is one single ActivityPub actor in the `to` field.
  24 - There's always only one Chat between two actors. If you start chatting with someone and later start a 'new' Chat, the old Chat will be continued.
  25 - `ChatMessage`s are posted with a different api, making it very hard to accidentally send a message to the wrong person.
  26 - `ChatMessage`s don't show up in the existing timelines.
  27 - Chats can never go from private to public. They are always private between the two actors.
  28
  29 ## Caveats
  30
  31 - Chats are NOT E2E encrypted (yet). Security is still the same as email.
  32
  33 ## API
  34
  35 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`.
  36
  37 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`.
  38
  39 ### Creating or getting a chat.
  40
  41 To create or get an existing Chat for a certain recipient (identified by Account ID)
  42 you can call:
  43
  44 `POST /api/v1/pleroma/chats/by-account-id/{account_id}`
  45
  46 The account id is the normal FlakeId of the user
  47 ```
  48 POST /api/v1/pleroma/chats/by-account-id/someflakeid
  49 ```
  50
  51 If you already have the id of a chat, you can also use
  52
  53 ```
  54 GET /api/v1/pleroma/chats/:id
  55 ```
  56
  57 There will only ever be ONE Chat for you and a given recipient, so this call
  58 will return the same Chat if you already have one with that user.
  59
  60 Returned data:
  61
  62 ```json
  63 {
  64   "account": {
  65     "id": "someflakeid",
  66     "username": "somenick",
  67     ...
  68   },
  69   "id" : "1",
  70   "unread" : 2,
  71   "last_message" : {...} // The last message in that chat
  72 }
  73 ```
  74
  75 ### Marking a chat as read
  76
  77 To set the `unread` count of a chat to 0, call
  78
  79 `POST /api/v1/pleroma/chats/:id/read`
  80
  81 Returned data:
  82
  83 ```json
  84 {
  85   "account": {
  86     "id": "someflakeid",
  87     "username": "somenick",
  88     ...
  89   },
  90   "id" : "1",
  91   "unread" : 0
  92 }
  93 ```
  94
  95
  96 ### Getting a list of Chats
  97
  98 `GET /api/v1/pleroma/chats`
  99
 100 This will return a list of chats that you have been involved in, sorted by their
 101 last update (so new chats will be at the top).
 102
 103 Returned data:
 104
 105 ```json
 106 [
 107    {
 108       "account": {
 109         "id": "someflakeid",
 110         "username": "somenick",
 111         ...
 112       },
 113       "id" : "1",
 114       "unread" : 2,
 115       "last_message" : {...} // The last message in that chat
 116    }
 117 ]
 118 ```
 119
 120 The recipient of messages that are sent to this chat is given by their AP ID.
 121 The usual pagination options are implemented.
 122
 123 ### Getting the messages for a Chat
 124
 125 For a given Chat id, you can get the associated messages with
 126
 127 `GET /api/v1/pleroma/chats/{id}/messages`
 128
 129 This will return all messages, sorted by most recent to least recent. The usual
 130 pagination options are implemented.
 131
 132 Returned data:
 133
 134 ```json
 135 [
 136   {
 137     "account_id": "someflakeid",
 138     "chat_id": "1",
 139     "content": "Check this out :firefox:",
 140     "created_at": "2020-04-21T15:11:46.000Z",
 141     "emojis": [
 142       {
 143         "shortcode": "firefox",
 144         "static_url": "https://dontbulling.me/emoji/Firefox.gif",
 145         "url": "https://dontbulling.me/emoji/Firefox.gif",
 146         "visible_in_picker": false
 147       }
 148     ],
 149     "id": "13"
 150   },
 151   {
 152     "account_id": "someflakeid",
 153     "chat_id": "1",
 154     "content": "Whats' up?",
 155     "created_at": "2020-04-21T15:06:45.000Z",
 156     "emojis": [],
 157     "id": "12"
 158   }
 159 ]
 160 ```
 161
 162 ### Posting a chat message
 163
 164 Posting a chat message for given Chat id works like this:
 165
 166 `POST /api/v1/pleroma/chats/{id}/messages`
 167
 168 Parameters:
 169 - content: The text content of the message
 170 - media_id: The id of an upload that will be attached to the message.
 171
 172 Currently, no formatting beyond basic escaping and emoji is implemented, as well as no
 173 attachments. This will most probably change.
 174
 175 Returned data:
 176
 177 ```json
 178 {
 179   "account_id": "someflakeid",
 180   "chat_id": "1",
 181   "content": "Check this out :firefox:",
 182   "created_at": "2020-04-21T15:11:46.000Z",
 183   "emojis": [
 184     {
 185       "shortcode": "firefox",
 186       "static_url": "https://dontbulling.me/emoji/Firefox.gif",
 187       "url": "https://dontbulling.me/emoji/Firefox.gif",
 188       "visible_in_picker": false
 189     }
 190   ],
 191   "id": "13"
 192 }
 193 ```
 194
 195 ### Notifications
 196
 197 There's a new `pleroma:chat_mention` notification, which has this form:
 198
 199 ```json
 200 {
 201   "id": "someid",
 202   "type": "pleroma:chat_mention",
 203   "account": { ... } // User account of the sender,
 204   "chat_message": {
 205     "chat_id": "1",
 206     "id": "10",
 207     "content": "Hello",
 208     "account_id": "someflakeid"
 209   },
 210   "created_at": "somedate"
 211 }
 212 ```