Quickstart

Getting a demo up and running

Option 1: Use the content delivery network

Converse has a CDN, provided by KeyCDN, which hosts its JavaScript and CSS files.

The latest versions of these files are available at these URLs:

If you are integrating Converse into an existing website or app, then we recommend that you load a specific version of Converse. Otherwise your website or app might break when a new backwards-incompatible version of Converse is released.

To load a specific version of Converse you can put the version in the URL:

You can include these two URLs inside the <head> element of your website via the script and link tags:

<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/4.0.5/css/converse.min.css">
<script src="https://cdn.conversejs.org/4.0.5/dist/converse.min.js" charset="utf-8"></script>

Option 2: Building the files yourself

Instead of using the CDN, you can also create your own builds and host them yourself.

Have a look at the Creating JavaScript and CSS bundles and distribution files section on how to create your own builds.

In short, you should be able to do it by running make dist inside a checkout of the Converse repo.

Besides including the converse.min.js and converse.min.css files, you’ll also need to make sure that the webfonts directory is available in the same location as converse.min.css.

Initializing Converse

You’ll need to initialize Converse with configuration settings relevant to your requirements. Take a look at the Configuration settings section for info on all the available settings.

To quickly get started, you can put the following JavaScript code at the bottom of your page (after the closing </body> element):

<script>
    converse.initialize({
        bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
        show_controlbox_by_default: true
    });
</script>

The index.html file inside the Converse repository serves as a nice, usable example.

Fullscreen version

Converse also comes in a fullscreen version. A hosted version is available online at conversejs.org/fullscreen.

Originally this version was available as a separate build file, but as of version 4.0.0 and higher, the difference between the “overlay” and the “fullscreen” versions of converse.js is simply a matter of configuring the view_mode.

For example:

<script>
    converse.initialize({
        bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
        view_mode: 'fullscreen'
    });
</script>

Where to go from here?

Have a look at the various features that Converse provides, for some of them you might have to do more setup work, like configuring an XMPP server or webserver.

You might want to implement some kind of persistent single-session solution for your website, where users authenticate once in your website and are then automatically logged in to the XMPP server as well. For more info on how this can be achieved, read: Single Session Support.

Perhaps you want to create your own custom build of Converse? Then head over to the Generating builds section, or more generally the development documentation.

Do you want to know how to theme Converse? Then read the theming documentation.