Websocket Event-Manager Interface

You can also send and receive commands from the Freeswitch Adapter using the built in Websocket interface. To use it, simply follow the steps below.

Configuring your Event Manager

When you instantiate an imm_em_ws object, you provide a path to your websocket configuration file, imm_websocket_config.json. In this file, there are several parameter you can edit that will allow the server to work under your preferences and utilize your specific keys to ensure a secure connection.

{
    "port": 9002,
    "certificate_file": "none",
    "certificate_chain_file": "/usr/src/server.pem",
    "private_key_file": "/usr/src/server.pem",
    "rsa_private_key_file": "none",
    "tmp_dh_file": "/usr/src/dh.pem",
    "authentification_key": "Immersitech",
    "authentification_value": "I_am_valid_immersitech_please_accept_me"
}

There are 5 different options for certificates you can provide. You do not need to provide all or any of them, only the ones you want to use. If you do not want to use an option, just provide "none" in the field. The two authentication fields can be any key-value pair that you desire to require in your custom handshake header.

Connecting Your Client to Event Manager

In order to connect your client to event manager, you must follow a few steps. First you should use the standard websocket connection method of calling wss://example.com:8000 where you replace example.com with the IP address to your server and 8000 with the port number you used when calling run().

The event manager always utilizing TLS security, so ensure your provided keys are correct and match for the server and client.

In order for event manager to authorize any client, it requires that a special key is added to the websocket handshake header. This ensures the safety of all incoming connections. You will need to add the following to your header: "Immersitech": "I_am_valid_immersitech_please_accept_me".

At any given point while trying to establish a connection, watch your terminal on the server for helpful debugging messages.

Making a Request with Your Client

For a client to make a request, they must simply create a JSON message and pass it to the websocket server. Your JSON will need to include the following key-value pairs:

"Command": "string"

"room_id": "string"

"participant_id": "string"

"room_config_id": integer_number

"seat_index":  integer_number

"control_to_edit": integer_number

"value": integer_number

Note that not all the key-value pairs must be included, it depends on which command you are using. For example, if your command is get_version, you do not need any other key-value pairs besides "Command": "get_version".

Receiving a Response to Your Request

When the server receives your request, it will be processed and a JSON response with the following key-value pairs will be returned to you:

"Status": "string - either OK or ERROR. OK indicates a success while ERROR indicates a failure to fulfill request"

"Error": "string - a description of what went wrong if there was an error"

"Request": JSON - the JSON object that was originally requested

"value": string / int - additional information you requested, such as get participant state

Note that if you receive "Status": "OK", then you will not see a key-value pair for "Error" in your response JSON. Additionally, you will only receive "Value" or other key-value pairs if your original request was asking for a value.

Receiving an Event from the Host

Sometimes a host program may perform actions with the request of a client. In this case, the server will want to keep the client up to date by sending a message to the client about an event that occurred. If an event occurred, you will see a JSON formatted message with the following key-value pairs:

"Event": "string - describing what event occurred"

"values": "string / integer_value - providing additional information about the event"

v3