Quickstart

You can use the latest version of Converse at conversejs.org.

There are several ways to run Converse yourself or to add it to your website or web app:

Option 1: Host it via your XMPP Server

If you run your own XMPP server, check if it has a plugin for hosting Converse.

For example, the following XMPP servers have plugins available:

Option 2: Self-hosting

Getting the necessary files

You can host Converse on your own server without requiring any XMPP server. There are three ways to get the necessary files:

B. Download Pre-built Files

  1. Download the latest release from the Converse GitHub releases page

  2. Extract the archive file

  3. Include the minified files in your HTML:

<link rel="stylesheet" href="path/to/converse.min.css">
<script src="path/to/converse.min.js" charset="utf-8"></script>

Important

  • All the files from the dist directory need to be available and hosted on your server

  • Converse will dynamically load additional files from this directory

  • To use a different path, change the assets_path setting

C. Build from Source

For custom builds and development, run the following commands:

  1. git clone git@github.com:conversejs/converse.js.git to clone the repo.

  2. cd converse.js && npm install to install dependencies

  3. npm run build to build distribution files to the ./dist folder

  4. npm run serve to start a local server at port 8080.

  5. You can now access Converse at http://localhost:8080/dev.html in your browser.

See the Creating JavaScript and CSS bundles and distribution files section for detailed build instructions and customization options.

Tip

You can run npm run watch to automatically rebuild the dist files whenever a source file changes.

Initializing Converse

After building and including the necessary files, you need to initialize Converse:

<script>
    converse.initialize();
</script>

See the Configuration settings section for all available initialization options and the index.html file in the repository for a complete example.

Display Modes

Converse supports different display modes:

  • Full page mode (default): Chat takes up the entire page

  • Overlay mode: Chat appears in a corner of your page

  • Embedded mode: Chat appears embedded inside a container element in your page

To use fullscreen mode, simply set the view_mode parameter:

converse.initialize({
    view_mode: 'fullscreen' // other options are `overlay` and `embedded`
});

Further reading

Now that you have Converse running, you might want to: