# WebSocket Server

This exposes a local WebSocket server that allows communication between your web app running in a browser, and your desktop app.

You generally will only have one client (the browser tab) but if multiple tabs are open and requesting a connection, you'll need to handle multiple connections.\
\
Example code in the browser:

{% code overflow="wrap" %}

```javascript
const socket = new WebSocket('wss://local.deskifier.com:50050?token=YOUR_SECURE_KEY'); // Replace 50050 with the actual port your server is using

socket.onopen = () => {
  console.log('Connected to WebSocket server');
};

socket.onmessage = (event) => {
  console.log('Message from app:', event.data);
};

// Event: Connection closed
socket.onclose = () => {
  console.log('WebSocket connection closed');
};

socket.send('Hello from the browser!');
```

{% endcode %}

Use this URL as your connection string

```
wss://local.deskifier.com
```

This URL will resolve to 127.0.0.1

## Methods

### <mark style="color:purple;">Start Server</mark>

Attempts to start a WebSocket server on one of the given ports.

{% hint style="danger" %}
Security Warning:\
\
When enabled, the WebSocket server opens a port that **any reachable webpage or application can connect to** (including browsers, local apps, and possibly other devices on your network).

**All incoming requests should be treated as untrusted.** You should validate and authorize messages before using them.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.webSocket.startServer({ arguments })
```

**Arguments**

* `possiblePorts` <mark style="color:green;">Array Of Numbers</mark> (Required)\
  This will start a WebSocket server on the **first available** port.
* `token` <mark style="color:green;">String</mark> (Required)\
  Your provided security token, used to validate clients before allowing a connection.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `port` <mark style="color:green;">Number</mark>\
  The port used.

**Example**

{% code overflow="wrap" %}

```javascript
const result = await window.deskifier.webSocket.startServer({ 
    possiblePorts: [50050, 50060],
    token: "YOUR_SECURE_KEY" 
});

console.log(result.port) //50050
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Stop Server</mark>

Stops the running WebSocket server.<br>

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.webSocket.stopServer()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Broadcast Message</mark>

Sends a message to all connected clients.<br>

{% hint style="info" %}
This will not return an error if one of the clients aren't able to receive the message. If you want to ensure deliverability, use the Send Message method.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.webSocket.broadcast({ arguments })
```

**Arguments**

* `message` <mark style="color:green;">String</mark>\
  The message to broadcast.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Send Message</mark>

Sends a message to a specific client.<br>

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.webSocket.send({ arguments })
```

**Arguments**

* `clientId` <mark style="color:green;">String</mark>\
  The client to send the message to.
* `message` <mark style="color:green;">String</mark>\
  The message to send.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

## Properties

### <mark style="color:purple;">Get Server</mark>

Retrieves the running server details (if any)<br>

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.webSocket.getServer()
```

**Returns**

* `isRunning` <mark style="color:green;">Boolean</mark>\
  If the server is currently running.
* `clientIds` <mark style="color:green;">Array Of Strings</mark>\
  A list of connected client ids.
* `port` <mark style="color:green;">Number</mark>\
  The port the server is currently running on (null if not running)
  {% endtab %}
  {% endtabs %}

***

## Events

### <mark style="color:purple;">Client Connected</mark>

Fires when a client connects.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.webSocket.onClientConnected((data) => { })
```

**Arguments**

* `id` <mark style="color:green;">String</mark>\
  The ID of the client.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Client Disconnected</mark>

Fires when a client disconnects either gracefully or unexpectedly.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.webSocket.onClientDisconnected((data) => { })
```

**Arguments**

* `id` <mark style="color:green;">String</mark>\
  The ID of the client.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Web Socket Message</mark>

Fires when a client sends a message to the server.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.webSocket.onMessage((data) => { })
```

**Arguments**

* `id` <mark style="color:green;">String</mark>\
  The ID of the client.
* `content` <mark style="color:green;">String</mark>\
  The message content.
  {% endtab %}
  {% endtabs %}

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://deskifier.gitbook.io/deskifier/websocket-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.