Skip to content

Latest commit

 

History

History
362 lines (287 loc) · 11 KB

APIREF-Chats.md

File metadata and controls

362 lines (287 loc) · 11 KB

API Reference

USERS • CHATS • CONTACTS • FILES • WEBSOCKET • JSON

A collection of methods for managing chats and messages. Each method requires authentication and thus should contain Authorization: Bearer <token> in the request header. Request body is a JSON object, but placeholders for data types instead of concrete samples might be used like so: <UUID> or "…" for strings.

1. Creating a chat

Create a personal or a group chat. An error is returned in case of more than two participants in a personal chat. If participants are the same as for an existing chat, that chat will be returned instead.

Path:

POST /chats

Request body:

{
    "title": "…",       // ignored for personal chats
    "participants": [
       1, 2             // list of `UserID`s
    ],
    "isPersonal": false // `true` if omitted and number of participants together with the chat creator is two
}

Response: ChatInfo object.

2. Posting a message

You can attach a picture/video with a preview to your message. Depending on how you want your client to behave you might want to upload you media first and using returned file name as an id for the message's attachment. Or vice versa - obtain attachment's id first (by posting a message) and then upload files with this attachment's id as a file name. You can upload multiple files and then construct their URLs as http://<server[:port]>/files/<file_name>.<file_type> and for example http://<server[:port]>/files/<file_name>-preview.jpeg

All participants will be notified about this event via websocket and push according to their settings.

See also:

  • Files section for more details.
  • Tests for an example.

Path:

POST /chats/<id>/messages

Request body:

{
   "localId": "…",       // should be "<UserID>+<UUID>"
   "text": "…",          // up to 2048 bytes
   "isVisible": "…",     // true by default
   "attachment": {
      "fileType": "png",
      "fileSize": 100000 // in bytes
   }
}

Response: MessageInfo object.

3. Get your chats

Returns all the chats where you is a participant. Pass full=true in the path if you want the full information for all returned chats (thus all the users in each chat will be included). By default it's false.

Path:

GET /chats/?full=1

Response: an array of ChatInfo objects.

4. Get chat information

Returns all the information about the chat together with all participants or an error if you are not a participant.

Path:

GET /chats/<id>

Response: ChatInfo object.

5. Update title

Updates the title of the chat. Returns error for personal chat. All participants will be notified about this event via websocket.

Path:

PUT /chats/<id>

Request body:

{
   "title": "…", // ignored for personal chat
}

Response: ChatInfo object.

6. Update settings

Updates various settings of the chat.

Path:

PUT /chats/<id>/settings

Request body:

{
   "isMuted": false,            // use to mute chat (stop sending push notifications)
   "isArchived": false,         // use to move chat to "Archive" list
   "isRemovedOnDevice": false,  // see `Remove chat from device` method
}

Response: ChatInfo object.

7. Add picture

Adds a picture to the chat similar to user's avatar. All participants will be notified about this event via websocket.

Path:

POST /chats/<id>/images

Request body:

{
   "image": {
      "id": <UUID>,       // should be obtained beforehand by uploading a file, see `Files` section
      "fileType": "png",
      "fileSize": 100000  // in bytes
   }
}

Response: ChatInfo object.

8. Remove picture

Removes chat's picture. All participants will be notified about this event via websocket.

Path:

DELETE /chats/<id>/images/<id>

Response: OK

9. Add users

Adds users to the chat if they were not already added. If no users were added error will be returned. Also you can't add more than 10 users at a time. All participants will be notified about this event via websocket.

Path:

POST /chats/<id>/users

Request body:

{
   "users": {
      1, 2, 3 // list of `UserID`s
   }
}

Response: ChatInfo object.

10. Remove users

Removes users from the chat if they are participants. Returns error for personal chat.

Path:

DELETE /chats/<id>/users

Request body:

{
   "users": {
      1, 2, 3 // list of `UserID`s
   }
}

Response: ChatInfo object.

11. Delete chat

Deletes the chat with the all the assotiated data (messages, settings, read marks etc.). Can't be undone. All participants will be notified about this event via websocket.

Path:

DELETE /chats/<id>

Response: OK

12. Remove chat from device

Stops appearing of the chat on the device. To get it back you need to find (or create) it again and post message into it. You need to delete the local chat object by yourself.

Path:

PUT /chats/<id>/settings

Request body:

{
   "isRemovedOnDevice": true
}

Response: OK

13. Exit chat

Exits multiuser chat. In case of a personal chat results in an error. All participants will be notified about this event via websocket.

Path:

DELETE /chats/<id>/me

Response: OK

14. Clear chat

Similar to deleting the chat, but instead only deletes all the messages with all the assotiated data (read marks). Can't be undone. All participants will be notified about this event via websocket.

Path:

DELETE /chats/<id>/messages

Response: OK

15. Block chat

Exits the chat and makes it impossible to add the user who blocked it as a participant. Ignored for personal chats.

Path:

PUT /chats/<id>/block

Response: OK

16. Unblock chat

Makes it possible to add the user who blocked it as a participant. Ignored for personal chats.

Path:

PUT /chats/<id>/unblock

Response: OK

17. Block user

Blocks a user from posting messages into the chat.

Path:

PUT /chats/<id>/users/<id>/block

Response: OK

18. Unblock user

Unblocks the user from posting messages into the chat.

Path:

PUT /chats/<id>/users/<id>/unblock

Response: OK

19. Get blocked users

Retrives the list of all blocked users in the chat.

Path:

GET /chats/<id>/users/blocked

Response: An array of UserInfo objects.

20. Get messages

Retrives number messages before the message with the id. If id is omitted retrives last number of messages or 50 by default.

Path:

GET /chats/<id>/messages?count=<number>&before=<id>

Response: An array of MessageInfo objects.

21. Delete message

Message is deleted by deletion of its content (text and attachment). MessageInfo will contain a deletedAt field. All participants will be notified about this event via websocket.

Path:

DELETE /chats/<id>/messages/<id>

Response: MessageInfo object.

22. Edit message

Edits a message. All participants will be notified about this event via websocket.

Path:

PUT /chats/<id>/messages/<id>

Request body:

{
   "text": "…",           // use this to edit message's content
   "isVisible": true,     // use this to update message's visibility (up to the UI how to use it)
   "fileExists": true,    // use this to inform participants that the file is now uploaded
   "previewExists": true  // use this to inform participants that the preview is now available
}

Response: MessageInfo object.

23. Read message

Puts a read mark on the message by a particular user. All participants will be notified about this event via websocket.

Path:

PUT /chats/<id>/messages/<id>/read

Response: OK

24. Send notification

Sends additional data to the chat that is not required to be saved on the server, so the format is any JSON. Can be used to send typing notifications or trigger some animations etc. All participants will be notified about this event via websocket and/or push.

Path:

POST /chats/<id>/notify

Request body:

{
   "name": "…",    // arbitrary string, use for purpose of this notification, f.e. "typing_started"
   "text": "…",    // arbitrary string (will also be shown as a push text if possible)
   "realm": "…",   // "webSocket", "push" or "all", "webSocket" is by default
   "data": <Data>  // optional JSON dictionary converted to a binary data (f.e. using `Foundation.JSONEncoder()`)
}

Response: OK