# &adminguide;

## Overview

This module provides a websocket client implementation to interact with external systems, similar to http client. It is not for routing SIP traffic.

It relies on libwebsockets library (https://libwebsockets.org/).

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- libwebsockets - probably v2.0 or newer.

## Parameters

### `protocol` (str)

The websocket sub-protocol.

Default value is "kmsg".

#### Set `protocol` parameter

    ...
    modparam("lwsc", "protocol", "ksr")
    ...

### `timeout_init` (int)

The interval in microseconds to wait for websocket connection to be initialized.

Default value is 2000000 (2 seconds).

#### Set `timeout_init` parameter

    ...
    modparam("lwsc", "timeout_init", 4000000)
    ...

### `timeout_read` (int)

The interval in microseconds to wait for the response of the lwsc_request() group of functions.

Default value is 2000000 (2 seconds).

#### Set `timeout_read` parameter

    ...
    modparam("lwsc", "timeout_init", 1000000)
    ...

### `verbosity` (int)

Control the verbosity of debug messages on libwebsockets events, higher value means more debug messages. It has to be a positive number, currently 2 or higher results in maximum verbosity.

Default value is 0.

#### Set `verbosity` parameter

    ...
    modparam("lwsc", "verbosity", 1)
    ...

## Functions

### `lwsc_notify(wsurl, data)`

Send data via websockets to the address specified by wsurl. No response is expected. Transmission is not guaranteed (e.g., cannot connect to target).

The parameters are:

- wsurl - websocket url

- data - what to send

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

#### `lwsc_notify` usage

    ...
        jwt_notify("ws://10.1.1.10:8080/log",
            "caller=$fU;callee=$tU;callid=$ci");
    ...

### `lwsc_notify_proto(wsurl, wsproto, data)`

Send data via websockets to the address specified by wsurl, providing websocket protocol. No response is expected. Transmission is not guaranteed (e.g., cannot connect to target).

The parameters are:

- wsurl - websocket url

- wsproto - websocket protocol

- data - what to send

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

#### `lwsc_notify_proto` usage

    ...
        jwt_notify_proto("ws://10.1.1.10:8080/log", "kmsg"
            "caller=$fU;callee=$tU;callid=$ci");
    ...

### `lwsc_request(wsurl, data)`

Send data via websockets to the address specified by wsurl, a response is expected and made available in $lwsc(rdata).

The parameters are:

- wsurl - websocket url

- data - what to send

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

#### `lwsc_request` usage

    ...
        jwt_request("ws://10.1.1.10:8080/log",
            "caller=$fU;callee=$tU;srcip=$si");
    ...

### `lwsc_request_proto(wsurl, wsproto, data)`

Send data via websockets to the address specified by wsurl, providing websocket protocol. A response is expected and made available in $lwsc(rdata).

The parameters are:

- wsurl - websocket url

- wsproto - websocket protocol

- data - what to send

The parameters can contain pseudo-variables.

This function can be used from ANY_ROUTE.

#### `lwsc_request_proto` usage

    ...
        jwt_request_proto("ws://10.1.1.10:8080/log", "kmsg",
            "caller=$fU;callee=$tU;srcip=$si");
    ...

## Variables

### `$lwsc(key)`

Get the values and attributes after using LWSC functions.

The key can be:

- rdata - the response retrieved after lwsc_request().

- status - the status of verification after a failed jwt_verify().

#### `$lwsc(name)` usage

    ...
      jwt_request("ws://10.1.1.10:8080/log",
            "caller=$fU;callee=$tU;srcip=$si");
      xinfo("jwt is: $lwsc(rdata)");
    ...