WebSockets (Socket.IO)

🔔 Connect your scenarios and web-app in real-time

What is WebSocket

The WebSocket API, built on socket.io technology, is an advanced feature that makes it possible to open a two-way interactive communication session between a user's browser and a server. Through this API, you can send messages to the server and receive event-driven responses, all without the need to continuously poll the server for replies.

How to Add WebSockets to Your App:

1) Select the app you want to add a WebSocket to

2) Go to the Plugins section and install the Socket.io plugin.

Where Can You Use WebSocket API (Socket.IO)?

If you use Directual web-page builder:

• Refresh the page (e.g. update the content after submitting the form — that is an alternative to synchronous scenarios)

• Alert users with Toast notifications

• Redirect user

If you use external front-end (e.g., ReactJS):

• Receive signals about changes in systems and refresh data instantly

• Build interactive messengers 💬

• Build scenarios with messages for specific users (alerts, notifications and etc.).

How to Use Sockets for user notifications

1. Create a scenario that calls socket plugin (send PUSH-message step)

2. Set "Event name" to alert

3. Configure your message.

There are two options for configuring the message: simple and complex.

Simple notification:

Complex notification (with notification settings like page to display on, position, duration, etc.)

Notifications are based on React-hot-toast. Find the full list of parameters here

Example of a message:

{
    "message": "Hello world! My name is {{name}}",
    "parameters": {
      "position": "top-right",
      "duration": 4000,
      "icon": "🇷🇺"
    }
}

// if you want to send push to the certain page (or a few, comma separated) and its subpages (my-home-page)
{
    "message": "Hello world! My name is {{name}}",
    "page": "my-home-page,profile",
    "parameters": {
      "position": "top-right",
      "duration": 4000,
      "icon": "🇷🇺"
    }
}

Message in the app:

How to Use Sockets for redirecting user

1. Create a scenario that calls socket plugin (send PUSH-message step)

2. Set "Event name" to redirect

3. Configure redirect details in message field:

{
   "target": "/my-page",
   "delay": 200
}

// or optioannly with indicating page/pages (comma separated)

{
   "target": "<=",
   "page": "my-home-page,profile",
   "delay": 200
}

A redirection will occur based on our routing rules. The rules for redirection are as follows:

• <= – navigate back in history

• ../ – move up in the directory

• ../../ – move up two levels, and so on

• ./param – append a parameter to the right in the URL.

How to Use Sockets in Web-page Builder as a refresher

1. Create a scenario that calls socket plugin (send PUSH-message step)

2. Add a refresher to the page (if needed)

The Refresher web-plugin (indicate the event_name):

Scenario with the same event_name:

In this case scenario triggers on Changed objects

• Message: no need here (although you can combine refresher and user notifications)

• Event name: the same event_name

• UserID: set * if you want to broadcast the message. set user's ID if you want to send a message to a certain user.

Here is how it works:

How to Use WebSockets in React Apps

You can find an example template with Socket.IO support in Directual and React JS section.

1. Clone the repo

2. Copy your Directual APP ID into .env file

3. Create a user and log in (for example, the user's ID is testUser)

4. Go to WebSocket Page

5. Create a scenario, add Send PUSH-message step (it is a part of Socket.io plugin):

Configuring the step:

• UserID: set * if you want to broadcast the message. set user's ID if you want to send a message to a certain user (in our case — testUser)

• Event name: the first parameter of socket event (eventName)

• Message: the second parameter of socket event (args)

Have a look at the boilerplate, websocket.js:

//subscribe to any events
socket.onAny((eventName, args) => {
        setMessage(<div>{`${eventName}: ${JSON.stringify(args)}`} &nbsp;<code>{(new Date()).toISOString()}</code></div>);
});

//subscribe to only 'message' events (the 'Event name' parameter)
socket.on('message', (msg) => {
    setMessage(<div>{msg} &nbsp;<code>{(new Date()).toISOString()}</code></div>);
})

Here is how it works (we send objects to the scenario, the web-page is refreshed without reload):

How to Use WebSocket API in Any Apps

You can use any WebSocket API (Socket.IO) client in any app.

Directual offers a standard endpoint for connection to WebSockets: https://api.directual.com

You can see how to connect and receive messages from the Platform in the code below:

import io from 'socket.io-client';

// autoConnect set to false, 
// because before we must get session_id for auth users
const socket = io('https://api.directual.com', {autoConnect: false})

var sessionID = ? // you'll get sessioID when authorise your user
var appID = ? // you could get appID in API section
//login users process...

socket.auth = {app_id: appID, session_id: sessionID};
socket.connect();

//subscribe to any events
socket.onAny((eventName, args) => {
   console.log(`${eventName}: ${JSON.stringify(args)}`);
});

//subscribe to only 'message' events
socket.on('message', (msg) => {
   console.log(msg);
})