Graphileon Documentation Graphileon.com

For Dashboard Designers Reference WebSocket

Thursday, August 21, 2025 8:02 AM

WebSocket

Label: :IA_Function
Property: type: WebSocket
Inherits from: Function

The WebSocket function enables two-way interactive communication between Graphileon clients, facilitated by the Graphileon server. This allows for real-time data exchange without the need for clients to poll the server for updates. For more information on the underlying technology, you can refer to the official WebSocket documentation on MDN.

Core Concepts

The WebSocket function is built on top of the popular Socket.IO library, providing a reliable and efficient real-time communication layer.

Connection Details

  • Namespace: The client connects to the /websocket_function namespace on the Graphileon server.

Message Format

Internally, messages are transmitted with a specific format: channel#message. This is handled automatically by the function and you do not need to worry about this when sending or receiving messages.

Parameters

Key Description Default value Possible values Required
channel Name of the channel to connect. '' string Yes
broadcast Enables broadcasting to the channel. false boolean No
listen Enables listening on the channel. false boolean No
data Data to send to the channel. After the message is sent, this parameter is automatically cleared. null object No
message The message that you want to listen to or broadcast. After the message is sent, this parameter is automatically cleared. null string No
messagesToListen A list of messages to listen for from the server. Can be a single string, which will be automatically converted to an array. [] array or string No
messagesToBroadcast A list of messages to broadcast to the server. Can be a single string, which will be automatically converted to an array. [] array or string No

Outgoing triggers

Type: onReceive

Occurrence: When data is successfully received.

The onReceive trigger receives a data object with the following properties:

Key Description
origin The origin of the trigger, which is always 'websocket'.
channel The channel from which the message was received.
message The message that was received.
... The properties of the data object received with the message are destructured into the data object.

Example configuration

WebSocket function

This WebSocket example demonstrates handling a user joining or leaving with basic WebSocket functions. The function listens for userJoined, messageSend, userOnline, and userLeft messages from the WebSocket and also broadcasts the same messages (broadcasting is not required).

{
  "type": "WebSocket",
  "#messagesToBroadcast": "evaluate([\"userJoined\", \"messageSend\", \"userOnline\", \"userLeft\"])",
  "#messagesToListen": "evaluate([\"userJoined\", \"messageSend\", \"userOnline\", \"userLeft\"])",
  "$broadcast": "true",
  "$data": "",
  "$listen": "true",
  "$message": "",
  "_instance": "ChatWebSocket",
  "channel": "chatChannel",
  "name": "Chat WebSocket",
  "stayAlive": "dashboard"
}

onReceive trigger

This trigger updates the user list in the HTML view when a user leaves the chat. It should connect to the user list HTML view.

{
  "type": "onReceive",
  "#_update.remove.users": "evaluate([{id: (%).data.user.id}])",
  "$_instanceUpdateOnly": "true",
  "(%).data.message": "userLeft",
  "true": "evaluate(\r\n\t(%).data.user.name &&\r\n\t(%).data.user.name !== ''\r\n)"
}

onReceive trigger

This trigger sends a message to the channel to inform that a user has joined. It should connect to the WebSocket function itself.

{
  "type": "onReceive",
  "$data": "evaluate({\r\n   user:{\r\n\t  name: (@).user.name,\r\n\t  id: (@).user.id,\r\n\t  color: (@).user.chatColor\r\n   }\r\n})",
  "$message": "userOnline",
  "data.message": "userJoined",
  "true": "(%).data.user.id !== (@).user.id"
}

HtmlView user list

This view shows a list of users that are currently in the same channel. The list is updated in real-time as users join or leave the channel.

{
  "type": "HtmlView",
  "#users": "evaluate([])",
  "$area": "chatUsersArea",
  "_instance": "ChatUsersList",
  "name": "Users",
  "template": "<ul class=\"list-group\">\r\n  {{#users}}\r\n  <li style=\"color: {{color}};\">{{name}} \r\n\t{{#isMe}} (me){{/isMe}}\r\n\t<small>{{message}}</small>\r\n  </li>\r\n  {{/users}}\r\n</ul>"
}