Messaging
The Cloudonix API.Messaging services offer subscriber-to-subscriber message delivery and (in the future) indirect data streams.
WebSocket API
The Cloudonix API.Messaging service exposes a WebSocket protocol for interactive messaging applications (the service is SockJS compatible, so supports a wide range of implementations).
Each client connection must be authorized using a bearer token[^1] received by authenticating with the API.Core subscriber authorization service. Once a subscriber application retrieves an authorization token, they can connect to the API.Messaging WebSocket protocol. If the bearer token is invalidated at any point, all existing connections authorized by that token will be dropped and further connections will be rejected with HTTP error 401 (“Unauthorized”). If the subscriber authentication has not been invalidated, the application should retrieve a new bearer token and try to reconnect with the new token.
Message Format
Each protocol message is a JSON formatted object[^2] which must include a field named type containing the type of the message as a string and additional fields as detailed in the specific message specification as detailed below.
Message can be either “client messages” - i.e. messages sent from the client to the server, or “server message” - i.e. messages sent from the server to the client. Some client messages require a specific server message as a response, in which case the server must reply with the specified message before sending any unsolicited messages to the client.
The server shall ignore messages that are either not formatted correctly or use an unsupported type parameter.
Client Message Fields
In addition to the standard field type, client messages can have an optional “id” string field that specifies the transaction identifier. When the server receives a message with an id field, all messages sent in response to that client message will also reproduce the same string value of the client message id field in the server messages reply-to field.
Server Message Fields
In addition to the standard field type, server messages can have an optional reply-to field that specifies the value of client transaction they are in reply to.
Models
Channel Subscriber
Server messages may provide information about subscribers in a channel, using this model object.
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
id | String | Identity of the subscriber whose availability is reported |
status | String | The subscriber's status text |
availability | String | One of the valid subscriber availability statuses prescribed in the protocol |
administrator | true/false | Whether the listed subscriber has administrator rights |
attributes | Object | List of metadata properties for the subscriber |
Channel Membership
Server messages may provide information about the current subscriber's channel membership status using this model object.
Fields:
| Field Name | JSON Type | Description |
|---|---|---|
channel-id | String | Channel identification of the channel |
name | String | Description of the channel to show to subscribers |
administrator | true/false | Whether the subscriber is a channel administrator or not |
Notes
- See RFC 6750
- See RFC 7159 section 4