Welcome to
developer section

Hello developers, ready to achieve more? Here you will find the official resources and guides to support you in using semilimes at its fullest.

Before you proceed, make sure to stay connected with us for updates and insights. Explore our blog section for the latest news and engage with us on social media to be part of the conversation.

Your feedback is invaluable in making semilimes better for you and the broader community!

Tools

Below are listed the official tools for having your systems up and running in semilimes with no hassle.

**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.

Guide and Download

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

Swagger Editor Page

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.

Guide and Download

API Documentation

Let’s cover the main actions to get you up and running with your custom implementation and start experimenting. We will also show some use cases to tease your creativity!

Table of Contents

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.

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

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:

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 names 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.

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 contact
INVITED if the account has been invited as a contact and it has not confirmed the invite yet
WAITING 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

GET /communication/p2p

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

GET /communication/p2p/message?recipientId={recipientId}&messageId={messageId}&limit=100

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.

POST /communication/p2p/message/send

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

POST /communication/p2p/message/update

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.

POST /communication/p2p/message/reaction/send

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.

POST /communication/p2p/message/reaction/remove

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.

POST /communication/p2p/message/reply

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.

GET /communication/groupchat?recipientIds={recipientIds}

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.

POST /communication/groupchat/create

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

GET /communication/groupchat/message?groupChatId={groupChatId}&messageId={messageId}&limit=100

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

POST /communication/groupchat/invite

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

POST /communication/groupchat/message/send

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

POST /communication/groupchat/message/update

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.

POST /communication/groupchat/message/reaction/send

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.

POST /communication/groupchat/message/reaction/remove

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.

POST /communication/groupchat/message/reply

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.

GET /communication/channel/my?owner={isOwner}&editor={isEditor}&subscriber={isSubscriber}

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

GET /communication/channel?ownerId={ownerId}&editorId={editorId}&channelId={channelId}&title={channelTitle}

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

POST /communication/channel/create

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

GET /communication/channel/message?channelId={channelId}&messageId={messageId}&limit={limit}

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

POST /communication/channel/message/send

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

POST /communication/channel/message/update

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" : {
             //...
        }
    } 
}

This endpoint makes the calling account to subscribe to an existing channel

POST /communication/channel/subscribe

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

POST /communication/channel/unsubscribe

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

POST /communication/bucket

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.

POST /communication/bucket/update

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.

POST /communication/bucket/like

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.

POST /communication/bucket/unlike

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

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

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

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

POST /service/tunnel/close

Request body

{
    "tunnelId": "tunnelToClose"
}

Response body

{

}

Delete Tunnel

This endpoint deletes a tunnel on the tunnel provider

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

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.

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
        }
    }
}

Welcome todeveloper section

Tools

Node-RED semilimes Connector

What about:

Build your own client

semilimes remote

API Documentation

API Connection

HTTP

WebSocket

Sending WebSocket requests

Receiving WebSocket messages

API Specification

API Response Schema

Data Components

Simple Text

Html Text

File

Contact

Location

WebView

Channel reference

Tunnel

Form

Form Submission

Form Components

Label

Textbox

Button List

Single Choice

Multi Choice

Switch

Slider

Date Picker

Time Picker

Location Picker

Photo Picker

File Picker

Contact Picker

Bucket Picker

Hidden Value

QR Code Scanner

NFC Reader

Buckets

Creating buckets

Referencing buckets

Accounts

Account Profile

Account Feed

Endpoints

Get My Accounts

Access Roles

Account advanced properties

Get Account Profile

Update Account Profile

Get Account Feed

Add post to account feed

Edit post content

Get account contacts

Communication

P2P Chat

Group Chat

Channels

Endpoints

Get P2P Chats

Get P2P Chat Messages

Send to P2P Chat

Edit P2P Chat Message

React to P2P Message

Cancel reaction to P2P Message

Reply to P2P Message

Get Group Chats

Create Group Chat

Get Group Chat Messages

Invite to Group Chat

Send to Group Chat

Edit Group Chat Message

React to Group Chat Message

Cancel reaction to Group Chat Message

Reply to Group Chat Message

Welcome to
developer section