<li><aclass="reference internal"href="#install-the-development-and-front-end-dependencies"id="id24">Install the development and front-end dependencies</a></li>
<li><aclass="reference internal"href="#with-amd-and-require-js-recommended"id="id25">With AMD and require.js (recommended)</a></li>
<li><aclass="reference internal"href="#without-amd-and-require-js"id="id26">Without AMD and require.js</a></li>
<li><aclass="reference internal"href="#before-submitting-a-pull-request"id="id27">Before submitting a pull request</a><ul>
<li><aclass="reference internal"href="#add-tests-for-your-bugfix-or-feature"id="id28">Add tests for your bugfix or feature</a></li>
<li><aclass="reference internal"href="#check-that-the-tests-pass"id="id29">Check that the tests pass</a></li>
<li><aclass="reference internal"href="#check-your-code-for-errors-or-bad-habits-by-running-jshint"id="id30">Check your code for errors or bad habits by running JSHint</a></li>
<h1><aclass="toc-backref"href="#id8">Quickstart (to get a demo up and running)</a><aclass="headerlink"href="#quickstart-to-get-a-demo-up-and-running"title="Permalink to this headline">¶</a></h1>
<p>For more info on this, read: <aclass="reference internal"href="#prebinding-and-single-session-support">Prebinding and Single Session Support</a>.</p>
<p>You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read <aclass="reference internal"href="#configuration">Configuration</a> and <aclass="reference internal"href="#minification">Minification</a> for more info on how to do
<aclass="reference internal"href="#session-support">Session Support</a> (i.e. single-signon functionality whereby users are authenticated once and stay
<h2><aclass="toc-backref"href="#id11">Off-the-record encryption</a><aclass="headerlink"href="#off-the-record-encryption"title="Permalink to this headline">¶</a></h2>
<p>The OTR protocol not only <strong>encrypts your messages</strong>, it provides ways to
<strong>verify the identity</strong> of the person you are talking to,
<strong>plausible deniability</strong> and <strong>perfect forward secrecy</strong> by generating
new encryption keys for each conversation.</p>
<p>In its current state, Javascript cryptography is fraught with dangers and
challenges that make it impossible to reach the same standard of security that
is available with native “desktop” software.</p>
<p>This is due to its runtime malleability, the way it is “installed” (e.g.
served) and the browser’s lack of cryptographic primitives needed to implement
secure crypto.</p>
<p>For harsh but fairly valid criticism of Javascript cryptography, read:
<aclass="reference external"href="http://www.matasano.com/articles/javascript-cryptography/">Javascript Cryptography Considered Harmful</a>.</p>
<p>To get an idea on how this applies to OTR support in Converse.js, please read
<aclass="reference external"href="https://opkode.com/media/blog/2013/11/11/conversejs-otr-support">my thoughts on it</a>.</p>
<p>For now, suffice to say that although its useful to have OTR support in
Converse.js in order to avoid most eavesdroppers, if you need serious
communications privacy, then you’re much better off using native software.</p>
</div>
<divclass="section"id="sound-notifications">
<h2><aclass="toc-backref"href="#id12">Sound Notifications</a><aclass="headerlink"href="#sound-notifications"title="Permalink to this headline">¶</a></h2>
<p>From version 0.8.1 Converse.js can play a sound notification when you receive a
message.</p>
<p>For more info, please see the <aclass="reference internal"href="#play-sounds">play_sounds</a> configuration setting.</p>
</div>
<divclass="section"id="multilingual-support">
<h2><aclass="toc-backref"href="#id13">Multilingual Support</a><aclass="headerlink"href="#multilingual-support"title="Permalink to this headline">¶</a></h2>
<p>Converse.js is translated into multiple languages. The default build,
<ttclass="docutils literal"><spanclass="pre">converse.min.js</span></tt>, includes all languages.</p>
<p>Languages increase the size of the Converse.js significantly.</p>
<p>If you only need one, or a subset of the available languages, it’s better to
make a custom build which includes only those languages that you need.</p>
</div>
<divclass="section"id="chat-rooms">
<h2><aclass="toc-backref"href="#id14">Chat Rooms</a><aclass="headerlink"href="#chat-rooms"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="commands">
<h3><aclass="toc-backref"href="#id15">Commands</a><aclass="headerlink"href="#commands"title="Permalink to this headline">¶</a></h3>
<p>Here are the different commands that may be used in a chat room:</p>
<h1><aclass="toc-backref"href="#id16">What you will need</a><aclass="headerlink"href="#what-you-will-need"title="Permalink to this headline">¶</a></h1>
<divclass="section"id="an-xmpp-server">
<h2><aclass="toc-backref"href="#id17">An XMPP server</a><aclass="headerlink"href="#an-xmpp-server"title="Permalink to this headline">¶</a></h2>
<p><em>Converse.js</em> implements <aclass="reference external"href="https://en.wikipedia.org/wiki/Xmpp">XMPP</a> as its messaging protocol, and therefore needs
to connect to an XMPP/Jabber server (Jabber is really just a synonym for XMPP).</p>
<h2><aclass="toc-backref"href="#id18">A BOSH Connection Manager</a><aclass="headerlink"href="#a-bosh-connection-manager"title="Permalink to this headline">¶</a></h2>
<p>Your website and <em>Converse.js</em> use <aclass="reference external"href="https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol">HTTP</a> as protocol to communicate with
the webserver. HTTP connections are stateless and usually shortlived.</p>
<p><aclass="reference external"href="https://en.wikipedia.org/wiki/Xmpp">XMPP</a> on the other hand, is the protocol that enables instant messaging, and
its connections are stateful and usually longer.</p>
<p>To enable a web application like <em>Converse.js</em> to communicate with an XMPP
server, we need a proxy in the middle that can act as a bridge between the two
standalone application or part of an XMPP server. Popular XMPP servers such as
<aclass="reference external"href="http://www.ejabberd.im">ejabberd</a>, <aclass="reference external"href="http://prosody.im/doc/setting_up_bosh">prosody</a> and
<aclass="reference external"href="http://www.igniterealtime.org/projects/openfire/">openfire</a> all include their own connection managers
(but you usually have to enable them in the configuration).</p>
<p>Standalone connection managers also exist, see for example <aclass="reference external"href="https://github.com/twonds/punjab">Punjab</a>.</p>
<p>The demo on the <aclass="reference external"href="http://conversejs.org">Converse.js homepage</a> uses a connection manager located at <aclass="reference external"href="https://bind.conversejs.org">https://bind.conversejs.org</a>.
This connection manager is available for testing purposes only, please don’t use it in production.</p>
<h3><aclass="toc-backref"href="#id19">Overcoming cross-domain request restrictions</a><aclass="headerlink"href="#overcoming-cross-domain-request-restrictions"title="Permalink to this headline">¶</a></h3>
Until recently, it was not possible to make such requests to a different domain
than the one currently being served (to prevent XSS attacks).</p>
<p>Luckily there is now a standard called <aclass="reference external"href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a> (Cross-origin resource sharing), which enables exactly that.
Modern browsers support CORS, but there are problems with Internet Explorer <
10.</p>
<p>IE 8 and 9 partially support CORS via a proprietary implementation called
XDomainRequest. There is a <aclass="reference external"href="https://gist.github.com/1095825/6b4517276f26b66b01fa97b0a78c01275fdc6ff2">Strophe.js plugin</a> which you can use to enable
support for XDomainRequest when it is present.</p>
<p>In IE < 8, there is no support for CORS.</p>
<h4>For example:<aclass="headerlink"href="#for-example"title="Permalink to this headline">¶</a></h4>
<p>Assuming your site is accessible on port <ttclass="docutils literal"><spanclass="pre">80</span></tt> for the domain <ttclass="docutils literal"><spanclass="pre">mysite.com</span></tt>
and your connection manager manager is running at <ttclass="docutils literal"><spanclass="pre">someothersite.com/http-bind</span></tt>.</p>
<p>The <em>bosh_service_url</em> value you want to give Converse.js to overcome
the cross-domain restriction is <ttclass="docutils literal"><spanclass="pre">mysite.com/http-bind</span></tt> and not
<p>Your <ttclass="docutils literal"><spanclass="pre">nginx</span></tt> or <ttclass="docutils literal"><spanclass="pre">apache</span></tt> configuration will look as follows:</p>
</div>
<divclass="section"id="nginx">
<h4>Nginx<aclass="headerlink"href="#nginx"title="Permalink to this headline">¶</a></h4>
<h2><aclass="toc-backref"href="#id20">Server-side authentication</a><aclass="headerlink"href="#server-side-authentication"title="Permalink to this headline">¶</a></h2>
<spanid="session-support"></span><h3><aclass="toc-backref"href="#id21">Prebinding and Single Session Support</a><aclass="headerlink"href="#prebinding-and-single-session-support"title="Permalink to this headline">¶</a></h3>
<p>To do this you will require a <aclass="reference external"href="http://xmpp.org/about-xmpp/technology-overview/bosh/">BOSH server</a>
for converse.js to connect to (see the <aclass="reference internal"href="#bosh-service-url">bosh_service_url</a> under <aclass="reference internal"href="#configuration-variables">Configuration variables</a>)
<p>Jack Moffitt has a great <aclass="reference external"href="http://metajack.im/2008/10/03/getting-attached-to-strophe">blogpost</a> about this and even provides an <aclass="reference external"href="https://github.com/metajack/strophejs/tree/master/examples/attach">example Django application</a> to demonstrate it.</p>
<p>When you authenticate to the XMPP server on your backend application (for
<h3><aclass="toc-backref"href="#id22">Example code for server-side prebinding</a><aclass="headerlink"href="#example-code-for-server-side-prebinding"title="Permalink to this headline">¶</a></h3>
<dd><pclass="first last">See <aclass="reference external"href="https://github.com/candy-chat/xmpp-prebind-php">xmpp-prebind-php</a> by
Michael Weibel and the folks from Candy chat.</p>
</dd>
</dl>
</li>
<li><dlclass="first docutils">
<dt>Python:</dt>
<dd><pclass="first last">See this <aclass="reference external"href="https://github.com/metajack/strophejs/tree/master/examples/attach">example Django application</a> by Jack Moffitt.</p>
<h2><aclass="toc-backref"href="#id24">Install the development and front-end dependencies</a><aclass="headerlink"href="#install-the-development-and-front-end-dependencies"title="Permalink to this headline">¶</a></h2>
<p>We use development tools (<aclass="reference external"href="http://gruntjs.com">Grunt</a> and <aclass="reference external"href="http://bower.io">Bower</a>)
which depend on Node.js and npm (the Node package manager).</p>
<p>If you don’t have Node.js installed, you can download and install the latest
version <aclass="reference external"href="https://nodejs.org/download">here</a>.</p>
<p>Also make sure you have <ttclass="docutils literal"><spanclass="pre">git</span></tt> installed. <aclass="reference external"href="http://git-scm.com/book/en/Getting-Started-Installing-Git">Details</a>.</p>
<p>Once you have <em>Node.js</em> and <em>git</em> installed, run the following command inside the Converse.js
<pclass="last">After running <ttclass="docutils literal"><spanclass="pre">`make</span><spanclass="pre">dev`</span></tt>, you should now have a new directory <em>components</em>,
which contains all the front-end dependencies of Converse.js.
If this directory does NOT exist, something must have gone wrong.
Double-check the output of <ttclass="docutils literal"><spanclass="pre">`make</span><spanclass="pre">dev`</span></tt> to see if there are any errors
listed. For support, you can write to the mailing list: <aclass="reference external"href="mailto:conversejs%40librelist.com">conversejs<span>@</span>librelist<span>.</span>com</a></p>
<h2><aclass="toc-backref"href="#id25">With AMD and require.js (recommended)</a><aclass="headerlink"href="#with-amd-and-require-js-recommended"title="Permalink to this headline">¶</a></h2>
<h2><aclass="toc-backref"href="#id26">Without AMD and require.js</a><aclass="headerlink"href="#without-amd-and-require-js"title="Permalink to this headline">¶</a></h2>
<h2><aclass="toc-backref"href="#id27">Before submitting a pull request</a><aclass="headerlink"href="#before-submitting-a-pull-request"title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref"href="#id28">Add tests for your bugfix or feature</a><aclass="headerlink"href="#add-tests-for-your-bugfix-or-feature"title="Permalink to this headline">¶</a></h3>
<p>Add a test for any bug fixed or feature added. We use Jasmine
for testing.</p>
<p>Take a look at <ttclass="docutils literal"><spanclass="pre">tests.html</span></tt> and <ttclass="docutils literal"><spanclass="pre">spec/MainSpec.js</span></tt> to see how
<h3><aclass="toc-backref"href="#id29">Check that the tests pass</a><aclass="headerlink"href="#check-that-the-tests-pass"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id30">Check your code for errors or bad habits by running JSHint</a><aclass="headerlink"href="#check-your-code-for-errors-or-bad-habits-by-running-jshint"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id33">“contacts” grouping</a><aclass="headerlink"href="#contacts-grouping"title="Permalink to this headline">¶</a></h3>
<divclass="section"id="get">
<h4>get<aclass="headerlink"href="#get"title="Permalink to this headline">¶</a></h4>
<p>Returns a map of attributes for a given buddy (i.e. roster contact), specified
<td>If ask === ‘subscribe’, then we have asked this person to be our chat buddy.</td>
</tr>
<trclass="row-odd"><td>fullname</td>
<td>The person’s full name.</td>
</tr>
<trclass="row-even"><td>jid</td>
<td>The person’s Jabber/XMPP username.</td>
</tr>
<trclass="row-odd"><td>requesting</td>
<td>If true, then this person is asking to be our chat buddy.</td>
</tr>
<trclass="row-even"><td>subscription</td>
<td>The subscription state between the current user and this chat buddy. Can be <cite>none</cite>, <cite>to</cite>, <cite>from</cite> or <cite>both</cite>.</td>
</tr>
<trclass="row-odd"><td>id</td>
<td>A unique id, same as the jid.</td>
</tr>
<trclass="row-even"><td>chat_status</td>
<td>The person’s chat status. Can be <cite>online</cite>, <cite>offline</cite>, <cite>busy</cite>, <cite>xa</cite> (extended away) or <cite>away</cite>.</td>
</tr>
<trclass="row-odd"><td>user_id</td>
<td>The user id part of the JID (the part before the <cite>@</cite>).</td>
</tr>
<trclass="row-even"><td>resources</td>
<td>The known resources for this chat buddy. Each resource denotes a separate and connected chat client.</td>
</tr>
<trclass="row-odd"><td>groups</td>
<td>The roster groups in which this chat buddy was placed.</td>
</tr>
<trclass="row-even"><td>status</td>
<td>Their human readable custom status message.</td>
</tr>
<trclass="row-odd"><td>image_type</td>
<td>The image’s file type.</td>
</tr>
<trclass="row-even"><td>image</td>
<td>The Base64 encoded image data.</td>
</tr>
<trclass="row-odd"><td>url</td>
<td>The buddy’s website URL, as specified in their VCard data.</td>
</tr>
<trclass="row-even"><td>vcard_updated</td>
<td>When last the buddy’s VCard was updated.</td>
<h3><aclass="toc-backref"href="#id34">“chats” grouping</a><aclass="headerlink"href="#chats-grouping"title="Permalink to this headline">¶</a></h3>
<divclass="section"id="id2">
<h4>get<aclass="headerlink"href="#id2"title="Permalink to this headline">¶</a></h4>
<p>Returns an object/map representing a chat box (without opening or affecting that chat box).</p>
<h3><aclass="toc-backref"href="#id35">“tokens” grouping</a><aclass="headerlink"href="#tokens-grouping"title="Permalink to this headline">¶</a></h3>
<divclass="section"id="id3">
<h4>get<aclass="headerlink"href="#id3"title="Permalink to this headline">¶</a></h4>
<p>Returns a token, either the RID or SID token depending on what’s asked for.</p>
<h3><aclass="toc-backref"href="#id36">“listen” grouping</a><aclass="headerlink"href="#listen-grouping"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id40">Minifying Javascript and CSS</a><aclass="headerlink"href="#minifying-javascript-and-css"title="Permalink to this headline">¶</a></h3>
<p>Please make sure to read the section <aclass="reference internal"href="#development">Development</a> and that you have installed
all development dependencies (long story short, you can run <ttclass="docutils literal"><spanclass="pre">npm</span><spanclass="pre">install</span></tt>
and then <ttclass="docutils literal"><spanclass="pre">grunt</span><spanclass="pre">fetch</span></tt>).</p>
<p>We use <aclass="reference external"href="http://requirejs.org">require.js</a> to keep track of <em>Converse.js</em> and its dependencies and to
to bundle them together in a single minified file fit for deployment to a
production site.</p>
<p>To minify the Javascript and CSS, run the following command:</p>
<p>The gettext POT file located in ./locale/converse.pot is the template
containing all translations and from which for each language an individual PO
file is generated.</p>
<p>The POT file contains all translateable strings extracted from converse.js.</p>
<p>To make a user facing string translateable, wrap it in the double underscore helper
function like so:</p>
<divclass="highlight-python"><divclass="highlight"><pre><spanclass="n">__</span><spanclass="p">(</span><spanclass="s">'This string will be translated at runtime'</span><spanclass="p">);</span>
<p>Unfortunately <aclass="reference external"href="http://slexaxton.github.io/Jed">Jed</a> cannot use the PO files directly. We have to generate from it
a file in JSON format and then put that in a .js file for the specific
language.</p>
<p>To generate JSON from a PO file, you’ll need po2json for node.js. Run the
following command to install it (npm being the node.js package manager):</p>
<h2><aclass="toc-backref"href="#id43">Conflicts with other Javascript libraries</a><aclass="headerlink"href="#conflicts-with-other-javascript-libraries"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="problem">
<h3><aclass="toc-backref"href="#id44">Problem:</a><aclass="headerlink"href="#problem"title="Permalink to this headline">¶</a></h3>
<p>You are using other Javascript libraries (like JQuery plugins), and
get errors like these in your browser console:</p>
<divclass="highlight-python"><divclass="highlight"><pre>Uncaught TypeError: Object [object Object] has no method 'xxx' from example.js
</pre></div>
</div>
</div>
<divclass="section"id="solution">
<h3><aclass="toc-backref"href="#id45">Solution:</a><aclass="headerlink"href="#solution"title="Permalink to this headline">¶</a></h3>
<p>First, find out which object is referred to by <ttclass="docutils literal"><spanclass="pre">Object</span><spanclass="pre">[object</span><spanclass="pre">Object]</span></tt>.</p>
<p>It will probably be the jQuery object <ttclass="docutils literal"><spanclass="pre">$</span></tt> or perhaps the underscore.js object <ttclass="docutils literal"><spanclass="pre">_</span></tt>.</p>
<p>For the purpose of demonstration, I’m going to assume its <ttclass="docutils literal"><spanclass="pre">$</span></tt>, but the same
rules apply if its something else.</p>
<p>The bundled and minified default build of converse.js, <ttclass="docutils literal"><spanclass="pre">converse.min.js</span></tt>
includes within it all of converse.js’s dependencies, which include for example <em>jQuery</em>.</p>
<p>If you are having conflicts where attributes or methods aren’t available
on the jQuery object, you are probably loading <ttclass="docutils literal"><spanclass="pre">converse.min.js</span></tt> (which
includes jQuery) as well as your own jQuery version separately.</p>
<p>What then happens is that there are two <ttclass="docutils literal"><spanclass="pre">$</span></tt> objects (one from
converse.js and one from the jQuery version you included manually)
and only one of them has been extended to have the methods or attributes you require.</p>
<p>Which jQuery object you get depends on the order in which you load the libraries.</p>
<p>There are multiple ways to solve this issue.</p>
<p>Firstly, make sure whether you really need to include a separate version of
jQuery. Chances are that you don’t. If you can remove the separate
version, your problem should be solved, as long as your libraries are loaded in
the right order.</p>
<p>Either case, whether you need to keep two versions or not, the solution depends
on whether you’ll use require.js to manage your libraries or whether you’ll
load them manually.</p>
<divclass="section"id="with-require-js">
<h4>With require.js<aclass="headerlink"href="#with-require-js"title="Permalink to this headline">¶</a></h4>
<p>Instead of using <ttclass="docutils literal"><spanclass="pre">converse.min.js</span></tt>, manage all the libraries in your project
(i.e. converse.js and its dependencies plus all other libraries you use) as one
require.js project, making sure everything is loaded in the correct order.</p>
<p>Then, before deployment, you make your own custom minified build that bundles everything
you need.</p>
</div>
<divclass="section"id="with-script-tags">
<h4>With <script> tags<aclass="headerlink"href="#with-script-tags"title="Permalink to this headline">¶</a></h4>
<p>Take a look at <aclass="reference external"href="https://github.com/jcbrand/converse.js/blob/master/non_amd.html">non_amd.html</a>
in the converse.js repo.</p>
<p>It shows in which order the libraries must be loaded via <ttclass="docutils literal"><spanclass="pre"><script></span></tt> tags. Add
your own libraries, making sure that they are loaded in the correct order (e.g.
<h2><aclass="toc-backref"href="#id47">Configuration variables</a><aclass="headerlink"href="#configuration-variables"title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref"href="#id48">allow_contact_requests</a><aclass="headerlink"href="#allow-contact-requests"title="Permalink to this headline">¶</a></h3>
<p>Let the <aclass="reference external"href="https://otr.cypherpunks.ca">OTR (Off-the-record encryption)</a> private
key be cached in your browser’s session storage.</p>
<p>The browser’s session storage persists across page loads but is deleted once
the tab or window is closed.</p>
<p>If this option is set to <ttclass="docutils literal"><spanclass="pre">false</span></tt>, a new OTR private key will be generated
for each page load. While more inconvenient, this is a much more secure option.</p>
<p>This setting can only be used together with <ttclass="docutils literal"><spanclass="pre">allow_otr</span><spanclass="pre">=</span><spanclass="pre">true</span></tt>.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">A browser window’s session storage is accessible by all javascript that
is served from the same domain. So if there is malicious javascript served by
the same server (or somehow injected via an attacker), then they will be able
to retrieve your private key and read your all the chat messages in your
current session. Previous sessions however cannot be decrypted.</p>
<h3><aclass="toc-backref"href="#id60">expose_rid_and_sid</a><aclass="headerlink"href="#expose-rid-and-sid"title="Permalink to this headline">¶</a></h3>
<p>Hide the <ttclass="docutils literal"><spanclass="pre">server</span></tt> input field of the form inside the <ttclass="docutils literal"><spanclass="pre">Room</span></tt> panel of the
controlbox. Useful if you want to restrict users to a specific XMPP server of
<p>For prebinding to work, you must set up a pre-authenticated BOSH session,
for which you will receive a JID (jabber ID), SID (session ID) and RID
(Request ID).</p>
<p>These values (<ttclass="docutils literal"><spanclass="pre">rid</span></tt>, <ttclass="docutils literal"><spanclass="pre">sid</span></tt> and <ttclass="docutils literal"><spanclass="pre">jid</span></tt>) need to be passed into
<ttclass="docutils literal"><spanclass="pre">converse.initialize</span></tt> (with the exception of <ttclass="docutils literal"><spanclass="pre">keepalive</span></tt>, see below).</p>
<p>Additionally, you also have to specify a <ttclass="docutils literal"><spanclass="pre">bosh_service_url</span></tt>.</p>
<h4>Using prebind in connection with keepalive<aclass="headerlink"href="#using-prebind-in-connection-with-keepalive"title="Permalink to this headline">¶</a></h4>
<p>The <ttclass="docutils literal"><spanclass="pre">prebind</span></tt> and <aclass="reference internal"href="#keepalive">keepalive</a> options can be used together.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">keepalive</span></tt> option caches the <ttclass="docutils literal"><spanclass="pre">rid</span></tt>, <ttclass="docutils literal"><spanclass="pre">sid</span></tt> and <ttclass="docutils literal"><spanclass="pre">jid</span></tt> values
(henceforth referred to as <em>session tokens</em>) one receives from a prebinded
BOSH session, in order to re-use them when the page reloads.</p>
<p>However, if besides setting <ttclass="docutils literal"><spanclass="pre">keepalive</span></tt> to <ttclass="docutils literal"><spanclass="pre">true</span></tt>, you also set <ttclass="docutils literal"><spanclass="pre">prebind</span></tt>
to <ttclass="docutils literal"><spanclass="pre">true</span></tt>, and you pass in valid session tokens to <ttclass="docutils literal"><spanclass="pre">converse.initialize</span></tt>,
then those passed in session tokens will be used instead of any tokens cached by
<p>If you set <ttclass="docutils literal"><spanclass="pre">prebind</span></tt> to <ttclass="docutils literal"><spanclass="pre">true</span></tt> and don’t pass in the session tokens to
<ttclass="docutils literal"><spanclass="pre">converse.initialize</span></tt>, then converse.js will look for tokens cached by
<p>If you’ve set <ttclass="docutils literal"><spanclass="pre">keepalive</span></tt> and <ttclass="docutils literal"><spanclass="pre">prebind</span></tt> to <ttclass="docutils literal"><spanclass="pre">true</span></tt>, don’t pass in session
tokens and converse.js doesn’t find any cached session tokens, then
converse.js will emit an event <ttclass="docutils literal"><spanclass="pre">noResumeableSession</span></tt> and exit.</p>
<p>This allows you to start a prebinded session with valid tokens, and then fall
back to <ttclass="docutils literal"><spanclass="pre">keepalive</span></tt> for maintaining that session across page reloads. When
for some reason <ttclass="docutils literal"><spanclass="pre">keepalive</span></tt> doesn’t have cached session tokens anymore, you
can listen for the <ttclass="docutils literal"><spanclass="pre">noResumeableSession</span></tt> event and take that as a cue that
you should again prebind in order to get valid session tokens.</p>
<p>Here is a code example:</p>
<divclass="highlight-python"><divclass="highlight"><pre>converse.on('noResumeableSession', function () {
<h3><aclass="toc-backref"href="#id68">show_controlbox_by_default</a><aclass="headerlink"href="#show-controlbox-by-default"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id69">show_only_online_users</a><aclass="headerlink"href="#show-only-online-users"title="Permalink to this headline">¶</a></h3>
<p>This option determines the type of <aclass="reference external"href="https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage">storage</a>
(<ttclass="docutils literal"><spanclass="pre">localStorage</span></tt> or <ttclass="docutils literal"><spanclass="pre">sessionStorage</span></tt>) used by converse.js to cache user data.</p>
<p>Originally converse.js used only localStorage, however sessionStorage is from a
privacy perspective a better choice.</p>
<p>The main difference between the two is that sessionStorage only persists while
the current tab or window containing a converse.js instance is open. As soon as
it’s closed, the data is cleared.</p>
<p>Data in localStorage on the other hand is kept indefinitely.</p>
<h3><aclass="toc-backref"href="#id71">use_otr_by_default</a><aclass="headerlink"href="#use-otr-by-default"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id73">visible_toolbar_buttons</a><aclass="headerlink"href="#visible-toolbar-buttons"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id75">xhr_custom_status_url</a><aclass="headerlink"href="#xhr-custom-status-url"title="Permalink to this headline">¶</a></h3>
<li>The user inputs some text (for example part of a firstname or lastname), an XHR (Ajax Request) will be made to a remote server, and a list of matches are returned. The user can then choose one of the matches to add as a contact.</li>
<p>This setting enables the second mechanism, otherwise by default the first will be used.</p>
<p><em>What is expected from the remote server?</em></p>
<p>A default JSON encoded list of objects must be returned. Each object
corresponds to a matched user and needs the keys <ttclass="docutils literal"><spanclass="pre">id</span></tt> and <ttclass="docutils literal"><spanclass="pre">fullname</span></tt>.</p>
<h3><aclass="toc-backref"href="#id77">xhr_user_search_url</a><aclass="headerlink"href="#xhr-user-search-url"title="Permalink to this headline">¶</a></h3>
