1. Overview
  2. Connecting to Socket.IO
  3. The Pub/Sub Model
  4. Socket.IO Implementation

1 Overview

Socket.IO is a javascript library that uses the WebSocket protocol to facilitate real time communications. Avaya Spaces uses Socket.IO to implement messaging functionality. Every message sent (chat, task, or post) is broadcast as a Socket.IO event. See the tutorial for the step-by-step walkthrough of the connection process, or see the Socket.IO reference for full documentation.

Avaya Spaces uses version 2.0.4 of Socket.IO. Client applications should ensure their implementation of Socket.IO is compatible with version 2.0.4. You can obtain the JS script here by downloading the file or linking to a CDN.

We recommend the following Socket.IO client libraries:

2 Connecting to Socket.IO

Clients are authenticated via JWT or OAuth 2 token. The tokens are simply passed to Socket.IO as an argument of the IO.connect() function. An example Socket.IO connection request is shown below.

Must set websocket only in transports explicitly.

var socketio = io.connect(
    "wss://spacesapis-socket.avayacloud.com/chat",
    {query: 'tokenType=jwt&token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhbm9ueW1vdXNfaWQiOiI1NmRmMzk2MzY3NmU4Mjk0N2IyZjkyNDMiLCJwcm9kdWN0X3R5cGUiOiJvbmVzbmEiLCJpc3MiOlsiZXNuYSIsImNvbSJdLCJpYXQiOjE0NTc0Njk4MDAsImV4cCI6MTQ1NzU1NjIwMH0.can9AMXZuw9NGF1a-qQBxC87q8j4ov7taa86HxIDo9g',
     transports: ['websocket']}
});

URL:

For Production: wss://spacesapis-socket.avayacloud.com/chat
For Staging: wss://loganstagingapis-socket.esna.com/chat

Alternatively, using an OAuth 2 token:

var socketio = io.connect(
    "wss://spacesapis-socket.avayacloud.com/chat",
    {query: 'tokenType=oauth&token=f746696f5de4528u128ae2f274eea253e8a7943a',
    transports: ['websocket']}
});

Using service app JWT with credentials:

  • Activate the service app.
  • Add a new public/private key pair under the "Credentials" tab.
  • Click on the “Download Key” button.
    • Note: The downloaded file “service-key-f14f61d7f84347880427.json” contains the private key information needed to create the JWT. Once you used it in your code, you should delete the file as soon as possible because you can always download it again or generate new one if needed. For your protection, you should treat the file as password and don’t share with anyone who don’t need to know.
  • Create the JWT using the data from the downloaded json file and sign it using the private key included in the file.

The following is an example of downloaded service-key-f14f61d7f84347880427.json file:

{
  "iss": "66862e5f427b7cf325db", 
  "sub": "66862e5f427b7cf325db@psrsu9.servicesapps.spaces.avayacloud.com", 
  "kid": "f14f61d7f84347880427", 
  "private_key": "-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAzA/6J6IiJIH4e1HXFLdvw/YTeSvIjzzTkFyWeNtDDoC8fhhs
h56HkwRvX4CnEsB+ebiyQPf3bvvnqzVcJPVaei2mXbEaROpqaNEnRHWhEV3PcHFY
nEPbThYddEU9BmupSoxpESZU5R0GfaWfmGypZxbBhI2TkELE36t4ictIO86ajVSd\nhaAc32djbOUYvkEi9w3/o0fMPKY//z6DSTl92Cu09nnoZtAWnU3lL4HnTXYxv7
/he1evxAqIi4kvK+DcguHgOMPNzWepltqFu98M06dNx+joeuWjMtq0K7y2QHSk01
Y2aGHVOv8hNx9cgtYoSiBz2JWT1ZQ+TG3K+AM50CgYARQ/tqHBnaXD1vE1rueVG3
Xk6Mp8lab1znpdsgeTHkB7nKzoMEkoQxBytW+dh8/3nxfPQwgOozJJ1sAIja772B
IW10xTglL2f1lH7+5BgqLiGyf4bh7zKmW3xDC3gCekJrT4BrHc9lkEyCUJgj0tbz
9CndCLR70ymT6neMoe0VZQKBgGrrRYnKod5WNuYkmmvlMlvZFRu3tPt9tsrShC9a
+9GO2qpR1l5HcOJ3+y0XUzIA/Y+eBjU2GhtjWLS38Szjx7k526RvbVDFfMZR1dRz
UXkfwAQBw2wPLms0XMwudjPK/c4cgtTBEcuNCG4uN+2SBvr6/TOeXfkuO5DPkdcC
ztWRAoGAHN7cLV4ORtcdEIs4GAm0hgejIhNX7gaES0hR1h2C3gwKsvPPAkFkaiqs
fBv7sJKn0fZ7AVRYfUwJTvFDpVyrtuIFzy7jMTezDm6mKqBeK0C3R6AAsPubKqeS
WBoAlIdaQM5iOCuxtRe6YlpEUPMJfgtPVn/iTw+U2DdpuUrBzi0=
-----END RSA PRIVATE KEY-----"
}

The following is an example of service app JWT that you can create based on the downloaded JSON:

header:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "f14f61d7f84347880427"
}

payload:

{
"iss": " 66862e5f427b7cf325db",
"sub": " 66862e5f427b7cf325db@psrsu9.servicesapps.spaces.avayacloud.com",
"aud": "spaces.avayacloud.com",
"exp": 2631806787
}

The “exp” is the JWT expiry time. The maximum “exp” time you can set is 3600 seconds for security reasons. The JWT token will be rejected by Spaces server if the “exp” time is greater than 3600 seconds. The “exp” time should be in the Unix timestamp format. For testing, you can manually generate the “exp” time value using online tools such as https://www.unixtimestamp.com/.

After you created the “exp” value, you can sign the JWT with the private key included in the downloaded JSON file. For testing, you can use online tools such as https://dinochiesa.github.io/jwt/ to generate and signed JWT token.

3 The Pub/Sub Model

Avaya Spaces uses a modified Publisher-Subscriber (Pub/Sub) model to manage messages. When a Socket.IO connection joins a particular Avaya Cloud Space, it becomes both a publisher and subscriber to that space. It will be able to broadcast messages to others within the space, and will also receive messages from others broadcasting within the space. Upon leaving the space, it will no longer be able to do either. In a way, this closely mirrors the experience of a user sitting at a computer. They may have multiple Spaces open in different tabs, each of which can send and receive messages, but when they close a tab they won’t be able to send or receive messages anymore.

Note the critical distinction between users joining a Space and socket sessions joining a Space. Users can join or quit spaces through the Spaces GUI. When a socket session joins a Space, all it’s doing is establishing a socket connection with the Space for real time communications purposes.

4 Socket.IO Implementation

This Pub/Sub functionality is achieved by providing an additional layer of abstraction over Socket.IO. Avaya Spaces still uses the methods of Socket.IO, but adds authentication, authorization, and implements the model described above. Each Socket.IO room has a 1 to 1 correspondence to a Avaya Cloud Space. To join a space, the socket session must send a SUBSCRIBE_CHANNEL event, specifying the id of the Space they wish to join. Sending messages is easily accomplished with the SEND_MESSAGE event. It’s important to note that the Space ID must still be specified in the SEND_MESSAGE event, as a socket session may have joined multiple spaces at the same time. To leave a space, the session simply broadcasts an UNSUBSCRIBE_CHANNEL event.