Welcome to
developer section
Tools
**Don't forget to check this page regularly, more will come!**
Node-RED semilimes Connector
You probably have heard about Node-RED, a very powerful and free flow builder to (not only) connect and control your devices within your local network. If not, learn more about.
What about:
- securely extending your device communication to the whole internet through semilimes?
- building your preferred manual or automated use cases to monitor and control them?
- sharing them with someone at any time?
Here you can take advantage of our pre-made connector and its actions to easily integrate Node-RED flows to semilimes.
Build your own client
Do you have any other use case that requires integration of our APIs in other tools or languages?
We provide a full OpenAPI3 specification that can be easily used with a code generation tool like Swagger Editor for you to build your own client in the language of your preference!
Explore the link below to get to a Swagger Editor page with our specification preloaded
semilimes remote
Our application empowers users to effortlessly establish secured tunnel connections, enabling the secure streaming of RTSP camera feeds from their homes or businesses. This innovative tool is ideal for those without a white IP address, offering a reliable and secure way to remotely access camera streams.
Additionally, semilimes remote integrates seamlessly with local web-based systems like Home Assistant, openHAB and Node-RED, and allows to access them remotely. Whether you’re keeping an eye on your property while traveling, managing your home or office automation, semilimes remote is your go-to solution for accessible, secure, and intelligent remote monitoring.
Here, you will find instructions and a selection of download links for various operating systems.
API Documentation
API Connection
HTTP
The semilimes API is hosted at this base address: api.semilimes.net
All requests need to be authenticated via an API key, by passing the following header
property:
Property Name | Property Value |
---|---|
Authorization | Bearer <API_KEY> |
WebSocket
The API supports a websocket connection for enabling sending/receiving commands and messages where supported:
wss://api.semilimes.net/service/ws
The websocket connection needs to be authenticated via an API key, by passing the following header
property to the initial websocket connection request:
Property Name | Property Value |
---|---|
Authorization | Bearer <API_KEY> |
All the payloads exchanged under the established websocket connection will be implicitly authorized and billed like HTTP requests.
Sending WebSocket requests
To send websocket requests, please refer to the WebSocket
section under each API endpoint, where specified.
Note: Not all the API endpoints are supported by websocket
Receiving WebSocket messages
For further details about how to handle received messages via Websocket, please refer to the Inbound events section.
API Specification
The semilimes API is OpenAPI3-compliant.
Its schema can be fully tested at this Swagger Editor page, where you can also generate compliant clients in one of the supported languages of the swagger editor platform.
In alternative, you can find and download the specification at this GitHub page.
API Response Schema
This API follows a fixed schema when returning a response to the client.
The response schema is the following:
Property | Type | Description | Example Values |
---|---|---|---|
success | Boolean | Determines if the request was successful | true / false |
statusCode | Integer | Standard HTTP response status code | HttpStatus == 200 -> null / HttpStatus != 200 -> HttpStatus |
error | String | Brings an error message if something went wrong | Error message / null |
data | Object | Array | Variable property bringing the functional data of the API response | Any |
Note: the Response body references throughout the document are meant to be found in the
data
property of the API response
Data Components
The following section describes all the data components that can be transferred through the Semilimes platform. Keep this section as a reference when sending data components through all the forms of communication listed below.
Simple Text
A simple text message
{
"dataComponentType": "text",
"text": "This is a text message."
}
Html Text
An html message
{
"dataComponentType": "html",
"html": "<p> html text </p>"
}
File
A file object containing one or more files to open or download
{
"dataComponentType": "file",
"fileIds": [
"myFileId"
]
}
Contact
A message that references one or more account Ids to be added as contacts
{
"dataComponentType": "contact",
"contactIds": [
"myContactId"
]
}
Location
A location message containing coordinates
{
"dataComponentType": "location",
"locationName" : "locationName",
"latitude" : 12.3456,
"longitude" : 12.3456
}
WebView
A message referencing a webpage, to be viewed as a web frame
{
"dataComponentType": "webview",
"url": "my-url",
"enableFullScreenView" : true,
"viewSize" : "1:2"
}
url
is the address to be rendered in the webview
enableFullScreenView
allows …
viewSize
determines the view proportions. Allowed values are:
- 1:1
- 1:2
- 3:2
- 2:1
Channel reference
A message referencing an existing channel
{
"dataComponentType": "channel",
"channelId": "myChannelId"
}
Tunnel
A message referencing an existing Tunnel
{
"dataComponentType": "tunnel",
"tunnelId": "myTunnelId"
}
Form
A form message is a complex data component which can be arbitrarily structured using available form components, listed below. The outer form structure is the following:
{
"dataComponentType": "form",
"submitEnabled" : true,
"retainStatus": true,
"submitText" : "",
"receiver": {
"id": "<accountId>",
"featureType": "contact"
},
"refName": "formReferenceName",
"formComponents": [
{
//Form Component 1
}
]
}
submitEnabled
enables the Submit button to be pressed before the form is actually submitted. Otherwise, the form will be submitted each time a user fills in/change values of a form component.
retainStatus
enables the form to maintain the last submitted values when the use case requires many users to operate the same form
submitText
is the text to be displayed in the Submit button of the form
receiver
is the recipient entity that will receive the submitted responses. Its structure can be either:
Contact
"receiver" : {
"id": "<accountId>",
"featureType": "contact"
}
Group Chat
"receiver" : {
"id": "<groupChatId>",
"featureType": "groupchat"
}
Channel
"receiver" : {
"id": "<channelId>",
"featureType": "channel"
}
refName
is a friendly name given to the form for later reference when filtering form submissions from clients.
Form Submission
A form submission is a message very similar to the Form
one. This is sent when submitting a previously received form message, and it maintains the same form components structure, with these differences:
- each form component will also have a populated
value
property
{
"dataComponentType": "formsubmission",
"replyTo": {
"messageId": "formMessageId",
"refName": "formRefName"
},
"formComponents": [
{
//Form Component 1
//having the value property populated
}
]
}
replyTo
contains the Id of the original form message and the chosen reference name of the form itself.
Form Components
Form components are functional blocks that can be mixed together to compose a form.
The discriminant of this type of components is the formComponentType
property.
The first-level properties are fixed, while the properties nested under value
are specific of the form component type.
Label
A simple read-only label
{
"refName": "myLabel",
"formComponentType": "label",
"title" : "Label Title"
}
value
is a text member containing the label text
Textbox
A text field with a title and a user-editable text field.
{
"refName": "myTextbox",
"formComponentType": "textbox",
"title" : "Textbox",
"requiredSelection": false,
"value" : "Textbox value" //When submitted
}
title
is the textbox title
value
is the text pre-populated in the textbox and the text input by the user at form submission
requiredSelection
sets this component interaction as required before submitting the parent form
Button List
A group of user-clickable buttons with a label
{
"refName": "myButtonList",
"formComponentType" : "buttonlist",
"title": "Button List",
"requiredSelection": false,
"value": "buttonName", //When submitted
"verticalList": true,
"options": [
{
"name" : "button1",
"value": "buttonLabel1"
},
{
"name" : "button2",
"value": "buttonLabel2"
}
]
}
verticalList
is a preference to tell a client app to display the buttons vertically
requiredSelection
sets this component interaction as required before submitting the parent form
options
is an array of buttons pertaining to the list, where name
is the button reference and value
is the text displayed to the user
value
will be populated with a button name
when a user submits a form with a button selection
Single Choice
A component displaying a list of options and allowing only one choice
{
"refName": "mySingleChoice",
"formComponentType" : "singlechoice",
"title": "Single Choice",
"requiredSelection" : false,
"value" : "choice1", //When submitted
"options" : [
{
"name" : "choice1",
"value": "Choice 1"
},
{
"name" : "choice2",
"value": "Choice 2"
}
]
}
title
is the global label displayed at the beginning of the component
requiredSelection
indicates if the selection is required to submit the form
options
is an array of options where name
is the option identifier and value
is the text displayed to the user
value
points to one of the choices name
and determines which option is selected on submission
Multi Choice
A component displaying a list of options and allowing multiple choices
{
"refName": "myMultiChoice",
"formComponentType" : "multichoice",
"title": "Multi Choice",
"requiredSelection" : false,
"value" : ["choice1", "choice2"], //When submitted
"options" : [
{
"name" : "choice1",
"value": "Choice 1"
},
{
"name" : "choice2",
"value": "Choice 2"
}
]
}
title
is the global label displayed at the beginning of the component
requiredSelection
indicates if the selection is required to submit the form
options
is an array of options where name
is the option identifier and value
is the text displayed to the user
value
is an array containing the name
s of the choices that are selected on submission
Switch
An on/off switch
{
"refName": "mySwitch",
"formComponentType": "switch",
"title": "Switch",
"value": false //When submitted
}
title
is the text displayed next to the switch
value
is the default value of the switch when creating and the selected value when submitting
Slider
A slider to let the user select a value by dragging its handle
{
"refName": "mySlider",
"formComponentType" : "slider",
"title": "Slider",
"requiredSelection": false,
"value" : 20, //When initialized or submitted
"min": 0,
"max": 100,
"step": 5
}
title
is the text displayed next to the slider
requiredSelection
indicates if the selection is required to submit the form
value
is the value selected on the slider on initializing (sending the form) or submission
min
is the value selected when slider is at its minimum
max
is the value selected when slider is at its maximum
step
is the value amount that sums or subtracts to the initial value at each slider minimum drag
Date Picker
A graphical date-picker to select a date from a calendar
{
"refName": "myDatePicker",
"formComponentType" : "datepicker",
"title" : "Date Picker",
"requiredSelection": false,
"value" : "", //When submitted
"actionButtonTitle": "Select Date"
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the chosen date when the form is submitted
actionButtonTitle
is the label of the pick button
Time Picker
A graphical time-picker to select a date from a calendar
{
"refName": "myTimePicker",
"formComponentType" : "timepicker",
"title" : "Time Picker",
"requiredSelection": false,
"value": "", //When submitted
"actionButtonTitle": "Select Time"
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the chosen time value when the form is submitted
actionButtonTitle
is the label of the pick button
Location Picker
A picker showing a map where to choose a location or address
{
"refName": "myLocationPicker",
"formComponentType" : "locationpicker",
"title" : "Location Picker",
"requiredSelection": false,
"value" : "", //When submitted
"actionButtonTitle": "Select Location",
"currentLocationOnly": false
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the chosen location value when the form is submitted
actionButtonTitle
is the label of the pick button
currentLocationOnly
…
Photo Picker
A picker allowing to select and reference a photo
{
"refName": "myPhotoPicker",
"formComponentType" : "photopicker",
"title" : "Photo Picker",
"requiredSelection": false,
"value" : [ //When submitted
{
"fileType": "fileType",
"fileID": "fileId",
"fileName": "fileName",
"fileSize": 1234
}
],
"actionButtonTitle": "Select Photos",
"multiSelection": true
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the photo objects picked when the form is submitted
actionButtonTitle
is the label of the pick button
multiSelection
is a flag that allows the user to select multiple objects in the UI
File Picker
A picker allowing to select and reference a file
{
"refName": "myFilePicker",
"formComponentType" : "filepicker",
"title": "File Picker",
"requiredSelection": false,
"value" : [ //When submitted
{
"fileType": "fileType",
"fileID": "fileId",
"fileName": "fileName",
"fileSize": 1234
}
],
"actionButtonTitle" : "Select Files",
"multiSelection": true
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the file objects picked when the form is submitted
actionButtonTitle
is the label of the pick button
multiSelection
is a flag that allows the user to select multiple objects in the UI
Contact Picker
A picker allowing to select and reference contacts
{
"refName": "myContactPicker",
"formComponentType" : "contactpicker",
"title": "Contact Picker",
"requiredSelection": false,
"value" : [],
"actionButtonTitle" : "Select Contacts",
"multiSelection": true
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the chosen contact ids when form is submitted
actionButtonTitle
is the label of the pick button
multiSelection
is a flag that allows the user to select multiple objects in the UI
Bucket Picker
A picker allowing to select and reference buckets
{
"refName": "myBucketPicker",
"formComponentType" : "bucketpicker",
"title": "Bucket Picker",
"requiredSelection": false,
"value" : [ //When submitted
{
"id": "groupChatId",
"featureType": "groupchat"
}
],
"filter": {
"types": ["post", "profile", "groupchat", "channel"]
},
"actionButtonTitle" : "Select Bucket",
"multiSelection": true
}
title
is the text displayed next to the picker
requiredSelection
indicates if the selection is required to submit the form
value
is the selected bucket id upon form submission. It can be of the following types:
Group Chat
{
"id": "groupChatId",
"featureType": "groupchat"
}
Channel
{
"id": "channelId",
"featureType": "channel"
}
filter/types
determines what type of bucket one wants the user to pick from. Allowed (multiple) values are: post
| profile
| groupchat
| channel
actionButtonTitle
is the label of the pick button
multiSelection
is a flag that allows the user to select multiple objects in the UI
Hidden Value
A value into the form which is not visible to the user
{
"refName": "myHiddenValue",
"formComponentType" : "hiddenvalue",
"value": "mySecretValue" //When submitted
}
QR Code Scanner
A scanner button allowing to scan and read QR Codes
{
"refName": "myQrCodeScanner",
"formComponentType" : "qrcodescanner",
"title": "QR Code",
"requiredSelection": false,
"value" : null, //When submitted
"actionButtonTitle": "Scan QR Code"
}
title
is the text displayed next to the scanner
requiredSelection
indicates if the selection is required to submit the form
value
is the decoded value of the QR Code scanned upon form submission
actionButtonTitle
is the label of the scan button
NFC Reader
A scanner button allowing to read NFC tags
{
"refName": "myNfcReader",
"formComponentType" : "nfcreader",
"title" : "NFC Reader",
"requiredSelection": false,
"value" : null, //When submitted
"actionButtonTitle": "Read NFC"
}
title
is the text displayed next to the scanner
requiredSelection
indicates if the selection is required to submit the form
value
is the decoded value of the NFC scan upon form submission
actionButtonTitle
is the label of the scan button
Buckets
Buckets are flexible structures which hold data and specific functions according to their type. Let’s explore all the peculiarities.
A generic bucket is an object with fixed properties that:
- can be added to profiles and feeds
- can be added as child of other existing generic buckets, in a matrioska-style
- has standard information, interaction, permissions properties
- can fit all kinds of supported messages
- can fit other buckets via reference, by including the child bucketId
{
"bucketId" : "<auto_generated>",
"dataComponentType" : "bucket",
"title": "New Bucket",
"description" : "This is the bucket description",
"role": "Owner",
"ownerId": "ownerAccountId",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"dataComponents" : [
{
//...
}
]
}
bucketId
is the unique Id to reference an existing or a newly created bucket. It serves different purposes:
- if it’s not specified in a bucket structure, it means that the bucket has to be created. In this case, the user will have to specify the entire bucket structure, including child datacomponents and child bucket references (see Creating Buckets example). A new bucketId will be returned in the response for future referencing
- if it is specified in a bucket structure, it means that the user wants to reference an existing bucket in the current object/message. In this case, the user only needs to specify the bucket id and its component type (see Referencing Buckets example).
title
sets the bucket title
description
sets the bucket description
role
is the role of the current account for the bucket. It may be either Owner
, Admin
, Editor
or Viewer
ownerId
is the account Id who owns the bucket
avatar
takes a fileId (obtained by a File Upload endpoint) and sets the main avatar image of the bucket
visible
sets the bucket general visibility. If set to false
, the bucket will be only visible to its creator
locked
sets the bucket’s general edit permissions. If set to true
, its content cannot be interacted by other users
enableReactions
allows other users to post reactions (e.g. likes) to bucket’s content
Creating buckets
Here is an example request body to add a new bucket to the user’s feed. The created bucket will also specify two children components: a text component and a bucket reference.
{
"dataComponent": {
"bucketId" : "<auto_generated>",
"dataComponentType" : "bucket",
"title": "New Bucket",
"description" : "This is the bucket description",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"dataComponents" : [
{
"dataComponentType": "text",
"text": "hello"
},
{
"dataComponentType": "bucket",
"bucketId": "bucketId"
}
]
}
}
Referencing buckets
Here is an example request body to reference an existing bucket (on which the user has the right permissions) to the user’s feed.
{
"dataComponent": {
"bucketId" : "existingBucketId",
"dataComponentType": "bucket"
}
}
Accounts
Account Profile
The account profile is a special data holder and acts as the main content page of the account. The profile has the following schema to display data:
graph LR subgraph Tiles Tile1 Tile2 TileN end subgraph Components[Data Components] Component1 Component2 ComponentN end subgraph Properties Property1 Property2 PropertyN end Profile --> Properties Profile --> Components Profile --> Tiles
Account Feed
The feed is a timeline-based section where the account can publish new multimedia posts, so the feed gets a content history over time. Each post is essentially a bucket, enriched with publishing time records. The feed has the following schema:
graph TD subgraph Feed direction LR Post1["Post 1 (Bucket)"] Post2["Post 2 (Bucket)"] PostN["Post N (Bucket)"] Post1 ~~~ Post2 ~~~ PostN end Account --> Feed
Endpoints
Get My Accounts
This endpoint lists all the user accounts somehow linked to the calling user, including owned subaccounts and shared accounts.
GET /account/my?main={main}&sub={sub}&shared={shared}&details={details}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
main | Boolean | Yes | Include the main account of the calling user |
sub | Boolean | Yes | Include the owned subaccounts |
shared | Boolean | Yes | Include the accounts shared with the user |
details | Boolean | Yes | Include accounts’ advanced properties |
Response body
{
"currentAccount": {
"accountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"semilimesId": "ND093HW",
"accountName": "MyMainAccount",
"ownerAccountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"lastSeen": 1700562656,
"updatedAt": 1700562656,
"createdAt": 1700562656
},
"mainAccount": {
"accountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"semilimesId": "ND093HW",
"accountName": "MyMainAccount",
"ownerAccountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"lastSeen": 1700562656,
"updatedAt": 1700562656,
"createdAt": 1700562656
},
"subAccounts": [
{
"parentAccountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"accessRole": "Owner",
"accountId": "c6e56f99-70d6-47b1-ac2b-1efb927806f6",
"semilimesId": "VT532VV",
"accountName": "MySubAccount1",
"ownerAccountId": "c6e56f99-70d6-47b1-ac2b-1efb927806f6",
"lastSeen": 1700562656,
"updatedAt": 1700562656,
"createdAt": 1700562656
}
],
"sharedAccounts": [
{
"accountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"semilimesId": "ND093HW",
"accountName": "MyMainAccount",
"ownerAccountId": "0edb81a1-591d-44bb-b5b4-66e3dc40e804",
"lastSeen": 1700562656,
"updatedAt": 1700562656,
"createdAt": 1700562656
}
]
}
An Account has the following base properties
Property | Type | Account Type | Description |
---|---|---|---|
accountId | String | All | Account’s global identifier |
semilimesId | String | All | Human readable account’s reference id, displayed in the semilimes app |
accountName | String | All | Account’s friendly name |
ownerAccountId | String | All | Account Id of the current account owner |
lastSeen | Unix Time | All | Last time the account has been seen on semilimes servers |
updatedAt | Unix Time | All | Last time the account has been updated |
createdAt | Unix Time | All | Time of account’s creation |
parentAccountId | String | Subaccount | Id of the account holding this subaccount |
accessRole | String | Subaccount | Access role the current account has on this subaccount |
Access Roles
Role | Description |
---|---|
Owner | All permissions |
Admin | All permissions |
Editor | Editing content permissions |
Viewer | Viewing content permissions |
Account advanced properties
Property | Type | Description | Example |
---|---|---|---|
viewCount | Number | Views by other users | 127 |
likeCount | Number | Likes received by the account | 98 |
commentCount | Number | Comments received by the account | 22 |
onlineStatus | String | Users’ current online status | Online / Offline |
Sample account response with advanced properties:
"currentAccount": {
//...
"viewCount": 127,
"likeCount": 98,
"commentCount": 22,
"onlineStatus": "Offline",
//...
}
Get Account Profile
Gets the account profile’s configuration and content
GET /account/profile?accountId={accountId}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
accountId | String | Yes | If not specified, the current account’s profile gets returned |
Response body
{
"profileId" : "myProfileId",
"featureType": "profile",
"title": "Profile Title",
"description" : "This is the profile description",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"pinWall": [
{
//Data component
}
],
"subBuckets": [
{
//Bucket
}
]
}
Property | Type | Description |
---|---|---|
title | String | The title displayed in the profile page |
description | String | The subtitle displayed under the title |
avatar | String | Foreground image (id) showed in the profile |
visible | Boolean | Visibility of the profile to other users when accessing the account |
locked | Boolean | Global ability of the other users to interact with the profile content |
enableReactions | Boolean | Global ability of the other users to leave likes/reactions to the profile content |
pinWall | Array | Array of data components showing in the pin wall of the semilimes app’s profile |
subBuckets | Array | Array of additional buckets added under the app’s profile page |
Update Account Profile
This endpoint lets the user update the specified profile and its pinwall content
POST /account/profile/update
Request body
{
"title": "Profile Title",
"description" : "This is the profile description",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"pinWall": [
{
//Data component
}
]
}
Response body
{
"accountId": "accountUpdated",
"updatedProfile": {
"refName" : "myProfileRefName",
"featureType": "profile",
"title": "Profile Title",
"description" : "This is the profile description",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"pinWall": [
{
//Data component
}
],
"subBuckets": [
{
//Bucket
}
]
}
}
Get Account Feed
Gets the account feed’s configuration and content. Each post can only contain a bucket
component type.
GET /account/feed?accountId={accountId}&before={before}&after={after}&limit={limit}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
accountId | String | Yes | If not specified, the current account’s feed gets returned |
before | Unix Time | Yes | Get feed’s content published before this date |
after | Unix Time | Yes | Get feed’s posts published before this date |
limit | Integer | Yes | Maximum number of posts returned |
Response body
{
"feedId" : "feedId",
"accountId": "accountId",
"featureType": "feed",
"title": "Feed Title",
"avatar" : "avatarFileId",
"posts": [
{
"publishedOn": 1700562656,
"editedOn": 1700562656,
"dataComponent" : {
"bucketId" : "bucketId",
"dataComponentType" : "bucket"
}
}
]
}
Property | Type | Description |
---|---|---|
title | String | The title displayed in the feed page |
avatar | String | Foreground image (id) showed in the feed page |
posts | Array | Array of posts added to the feed |
publishedOn | Unix Time | When the post was published |
updatedOn | Unix Time | When the post was updated |
Add post to account feed
This endpoint allows the user to add a new post to the feed.
Note: This action will automatically create a new bucket with the specified information. To update this post afterwards, the returned bucketId will be requested.
POST /account/feed/post/add
Request body - New bucket
{
"title": "New Bucket",
"description" : "This is the post description",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"dataComponents" : [
{
//...
}
]
}
Response body
{
"feedId" : "feedId",
"accountId": "accountId",
"addedPost": {
"publishedOn": 1700562656,
"editedOn": 1700562656,
"dataComponent" : {
"bucketId" : "bucketId",
"dataComponentType" : "bucket"
}
}
}
Edit post content
This endpoint allows the user to access the content of a post (bucket) and modify its content. The action is possible only if the user has the right permissions to modify the bucket.
POST /account/feed/post/update
Request body
{
"bucketId": "bucketIdToUpdate",
"title": "Edited Bucket",
"description" : "This is the new bucket description",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"enableReactions": true,
"dataComponents" : [
{
//...
}
]
}
Response body
{
"feedId" : "feedId",
"accountId": "accountId",
"updatedPost": {
"publishedOn": 1700562656,
"editedOn": 1700562656,
"dataComponent" : {
"bucketId" : "bucketId",
"dataComponentType" : "bucket"
}
}
}
Get account contacts
This endpoint allows to retrieve all the current account contacts
GET /account/contacts
Response body
[
{
"accountId": "myContactId1",
"accountName": "myContactName1",
"contactStatus": "CONFIRMED"
}
]
accountId
is the contact’s accountId
accountName
is the contact’s display name
contactStatus
is the current status of the contact:
CONFIRMED
if the account is an actual contactINVITED
if the account has been invited as a contact and it has not confirmed the invite yetWAITING
if the current account has been invited by the contact and the invite has not been confirmed yet
Communication
P2P Chat
This is a one-to-one form of messaging, therefore it supports only two members, both acting as senders and recipients. This chat is created by an explicit creation action or implicitly by sending the first message to a recipient.
graph LR A1[Account 1] A2[Account 2] A3[Account 3] C12([P2P]) C13([P2P]) C23([P2P]) A1 <--> C12 <--> A2 A2 <--> C23 <--> A3 A3 <--> C13 <--> A1
Group Chat
This is a conversation space between two or more users, where each user can send, receive or react to messages within the group. This is created by an explicit create action, inviting recipients at creation time and/or afterwards.
graph LR A1[Account 1] A2[Account 2] A3[Account 3] G([Group Chat]) A1 & A2 & A3 <--> G
Channels
Channels are a form of communication space meant to publish content to a broad set of users. Specifically channels have:
- one or few content editors, which will provide new content
- many subscribers, which will be notified on new events and can read news
A channel is created explicitly by a creation action, and users can be added as editors or viewers upon creation or at a later time.
graph LR A1[Account 1] A2[Account 2] A3[Account 3] A4[Account 4] C([Channel]) A1 --> C --> A2 & A3 & A4
Endpoints
Communication endpoints can be triggered via:
- HTTP REST mode
- WebSocket mode
Get P2P Chats
This endpoint retrieves the p2p chats of the calling user account
HTTP REST
GET /communication/p2p
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
None
Response body
[
{
"recipientId" : "recipientId"
}
]
Get P2P Chat Messages
This endpoint returns a list of messages in the specified P2P chat
HTTP REST
GET /communication/p2p/message?recipientId={recipientId}&messageId={messageId}&limit=100
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p/message",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
recipientId | String | No | Identifies the p2p chat by the recipientId |
messageId | String | Yes | Search for a specific messageId |
limit | Integer | Yes | Limits the number of messages retrieved |
Response body
{
"recipientId" : "recipientId",
"messages" : [
{
"messageId" : "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//Data component here
},
"messageReactions": {
"reactionCode1": [
"accountId1",
"accountId2",
//...
],
"reactionCode2": [
"accountId1",
"accountId2",
//...
]
//...
}
}
]
}
Send to P2P Chat
This endpoint allows to send a data component to a P2P Chat as a new message, by specifying a conversation name or by identifying the actual recipient. If a recipientId
is specified, and no P2P chats exist between the current account and the specified recipient, a new P2P chat will be created automatically.
HTTP REST
POST /communication/p2p/message/send
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p/message/send",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"recipientId": "recipientAccountId",
"dataComponent": {
//Data component here
}
}
recipientId
refers to the other accountId that is having a conversation with the current account.
dataComponent
is the type of payload accepted among the supported ones
Response body
{
"recipientId": "recipientAccountId",
"sentMessage": {
"messageId": "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//...
}
}
}
messageId
is the generated unique id for referencing the sent message
Edit P2P Chat Message
This endpoint allows to edit a previously sent message
HTTP REST
POST /communication/p2p/message/update
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p/message/update",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "messageToUpdate",
"dataComponent": {
//New data component here
}
}
Response body
{
"updatedMessage": {
"messageId" : "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//...
}
}
}
React to P2P Message
This endpoint allows the account to send a reaction to a specific message in a P2P conversation.
HTTP REST
POST /communication/p2p/message/reaction/send
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p/message/reaction/send",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "messageToReactTo",
"reaction": ""
}
reaction
is a string usually containing an emoji character
messageRefName
is the refName that identifies a data component included in a message
Response body
{
"messageId" : "uniqueMessageId",
"addedReaction": ""
}
Cancel reaction to P2P Message
This endpoint allows the account to send a reaction to a specific message in a P2P conversation.
HTTP REST
POST /communication/p2p/message/reaction/remove
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p/message/reaction/remove",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "uniqueMessageId",
"reaction" : "reaction-code-to-remove"
}
reaction
is the reaction string code to remove
messageId
is the Id that identifies a data component included in a message
Response body
{
"messageId" : "uniqueMessageId",
"removedReaction": "reaction-type"
}
Reply to P2P Message
This endpoint allows the account to reply to a specific message with a simple text.
HTTP REST
POST /communication/p2p/message/reply
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/p2p/message/reply",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "messageToReplyTo",
"dataComponent": {
"dataComponentType": "text",
"text" : "myReplyText"
}
}
messageId
identifies the message to reply to
dataComponent
can only contain text
as it is the only supported reply type
Response body
{
"messageId" : "uniqueMessageId",
"sentReply": {
"messageId" : "replyMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
"dataComponentType": "text",
"text" : "myReplyText"
}
}
}
messageId
is the Id of the cited message
sentReply/messageId
is the generated Id for the reply message
Get Group Chats
This endpoint retrieves the group chat buckets the calling user account is editor of.
HTTP REST
GET /communication/groupchat?recipientIds={recipientIds}
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
recipientIds | String | Yes | Comma separated string of multiple recipient Ids. It will filter the group chats containing the specified Ids as recipients |
Response body
[
{
"groupChatId" : "myGroupChatId",
"title": "myGroupChatTitle",
"recipientIds" : [
"recipientId1",
"recipientId2",
"recipientId3"
]
}
]
title
is the conversation display name
ownerId
is the account id who owns the group chat
recipientIds
is an array of all the editors of the group chat
Create Group Chat
This endpoint creates a new group chat with a specified name. It’s also possible to directly invite other accounts to the chat upon creation.
HTTP REST
POST /communication/groupchat/create
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/create",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"title": "myGroupChatTitle",
"recipientIds" : [
"recipientId1",
"recipientId2",
"recipientId3"
]
}
Response body
{
"createdGroupChat": {
"groupChatId" : "myGroupChatId",
"title": "myGroupChatTitle",
"recipientIds" : ["recipientId1","recipientId2","recipientId3"]
}
}
Get Group Chat Messages
This endpoint returns a list of messages in the specified P2P chat
HTTP REST
GET /communication/groupchat/message?groupChatId={groupChatId}&messageId={messageId}&limit=100
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/message",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
groupChatId | String | No | Identify the group chat by its unique id |
messageId | String | Yes | Search a specific messageId |
limit | Integer | Yes | Limits the number of messages retrieved |
Response body
{
"groupChatId" : "myGroupChatId",
"messages" : [
{
"messageId" : "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//Data component...
},
"messageReactions": {
"reactionCode1": [
"accountId1",
"accountId2",
//...
],
"reactionCode2": [
"accountId1",
"accountId2",
//...
]
//...
}
}
]
}
Invite to Group Chat
This endpoint allows to invite other recipients to the specified group chat
HTTP REST
POST /communication/groupchat/invite
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/invite",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"groupChatId": "myGroupChatId",
"recipientIds": [
"recipientId1",
"recipientId2",
//...
]
}
Response body
{
"groupChatId": "myGroupChatId",
"invitedRecipientsIds": [
"recipientId1",
"recipientId2",
//...
]
}
Send to Group Chat
This endpoint allows to send a data component to a Group Chat as a new message, by specifying a conversation name
HTTP REST
POST /communication/groupchat/message/send
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/message/send",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"groupChatId" : "myGroupChatId",
"dataComponent": {
//Data component here
}
}
groupChatId
is the specific conversation Id to send the payload to
dataComponent
is the type of payload accepted among the supported ones
Response body
{
"groupChatId" : "myGroupChatId",
"sentMessage": {
"messageId" : "messageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//...
}
}
}
Edit Group Chat Message
This endpoint allows to edit a previously sent message
HTTP REST
POST /communication/groupchat/message/update
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/message/update",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body*
{
"messageId" : "messageToUpdate",
"dataComponent": {
//Updated data component here
}
}
Response body
{
"updatedMessage": {
"messageId" : "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//...
}
}
}
React to Group Chat Message
This endpoint allows the account to send a reaction to a specific message in a group conversation.
HTTP REST
POST /communication/groupchat/message/reaction/send
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/message/reaction/send",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "messageToReactTo",
"reaction": ""
}
reaction
is a string usually containing an emoji character
Response body
{
"messageId" : "uniqueMessageId",
"addedReaction": ""
}
Cancel reaction to Group Chat Message
This endpoint allows the account to send a reaction to a specific message in a group conversation.
HTTP REST
POST /communication/groupchat/message/reaction/remove
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/message/reaction/remove",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "messageToCancelReactionFrom",
"reaction": "reaction-code-to-remove"
}
Response body
{
"messageId" : "uniqueMessageId",
"removedReaction": "reaction-code"
}
Reply to Group Chat Message
This endpoint allows the account to reply to a specific message with a simple text.
HTTP REST
POST /communication/groupchat/message/reply
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/groupchat/message/reply",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"messageId" : "messageToReplyTo",
"dataComponent": {
"text" : "myReplyText"
}
}
dataComponent
can only contain text
as its the only message type supported
Response body
{
"messageId" : "uniqueMessageId",
"sentReply": {
"messageId": "replyMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//the added data component
}
}
}
messageId
is the Id of the cited message
sentReply/messageId
is the generated Id for the reply message
Get My Channels
This endpoint retrieves the channels the calling user account is owner, editor or subscriber of.
HTTP REST
GET /communication/channel/my?owner={isOwner}&editor={isEditor}&subscriber={isSubscriber}
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/my",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
owner | Boolean | Yes | Includes the channels where the current account is an owner |
editor | Boolean | Yes | Includes the channels where the current account is a editor |
subscriber | Boolean | Yes | Includes the channels where the current account is a subscriber |
Response body
[
{
"channelId" : "myChannelId",
"title" : "Channel Title",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"role" : "Editor",
"ownerId" : "accountId",
"editorIds" : [
"accountId1",
"accountId2"
]
}
]
title
is the channel title
avatar
specifies a fileId (obtained by a File Upload endpoint) if an avatar image is specified for the channel
visible
indicates the channel general visibility. If set to false
, the channel is only visible to its creator
locked
indicates the channel’s general edit permissions. If set to true
, its content cannot be interacted by other users
role
is the current account’s role on the channel. Can be either Owner
, Editor
or Subscriber
ownerId
is the owner account of the channel
editorIds
is the list of the accounts that can publish content on this channel
Get Channels
This endpoint finds channels based on specified parameters
HTTP REST
GET /communication/channel?ownerId={ownerId}&editorId={editorId}&channelId={channelId}&title={channelTitle}
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
ownerId | String | Yes | Returns channels owned by the specified account Id |
editorId | String | Yes | Returns channels whose editor is this account Id |
channelId | String | Yes | Returns the channel with this id |
title | String | Yes | Returns channels with this title |
At least one of the parameters must be set, otherwise the request will fail.
Response body
[
{
"channelId" : "myChannelId",
"title" : "Channel Title",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"role" : "Editor",
"ownerId" : "accountId",
"editorIds" : [
"accountId1",
"accountId2"
]
}
]
title
is the channel title
avatar
specifies a fileId (obtained by a File Upload endpoint) if an avatar image is specified for the channel
visible
indicates the channel general visibility. If set to false
, the channel is only visible to its creator
locked
indicates the channel’s general edit permissions. If set to true
, its content cannot be interacted by other users
role
is the current account’s role on the channel. Can be either Owner
, Editor
or Subscriber
ownerId
is the owner account of the channel
editorIds
is the list of the accounts that can publish content on this channel
Create Channel
This endpoint allows to create a new channel and set the initial editors. The role of the current accountId will be automatically Owner
HTTP REST
POST /communication/channel/create
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/create",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"title" : "Channel Title",
"avatar" : "avatarFileId",
"visible" : true,
"locked": false,
"editorIds" : [
"accountId1",
"accountId2"
]
}
title
is the channel title
avatar
takes a fileId (obtained by a File Upload endpoint) and sets the main avatar image of the channel
visible
sets the channel general visibility. If set to false
, the channel will be only visible to its creator
locked
sets the channel’s general edit permissions. If set to true
, its content cannot be interacted by other users
editorIds
array can be set with additional account Ids to let them become editors of the channel
Response body
{
"createdChannel" : {
"channelId" : "myChannelId",
"title" : "Channel Title",
"avatar": "avatarFileId",
"role" : "Owner",
"ownerId" : "accountId",
"editors" : [
"accountId1",
"accountId2"
]
}
}
Get Channel Messages
This endpoint returns the messages of a channel
HTTP REST
GET /communication/channel/message?channelId={channelId}&messageId={messageId}&limit={limit}
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/message",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
channelId | String | Yes | Identify the channel from which to extract the messages |
messageId | String | Yes | Retrieve a specific message |
limit | Integer | Yes | Limit the number of messages returned |
Response body
{
"channelId": "b04722ea-c480-4c80-9896-efc0eb3fdf29",
"messages": [
//...
]
}
Send to Channel
This endpoint allows to send a data component to a Channel as a new message, by specifying a conversation name
HTTP REST
POST /communication/channel/message/send
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/message/send",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"channelId" : "myChannelId",
"dataComponent": {
//Data component here
}
}
channelId
is the specific channel to send the payload to
dataComponent
is the type of payload accepted among the supported ones
Response body
{
"channelId" : "myChannelRefName",
"sentMessage": {
"messageId": "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//the added data component
}
}
Edit Channel Message
This endpoint allows to edit a previously sent message
HTTP REST
POST /communication/channel/message/update
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/message/update",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body*
{
"messageId" : "messageToUpdate",
"dataComponent": {
//Updated data component here
}
}
Response body
{
"updatedMessage": {
"messageId" : "uniqueMessageId",
"publisherId" : "publisherAccountId",
"publishedOn" : 1700562656,
"updatedOn" : 1700562656,
"dataComponent" : {
//...
}
}
}
Subscribe to Channel
This endpoint makes the calling account to subscribe to an existing channel
HTTP REST
POST /communication/channel/subscribe
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/subscribe",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"channelId" : "myChannelId"
}
Response body
{
"channelId" : "myChannelId",
"subscribed": true
}
Unsubscribe from Channel
This endpoint makes the calling account to unsubscribe from an existing channel
HTTP REST
POST /communication/channel/unsubscribe
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/channel/unsubscribe",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"channelId" : "myChannelId"
}
Response body
{
"channelId" : "myChannelId",
"subscribed": false
}
Open bucket
This endpoint let the user access the bucket content by its bucketId
HTTP REST
POST /communication/bucket
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/bucket",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request params
Parameter | Type | Optional | Description |
---|---|---|---|
bucketId | String | Yes | Identify the bucket from which to extract the content |
Response body
{
//bucket component
}
Update bucket content
This endpoint allows the user to update the content of a specific bucket.
HTTP REST
POST /communication/bucket/update
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/bucket/update",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"bucketId": "bucketIdToUpdate",
//... Bucket data component
}
Response body
{
"accountId": "callerAccountId",
"updatedBucket": {
"bucketId": "bucketIdToUpdate",
"dataComponentType": "profileitem",
"title": "Edited bucket 1",
"description": "myTagEdited",
"visible": false,
"locked": false,
"enableReactions": true,
"viewCount": 1
}
}
Add a like to a bucket
This endpoint sets a like by the current account to any referenced bucket that allows likes.
HTTP REST
POST /communication/bucket/like
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/bucket/like",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"bucketId" : "mybucketId"
}
Response body
{
"bucketId": "myBucketId",
"like": true
}
Remove a like to a bucket
This endpoint unsets a like of the current account to any referenced bucket that allows likes.
HTTP REST
POST /communication/bucket/unlike
WebSocket
Send to /wsclient
{
"requestId": "<randomCorrelationId>",
"requestType": "/communication/bucket/unlike",
"version": "2",
"parameters" : {
//parameters used in REST
},
"body" : {
//request body used in REST
}
}
Request body
{
"bucketId" : "mybucketId"
}
Response body
{
"bucketId": "myBucketId",
"like": false
}
Services
This section contains all the endpoints for triggering special backend functions
Endpoints
Get Tunnels
This endpoint lists all created tunnels for the requesting user
HTTP REST
GET /service/tunnel
Response body
[
{
"tunnelId": "createdTunnelId",
"name": "TunnelName",
"description": "TunnelDescription",
"clientPort": 12345,
"clientPath": "clientPath",
"publicKey": "publicKeyHere",
"host": "tunnelServiceHost",
"username": "tunnelServiceUsername",
"port": 0,
"tunnelUrl": "tunnelUrl"
}
]
host
, username
and port
won’t be set if the tunnel is not opened
tunnelUrl
is the actual URL provided by the tunnel service to access the local content
Create Tunnel
This endpoint requests a tunnel creation and setup on the tunnel provider
Note This requires a public RSA key of a SSH certificate generated by the client
HTTP REST
POST /service/tunnel/create
Request body
{
"name": "myTunnel",
"description": "TunnelDescription",
"clientPort": 12345,
"clientPath": "clientPath",
"publicKey": "publicKeyHere"
}
clientPath
is an additional subpath after the main domain address
Response body
{
"tunnelId": "createdTunnelId"
}
Open Tunnel
This endpoint activates the tunnel and allocates a remote port on the tunnel provider
HTTP REST
POST /service/tunnel/open
Request body
{
"tunnelId": "tunnelToOpen"
}
Response body
{
"tunnelId": "tunnelId",
"host": "tunnelServiceHost",
"username": "username",
"port": 1234,
"tunnelUrl": "TunnelUrl"
}
host
is the remote address of the tunneling server
username
is the username to provide to the tunneling server when initiating an ssh connection
port
is the remote port of the tunneling server to be mapped to the client port when initiating an ssh connection
tunnelUrl
is the actual URL provided by the tunnel service to access the local content
The client SSH connection should be performed like in this cmd example
ssh -N -R <port>:<name>:<clientPort>/<clientPath> <username>@<host>:22
Close Tunnel
This endpoint shuts off a tunnel
HTTP REST
POST /service/tunnel/close
NOTE: this endpoint should be called after the client has successfully disconnected its SSH session
Request body
{
"tunnelId": "tunnelToClose"
}
Response body
{
}
Delete Tunnel
This endpoint deletes a tunnel on the tunnel provider
HTTP REST
POST /service/tunnel/delete
Request body
{
"tunnelId": "tunnelToDelete"
}
Response body
{
}
File Download
This endpoint makes the client download file content from the server, based on the file id specified
HTTP REST
POST /service/file/download
Request body
{
"fileId": "fileIdToDownload",
"thumbnailSize": 800
}
thumbnailSize
is optional and is an integer requesting a specific width of the image (if the file is an image).
Response body
Content-Type:
<[content-type-based-on-mime-type]>
/
<application/octet-stream>
File Upload
This endpoint makes the client upload file content onto the server and returns a file identifier to be used when sending this file to a recipient.
HTTP REST
POST /service/file/upload
Request body
Content-Type: multipart/form-data
application/json
{}
application/octet-stream
"httpFiles" : [<binary files>]
Response body
{
"uploadedFiles": [
{
"fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "myFileName",
"size": 0
}
]
}
fileId
is the Id to use to reference the source in each “file” data component
title
is the file display name
size
is the actual uploaded file size
Inbound events
This section contains the server->client messages within a WebSocket connection.
Standard WebSocket Response
This message is sent from the server as a response to a specific request has been send via WebSocket.
The requestId
property helps the client correlate the response to the original request.
{
"eventType": "Response",
"requestId": "originalRequestId",
"eventBody": {
"success": true,
"error": "errorMessage",
"data": {
//Response content
}
}
}
Received P2P Message
The following structure contains the necessary information to decode a P2P message received by the client
{
"eventType": "MessageReceived",
"featureType": "p2p",
"eventBody": {
"senderId": "Sender Id",
"messageId": "Message Id",
"receivedOn": 1700562656,
"dataComponent" : {
// data component
}
}
}
Received Group Chat Message
The following structure contains the necessary information to decode a Group Chat message received by the client
{
"eventType": "MessageReceived",
"featureType": "groupchat",
"eventBody" : {
"messageId": "Message Id",
"receivedOn": 1700562656,
"senderId": "Sender Id",
"groupChatId": "Conversation Id",
"dataComponent" : {
// data component
}
}
}
Received Channel Message
The following structure contains the necessary information to decode a Channel message received by the client
{
"eventType": "MessageReceived",
"featureType": "channel",
"eventBody": {
"messageId": "Message Id",
"receivedOn": 1700562656,
"senderId": "Sender Id",
"channelId": "Channel Id",
"dataComponent" : {
// data component
}
}
}