total rebase
[anni] / docs / development / 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   "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.