logo

pleroma

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

chats.md (9037B)

    

  1. # Chats
  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.
  5. ## Why Chats?
  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.
  9. This is an awkward setup for a few reasons:
  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.
  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. 
  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:
  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.
  29. ## Caveats
  31. - Chats are NOT E2E encrypted (yet). Security is still the same as email.
  33. ## API
  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`.
  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`.
  39. ### Creating or getting a chat.
  41. To create or get an existing Chat for a certain recipient (identified by Account ID)
  42. you can call:
  44. `POST /api/v1/pleroma/chats/by-account-id/:account_id`
  46. The account id is the normal FlakeId of the user
  47. ```
  48. POST /api/v1/pleroma/chats/by-account-id/someflakeid
  49. ```
  51. If you already have the id of a chat, you can also use
  53. ```
  54. GET /api/v1/pleroma/chats/:id
  55. ```
  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.
  60. Returned data:
  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. ```
  76. ### Marking a chat as read
  78. To mark a number of messages in a chat up to a certain message as read, you can use
  80. `POST /api/v1/pleroma/chats/:id/read`
  83. Parameters:
  84. - last_read_id: Given this id, all chat messages until this one will be marked as read. Required.
  87. Returned data:
  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. ```
  102. ### Marking a single chat message as read
  104. To set the `unread` property of a message to `false`
  106. `POST /api/v1/pleroma/chats/:id/messages/:message_id/read`
  108. Returned data:
  110. The modified chat message
  112. ### Getting a list of Chats
  114. `GET /api/v2/pleroma/chats`
  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).
  119. Parameters:
  121. - with_muted: Include chats from muted users (boolean).
  122. - pinned: Include only pinned chats (boolean).
  124. Returned data:
  126. ```json
  127. [
  128.    {
  129.       "account": {
  130.         "id": "someflakeid",
  131.         "username": "somenick",
  132.         ...
  133.       },
  134.       "id": "1",
  135.       "unread": 2,
  136.       "last_message": {...}, // The last message in that chat
  137.       "updated_at": "2020-04-21T15:11:46.000Z"
  138.    }
  139. ]
  140. ```
  142. The recipient of messages that are sent to this chat is given by their AP ID.
  143. The usual pagination options are implemented.
  145. ### Getting the messages for a Chat
  147. For a given Chat id, you can get the associated messages with
  149. `GET /api/v1/pleroma/chats/:id/messages`
  151. This will return all messages, sorted by most recent to least recent. The usual
  152. pagination options are implemented.
  154. Returned data:
  156. ```json
  157. [
  158.   {
  159.     "account_id": "someflakeid",
  160.     "chat_id": "1",
  161.     "content": "Check this out :firefox:",
  162.     "created_at": "2020-04-21T15:11:46.000Z",
  163.     "emojis": [
  164.       {
  165.         "shortcode": "firefox",
  166.         "static_url": "https://dontbulling.me/emoji/Firefox.gif",
  167.         "url": "https://dontbulling.me/emoji/Firefox.gif",
  168.         "visible_in_picker": false
  169.       }
  170.     ],
  171.     "id": "13",
  172.     "unread": true
  173.   },
  174.   {
  175.     "account_id": "someflakeid",
  176.     "chat_id": "1",
  177.     "content": "Whats' up?",
  178.     "created_at": "2020-04-21T15:06:45.000Z",
  179.     "emojis": [],
  180.     "id": "12",
  181.     "unread": false,
  182.     "idempotency_key": "75442486-0874-440c-9db1-a7006c25a31f"
  183.   }
  184. ]
  185. ```
  187. - 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.
  189. ### Posting a chat message
  191. Posting a chat message for given Chat id works like this:
  193. `POST /api/v1/pleroma/chats/:id/messages`
  195. Parameters:
  196. - content: The text content of the message. Optional if media is attached.
  197. - media_id: The id of an upload that will be attached to the message.
  199. Currently, no formatting beyond basic escaping and emoji is implemented.
  201. Returned data:
  203. ```json
  204. {
  205.   "account_id": "someflakeid",
  206.   "chat_id": "1",
  207.   "content": "Check this out :firefox:",
  208.   "created_at": "2020-04-21T15:11:46.000Z",
  209.   "emojis": [
  210.     {
  211.       "shortcode": "firefox",
  212.       "static_url": "https://dontbulling.me/emoji/Firefox.gif",
  213.       "url": "https://dontbulling.me/emoji/Firefox.gif",
  214.       "visible_in_picker": false
  215.     }
  216.   ],
  217.   "id": "13",
  218.   "unread": false
  219. }
  220. ```
  222. ### Deleting a chat message
  224. Deleting a chat message for given Chat id works like this:
  226. `DELETE /api/v1/pleroma/chats/:chat_id/messages/:message_id`
  228. Returned data is the deleted message.
  230. ### Pinning a chat
  232. Pinning a chat works like this:
  234. `POST /api/v1/pleroma/chats/:id/pin`
  236. Returned data:
  238. ```json
  239. {
  240.   "account": {
  241.     "id": "someflakeid",
  242.     "username": "somenick",
  243.     ...
  244.   },
  245.   "id": "1",
  246.   "unread": 0,
  247.   "updated_at": "2020-04-21T15:11:46.000Z",
  248.   "pinned": true,
  249. }
  250. ```
  252. To unpin a pinned chat, use:
  254. `POST /api/v1/pleroma/chats/:id/unpin`
  256. ### Notifications
  258. 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`:
  260. ```json
  261. {
  262.   "id": "someid",
  263.   "type": "pleroma:chat_mention",
  264.   "account": { ... } // User account of the sender,
  265.   "chat_message": {
  266.     "chat_id": "1",
  267.     "id": "10",
  268.     "content": "Hello",
  269.     "account_id": "someflakeid",
  270.     "unread": false
  271.   },
  272.   "created_at": "somedate"
  273. }
  274. ```
  276. ### Streaming
  278. 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.
  280. ### Web Push
  282. 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.