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:
Openfire: inverse plugin
Prosody: mod_conversejs
ejabberd: mod_conversejs
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:
A. Using the CDN (Recommended)¶
Converse provides a CDN (via KeyCDN) for easy integration.
To use it, add these lines to your HTML page’s <head>
section:
<!-- Replace 10.1.5 with your desired version -->
<link rel="stylesheet" href="https://cdn.conversejs.org/11.0.0/dist/converse.min.css">
<script src="https://cdn.conversejs.org/11.0.0/dist/converse.min.js" charset="utf-8"></script>
Warning
Always specify a version number in production to avoid breaking changes.
B. Download Pre-built Files¶
Download the latest release from the Converse GitHub releases page
Extract the archive file
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 serverConverse 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:
git clone git@github.com:conversejs/converse.js.git
to clone the repo.cd converse.js && npm install
to install dependenciesnpm run build
to build distribution files to the./dist
foldernpm run serve
to start a local server at port8080
.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:
Explore available features (some require additional setup)
Implement Shared Sessions for single sign-on between your site and XMPP
Enable OMEMO encryption (requires loading libsignal-protocol.js)
Create custom builds with specific features
Customize the appearance with theming
Dive into development to contribute or extend Converse