mod_conversejs

Introduction

This module serves a small snippet of HTML that loads Converse.js, configured to work with the VirtualHost that it is loaded onto.

It becomes available on an URL like https://example.com:5281/conversejs

Configuration

The module uses general Prosody options for basic configuration. It should just work after loading it.

modules_enabled = {
    -- other modules...
    "conversejs";
}

Authentication

Authentication settings are used determine whether to configure Converse.js to use login or anonymous mode.

Connection methods

mod_conversejs also determines the BOSH and WebSocket URL automatically, see their respective documentation for how to configure them. Both connection methods are loaded automatically.

Auto-loading of mod_bosh or mod_websocket can be prevented by adding it to modules_disabled but note that at least one of them must be allowed for Converse.js to work.

HTTP

The module is served on Prosody’s default HTTP ports at the path /conversejs. More details on configuring HTTP modules in Prosody can be found in our HTTP documentation.

Templates

The HTML and JS can be customized either by editing the included template.html and template.js files or configuring your own like:

conversejs_html_template = "/path/to/my-template.html"
conversejs_js_template = "/path/to/my-template.js"

The HTML template uses Prosodys util.interpolation template library while the JS template has %s where generated settings are injected.

Other

To pass other Converse.js options, or override the derived settings, one can set conversejs_options like this:

conversejs_options = {
    debug = true;
    view_mode = "fullscreen";
}

Note that the following options are automatically provided, and overriding them may cause problems:

• authentication based on Prosody’s authentication settings
• bosh_service_url
• websocket_url
• discover_connection_methods Disabled since we provide this
• assets_path
• allow_registration based on whether registration is enabled
• These settings are set to the current VirtualHost:
  • jid
  • default_domain
  • domain_placeholder
  • registration_domain

mod_bosh and/or mod_websocket are automatically enabled if available and the respective endpoint is included in the generated options.

Loading resources

By default the module will load the main script and CSS from cdn.conversejs.org. For privacy or performance reasons you may want to load the scripts from somewhere else.

To use a local distribution or build of Converse.js set conversejs_resources to the local path of “dist” directory:

conversejs_resources = "/usr/src/conversejs/dist";

To use a different web server or CDN simply use the conversejs_cdn option:

conversejs_cdn = "https://cdn.example.com"

To select a specific version of Converse.js, you may override the version:

conversejs_version = "5.0.0"

Note that versions other than the default may not have been tested with this module, and may include incompatible changes.

Finally, if you can override all of the above and just specify links directly to the CSS and JS files:

conversejs_script = "https://example.com/my-converse.js"
conversejs_css = "https://example.com/my-converse.css"

Additional tags

To add additional tags to the module, such as custom CSS or scripts, you may use the conversejs_tags option:

conversejs_tags = {
        -- Load custom CSS
        [[<link rel="stylesheet" href="https://example.org/css/custom.css">]];

        -- Load libsignal-protocol.js for OMEMO support (GPLv3; be aware of licence implications)
        [[<script src="https://cdn.conversejs.org/3rdparty/libsignal-protocol.min.js"></script>]];
}

The example above uses the [[ and ]] syntax simply because it will not conflict with any embedded quotes.

Compatibility