Skip to content

RealTime API

Real-time API

Channels

Simplified example of a real-time change message for an added resource

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "channel": "/api/v5/orgs/d5516bd8-c5f7-4e8b-86c3-0cdcb21df559/users",
  "action": "added",
  "resource_id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
  "resource": {
    "id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
    "email": "john.smith@example.com",
    "organization_id": "d5516bd8-c5f7-4e8b-86c3-0cdcb21df559",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "is_manager": false,
    "is_staff": false,
    "created_at": "2017-08-03T13:45:00.123Z",
    "updated_at": "2017-10-24T07:03:00.123Z",
    "is_online_enabled": true,
    "is_online": true,
    "is_present": true,
    "current_chat_count": 3,
    "is_deleted": false
  }
}

Example of a real-time change message for an updated resource

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "channel": "/api/v5/orgs/d5516bd8-c5f7-4e8b-86c3-0cdcb21df559/users",
  "action": "changed",
  "resource_id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
  "resource": {
    "id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
    "is_online": false,
    "is_present": false
  }
}

Example of a real-time change message for a removed resource

1
2
3
4
5
{
  "channel": "/api/v5/orgs/d5516bd8-c5f7-4e8b-86c3-0cdcb21df559/users",
  "action": "removed",
  "resource_id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670"
}

Giosg uses a concept called channels to deliver real-time changes to resources and collections.

Simply put:

The channel for listening real-time changes for a resource/collection, is the path of the related API endpoint URL. Therefore you can use the HTTP API reference documentation as a catalog for the real-time channels.

The channel always starts with a trailing slash and never ends with a trailing slash. The channel does not include any URL query parameters, such as filtering or ordering criteria.

Here are examples of real-time channels for some resources and collections:

Resource/collection Channel
An organization resource with an ID f9a3c249-736e-4361-b2f5-0e48a1e5795c /api/v5/orgs/f9a3c249-736e-4361-b2f5-0e48a1e5795c
User resources of an organization with an ID f9a3c249-736e-4361-b2f5-0e48a1e5795c /api/v5/orgs/f9a3c249-736e-4361-b2f5-0e48a1e5795c/users
Chats of a user with an ID 4f63a5bd-7f9b-42ce-8764-965f30806534 /api/v5/users/4f63a5bd-7f9b-42ce-8764-965f30806534/chats

The real-time channels are broadcasted with change messages. It can be one of the three (3) different actions:

Action Description Example
added A new resource was added to the collection. A new user is added to an organization, or a new chat message is sent to a user's chat.
changed Attributes of an existing resource in a collection is updated. A user changes from offline to online state.
removed A resource was removed from the collection. A team member is removed from a team.

The change messages are re-presented as JSON objects with the following attributes:

Attribute Description
channel URL path of the API endpoint of the resource/collection
action What kind of change it is: added, changed or removed
resource_id Identifier for the resource that was changed (usually the id attribute)
resource If the action is added, this is the whole added resource object with all of its attributes. If changed, then this is the object containing only the updated resource attributes. If the action is removed, then this attribute does not exist.

WebSocket API

Warning

NOT YET AVAILABLE! This feature is currently in internal testing. The documentation described below is yet partially a draft and may change without prior warning.

You can listen real-time channels from a web browser client or from a server by using the WebSocket API.

Giosg has a service called message router server that allows WebSocket connections to subscribe to any channels.

Connecting WebSocket

Warning

In order to connect the WebSocket, your clients first needs to authenticate with a HTTP request. A guide can be found here.

When you have the access token, then create a WebSocket connection to the following URL:

1
wss://messagerouter.giosg.com/websocket?token=<TOKEN>

You need to replace the <TOKEN> with your access token.

The message router won't accept the connection if the token is missing, is invalid, or has expired or revoked.

WebSocket message protocol

When the client has successfully connected to the message router, the client can start sending messages.

The message format and protocol is similar to JSON-RPC.

All the messages must be valid JSON objects, and their content depends of their type and the intended action. There are three (3) types of messages:

WebSocket requests

The format of WebSocket requests

1
2
3
4
5
6
7
8
9
{
  "method": "<METHOD>",
  "params": {
    "param1": "<VALUE 1>",
    "param2": "<VALUE 2>",
    "paramN": "<VALUE N>"
  },
  "id": "<REQUEST_ID>"
}

A client can send a request to the message router. The message JSON object must contain the following attributes:

Attribute Description
method A string with the name of the method to be invoked. E.g. sub, unsub or ping. See the following sections for supported methods.
params An object containing parameters how the methods should be invoked. This can be omitted if the method does not expect any parameters, e.g. when the method is ping.
id Identifier for the request. This can be any string or number. It is recommended that this is unique during a connection. The client uses this to recognize the response to this request.

WebSocket responses

The format of a successful WebSocket response

1
2
3
4
5
6
7
8
{
  "result": {
    "key1": "<KEY 1>",
    "key2": "<KEY 2>",
    "keyN": "<KEY N>"
  },
  "id": "<REQUEST_ID>"
}

The format of a failed WebSocket response

1
2
3
4
{
  "error": "<ERROR_CODE>",
  "id": "<REQUEST_ID>"
}

For each request sent to the message router, the message router will send back a response message.

The response can be either successful or it can be a failure. A successful response contains the following two (2) attributes:

Attribute Description
id Equals the id attribute of the related request.
result Details for the result of the invoked method. In some cases, this may be omitted, if the message router just acknowledges a successful request.

If the request results in an error, then the response contains the following two (2) attributes:

Attribute Description
id Equals the id attribute of the related request.
error An error code (string) describing the reason why the request failed.

Whenever the WebSocket client receives the response from the message router, they should check if the message object contains a defined and non-null error. If it does, then the request matching the id should be considered failed. If not, then it should be considered successful with the result.

NOTE: In cases where no result is expected and the response object contains just the id, the response must be considered succesful, because it contains no error attribute.

WebSocket notifications

The format of a WebSocket notification

1
2
3
4
5
6
7
8
{
  "method": "<METHOD>",
  "params": {
    "param1": "<VALUE 1>",
    "param2": "<VALUE 2>",
    "paramN": "<VALUE N>"
  }
}

WebSocket notifications are just requests that do not expect a response from the message router. They are otherwise equal to requests, but they are missing the id attribute.

The message router will never send a response to a notification, even if the invoked method fails. If you want to know if the method is successful or not, use requests instead.

Similarly, clients are not expected to send responses to notifications sent by a server.

Ping/pong

Example of a ping request:

1
2
3
4
{
  "method": "ping",
  "id": 123
}

Example of a response to a ping request:

1
2
3
{
  "id": 123
}

The client may send a ping request to the messu server to check if the connection is still alive. No params are required.

The message router will respond to the request immediately. The response does not contain the result attribute.

IMPORTANT: The server may also send a ping request to the client! The client must then also immediately respond with an empty response. Otherwise the message router may close the connection.

Subscribing to channels

Example of a channel subscription request:

1
2
3
4
5
6
7
8
{
  "method": "sub",
  "params": {
    "channel": "/api/v5/users/ef6ef6e8-9e35-11e7-9dab-6c4008c08dfe/chats",
    "token": "xxxxxxxxx.yyyyyyyyyy.zzzzzzzzz"
  },
  "id": 123
}

Example of a response to a successful subscription:

1
2
3
{
  "id": 123
}

Example of a response to a failed subscription:

1
2
3
4
{
  "id": 123,
  "error": "ChannelForbidden"
}

The core functionality of the message router is the ability to subscribe real-time channels for the changes to resources and collections. The subscription to a real-time channel is done with a sub request.

The request must contain the following params:

  • channel: The resource/collection channel to subscribe
  • token: A valid token which is used to authorize the subscription

If the channel and the token is valid, then the message router responds with an empy response (missing the result attribute).

The message router will respond with an error code

  • InvalidToken if the provided token is invalid
  • ChannelForbidden if the token was valid but did not allow subscribing the given channel

Info

IMPORTANT! The subscription only exists while the connection is alive! If the connection is closed for any reason, the client must create a new connection and re-send the sub requests for each channel they are still interested in!

Unsubscribing from channels

Example of a channel unsubscription

1
2
3
4
5
6
7
{
  "method": "unsub",
  "params": {
    "channel": "/api/v5/users/ef6ef6e8-9e35-11e7-9dab-6c4008c08dfe/chats"
  },
  "id": 123
}

The client may and should unsubscribe from any channels they are no more interested in by sending an unsub message.

The request must contain the following params:

  • channel: The resource/collection channel that was previously subscribed

No token is required in this case. This can also be send as a notification by omitting the id attribute, in which case the message router does not send a response.

Channel change notifications

Simplified example of a change notification for an added resource

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "method": "change",
  "params": {
    "channel": "/api/v5/orgs/d5516bd8-c5f7-4e8b-86c3-0cdcb21df559/users",
    "action": "added",
    "resource_id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
    "resource": {
      "id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
      "email": "john.smith@example.com",
      "organization_id": "d5516bd8-c5f7-4e8b-86c3-0cdcb21df559",
      "first_name": "John",
      "last_name": "Smith",
      "full_name": "John Smith",
      "is_manager": false,
      "is_staff": false,
      "created_at": "2017-08-03T13:45:00.123Z",
      "updated_at": "2017-10-24T07:03:00.123Z",
      "is_online_enabled": true,
      "is_online": true,
      "is_present": true,
      "current_chat_count": 3,
      "is_deleted": false
    }
  }
}

Example of a change message notification for an updated resource

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "method": "change",
  "params": {
    "channel": "/api/v5/orgs/d5516bd8-c5f7-4e8b-86c3-0cdcb21df559/users",
    "action": "changed",
    "resource_id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
    "resource": {
      "id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670",
      "is_online": false,
      "is_present": false
    }
  }
}

Example of a change message notification for a removed resource

1
2
3
4
5
6
7
8
{
  "method": "change",
  "params": {
    "channel": "/api/v5/orgs/d5516bd8-c5f7-4e8b-86c3-0cdcb21df559/users",
    "action": "removed",
    "resource_id": "6c85a961-c9fd-4ea2-8c91-36cd0eb49670"
  }
}

After a client has a channel with a sub request, the message router starts delivering change notifications to the channel.

The params attribute contains an a change object as described in the Channels section.