# WebSockets (Socket.IO)
What is WebSocket
The **WebSocket API,** built on [socket.io](https://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](https://readme.directual.com/web-pages/portal):
* Refresh the page (e.g. update the content after submitting the form — that is an alternative to [synchronous scenarios](https://readme.directual.com/scenarios/synchronic-scenarios-1))
* Alert users with Toast notifications
* Redirect user
If you use external front-end (e.g., [ReactJS](https://readme.directual.com/directual-react-js/boilerplate-for-react-js)):
* 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](https://react-hot-toast.com/). Find the full list of parameters [here](https://react-hot-toast.com/docs/toast)
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](https://readme.directual.com/directual-react-js/boilerplate-for-react-js) section.
1. [Clone the repo](https://github.com/directual/directual-react-boilerplate#step-1-cloning-directual-react-boilerplate-repo)
2. [Copy your Directual APP ID into .env file](https://github.com/directual/directual-react-boilerplate#step-2-copying-your-directual-app-id-into-env-file)
3. [Create a user and log in](https://github.com/directual/directual-react-boilerplate#step-3-testing-authentication) (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](https://github.com/directual/directual-react-boilerplate/blob/master/src/pages/Websocket.js):
```javascript
//subscribe to any events
socket.onAny((eventName, args) => {
setMessage(
);
});
//subscribe to only 'message' events (the 'Event name' parameter)
socket.on('message', (msg) => {
setMessage(
{msg} {(new Date()).toISOString()}
);
})
```
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:
You can see how to connect and receive messages from the Platform in the code below:
```javascript
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);
})
```
