Skip to main content

# IWebSocket

Scripting object for WebSocket communication with the server.

The microapp host implements this interface and guest microapps use it to subscribe/unsubscribe to server-side events delivered over WebSocket.

See WebSocketEvents for supported events

## Extends​

- `IScriptingObject`

## Methods​

### _dispose()?​

    optional _dispose(): void;

#### Returns​

`void`

#### Inherited from​

`IScriptingObject`.`_dispose`

### _toJSON()​

    _toJSON(): RemotingScriptingObject;

#### Returns​

`RemotingScriptingObject`

#### Inherited from​

`IScriptingObject`.`_toJSON`

### subscribe()​

    subscribe(options: SubscribeOptions): Promise<SubscribeResult>;

Subscribe to a WebSocket resource event.

Sends a subscribe command to the WebSocket server for the specified resource. Either `resourceId` or `filter` must be provided in the options.

On success, returns a SubscribeResult containing the `subscriptionId`. If a matching subscription is already active, the existing `subscriptionId` is returned. The `subscriptionId` is used to correlate incoming event messages and to unsubscribe.

#### Parameters​

##### options​

`SubscribeOptions`

subscription options including resource name, optional resourceId or filter

#### Returns​

`Promise`<`SubscribeResult`>

subscription result containing the unique subscriptionId

#### Throws​

error if the resource is unknown or filter/resourceId is invalid

#### Examples​

subscribe by resourceId

    const result = await websocket.subscribe({
      resource: 'serviceOrder',
      resourceId: '1e65313c-db09-496c-85ba-bb0758623f93'
    });
    console.log('Subscribed with id:', result.subscriptionId);

subscribe by filter

    const result = await websocket.subscribe({
      resource: 'serviceOrder',
      filter: { loanId: ['lo7ee116-ec80-4dbf-b387-14606d0e4807'] }
    });
    console.log('Subscribed with id:', result.subscriptionId);

### unsubscribe()​

    unsubscribe(subscriptionId: string): Promise<void>;

Unsubscribe from an active WebSocket subscription.

Sends an unsubscribe command to the WebSocket server for the given subscriptionId. After unsubscribing, no further event messages will be received for this subscription.

#### Parameters​

##### subscriptionId​

`string`

unique identifier of the subscription to cancel

#### Returns​

`Promise`<`void`>

#### Throws​

error if the subscriptionId does not exist

#### Example​

    await websocket.unsubscribe('4fa1ad8a-0ffa-46b5-8871-9b4b4cbf2eb3');

## Properties​

### id​

    readonly id: string;

#### Inherited from​

`IScriptingObject`.`id`

### Message​

    readonly Message: IEvent;

Event fired when a WebSocket message is received for an active subscription.

Use WebSocketMessageListener to handle this event

#### Examples​

with v2 SSF

    guest.subscribe({
      eventId: 'websocket.message',
      callback: ({ eventParams }) => {
        console.log('Received event for subscription', eventParams.subscriptionId);
        console.log('Resource:', eventParams.resource);
        console.log('Payload:', eventParams.payload);
      }
    });

with v1 SSF

    elli.script.subscribe('websocket', 'message', ({ eventParams }) => {
      console.log('Received event for subscription', eventParams.subscriptionId);
      console.log('Resource:', eventParams.resource);
      console.log('Payload:', eventParams.payload);
    });

### objectType​

    readonly objectType: string;

#### Inherited from​

`IScriptingObject`.`objectType`