---
schema_version: "1"
id: f45ea987e1e9df7200a0eaa91bc75757ae12e6af94303550f57b3e1e46d68d1f
title: WebSockets Connector Configuration
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/websockets-connector/latest/websockets-connector-config-topics.md
canonical_url: https://docs.mulesoft.com/websockets-connector/latest/websockets-connector-config-topics
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 86dd127aab21c4fb3d31bf8cc7e9a60917d8721ed80e3fb0005284554cedf20f
description: MuleSoft Documentation Site
release: "1.0"
latest: true
---
---
product: WebSockets Connector
version: 1.0
is-latest-version: true
---

# WebSockets Connector Configuration

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

If your app exposes a WebSockets inbound endpoint, you need to set that up using the
`<ws:server-settings>` element.

Because WebSockets connections are initiated with an HTTP Request, exposing a WebSockets inbound
endpoint requires pointing to an underlying HTTP listener configuration. This not only allows you to
reuse all the available features and configurations of an HTTP listener (such as host, port, TLS,
etc.), it also allows your app to expose both WebSockets and regular HTTP endpoints using the same
port.

Using the HTTP listener configuration, you can specify base connection settings like a host, port,
base path, or you can use it to configure a TLS based connection (WSS).

```xml
<http:listener-config name="httpListenerConfig" basePath="/regularHttp">
   <http:listener-connection host="0.0.0.0" port="80" />
</http:listener-config>

<websocket:config name="wsServer">
    <websocket:connection>
       <websocket:server-settings listenerConfig="httpListenerConfig" listenerBasePath="/ws"/>
    </websocket:connection>
</websocket:config>

<flow name="chat">
    <websocket:inbound-listener path="/chat" config-ref="wsServer"/>
    <logger level="INFO" message="A new message has been received! #[payload]"/>
</flow>
```

Notice the WebSockets server settings reference the HTTP listener configuration in the
`listenerConfig` attribute. In this example, the WebSockets inbound listener listens for incoming
messages on `localhost` and port 80, which are set in the HTTP listener configuration. This also
sets basePath to `/ws` to override the HTTP basePath setting in the WebSockets configuration. To sum
up, the WebSockets inbound listener listens for incoming messages at `ws://localhost:80/ws/chat`.

Because the HTTP listener does not have a reference to a TLS configuration component, the connection
opens by default using the WS protocol.

## Configure Server Timeouts

WebSockets connections are persistent and stateful. Therefore, it’s a good practice to set a timeout
to automatically close connections that have been idle.

The following example shows how to use the `<websocket:server-settings>` to configure a 1-hour idle
sockets timeout:

```xml
<http:listener-config name="httpListenerConfig" basePath="/regularHttp">
   <http:listener-connection host="0.0.0.0" port="80" />
</http:listener-config>

<websocket:config name="wsServer">
    <websocket:connection>
       <websocket:server-settings
         listenerConfig="httpListenerConfig"
         listenerBasePath="/ws"
         idleSocketTimeout="1"
         idleSocketTimeoutUnit="HOURS">
    </websocket:connection>
</websocket:config>
```

By default, all inbound sockets have an idle timeout of 15 minutes.

## Configure WebSockets Client

If your application needs to connect to external WebSockets services, provide the client settings
element:

```xml
<websocket:config name="wsClient">
    <websocket:connection>
       <websocket:client-settings
         host="localhost"
         port="80"
         basePath="/ws" />
    </websocket:connection>
</websocket:config>

<flow="connectToWebSocketFlow">
    <websocket:open-outbound-socket
      path="/chat"
      socketId="myCustomWebSocketID-123"
      config-ref="wsClient" />
    </websocket:open-outbound-socket>

    <logger info="INFO" message="Opened connection to external service!"/>
</flow>
```

In this example we have initialized an outbound socket which references the WebSockets client
configuration ("wsClient") in the config-ref attribute. In this case, there is no need to reference
an HTTP configuration.

In the configuration above, a `host`, `port`, and `basePath` are specified to build the WS request
URI. The `host` parameter is optional; if not set it is set to `localhost`.

The `port` parameter is optional; if not specified the default value is set according to the
protocol scheme. If WS is used, the default value is set to `80`. If WSS is used, the default is set
to `443`.

The `basePath` parameter is optional; if the URI is not set, it indicates the base path for all
client requests relative to the indicated host and port. If the `basePath` parameter is not set, the
default value is set to `/`.

You can also specify a URL:

```xml
<websocket:config name="wsClient">
    <websocket:connection>
       <websocket:client-settings uri="ws://www.mulesoft.com" />
    </websocket:connection>
</websocket:config>
```

However, in this case a path cannot be indicated because the `URL` and `path` parameters are
mutually exclusive. This is because URL indicates a full resource locator, while the path indicates
a path relative to the host, port, and basePath.

## Default Parameters and Headers

You can specify default headers and default query parameters in your client configuration to include
in the connection request message.

```xml
<websocket:config name="wsClient">
    <websocket:connection>
       <websocket:client-settings host="localhost" port="${listenerPort}" basePath="/ws">
           <websocket:default-headers>
                <websocket:header key="myFirstDefaultHeader" value="defaultHeader1" />
                <websocket:header key="mySecondDefaultHeader" value="defaultHeader2" />
            </websocket:default-headers>
            <websocket:default-query-params>
                <websocket:query-param key="myFirstDefaultQueryParam" value="query1" />
                <websocket:query-param key="mySecondDefaultQueryParam" value="query2" />
            </websocket:default-query-params>
       </websocket:client-settings>
    </websocket:connection>
</websocket:config>
```

You can also add headers or query parameters to your connect operation, which are sent along with
the default headers and parameters in the request to establish a connection:

```xml
<flow="connectToWebSocketFlow">
    <websocket:open-outbound-socket path="/chat" config-ref="wsClient">
            <websocket:headers><![CDATA[
                    #[
                        {
                            chatAlias: 'Captain Marvel'
                        }
                    ]
                ]]>
            </websocket:headers>
            <websocket:query-params><![CDATA[
                    #[
                        {
                            theme: 'USA'
                        }
                    ]
                ]]>
            </websocket:query-params>
    </websocket:open-outbound-socket>
</flow>
```

## Configure Client Timeouts

Just like for inbound connections, it’s a good practice to set a timeout to automatically close idle
outbound connections.

The following example shows how to use the `<websocket:client-settings>` to configure a 1-hour idle
sockets timeout:

```xml
<websocket:config name="wsServer">
    <websocket:connection>
       <websocket:client-settings
         host="localhost"
         port="${listenerPort}"
         basePath="/ws"
         connectionIdleTimeout="1"
         connectionIdleTimeoutUnit="HOURS" />
    </websocket:connection>
</websocket:config>
```

By default, outbound sockets have no idle timeout. However, the remote service they connect to is
likely to have one.

### Combined Configuration

If your app is doing both listening for incoming connections and issuing requests to external
services, you can configure server and client together:

```xml
<http:listener-config
   name="httpListenerConfig"
   basePath="/willBeOverriddenByWSConfig">
   <http:listener-connection host="0.0.0.0" port="${listenerPort}" />
</http:listener-config>

<websocket:config name="ws">
    <websocket:connection>
       <websocket:server-settings
         listenerConfig="httpListenerConfig"
         listenerBasePath="/ws" />
       <websocket:client-settings
         host="localhost"
         port="80"
         basePath="/ws" />
    </websocket:connection>
</websocket:config>
```

This configuration can be referenced from both inbound and outbound sockets.

```xml
<flow="acceptIncomingMessagesFlow">
    <websocket:inbound-listener path="/quotes" config-ref="ws" />
    <logger info="INFO" message="I listen for incoming messages at '/quotes'!"/>
</flow>

<flow="connectToWebSocketFlow">
    <websocket:open-outbound-socket path="/chat" config-ref="ws"/>
    <logger
      info="INFO"
      message="Open a connection to an external service listening at path '/chat'!"/>
</flow>
```

### TLS Configuration

TLS (Transport Layer Security) allows for client and server apps to communicate through a secure
channel and prevent attackers from eavesdropping or tampering with the transmitted data.

In the case of the WebSockets server, TLS configuration is inherited from the referenced HTTP
listener configuration, for example, to configure TLS on a WebSockets listener, point to
`<http:listener-config>` with TLS configured.

You first need to set up your truststore if your application connects to external services, or a
keystore if your application listens for incoming connections, or you can set up both.

In the following example, the WebSockets server inherits its TLS configuration from the HTTP
listener, which in turn references `<tls:context>` to configure a key store:

```xml
<tls:context name="listenerTlsContext" >
    <tls:key-store
      path="tls/muleKeystore"
      keyPassword="mulepassword"
      password="mulepassword"
      alias="muleserver" />
</tls:context>

<http:listener-config name="listenerTlsConfig">
    <http:listener-connection
      protocol="HTTPS"
      host="localhost"
      port="${listenerPort}"
      tlsContext="listenerTlsContext"/>
</http:listener-config>

<websocket:config name="requestConfigWithCertificate">
    <websocket:connection>
        <websocket:server-settings
         listenerConfig="listenerTlsConfig"
         listenerBasePath="/"/>
    </websocket:connection>
</websocket:config>
```

In case of a WebSocket client, you can set up a truststore by directly referencing the
`<tls:context>` in the `tlsConfig` property.

```xml
<tls:context name="requestTlsContextWithCertificate" >
    <tls:trust-store path="tls/trustStore" password="mulepassword" />
</tls:context>

<websocket:config name="requestConfigWithCertificate">
    <websocket:connection>
        <websocket:client-settings
         host="localhost"
         port="${listenerPort}"
         tlsContext="requestTlsContextWithCertificate"
         protocol="WSS"/>
    </websocket:connection>
</websocket:config>
```

The `protocol` parameter is optional and defaults to WS (not secure). If set to `WSS`, then SSL is
enabled in the connection. If `<tls:content>` was specified, then that configuration is used to
create the SSL session. Otherwise, default settings are used.

## Next

Now that you have completed configuration, you can try out the WebSockets
[Examples](https://docs.mulesoft.com/websockets-connector/latest/websockets-connector-examples).

## See Also

- [Salesforce Help](https://help.salesforce.com)

- [WebSockets Connector Overview](https://docs.mulesoft.com/websockets-connector/latest/)

- [CloudHub](https://docs.mulesoft.com/websockets-connector/latest/websockets-connector-cloudhub)

- [XML and Maven](https://docs.mulesoft.com/websockets-connector/latest/websockets-connector-xml-maven)