## API
-In general, the way to send a `ChatMessage` is to first create a `Chat`, then post a message to that `Chat`. The actors in the API are generally given by their ActivityPub id to make it easier to support later `Group` scenarios.
+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`.
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`.
### Creating or getting a chat.
-To create or get an existing Chat for a certain recipient (identified by AP ID)
+To create or get an existing Chat for a certain recipient (identified by Account ID)
you can call:
-`POST /api/v1/pleroma/chats/by-ap-id/{ap_id}`
+`POST /api/v1/pleroma/chats/by-account-id/{account_id}`
-The ap_id of the recipients needs to be www-form encoded, so
+The account id is the normal FlakeId of the usre
```
-https://originalpatchou.li/user/lambda
+POST /api/v1/pleroma/chats/by-account-id/someflakeid
```
-would become
+There will only ever be ONE Chat for you and a given recipient, so this call
+will return the same Chat if you already have one with that user.
-```
-https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda
+Returned data:
+
+```json
+{
+ "account": {
+ "id": "someflakeid",
+ "username": "somenick",
+ ...
+ },
+ "id" : "1",
+ "unread" : 2
+}
```
-The full call would then be
+### Marking a chat as read
-```
-POST /api/v1/pleroma/chats/by-ap-id/https%3A%2F%2Foriginalpatchou.li%2Fuser%2Flambda
-```
+To set the `unread` count of a chat to 0, call
-There will only ever be ONE Chat for you and a given recipient, so this call
-will return the same Chat if you already have one with that user.
+`POST /api/v1/pleroma/chats/:id/read`
Returned data:
```json
{
- "recipient" : "https://dontbulling.me/users/lain",
- "recipient_account": {
+ "account": {
"id": "someflakeid",
"username": "somenick",
...
},
"id" : "1",
- "unread" : 2
+ "unread" : 0
}
```
+
### Getting a list of Chats
`GET /api/v1/pleroma/chats`
```json
[
{
- "recipient" : "https://dontbulling.me/users/lain",
- "recipient_account": {
+ "account": {
"id": "someflakeid",
"username": "somenick",
...
`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
+pagination options are implemented.
Returned data:
```json
[
{
- "actor": "https://dontbulling.me/users/lain",
+ "account_id": "someflakeid",
"chat_id": "1",
"content": "Check this out :firefox:",
"created_at": "2020-04-21T15:11:46.000Z",
"id": "13"
},
{
- "actor": "https://dontbulling.me/users/lain",
+ "account_id": "someflakeid",
"chat_id": "1",
"content": "Whats' up?",
"created_at": "2020-04-21T15:06:45.000Z",
```json
{
- "actor": "https://dontbulling.me/users/lain",
+ "account_id": "someflakeid",
"chat_id": "1",
"content": "Check this out :firefox:",
"created_at": "2020-04-21T15:11:46.000Z",
"chat_id": "1",
"id": "10",
"content": "Hello",
- "actor": "https://dontbulling.me/users/lain"
+ "account_id": "someflakeid"
},
"created_at": "somedate"
}