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:

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:

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:

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

Gauge

A gauge to show numerical data with a configurable ranges and colors

{
    "dataComponentType": "gauge",
    "title" : "Gauge",
    "thickness": 20, // 10-100
    "degrees": 30,  // 30-360
    "spacing": 0, // 0-20
    "fontSize": 12, // 8-48
    "value": 50, // 0-100, Normalized value for the gauge
    "displayValue": "130 km/h", //Text value to be showed if the pointer is not active
    "segments": [
        {
            "from": 0, //0-100
            "to": 20, // from-100
            "color": "#00AAFF" //RGB string
        }
    ],
    "pointer": "none", // "none" | "triangle" | "circle" | "needle"
    "pointerColor": "#ABABAB", //RGB string
    "progressBar": "basic", // "none" | "basic" | "rounded"
    "progressBarColor": "#CCDD11", //RGB string
}

title is the title showed on top of the gauge

thickness controls thickness of the gauge segments. Allowed values: 10-100

degrees specifies the angular space the gauge will be using. Allowed values: 30-360

spacing specifies the separation distance between segments. Allowed values: 0-20

fontSize determines the size of the displayValue near to the gauge. Allowed values: 8-48

value is the normalized value to control the gauge. Allowed values: 0-100

displayValue is a free field to show the actual value, or the actual value + unit of measure, or just a custom text

segments is an array of the graphical segments composing the gauge.

A valid segment has:

• to > from
• from between the 0-99 range
• to between the 1-100 range

A valid segment array has:

• each segments’ to and from not overlapping.
• the total range covered by segments must match the total range of the gauge (0-100).

Example:

 "segments": [
      {
          "from": 0,
          "to": 20,
          "color": "#00AAFF"
      },
      {
          "from": 21,
          "to": 40,
          "color": "#FF12A1" 
      },
      {
          "from": 41,
          "to": 100,
          "color": "#BF45F0" 
      }
  ],

pointer shows a moving indicator on the gauge, depending on the value, and must have one of the following values:

• none
• triangle
• circle
• needle

Note: the displayValue will NOT be shown if the pointer is set to anything else than none

pointerColor defines the RGB color of the pointer, if set. The allowed value is in the #[0-F][0-F][0-F][0-F][0-F][0-F] format

progress shows a progress bar moving on the arch of the gauge, depending on the value, and must have one of the following values:

• none
• basic
• rounded

pointerColor defines the RGB color of the progress bar, if set. The allowed value is in the #[0-F][0-F][0-F][0-F][0-F][0-F] format

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
}

Appointment

An appointment message for defining a calendar event, complete with title, description, dates and location

{
    "dataComponentType": "appointment",
    "title": "Title", //required
    "description": "Description",
    "start": 123456789, //required - Epoch
    "end": 123456789, //required - Epoch
    "allDay": false, //default false
    "location": {
        "latitude": 12.3456,
        "longitude": 12.3456
    }
}

title is for assigning the main title to the appointment. This parameter is required

description is for assigning an optional description to the event

start is an epoch datetime for defining when the appointment will start

end is an epoch datetime for defining when the appointment will end

allDay is a boolean to determine if the appointment should cover all day, ignoring specific times of the selected start and end timestamps

location is an optional object to define a specific location where to attend the appointment. It includes mandatory latitude and longitude float variables.

timezone is a parameter to

WebView

A message referencing a webpage, to be viewed as a web frame

{
    "dataComponentType": "webview",
    "url": "my-url",
    "displayMode": "link",  //"link" | "thumbnail" | "liveweb"
    "linkDisplayName": "",
    "enableFullScreenView" : true,
    "viewSize" : "1:2"
}

url is the address to be rendered in the webview

displayMode gives the choice to display the destination url in multiple modes (the default behaviour is link):

• link for displaying as a direct link, (with an optional custom linkDisplayName replacing the full URL)
• thumbnail for showing a static preview of the destination page (where supported).
• liveweb for showing a dynamic embedded browser view, which uses enableFullScreenView to determine if the page can be opened in a full screen page, and viewSize to choose the shape of the view itself

linkDisplayName is used when displayMode is set to link, and it sets a custom name for the displaying URL

enableFullScreenView is used when displayMode is set to liveweb, and allows the user to open the browser view in a full screen page when clicking on it

viewSize is used when displayMode is set to liveweb, and it 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,
    "align": "left", // "left" | "center" | "right" 
    "authorizeSubmit": false,
    "submitText" : "",
    "receiver": {
        "id": "<accountId>",
        "featureType": "contact"
    },
    "hideSubmissionMsg": false,
    "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

align allows to align all the children form components to a direction. Allowed values: left (default), center, right

authorizeSubmit allows to protect the in-app submission of the form by a pin code or biometrics, whatever is set in the messenger app.

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

hideSubmissionMsg is a boolean to suppress in-app submission messages sent to receiver, while the API will still receive a submission for further processing.

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"
    },
    "submitterId": "SubmitterId",
    "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.

submitterId contains the Id of the user who submitted the form

Please note that in some cases the senderId of the outer message doesn’t match the submitterId by design, so please make sure you only rely on submitterId when you want to identify the original sender.

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

Gauge

A gauge to show numerical data with a configurable ranges and colors

{
    "refName": "myGauge",
    "formComponentType": "gauge",
    "title" : "Gauge",
    "thickness": 20, // 10-100
    "degrees": 30,  // 30-360
    "spacing": 0, // 0-20
    "fontSize": 12, // 8-48
    "value": 50, // 0-100, Normalized value for the gauge
    "displayValue": "130 km/h", //Text value to be showed if the pointer is not active
    "segments": [
        {
            "from": 0, //0-100
            "to": 20, // from-100
            "color": "#00AAFF" //RGB string
        }
    ],
    "pointer": "none", // "none" | "triangle" | "circle" | "needle"
    "pointerColor": "#ABABAB", //RGB string
    "progressBar": "basic", // "none" | "basic" | "rounded"
    "progressBarColor": "#CCDD11", //RGB string
}

title is the title showed on top of the gauge

thickness controls thickness of the gauge segments. Allowed values: 10-100

degrees specifies the angular space the gauge will be using. Allowed values: 30-360

spacing specifies the separation distance between segments. Allowed values: 0-20

fontSize determines the size of the displayValue near to the gauge. Allowed values: 8-48

value is the normalized value to control the gauge. Allowed values: 0-100

displayValue is a free field to show the actual value, or the actual value + unit of measure, or just a custom text

segments is an array of the graphical segments composing the gauge.

A valid segment has:

• to > from
• from between the 0-99 range
• to between the 1-100 range

A valid segment array has:

• each segments’ to and from not overlapping.
• the total range covered by segments must match the total range of the gauge (0-100).

Example:

 "segments": [
      {
          "from": 0,
          "to": 20,
          "color": "#00AAFF"
      },
      {
          "from": 21,
          "to": 40,
          "color": "#FF12A1" 
      },
      {
          "from": 41,
          "to": 100,
          "color": "#BF45F0" 
      }
  ],

pointer shows a moving indicator on the gauge, depending on the value, and must have one of the following values:

• none
• triangle
• circle
• needle

Note: the displayValue will NOT be shown if the pointer is set to anything else than none

pointerColor defines the RGB color of the pointer, if set. The allowed value is in the #[0-F][0-F][0-F][0-F][0-F][0-F] format

progress shows a progress bar moving on the arch of the gauge, depending on the value, and must have one of the following values:

• none
• basic
• rounded

pointerColor defines the RGB color of the progress bar, if set. The allowed value is in the #[0-F][0-F][0-F][0-F][0-F][0-F] format

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,
    "lineSize": "flexible", // "flexible", "1", "2", "3", "4", "5", "6"
    "options": [
        {
            "name" : "button1",
            "value": "buttonLabel1",
            "icon": {}
        },
        {
            "name" : "button2",
            "value": "",
            "icon": {
                "name": "emoji_emotions"
            }
        }
    ]
}

verticalList is a preference to tell a client app to display the buttons vertically

lineSize defines how the buttons should be spread on multiple lines (row/columns). Allowed values are:

• flexible
• 1 to 6

type within options determines if the button contains normal text or an icon. Allowed values are: text, icon

value within options contains the base display text for the button. It is ignored if icon is specified

icon within options specifies an object with a name for that icon. You can find the icon names reference at the official Google Fonts page

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,
    "mode": "list",
    "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

mode indicates if the choice should be displayed as a radio list or a dropdown control. The possible values are list or dropdown

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

Color Picker

A graphical color-picker to select a color from a palette and return its RGB value

{
    "refName": "myColorPicker",
    "formComponentType" : "colorpicker",    
    "title" : "Color Picker",
    "requiredSelection": false,
    "value" : "", //When submitted
    "actionButtonTitle": "Select Color"
}

title is the text displayed next to the picker

requiredSelection indicates if the selection is required to submit the form

value is the chosen color when the form is submitted

actionButtonTitle is the label of the pick button

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

Event Picker

A calendar-shaped form component which allows the user to navigate through events and pick one or more for sending it out in a form submission

{
    "refName": "myEventPicker",
    "formComponentType" : "eventpicker",    
    "title" : "Event Picker",
    "requiredSelection": false,
    "multiSelection": true,
    "eventsDisplayMode": "list", // list/buttons
    "events": [
        {
            "id": "eventId1", // Arbitrary Unique Id assigned by client
            "start": 123456789, //Epoch milliseconds for event start
            "title": "EventTitle",
            "description": "EventDescription",
            "referenceBucketId": "<bucketGuid>",
            "additionalInfo": {
                //Any additional info about the event here
            }
        }
    ],
    "value": [
        {
            //event object
        }
    ] //When submitted
}

multiselection is a boolean to tell the form it can only have one or more events selected before submission

eventsDisplayMode is a string that can hold list or buttons value. It will change how the events are displayed upon a date selection in the semilimes app

events is an array of predetermined events that populate the calendar widget displayed in the semilimes app

events/start is the only time reference for the event in the calendar, expressed in epoch time (milliseconds). Event end time or duration can be placed in title/description if you want it to be visible to the user, or placed in additionalInfo/<someProperty> to keep it as a hidden property.

events/referenceBucketId accepts any bucket GUID from semilimes environment, and allows the related event to display a details button that opens the destination bucket. The referenced bucket can be of any form (P2P/Group chat, channel, profile, bucket)

events/additionalInfo is an arbitrary object to keep hidden properties in the event and retrieve it upon submission.

value is an array that contains one or more selected events when the form is submitted

Hidden Value

A value into the form which is not visible to the user

{
    "refName": "myHiddenValue",
    "formComponentType" : "hiddenvalue",
    "value": "mySecretValue" //When submitted
}

Call Button

A special button to initiate a call to another user or group chat

{
    "refName": "myCallButton",
    "formComponentType" : "callbutton",    
    "title" : "Call Button",
    "actionButtonTitle": "Call"
}

title is the text displayed next to the button

actionButtonTitle is the label of the call button

QR Code Scanner

A scanner button allowing to scan and read QR Codes or Barcodes, and provide the read content as an output

{
    "refName": "myQrCodeScanner",
    "formComponentType" : "qrcodescanner",
    "title": "QR Code",
    "requiredSelection": false,
    "mode": "auto", //auto, qrcode, barcode
    "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

mode selects the type of code to support. Allowed values: auto, qrcode, barcode

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

API keys

An API key is a unique string of characters that serves as an authentication token between the client and cloud services API. It allows the cloud services to identify the client making the request and to authorize or restrict access to specific resources or actions. API keys can be issued through the user portal and must be kept secure by the client. Cloud services do not store API keys in a readable format, so the API key cannot be retrieved again once it is initially provided.

Rotation flow

sequenceDiagram
    participant Client
    participant API

    Client->>API: GET /apikey/~validate
    API-->>Client: Response with key details (including expiration date and previous_api_key_id)

    alt Key expiration date is less than 5 days
        Client->>API: POST /apikey
        Note right of Client: "name: API key name, expire_at: 2006-01-02T15:04:05Z07:00"
        API-->>Client: Response with new API key

        Client->>LocalStorage: Store new API key locally

        Client->>API: DELETE /apikey/{previous_api_key_id}
        API-->>Client: Previous API key deleted
    else Key expiration date is 5 days or more
        API-->>Client: No action required
    end

Endpoints

The purpose of these endpoints is to manage API keys securely, enabling clients to rotate API keys that are about to expire. API key rotation ensures that keys are refreshed periodically to maintain security and prevent unauthorized access. Through these endpoints, clients can validate, create or delete API keys, ensuring continuous access to cloud services without disruptions.

Validate API key

The purpose of this enpoint for client which doesn’t store the key expiration date to be able to get key info

GET /apikey/~validate

Response body

{
    "id": 400,
    "name": "API Key Name",
    "expire_at": "2027-09-06T17:41:33Z",
    "is_active": true,
}

Create API key

Creates a new API key with a provided name and expiration date. The key is returned in the response and must be securely stored as it won’t be retrievable again.

POST /apikey

Request body

{
    "name": "The name of the API key for distinguishing it in the user portal UI",
    "expire_at": "Expiration date in the format '2006-01-02T15:04:05Z07:00'"
}

Response body

{
    "id": 12345,
    "key": "abc123xyz456exampleapikey",
    "name": "My API Key",
    "created_at": "2024-09-06T14:00:00Z",
    "expire_at": "2025-09-06T14:00:00Z",
    "is_active": true,
    "revoked_at": null
}

Delete API key

Deletes or revokes an existing API key using the key_id. This is useful for deactivating an API key that is no longer needed, has expired, or is being replaced as part of a key rotation process.

DELETE /apikey/{key_id}

Response body

{
    "id": 400
}

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

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

Access Roles

Account advanced properties

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

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

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

Response body

{
    "feedId" : "feedId",
    "accountId": "accountId",
    "featureType": "feed",
    "title": "Feed Title",
    "avatar" : "avatarFileId",
    "posts": [
        {   
            "publishedOn": 1700562656,
            "editedOn": 1700562656,
            "dataComponent" : {
                "bucketId" : "bucketId",
                "dataComponentType" : "bucket"
            }
        }
    ]  
}

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

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

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",
    "options": {
        "silent": false
    },
    "dataComponent": {
        //Data component here
    } 
}

recipientId refers to the other accountId that is having a conversation with the current account.

options/silent is a boolean to allow sending the message without any in-app notification

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",
    "options": {
        "silent": false
    },
    "dataComponent": {
        //New data component here
    } 
}

options/silent is a boolean to allow updating the message without any in-app notification

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

Signal user typing in P2P Chat

This endpoint allows the calling user to let recipient know in advance that the user is going to publish a new message. This is particularly useful when having automated bots which need some time to elaborate the message to be sent.

HTTP REST

POST /communication/p2p/signal/typing

WebSocket

Send to /wsclient

{
  "requestId": "<randomCorrelationId>",
  "requestType": "/communication/p2p/signal/typing",
  "version": "2",
  "parameters" : {
       //parameters used in REST
   },
  "body" : {
       //request body used in REST
  }
}

Request body

{
    "recipientId": "recipientAccountId"
}

Response body

{}

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

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

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",
    "options": {
        "silent": false
    },
    "dataComponent": {
        //Data component here
    } 
}

groupChatId is the specific conversation Id to send the payload to

options/silent is a boolean to allow sending the message without any in-app notification

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",
    "options": {
        "silent": false
    },
    "dataComponent": {
        //Updated data component here
    } 
}

options/silent is a boolean to allow updating the message without any in-app notification

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

Signal user typing in Group Chat

This endpoint allows the calling user to let all group chat members know in advance that the user is going to publish a new message. This is particularly useful when having automated bots which need some time to elaborate the message to be sent.

HTTP REST

POST /communication/groupchat/signal/typing

WebSocket

Send to /wsclient

{
  "requestId": "<randomCorrelationId>",
  "requestType": "/communication/groupchat/signal/typing",
  "version": "2",
  "parameters" : {
       //parameters used in REST
   },
  "body" : {
       //request body used in REST
  }
}

Request body

{
    "groupChatId" : "myGroupChatId"
}

Response body

{}

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

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

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

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",
    "options": {
        "silent": false
    },
    "dataComponent": {
        //Data component here
    } 
}

channelId is the specific channel to send the payload to

options/silent is a boolean to allow sending the message without any in-app notification

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",
    "options": {
        "silent": false
    },
    "dataComponent": {
        //Updated data component here
    } 
}

options/silent is a boolean to allow updating the message without any in-app notification

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

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

LLM List

This endpoint lists the current llms (Large Language Models) for the calling subaccount. The caller subaccount is implicit, so only the llms pertaining to the caller subaccount will be returned.

HTTP REST

GET /service/llms

Request body

{}

Response body

{
    "llms": [
        {
            "id": "uuid_of_llm",
            "autoResponse": false
        }
    ] 
}

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