---
title: "Adding a Rocket.Chat Room to Your Web App"
slug: "adding-a-rocketchat-chat-room-to-your-web-app"
description: "Embed a Rocket Chat room in your web app. Enable secure communication, boost collaboration, and improve user engagement."
updated: 2026-02-09T08:37:45Z
published: 2026-02-09T08:37:45Z
---
> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.
# Adding a Rocket.Chat Room to Your Web App
After [configuring iframe auth](/v1/docs/configuring-iframe-auth), you can explore and customize Rocket.Chat. Iframe integration in Rocket.Chat allows you to embed chat rooms from your Rocket.Chat server on other websites or web apps.
## Prerequisites
- A running Rocket.Chat server with at least one room.
> [!NOTE]
> See the [official deployment guide](https://docs.rocket.chat/v1/docs/deploy-rocketchat) to explore various ways of setting up your Rocket.Chat workspace.
## Activate the iframe integration
To enable the Iframe integration setting in your Rocket.Chat workspace,
- Navigate to **Manage** **> Workspace > Settings > Accounts > Iframe**.
- Toggle **on** the **Enabled** option.
- Fill in the **iframe URL** with the application URL where you want to integrate the current Rocket.Chat application.
- Add the **API URL**, which is essential for Rocket.Chat to verify that a user is logged into the application. If a user in your application visits a web page containing the Rocket.Chat room iframe, the Rocket.Chat server will use this API endpoint to verify the following:
- The user is identified on your web app.
- The credentials provided are used to attempt a login to the Rocket.Chat server.
- Click **Save Changes**.
> [!NOTE]
> This demo sample uses `http://localhost:3030/` and assumes the application is running on port `3000`.
- Navigate to **Manage** **> Workspace > Settings > General**.
- Disable **Restrict access inside any Iframe**.
> [!WARNING]
> Disabling this feature is a security hole in your Rocket.Chat server. It allows anyone to load the iframe from your server into their app. Enabling it allows only your application's URL to use the iframe.
- Click **Save Changes**.
## Iframe authentication
For authentication, there are two possibilities:
- The user already has a Rocket.Chat account
- The user does not have a Rocket.Chat account
It is essential to know how to manage these cases to ensure Rocket.Chat can identify the user of the iframe.
> [!NOTE]
> You can test iframe authentication with our [sample demo on GitHub](https://github.com/RocketChat/iframe-auth-example).
### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#set-up-and-use-the-demo-code)Set up and use the demo code
- Clone the [GitHub repository](https://github.com/RocketChat/iframe-auth-example).
```bash
git clone
https://github.com/RocketChat/iframe-auth-example.git
```
- Navigate to the cloned directory and open it in your IDE.
```bash
cd iframe-auth-examples
```
- Install the demo packages.
```bash
npm install
```
> [!CAUTION]
> Do not launch the demo app directly now; you still need to make some modifications.
### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#modifying-the-demo-code)Modifying the demo code
Before using the demo code, there are still some modifications to do.
- Update the `index.js` file with this code:
```javascript
//
var express = require('express');
var bodyParser = require('body-parser');
var axios = require('axios');
var fs = require('fs');
var app = express();
app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());
// CORS in case you need
app.use((req, res, next) => {
res.set('Access-Control-Allow-Origin', 'http://localhost:3000'); // this is the rocket.chat URL
res.set('Access-Control-Allow-Credentials', 'true');
next();
});
// this is the endpoint configured as API URL
app.post('/sso', function (req, res) {
// add your own app logic here to validate user session (check cookies, headers, etc)
// if the user is not already logged in on your system, respond with a 401 status
var notLoggedIn = false;
if (notLoggedIn) {
return res.sendStatus(401);
}
// you can save the token on your database as well, if so just return it
// MongoDB - services.iframe.token
var savedToken = null;
if (savedToken) {
return res.json({
token: savedToken,
});
}
// if dont have the user created on rocket.chat end yet, you can now create it
var currentUsername = true;
if (!currentUsername) {
axios
.post('http://localhost:3000/api/v1/users.register', {
username: 'new-user',
email: 'mynewuser@email.com',
pass: 'new-users-passw0rd',
name: 'New User',
})
.then(function (response) {
// after creation you need to log the user in to get the `authToken`
if (response.data.success) {
return axios.post('http://localhost:3000/api/v1/login', {
username: 'new-user',
password: 'new-users-passw0rd',
});
}
})
.then(function (response) {
if (response.data.status === 'success') {
res.json({
loginToken: response.data.data.authToken,
});
}
})
.catch(function (error) {
res.sendStatus(401);
});
} else {
// otherwise create a rocket.chat session using rocket.chat's API
axios
.post('http://localhost:3000/api/v1/login', {
username: 'new-user',
password: 'new-users-passw0rd',
})
.then(function (response) {
if (response.data.status === 'success') {
res.json({
loginToken: response.data.data.authToken,
});
}
})
.catch(function () {
res.sendStatus(401);
});
}
});
// just render the form for the user authenticate with us
app.get('/login', function (req, res) {
res.set('Content-Type', 'text/html');
fs.createReadStream('login.html').pipe(res);
});
app.get('/home', function (req, res) {
res.set('Content-Type', 'text/html');
fs.createReadStream('home.html').pipe(res);
});
// receives login information
app.post('/login', function (req, res) {
// do your own authentication process
// after the user is authenticated we can proceed with authenticating him on rocket.chat side
//
//
// the code below is exactly the same as the on /sso endpoint, except for its response
// it was duplicated for understanding purpose
// the authentication process and is a well-designed app =)
//
//
// if dont have the user created on rocket.chat end yet, you can now create it
var currentUsername = null;
if (!currentUsername) {
axios
.post('http://localhost:3000/api/v1/users.register', {
username: 'new-user',
email: 'mynewuser@email.com',
pass: 'new-users-passw0rd',
name: 'New User',
})
.then(function (response) {
// after creation you need to log the user in to get the `authToken`
if (response.data.success) {
return axios.post('http://localhost:3000/api/v1/login', {
username: 'new-user',
password: 'new-users-passw0rd',
});
}
})
.then(function (response) {
if (response.data.status === 'success') {
res.redirect('/home');
}
})
.catch(function (error) {
res.sendStatus(401);
});
} else {
// otherwise create a rocket.chat session using rocket.chat's API
axios
.post('http://localhost:3000/api/v1/login', {
username: 'username-set-previously',
password: 'password-set-previously',
})
.then(function (response) {
if (response.data.status === 'success') {
// since this endpoint is loaded within the iframe, we need to communicate back to rocket.chat using `postMessage` API
res.set('Content-Type', 'text/html');
res.send(
``
);
}
})
.catch(function () {
res.sendStatus(401);
});
}
});
app.listen(3030, function () {
console.log('Example app listening on port 3030!');
});
```
- Create a new file called `home.html` in the root directory. Update the file with this code:
```xml
//
Document
```
When a new user is created, they are redirected to the `home.html`**page.
- Navigate to **Manage** **> Workspace > Settings > Accounts > Iframe**; the API method is `POST`. It must sync with the request methods in our backend for the link added as the API URL.
- The demo backend for handling the Rocket.Chat server is `/sso` `POST` request.
- In**`index.js`, the `app.post('/sso' ... )` function in the backend only runs once the user has been on the page containing the iframe, which is `home.html` in the demo. It also verifies that the user is logged in to Rocket.Chat.
- The `axios.post('http://localhost:3000/api/v1/users.register'....)` function makes a `POST `request to the Rocket.Chat server API with the user's credentials to create a new user and log the user in to obtain the `authToken`.
- The `axios.post('http://localhost:3000/api/v1/login' ....)` function onwards makes a `POST` request to the Rocket.Chat server API with the user's credentials to create a rocket.chat session for the user.
> [!NOTE]
> The login credentials must match those previously entered by the user. For the demo, we will put them back as we created them.
### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#launch-demo)Launch demo
Run this command to launch the demo app:
```bash
npm run start
```
### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#demo-code-overview)Demo code overview
The demo application is currently running on port `3030`. The `index.js` file is the backend of our demo, while `login.html` is the front end of the demo.
The `POST /login `and `POST /sso` endpoints in `index.js` are significant for iframe integration.
After receiving the credentials via the form on the front end, pass them through your application's authentication logic.
> [!WARNING]
> The sample demo doesn't have authentication. However, your application should have one to manage users.
When the credentials are passed through authentication in your application, they are used for two purposes:
- They are used to connect to the Rocket.chat app via the Rocket.Chat server `/login` endpoint.
> [!NOTE]
> You can copy and paste the demo code into your application.
- If Rocket.Chat has not found a user, it creates one with the identifiers received by your application.
The `home.html` file has the following two critical features:
- The **button**and its function: See [fast-loading](/v1/docs/adding-a-rocketchat-chat-room-to-your-web-app#enable-disable-embedded-layout) to learn more.
- The **iframe**: When the user arrives on the page, the iframe loads the `src` of the iframe and calls the URL to Rocket.Chat server. Then, Rocket.Chat requests to the SSO endpoint (`http://localhost:3030/sso`). It checks whether the user is logged in. Once the user is successfully identified, Rocket.Chat stores the token in the database and the user credentials in the user's browser local storage.
Now go to**`localhost:3030/login`*,*enter new credentials, and click **Submit**.
> [!NOTE]
> Use a private browser so the iframe doesn't use the credentials in your local storage and connect to your account instead of the one you are trying to create in the demo app.
### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#enabling-fast-loading-for-the-embedded-rocket.chat-room)Enabling fast-loading for the embedded Rocket.Chat room
Rocket.Chat is designed as a client-side rendered application to ensure a seamless user experience. Upon arrival, the entire application loads in the user's browser, eliminating wait time when switching rooms. However, when using an iframe, the experience may differ slightly due to latency when changing rooms within it.
To mitigate this, optimize the iframe loading process to ensure that the entire iframe loads completely upon the user's initial visit to the page. Doing so eliminates any latency and provides a smoother user experience for those using Rocket.Chat through an iframe.
Rocket.Chat provides [commands for iframe integration](/v1/docs/customize-and-embed-iframe-integration). One of these is `postMessage()`. Using this command in your client-side code, the iframe content Window will route the client-side to a chat room, making the switching instant without loading.
To use these commands, you must change a setting in your Rocket.Chat server.
- Go to **Manage** **> Settings > General > Iframe Integration**.
- Toggle on**Enable Receive**.
- Add the URL of your application that receives commands in the **Receive Origins**field**.**It allows the iframe's parent window to send commands to the Rocket.Chat server. For this demo, use `http://localhost:3030/`.
- Once saved, it allows the iframe's parent window to send commands to the Rocket.Chat server.
- In `home.html`*,*review the function for clicking the **Go To General** button.
```javascript
document.querySelector("iframe").contentWindow.postMessage({
externalCommand: "go",
path: "/channel/general/?layout-embedded"
},"
http://localhost:3000
"
);
```
This command navigates directly to the general room of the Rocket.Chat server. Once the necessary permissions are enabled on your server, you can switch rooms without reloading the page. This allows you to seamlessly add and manage chat rooms within your web application.
## Use cases
Rocket.Chat provides more than just the ability to embed a room. You can use the application code and server permissions to use specific commands and events that the embedded application triggers.
### Commands: change your user status
- Go to `home.html`**and add the `x() function` to the tag script.
```javascript
const x = () => {
document.getElementsByTagName("iframe")[0].contentWindow.postMessage({
externalCommand: "set-user-status",
status: "away"
},
"http://localhost:3000"
)
}
```
- Replace the `<button> `tag with this:
```xml
```
You can now click on the button in the embedded room and change your status.
[Iframe integration: Sending commands](/v1/docs/iframe-integration-sending-commands)
### Events: adding code for Rocket.Chat iframe events
Rocket.Chat provides events in the iframe. These events trigger different actions by the user.
To enable the sending of iframe events,
- Go to **Manage** **> Settings > General > Iframe Integration**.
- Toggle on **Enable Send**. It allows your Rocket.Chat server to send events to the parent window of the iframe.
- In the **Send Target Origin** field, add `*` or the URL of your application.
- Click **Save Changes**.
- In `home.html` add this script:
```javascript
window.addEventListener('message', function(e) {
if(e.data.eventName === 'room-opened') {
alert('You opened a room!')
}
});
```
- Go to your embedded room, and type `#<ARoomName>` in the message field.
- Click **Enter**. If you click the link and open a new room, an alert appears on your screen that you have opened a room.
[Iframe Events](/v1/docs/iframe-events)
### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#enable-disable-embedded-layout)Enable or disable embedded layout
Currently, the application is in embedded mode. You can only see the room you're in. The left sidebar and room header are not displayed.
#### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#enable-embedded-layout)Enable embedded layout
```xml
```
#### [](/docs/adding-a-rocketchat-chat-room-to-your-web-app#disable-embedded-layout)Disable embedded layout
```xml
```
After disabling, you can see the entire Rocket.Chat window in your application.