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
```
### 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`
+
+Parameters:
+- last_read_id: Given this id, all chat messages until this one will be marked as read. Required.
+
+
Returned data:
```json
}
```
+### Marking a single chat message as read
+
+To set the `unread` property of a message to `false`
+
+`POST /api/v1/pleroma/chats/:id/messages/:message_id/read`
+
+Returned data:
+
+The modified chat message
### Getting a list of Chats
This will return a list of chats that you have been involved in, sorted by their
last update (so new chats will be at the top).
+Parameters:
+
+- with_muted: Include chats from muted users (boolean).
+
Returned data:
```json
```
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
-`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.
"visible_in_picker": false
}
],
- "id": "13"
+ "id": "13",
+ "unread": true
},
{
"account_id": "someflakeid",
"content": "Whats' up?",
"created_at": "2020-04-21T15:06:45.000Z",
"emojis": [],
- "id": "12"
+ "id": "12",
+ "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:
-`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.
"visible_in_picker": false
}
],
- "id": "13"
+ "id": "13",
+ "unread": false
}
```
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.
### Notifications
-There's a new `pleroma:chat_mention` notification, which has this form:
+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`:
```json
{
"chat_id": "1",
"id": "10",
"content": "Hello",
- "account_id": "someflakeid"
+ "account_id": "someflakeid",
+ "unread": false
},
"created_at": "somedate"
}
```
+
+### Streaming
+
+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.
+
+### Web Push
+
+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.