LOC-29 Fix NO_RECP exception when calling gpg.encrypt on Debian9
[LocalChat.git] / docs / server-api.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
Server API
============

All requests to the server are placed with the `POST` method, using a JSON request body

The basic structure is

    {
        "action":"[api action]",
        "payload": [json payload]
    }

Which, if successful, will result in a `HTTP 200` and a JSON encapsulated response body.



Response Codes
---------------

The following HTTP statuses may be returned

* `200` - Request was successful
* `400` - Invalid request
* `403` - Authentication Invalid/Permission Denied
* `500` - Server had an issue




Supported Actions
-------------------


### joinRoom

Used to enter a room.

When the user was invited to the room, a password will have been set for them (the supplied client currently auto-generates that password), it will need to be provided for the user to authenticate.

    {
        "action":"joinRoom",
        "payload": {    
                    "roomName": "[name of room]",
                    "userpass": password,
                    "user": user
        }
    }

*Response*

If authentication is successful, the response will include a number of details that the client will need to take note of for future requests

    {
        "status": "ok",
        "last": last,
        "session": sessionkey,
        "syskey": systemkey
    }
    
The value `last` is the ID of the latest message in the room you've just joined. It should be included in `pollMsg` calls.

The value `sessionkey` is a server generated sessionkey. It must be included in the payload of all future requests (it's used to help authenticate those requests).

The value `syskey` is a decryption passphrase. The server's internal user `SYSTEM` will E2E encrypt any messages it pushes into rooms, this is the key you should use to decrypt those messages.





### pollMsg

Used to check whether there are any messages since the last the client received. It will return room-wide messages and direct messages addressed to the polling user.

Client provides the ID of the last message they've received, as well as the room they're polling. Where this is the first request, `last` should be 0

    {
        "action":"pollMsg",
        "payload": {    
                    "roomName": "[name of room]",
                    "mylast": "[last]",
                    "user": user,
                    "sesskey": sessionkey
        }
    }


*Response*

If there are no messages, then the response status will be `unchanged`.
If a specific error is being returned, the response status will be `errmessage` - you should disable any automatic polling and the print the content of `text`

If status is `updated` then messages have been returned:

    {
        "status": "updated",
        "messages" : [
                        [msgid,msgtext,timestamp,fromuser,touser],
                        [msgid,msgtext,timestamp,fromuser,touser]    
        ]

    }

Once the client has processed the received messages, the value of `last` in the next `pollMsg` request should be the maximum ID in the resultset.




### sendMsg

Used to send a message to the entire room

    {
        "action":"sendMsg",
        "payload": {    
                    "roomName": "[name of room]",
                    "msg": "[message payload]",
                    "user": user,
                    "sesskey": sessionkey
        }
    }

The message payload is encrypted and base64 encoded by the client, so the server only sees a base64 string. 

However, to keep compatability with the supplied client, your message payload (prior to encryption) should be a JSON encapsulated string of the format

        msg = {
            'user': user,
            'text': msg,
            "verb": verb
            }

This should then be PGP encrypted using the room passphrase, and then base64 encoded for embedding into the API payload.
            
Where `verb` is one of `do` or `say` (other values will be treated as `say` by the supplied client).


*Response*

If message sending is successful, the response will contain `status:"ok"`




### sendDirectMsg

Used to send a message to a specific user within the room. The message will not be visible to other room occupants.

    {
        "action":"sendDirectMsg",
        "payload": {    
                    "roomName": "[name of room]",
                    "msg": "[message payload]",
                    "to": recipient
                    "user": user,
                    "sesskey": sessionkey
        }
    }

The message payload is encrypted and base64 encoded by the client, so the server only sees a base64 string. 

However, to keep compatability with the supplied client, your message payload (prior to encryption) should be a JSON encapsulated string of the format

        msg = {
            'user': user,
            'text': msg,
            "verb": verb
            }

This should then be PGP encrypted using the room passphrase, and then base64 encoded for embedding into the API payload.
            
Where `verb` is one of `do` or `say` (other values will be treated as `say` by the supplied client).


*Response*

If message sending is successful, the response will contain `status:"ok"`