# STOMP Over WebSockets

RabbitMQ is a message broker that allows clients to connect over a range of different open and standardized protocols such as [AMQP,](/docs/amqp/)[HTTP,](/docs/http/)[STOMP,](/docs/stomp/)[MQTT,](/docs/mqtt/)[MQTT over WebSockets](/docs/mqtt-over-websockets/) and [STOMP over WebSockets](/docs/stomp-over-websockets/). However, here, we are only interested in _STOMP over WebSockets._

## STOMP Over Websockets ?

STOMP (Simple Text Oriented Messaging Protocol) is bare-bones, text-based messaging protocol, designed to be easily implemented and understood. RabbitMQ supports the STOMP protocol, natively, via a plugin.

Now, imagine you have a browser-based application that needs to communicate with other STOMP-based systems. You can enable this communication using a messaging broker such as RabbitMQ. RabbitMQ facilitates the exchange of messages between the web application and the systems, acting as a middleman.

But here’s the catch: web browsers don’t natively support STOMP. That’s where STOMP over Websockets comes in - It’s a clever solution that allows web browsers to route STOMP traffic over a Websocket connection.

RabbitMQ supports STOMP over WebSockets via the [Web-STOMP plugin](https://www.rabbitmq.com/web-stomp.html). You can activate the Web-STOMP plugin using the RabbitMQ CLI with the command: `rabbitmq-plugins enable rabbitmq_web_stomp` or from the CloudAMQP console.

**On CloudAMQP, the Web-STOMP plugin can only be enabled on dedicated plans.**

Once enabled, the Web-STOMP plugin exposes a WebSocket endpoint that allows web browsers to communicate directly with your RabbitMQ server/cluster.

## Usage

To use Web-STOMP, you first need to create at least one user with limited permissions and a new vhost, which you can expose publicly. The username, password, vhost, and your broker URL will be used to connect to your cluster in subsequent steps.

Next include [`stomp-js,`](https://github.com/stomp-js/stompjs) the JavaScript STOMP client library, in your HTML from a CDN(for example).

```html
<script src="//cdn.jsdelivr.net/npm/@stomp/stompjs@5.0.0/bundles/stomp.umd.min.js"></script>
```

Next, connect to the broker using client credentials. Then, publish and consume messages as shown in the snippet below:

```javascript
import { Client } from '@stomp/stompjs';

// Load client credentials from env vars
const clientSettings = {
  brokerURL: process.env.BROKER_URL,
  connectHeaders: {
    login: process.env.BROKER_USERNAME,
    passcode: process.env.BROKER_PASSWORD,
    host: process.env.VHOST,
  },
  reconnectDelay: 5000,
  heartbeatIncoming: 4000,
  heartbeatOutgoing: 4000,
}

// Connect to broker
const client = new Client(clientSettings)

// Publish and consume messages
client.onConnect = () => {
  client.subscribe('/queue/test', message => {
    console.log(`${message.body}`)
  })

  client.publish({
    destination: '/queue/test',
    body: 'Hello World !'
  })
}

// Error handling
client.onStompError = (frame) => {
  console.log('Broker reported error: ' + frame.headers['message'])
  console.log('Additional details: ' + frame.body)
}

client.onDisconnect = () => {
  console.log('Connection Terminated')
}

client.onWebSocketClose = (closeEevent) => {
  console.log('Websocket Terminated!!')
  console.log(`Reason: ${closeEevent.reason}`)
  console.log(`Code: ${closeEevent.code}`)
}

client.activate()
```

### Note:

- Our servers have nginx in front of them, which performs TLS/SSL-termination. You can only connect over HTTPS; HTTP is not allowed.

- When connecting to CloudAMQP via STOMP over WebSockets, you should use a connection URL like: `wss://hostname/ws/.` For example: `wss://blue-horse.rmq.cloudamqp.com/ws/`

If you are interested in learning more about connecting browser-based applications to RabbitMQ, we encourage you to check out our [2-part series on RabbitMQ and Websockets](https://www.cloudamqp.com/blog/rabbitmq-and-websockets-part-1-amqp-mqtt-stomp).

For questions or any feedback, please feel free to contact [support@cloudamqp.com](mailto:support@cloudamqp.com).