logo

pleroma

My custom branche(s) on git.pleroma.social/pleroma/pleroma git clone https://hacktivis.me/git/pleroma.git

chats.md (8625B)

    

  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.   "updated_at": "2020-04-21T15:11:46.000Z"

  73. }

  74. ```

  75. 

  76. ### Marking a chat as read

  77. 

  78. To mark a number of messages in a chat up to a certain message as read, you can use

  79. 

  80. `POST /api/v1/pleroma/chats/:id/read`

  81. 

  82. 

  83. Parameters:

  84. - last_read_id: Given this id, all chat messages until this one will be marked as read. Required.

  85. 

  86. 

  87. Returned data:

  88. 

  89. ```json

  90. {

  91.   "account": {

  92.     "id": "someflakeid",

  93.     "username": "somenick",

  94.     ...

  95.   },

  96.   "id" : "1",

  97.   "unread" : 0,

  98.   "updated_at": "2020-04-21T15:11:46.000Z"

  99. }

  100. ```

  101. 

  102. ### Marking a single chat message as read

  103. 

  104. To set the `unread` property of a message to `false`

  105. 

  106. `POST /api/v1/pleroma/chats/:id/messages/:message_id/read`

  107. 

  108. Returned data:

  109. 

  110. The modified chat message

  111. 

  112. ### Getting a list of Chats

  113. 

  114. `GET /api/v1/pleroma/chats`

  115. 

  116. This will return a list of chats that you have been involved in, sorted by their

  117. last update (so new chats will be at the top).

  118. 

  119. Parameters:

  120. 

  121. - with_muted: Include chats from muted users (boolean).

  122. 

  123. Returned data:

  124. 

  125. ```json

  126. [

  127.    {

  128.       "account": {

  129.         "id": "someflakeid",

  130.         "username": "somenick",

  131.         ...

  132.       },

  133.       "id" : "1",

  134.       "unread" : 2,

  135.       "last_message" : {...}, // The last message in that chat

  136.       "updated_at": "2020-04-21T15:11:46.000Z"

  137.    }

  138. ]

  139. ```

  140. 

  141. The recipient of messages that are sent to this chat is given by their AP ID.

  142. No pagination is implemented for now.

  143. 

  144. ### Getting the messages for a Chat

  145. 

  146. For a given Chat id, you can get the associated messages with

  147. 

  148. `GET /api/v1/pleroma/chats/:id/messages`

  149. 

  150. This will return all messages, sorted by most recent to least recent. The usual

  151. pagination options are implemented.

  152. 

  153. Returned data:

  154. 

  155. ```json

  156. [

  157.   {

  158.     "account_id": "someflakeid",

  159.     "chat_id": "1",

  160.     "content": "Check this out :firefox:",

  161.     "created_at": "2020-04-21T15:11:46.000Z",

  162.     "emojis": [

  163.       {

  164.         "shortcode": "firefox",

  165.         "static_url": "https://dontbulling.me/emoji/Firefox.gif",

  166.         "url": "https://dontbulling.me/emoji/Firefox.gif",

  167.         "visible_in_picker": false

  168.       }

  169.     ],

  170.     "id": "13",

  171.     "unread": true

  172.   },

  173.   {

  174.     "account_id": "someflakeid",

  175.     "chat_id": "1",

  176.     "content": "Whats' up?",

  177.     "created_at": "2020-04-21T15:06:45.000Z",

  178.     "emojis": [],

  179.     "id": "12",

  180.     "unread": false,

  181.     "idempotency_key": "75442486-0874-440c-9db1-a7006c25a31f"

  182.   }

  183. ]

  184. ```

  185. 

  186. - 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.

  187. 

  188. ### Posting a chat message

  189. 

  190. Posting a chat message for given Chat id works like this:

  191. 

  192. `POST /api/v1/pleroma/chats/:id/messages`

  193. 

  194. Parameters:

  195. - content: The text content of the message. Optional if media is attached.

  196. - media_id: The id of an upload that will be attached to the message.

  197. 

  198. Currently, no formatting beyond basic escaping and emoji is implemented.

  199. 

  200. Returned data:

  201. 

  202. ```json

  203. {

  204.   "account_id": "someflakeid",

  205.   "chat_id": "1",

  206.   "content": "Check this out :firefox:",

  207.   "created_at": "2020-04-21T15:11:46.000Z",

  208.   "emojis": [

  209.     {

  210.       "shortcode": "firefox",

  211.       "static_url": "https://dontbulling.me/emoji/Firefox.gif",

  212.       "url": "https://dontbulling.me/emoji/Firefox.gif",

  213.       "visible_in_picker": false

  214.     }

  215.   ],

  216.   "id": "13",

  217.   "unread": false

  218. }

  219. ```

  220. 

  221. ### Deleting a chat message

  222. 

  223. Deleting a chat message for given Chat id works like this:

  224. 

  225. `DELETE /api/v1/pleroma/chats/:chat_id/messages/:message_id`

  226. 

  227. Returned data is the deleted message.

  228. 

  229. ### Notifications

  230. 

  231. 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`:

  232. 

  233. ```json

  234. {

  235.   "id": "someid",

  236.   "type": "pleroma:chat_mention",

  237.   "account": { ... } // User account of the sender,

  238.   "chat_message": {

  239.     "chat_id": "1",

  240.     "id": "10",

  241.     "content": "Hello",

  242.     "account_id": "someflakeid",

  243.     "unread": false

  244.   },

  245.   "created_at": "somedate"

  246. }

  247. ```

  248. 

  249. ### Streaming

  250. 

  251. 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.

  252. 

  253. ### Web Push

  254. 

  255. 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.