configuration.rst 66 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156
  1. .. raw:: html
  2. <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/configuration.rst">Edit me on GitHub</a></div>
  3. =============
  4. Configuration
  5. =============
  6. The included minified JavaScript and CSS files can be used for demoing or testing, but
  7. you'll want to configure Converse to suit your needs before you deploy it
  8. on your website.
  9. Converse is passed its configuration settings when you call its *initialize* method.
  10. You'll most likely want to call the *initialize* method in your HTML page. For
  11. an example of how this is done, please see the bottom of the *./index.html* page.
  12. Please refer to the `Configuration settings`_ section below for info on
  13. all the available configuration settings.
  14. .. _`configuration-settings`:
  15. Configuration settings
  16. ======================
  17. authentication
  18. --------------
  19. * Default: ``login``
  20. * Allowed values: `login`_, `external`, `anonymous`_, `prebind`_
  21. This option states the way Converse will authenticate.
  22. login
  23. ~~~~~
  24. The default means is ``login``, which means that the user either logs in manually with their
  25. username and password, or automatically if used together with ``auto_login=true``
  26. and ``jid`` and ``password`` values. See `auto_login`_.
  27. external
  28. ~~~~~~~~
  29. This setting will still show a login form and submit button, but the form will
  30. only contain an input for the user's JID, *not* for the password.
  31. That's because this setting is intended to be used when you are using
  32. SASL-EXTERNAL as authentication mechanism, in which case a password is usually
  33. not required.
  34. SASL-EXTERNAL is generally used together with x509 client certificates to
  35. enable passwordless login or 2-factor authentication.
  36. For more details on this, `read this blog post <https://opkode.com/blog/strophe_converse_sasl_external/>`_.
  37. anonymous
  38. ~~~~~~~~~
  39. This enables anonymous login if the XMPP server supports it. This option can be
  40. used together with `auto_login`_ to automatically and anonymously log a user in
  41. as soon as the page loads.
  42. The server's domain is passed in via the `jid`_ setting.
  43. .. _`prebind`:
  44. prebind
  45. ~~~~~~~
  46. See also: :ref:`session-support`
  47. Use this option when you want to attach to an existing XMPP
  48. `BOSH <https://en.wikipedia.org/wiki/BOSH>`_ session.
  49. Usually a BOSH session is set up server-side in your web app.
  50. Attaching to an existing BOSH session that was set up server-side is useful
  51. when you want to maintain a persistent single session for your users instead of
  52. requiring them to log in manually.
  53. When a BOSH session is initially created, you'll receive three tokens.
  54. A JID (jabber ID), SID (session ID) and RID (Request ID).
  55. Converse needs these tokens in order to attach to that same session.
  56. In addition to setting ``authentication`` to ``prebind``, you'll also need to
  57. set the `prebind_url`_ and `bosh-service-url`_.
  58. Here's an example of Converse being initialized with these options:
  59. .. code-block:: javascript
  60. converse.initialize({
  61. bosh_service_url: 'https://bind.example.com',
  62. jid: 'me@example.com',
  63. authentication: 'prebind',
  64. prebind_url: 'http://example.com/api/prebind',
  65. auto_login: true,
  66. allow_logout: false
  67. });
  68. allow_adhoc_commands
  69. --------------------
  70. * Default: ``true``
  71. Allows privileged users to run XEP-0050 Ad-Hoc commands via the settings modal.
  72. allow_bookmarks
  73. ---------------
  74. * Default: ``true``
  75. Enables/disables chatroom bookmarks functionality.
  76. This setting is only applicable if the ``converse-bookmarks`` plugin is loaded.
  77. See also: `allow_public_bookmarks`_
  78. allow_chat_pending_contacts
  79. ---------------------------
  80. * Default: ``false``
  81. Allow the user to chat with pending contacts.
  82. allow_contact_removal
  83. ---------------------
  84. * Default: ``true``
  85. Allow the user to remove roster contacts by clicking on the delete icon
  86. (i.e. trashcan) next to a contact's name in the roster.
  87. allow_contact_requests
  88. ----------------------
  89. * Default: ``true``
  90. Allow users to add one another as contacts. If this is set to false, the
  91. **Add a contact** widget, **Contact Requests** and **Pending Contacts** roster
  92. sections will all not appear. Additionally, all incoming contact requests will be
  93. ignored.
  94. allow_dragresize
  95. ----------------
  96. * Default: ``true``
  97. Allow users to resize chats by dragging the edges. The min-height and min-width
  98. CSS properties set on a chatboxes (specifically on the ``#converse.js .chatbox > .box-flyout`` element)
  99. will be honored, IF they are set in pixels.
  100. allow_logout
  101. ------------
  102. * Default: ``true``
  103. Determines whether the user is allowed to log out. If set to ``false``, there will be no logout button.
  104. .. _`allow_message_corrections`:
  105. allow_message_corrections
  106. -------------------------
  107. * Default: ``'all'``
  108. * Possible values: ``'all'``, ``'last'``
  109. Configures the last message correction (LMC) feature of Converse. By default you can edit all of your own
  110. messages. Setting this to ``'last'`` will limit this feature to the message sent most recently as suggested by
  111. `XEP-0308: Last Message Correction <https://xmpp.org/extensions/xep-0308.html>`_.
  112. Setting it to anything else (including ``false``) will disable the ability to correct sent messages.
  113. allow_message_retraction
  114. ------------------------
  115. * Default: ``'all'``
  116. * Possible values: ``'all'``, ``'own'``, ``'moderator'`` or any falsy value
  117. Determines who is allowed to retract messages. If set to ``'all'``, then normal
  118. users may retract their own messages and ``'moderators'`` may retract the messages of
  119. other users.
  120. allow_muc
  121. ---------
  122. * Default: ``true``
  123. Allow multi-user chat (muc) in chatrooms. Setting this to ``false`` will remove
  124. the ``Chatrooms`` tab from the control box.
  125. allow_muc_invitations
  126. ---------------------
  127. * Default: ``true``
  128. Allows users to be invited to join MUC chatrooms. An "Invite" widget will
  129. appear in the sidebar of the chatroom where you can type in the JID of a user
  130. to invite into the chatroom.
  131. .. _`allow_non_roster_messaging`:
  132. allow_non_roster_messaging
  133. --------------------------
  134. * Default: ``false``
  135. Determines whether you'll receive messages from users that are not in your
  136. roster. The XMPP specification allows for this (similar to email).
  137. Setting this to ``true`` increases your chances of receiving spam (when using a
  138. federated server), while setting it to ``false`` means that people not on your
  139. roster can't contact you unless one (or both) of you subscribe to one another's
  140. presence (i.e. adding as a roster contact).
  141. allow_public_bookmarks
  142. ----------------------
  143. * Default: ``false``
  144. Some XMPP servers don't support private PEP/PubSub nodes, as required for
  145. private bookmarks and outlined in `XEP-0223 <https://xmpp.org/extensions/xep-0223.html>`_.
  146. Even though Converse asks for the bookmarks to be kept private (via the
  147. `<publish-options>` XML node), the server simply ignores the privacy settings
  148. and publishes the node contents under the default privacy setting, which makes
  149. the information available to all roster contacts.
  150. If your XMPP server does not support `XEP-0223`'s ``#publish-options``
  151. feature and you don't mind that your room bookmarks are visible to all
  152. contacts, then you can set this setting to ``true``. Otherwise you won't be
  153. able to have any room bookmarks at all for an account on that XMPP server.
  154. allow_registration
  155. ------------------
  156. * Default: ``true``
  157. Support for `XEP-0077: In band registration <https://xmpp.org/extensions/xep-0077.html>`_
  158. Allow XMPP account registration showing the corresponding UI register form interface.
  159. archived_messages_page_size
  160. ---------------------------
  161. * Default: ``50``
  162. See also: `message_archiving`_
  163. This feature applies to `XEP-0313: Message Archive Management (MAM) <https://xmpp.org/extensions/xep-0313.html>`_
  164. and will only take effect if your server supports MAM.
  165. It allows you to specify the maximum amount of archived messages to be returned per query.
  166. When you open a chatbox or room, archived messages will be displayed (if
  167. available) and the amount returned will be no more than the page size.
  168. You will be able to query for even older messages by scrolling upwards in the chatbox or room
  169. (the so-called infinite scrolling pattern).
  170. autocomplete_add_contact
  171. ------------------------
  172. * Default: ``true``
  173. Determines whether search suggestions are shown in the "Add Contact" modal.
  174. auto_focus
  175. ----------
  176. * Default: ``true``
  177. If set to ``true``, the textarea for composing chat messages will automatically
  178. become focused as soon as a chat is opened. This means you don't need to click
  179. the textarea first before starting to type a message. This also applies to the
  180. username field which is automatically focused after the login controlbox is
  181. loaded.
  182. For applications where chat is not the main feature, automatic focus of the
  183. chat box might be undesired.
  184. auto_list_rooms
  185. ---------------
  186. * Default: ``false``
  187. If true, and the XMPP server on which the current user is logged in supports
  188. multi-user chat, then a list of rooms on that server will be fetched in the
  189. "Query for Groupchats" modal.
  190. Not recommended for servers with lots of chatrooms.
  191. For each room on the server a query is made to fetch further details (e.g.
  192. features, number of occupants etc.), so on servers with many rooms this
  193. option will create lots of extra connection traffic.
  194. If the `muc_domain`_ is locked with the `locked_muc_domain`_ setting, then
  195. rooms will automatically be fetched in the "Query for Groupchats" modal,
  196. regardless of the value of this setting.
  197. .. _`auto_login`:
  198. auto_login
  199. ----------
  200. * Default: ``false``
  201. This option can be used to let Converse automatically log the user in as
  202. soon as the page loads.
  203. If ``authentication`` is set to ``login``, then you will also need to provide a
  204. valid ``jid`` and ``password`` values, either manually by passing them in, or
  205. by the `credentials_url`_ setting. Setting a ``credentials_url`` is preferable
  206. to manually passing in ``jid`` and ``password`` values, because it allows
  207. better reconnection with ``auto_reconnect``. When the connection drops,
  208. Converse will automatically fetch new login credentials from the
  209. ``credentials_url`` and reconnect.
  210. If ``authentication`` is set to ``anonymous``, then you will also need to provide the
  211. server's domain via the `jid`_ setting.
  212. This is a useful setting if you'd like to create a custom login form in your
  213. website. You'll need to write some JavaScript to accept that custom form's
  214. login credentials, then you can pass those credentials (``jid`` and
  215. ``password``) to ``converse.initialize`` to start Converse and log the user
  216. in to their XMPP account.
  217. .. note::
  218. The interaction between ``keepalive`` and ``auto_login`` is unfortunately
  219. inconsistent depending on the ``authentication`` method used.
  220. If ``auto_login`` is set to ``false`` and ``authentication`` is set to
  221. ``anonymous``, ``external`` or ``prebind``, then Converse won't automatically
  222. log the user in.
  223. If ``authentication`` set to ``login`` the situation is much more
  224. ambiguous, since we don't have a way to distinguish between wether we're
  225. restoring a previous session (``keepalive``) or whether we're
  226. automatically setting up a new session (``auto_login``).
  227. So currently if EITHER ``keepalive`` or ``auto_login`` is ``true`` and
  228. ``authentication`` is set to ``login``, then Converse will try to log the user in.
  229. auto_away
  230. ---------
  231. * Default: ``0``
  232. The amount of seconds after which the user's presence status should
  233. automatically become ``away``.
  234. If the user's status is ``extended away``, it won't be changed to ``away``.
  235. If the given value is negative or ``0``, this option is disabled.
  236. auto_xa
  237. -------
  238. * Default: ``0``
  239. The amount of seconds after which the user's presence status should
  240. automatically become ``extended away``.
  241. If the value is negative or ``0``, the function is disabled.
  242. auto_reconnect
  243. --------------
  244. * Default: ``false``
  245. Automatically reconnect to the XMPP server if the connection drops
  246. unexpectedly.
  247. This option works best when you have ``authentication`` set to ``prebind`` and have
  248. also specified a ``prebind_url`` URL, from where Converse can fetch the BOSH
  249. tokens. In this case, Converse will automaticallly reconnect when the
  250. connection drops but also reestablish earlier lost connections (due to
  251. network outages, closing your laptop etc.).
  252. When ``authentication`` is set to `login`, then this option will only work when
  253. the page hasn't been reloaded yet, because then the user's password has been
  254. wiped from memory. This configuration can however still be useful when using
  255. Converse in desktop apps, for example those based on `CEF <https://bitbucket.org/chromiumembedded/cef>`_
  256. or `electron <http://electron.atom.io/>`_.
  257. auto_register_muc_nickname
  258. --------------------------
  259. * Default: ``false``
  260. Determines whether Converse should automatically register a user's nickname
  261. when they enter a groupchat.
  262. See here fore more details: https://xmpp.org/extensions/xep-0045.html#register
  263. auto_subscribe
  264. --------------
  265. * Default: ``false``
  266. If true, the user will automatically subscribe back to any contact requests.
  267. auto_join_on_invite
  268. -------------------
  269. * Default: ``false``
  270. If true, the user will automatically join a chatroom on invite without any confirm.
  271. Also inviting users won't be prompted for a reason.
  272. auto_join_private_chats
  273. -----------------------
  274. * Default: ``[]``
  275. Allows you to provide a list of user JIDs for private (i.e. single) chats that
  276. should automatically be started upon login.
  277. For example::
  278. `['tom@example.org', 'dick@example.org', 'harry@example.org']`
  279. auto_join_rooms
  280. ---------------
  281. * Default: ``[]``
  282. This settings allows you to provide a list of groupchat conversations to be
  283. automatically joined once the user has logged in.
  284. You can either specify a simple list of room JIDs, in which case your nickname
  285. will be taken from your JID, or you can specify a list of maps, where each map
  286. specifies the room's JID and other options.
  287. For example::
  288. `[{'jid': 'room@example.org', 'nick': 'WizardKing69', 'minimized': true }]`
  289. blacklisted_plugins
  290. -------------------
  291. * Default: ``[]``
  292. A list of plugin names that are blacklisted and will therefore not be
  293. initialized once ``converse.initialize`` is called, even if the same plugin is
  294. whitelisted.
  295. From Converse 3.0 onwards most of the API is available only to plugins and
  296. all plugins need to be whitelisted first.
  297. The usecase for blacklisting is generally to disable removed core plugins
  298. (which are automatically whitelisted) to prevent other (potentially malicious)
  299. plugins from registering themselves under those names.
  300. The core, and by default whitelisted, plugins are::
  301. converse-bosh
  302. converse-bookmarks
  303. converse-chatboxes
  304. converse-chatview
  305. converse-controlbox
  306. converse-core
  307. converse-disco
  308. converse-dragresize
  309. converse-fullscreen
  310. converse-headline
  311. converse-mam
  312. converse-minimize
  313. converse-muc
  314. converse-muc-embedded
  315. converse-notification
  316. converse-ping
  317. converse-profile
  318. converse-register
  319. converse-roomslist
  320. converse-rosterview
  321. converse-singleton
  322. converse-smacks
  323. converse-spoilers
  324. converse-vcard
  325. Example:
  326. .. code-block:: javascript
  327. require(['converse-core', 'converse-muc-embedded'], function (converse) {
  328. converse.initialize({
  329. // other settings removed for brevity
  330. blacklisted_plugins: [
  331. 'converse-dragresize',
  332. 'converse-minimize'
  333. ],
  334. });
  335. });
  336. .. _`bosh-service-url`:
  337. bosh_service_url
  338. ----------------
  339. * Default: ``undefined``
  340. Example: ``http://xmpp.example.com:5280/bosh/``
  341. Example with reverse-proxy and TLS: ``https://xmpp.example.com/bosh/``
  342. To connect to an XMPP server over HTTP you need a `BOSH <https://en.wikipedia.org/wiki/BOSH>`_
  343. connection manager which acts as a middle man between the HTTP and XMPP
  344. protocols.
  345. The bosh_service_url setting takes the URL of a BOSH connection manager.
  346. Please refer to your XMPP server's documentation on how to enable BOSH.
  347. For more information, read this blog post: `Which BOSH server do you need? <http://metajack.im/2008/09/08/which-bosh-server-do-you-need>`_
  348. A more modern alternative to BOSH is to use `websockets <https://developer.mozilla.org/en/docs/WebSockets>`_.
  349. Please see the :ref:`websocket-url` configuration setting.
  350. clear_messages_on_reconnection
  351. ------------------------------
  352. * Default: ``false``
  353. In some cases, it might be desirable to clear cached chat messages once you've
  354. reconnected to the XMPP server.
  355. For example, if you want to prevent the chat history from getting too long or
  356. if you want to avoid gaps in the chat history (for example due to MAM not
  357. returning all messages since the last cached message).
  358. Beware, if you're using OMEMO, then you probably don't want to set this setting to
  359. ``true``. OMEMO messages can be decrypted only once, so if they then
  360. subsequently get cleared, you won't get the plaintext back.
  361. chatstate_notification_blacklist
  362. --------------------------------
  363. * Default: ``[]``
  364. A list of JIDs to be ignored when showing desktop notifications of changed chat states.
  365. Some user's clients routinely connect and disconnect (likely on mobile) and
  366. each time a chat state notificaion is received (``online`` when connecting and
  367. then ``offline`` when disconnecting).
  368. When desktop notifications are turned on (see `show-desktop-notifications`_),
  369. then you'll receive notification messages each time this happens.
  370. Receiving constant notifications that a user's client is connecting and disconnecting
  371. is annoying, so this option allows you to ignore those JIDs.
  372. connection_options
  373. ------------------
  374. * Default: ``{}``
  375. * Type: Object
  376. Converse relies on `Strophe.js <http://strophe.im>`_ to establish and
  377. maintain a connection to the XMPP server.
  378. This option allows you to pass a map of configuration options to be passed into
  379. the ``Strophe.Connection`` constructor.
  380. For documentation on the configuration options that ``Strophe.Connection``
  381. accepts, refer to the
  382. `Strophe.Connection documentation <http://strophe.im/strophejs/doc/1.2.8/files/strophe-js.html#Strophe.Connection.Strophe.Connection>`_.
  383. Restricting the supported authentication mechanisms:
  384. ****************************************************
  385. As an example, suppose you want to restrict the supported SASL authentication
  386. mechanisms, then you'd pass in the ``mechanisms`` as a ``connection_options``
  387. ``key:value`` pair:
  388. .. code-block:: javascript
  389. converse.initialize({
  390. connection_options: {
  391. 'mechanisms': [
  392. converse.env.Strophe.SASLMD5,
  393. ]
  394. }
  395. });
  396. Running the XMPP Connection inside a shared worker
  397. **************************************************
  398. Newer versions of Strophe.js, support the ability to run the XMPP Connection
  399. inside a `shared worker <https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker>`_ that's shared
  400. between open tabs in the browser in which Converse is running (and which have the same domain).
  401. *Note:* This feature is experimental and there currently is no way to
  402. synchronize actions between tabs. For example, sent 1-on-1 messages aren't
  403. reflected by the server, so you if you send such a message in one tab, it won't
  404. appear in another.
  405. .. code-block:: javascript
  406. converse.initialize({
  407. connection_options: { 'worker': true }
  408. });
  409. .. _`credentials_url`:
  410. credentials_url
  411. ---------------
  412. * Default: ``null``
  413. * Type: URL
  414. This setting should be used in conjunction with ``authentication`` set to ``login``.
  415. It allows you to specify a URL which Converse will call when it needs to get
  416. the username and password (or authentication token) which Converse will use
  417. to automatically log the user in.
  418. If ``auto_reconnect`` is also set to ``true``, then Converse will automatically
  419. fetch new credentials from the ``credentials_url`` whenever the connection or
  420. session drops, and then attempt to reconnect and establish a new session.
  421. If the request to the ``credentials_url`` URL fails for whatever reason,
  422. Converse will continuously retry to fetch the credentials every 2 seconds.
  423. The server behind ``credentials_url`` should return a JSON encoded object::
  424. {
  425. "jid": "me@example.com/resource",
  426. "password": "Ilikecats!"
  427. }
  428. csi_waiting_time
  429. ----------------
  430. * Default: ``0``
  431. This option adds support for `XEP-0352 Client State Indication <https://xmpp.org/extensions/xep-0352.html>_`
  432. If Converse is idle for the configured amount of seconds, a chat state
  433. indication of ``inactive`` will be sent out to the XMPP server (if the server
  434. supports CSI).
  435. Afterwards, ss soon as there is any activity (for example, the mouse moves),
  436. a chat state indication of ``active`` will be sent out.
  437. A value of ``0`` means that this feature is disabled.
  438. .. _`loglevel`:
  439. loglevel
  440. --------
  441. * Default: ``'info'``
  442. * Allowed values: ``'debug'``, ``'info'``, ``'warn'``, ``'error'``, ``'fatal'``
  443. You can also set this value by changing a URL fragment `#converse?loglevel=debug`
  444. default_domain
  445. --------------
  446. * Default: ``undefined``
  447. Specify a domain to act as the default for user JIDs. This allows users to log
  448. in with only the username part of their JID, instead of the full JID.
  449. For example, if ``default_domain`` is ``example.org``, then the user
  450. ``johnny@example.org`` can log in with only ``johnny``.
  451. JIDs with other domains are still allowed but need to be provided in full.
  452. To specify only one domain and disallow other domains, see the `locked_domain`_
  453. option.
  454. registration_domain
  455. -------------------
  456. * Default: ``''``
  457. Specify a domain name for which the registration form will be fetched automatically,
  458. without the user having to enter any XMPP server domain name.
  459. default_state
  460. -------------
  461. * Default: ``'online'``
  462. The default chat status that the user wil have. If you for example set this to
  463. ``'chat'``, then Converse will send out a presence stanza with ``"show"``
  464. set to ``'chat'`` as soon as you've been logged in.
  465. discover_connection_methods
  466. ---------------------------
  467. * Default: ``true``
  468. Use `XEP-0156 <https://xmpp.org/extensions/xep-0156.html>`_ to discover whether
  469. the XMPP host for the current user advertises any Websocket or BOSH connection
  470. URLs that can be used.
  471. If this is set to ``false``, then a `websocket_url`_ or `bosh_service_url`_ need to be
  472. set.
  473. Currently only the XML encoded host-meta resource is supported as shown in
  474. `Example 2 under section 3.3 <https://xmpp.org/extensions/xep-0156.html#httpexamples>`_.
  475. domain_placeholder
  476. ------------------
  477. * Default: ``e.g. conversejs.org``
  478. The placeholder text shown in the domain input on the registration form.
  479. emoji_categories
  480. ----------------
  481. * Default:
  482. ::
  483. {
  484. "smileys": ":grinning:",
  485. "people": ":thumbsup:",
  486. "activity": ":soccer:",
  487. "travel": ":motorcycle:",
  488. "objects": ":bomb:",
  489. "nature": ":rainbow:",
  490. "food": ":hotdog:",
  491. "symbols": ":musical_note:",
  492. "flags": ":flag_ac:",
  493. "custom": ":converse:"
  494. }
  495. This setting lets you define the categories that are available in the emoji
  496. picker, as well as the default image that's shown for each category.
  497. The keys of the map are the categories and the values are the shortnames of the
  498. representative images.
  499. If you want to remove a category, don't just remove the key, instead set its
  500. value to ``undefined``.
  501. Due to restrictions intended to prevent addition of undeclared configuration
  502. settings, it's not possible to add new emoji categories. There is however a
  503. ``custom`` category where you can put your own custom emojis (also known as
  504. "stickers").
  505. To add custom emojis, you need to edit ``src/headless/emojis.json`` to add new
  506. entries to the map under the ``custom`` key.
  507. emoji_categories_label
  508. ----------------------
  509. * Default:
  510. ::
  511. {
  512. "smileys": "Smileys and emotions",
  513. "people": "People",
  514. "activity": "Activities",
  515. "travel": "Travel",
  516. "objects": "Objects",
  517. "nature": "Animals and nature",
  518. "food": "Food and drink",
  519. "symbols": "Symbols",
  520. "flags": "Flags",
  521. "custom": "Stickers"
  522. }
  523. This setting lets you pass in the text value that goes into the `title`
  524. attribute for the emoji categories. These strings will be translated, but for
  525. your custom text to be translatable, you'll need to wrap it in `__()``
  526. somewhere in your own code.
  527. emoji_image_path
  528. ----------------
  529. * Default: ``'https://twemoji.maxcdn.com/2/'``
  530. When `use_system_emojis`_ is set to ``false``, then this is the URL from where image files for
  531. displaying emojis will be fetched.
  532. enable_muc_push
  533. ---------------
  534. * Default: ``false``
  535. If true, then Converse will try to register
  536. `XEP-0357 push notification App Server(s) <https://xmpp.org/extensions/xep-0357.html#general-architecture>`_
  537. for the MUC domain of any newly entered groupchat.
  538. The app servers are specified with the `push_app_servers`_ option.
  539. .. note::
  540. Registering a push app server against a MUC domain is not (yet) standardized
  541. and this feature should be considered experimental.
  542. enable_smacks
  543. -------------
  544. * Default: ``false``
  545. Determines whether `XEP-0198 Stream Management <https://xmpp.org/extensions/xep-0198.html>`_
  546. support is turned on or not.
  547. Recommended to set to ``true`` if a websocket connection is used.
  548. Please see the :ref:`websocket-url` configuration setting.
  549. filter_by_resource
  550. ------------------
  551. * Default: ``false``
  552. Before version 1.0.3 Converse would ignore received messages if they were
  553. intended for a different resource then the current user had. It was decided to
  554. drop this restriction but leave it configurable.
  555. filter_url_query_params
  556. -----------------------
  557. * Default: ``null``
  558. Accepts a string or array of strings. Any query strings from URLs that match this setting will be removed.
  559. fullname
  560. --------
  561. If you are using prebinding, can specify the fullname of the currently
  562. logged in user, otherwise the user's vCard will be fetched.
  563. geouri_regex
  564. ------------
  565. * Default: ``/https:\/\/www.openstreetmap.org\/.*#map=[0-9]+\/([\-0-9.]+)\/([\-0-9.]+)\S*/g``
  566. Regular expression used to extract geo coordinates from links to openstreetmap.
  567. geouri_replacement
  568. ------------------
  569. * Default: ``'https://www.openstreetmap.org/?mlat=$1&mlon=$2#map=18/$1/$2'``
  570. String used to replace geo-URIs with. Ought to be a link to osm or similar. ``$1`` and ``$2`` is replaced by
  571. latitude and longitude respectively.
  572. hide_offline_users
  573. ------------------
  574. * Default: ``false``
  575. If set to ``true``, then offline users aren't shown in the roster.
  576. hide_open_bookmarks
  577. -------------------
  578. * Default: ``false`` (``true`` when the :ref:`view_mode` is set to ``fullscreen``).
  579. This setting applies to the ``converse-bookmarks`` plugin and specfically the
  580. list of bookmarks shown in the ``Rooms`` tab of the control box.
  581. By default all bookmarks are shown in that list, if this setting is set to
  582. ``true``, then only bookmarks for rooms not currently open (i.e. that the
  583. current user hasn't joined), are shown.
  584. Makes sense to set this to ``true`` when also using the non-core
  585. ``converse-roomslist`` plugin, which shows a list of currently open (i.e.
  586. "joined") rooms.
  587. .. _`i18n`:
  588. i18n
  589. ----
  590. * Default: Auto-detection of the User/Browser language or ``en``;
  591. Specify the locale/language.
  592. The translations for that locale must be served in JSON format at `/dist/locales/${i18n}-LC_MESSAGES-converse-po.js`.
  593. The default webpack configuration for Converse.js ensures that these files are
  594. generated and placed in the right location.
  595. If an explicit locale is specified via the ``i18n`` setting and the
  596. translations for that locale are not found, then Converse will fall back to trying to determine the browser's language
  597. and fetching those translations, or if that fails the default English strings will be used.
  598. idle_presence_timeout
  599. ---------------------
  600. * Default: ``300``
  601. The amount of seconds after which the user is considered to be idle
  602. and an idle presence according to XEP-0319 is sent.
  603. If the given value is negative or ``0``, this feature is disabled.
  604. image_urls_regex
  605. ----------------
  606. * Default: ``null``
  607. Any URL in a message that matches the regex in this setting will be considered an image and rendered, if `show_images_inline`_ is set to ``true``.
  608. If the image cannot be rendered, a hyperlink will be rendered instead.
  609. For example, to render Imgur images inline, you can use the following regex: ``/^https?:\/\/(?:www.)?(?:imgur\.com\/\w{7})\/?$/i``
  610. jid
  611. ---
  612. The Jabber ID or "JID" of the current user. The JID uniquely identifies a user
  613. on the XMPP network. It looks like an email address, but it's used for instant
  614. messaging instead.
  615. This value may be provided together with a ``password`` instead of supplying a
  616. `credentials_url`_ when setting ``auto_login`` to ``true``.
  617. .. _`keepalive`:
  618. keepalive
  619. ---------
  620. * Default: ``true``
  621. Determines whether Converse will attempt to keep you logged in across page loads.
  622. .. _`locales`:
  623. locales
  624. -------
  625. * Default:
  626. .. code-block:: javascript
  627. locales: [
  628. 'af', 'ca', 'de',
  629. 'es', 'en', 'fr',
  630. 'he', 'hu', 'id',
  631. 'it', 'ja', 'nb',
  632. 'nl', 'pl', 'pt_BR',
  633. 'ru', 'uk', 'zh'
  634. ]
  635. This setting restricts the locales that are supported by Converse and
  636. therefore what may be given as value for the :ref:`i18n` option.
  637. Any other locales will be ignored.
  638. locked_domain
  639. -------------
  640. * Default: ``undefined``
  641. Similar to `default_domain`_ but no other domains are allowed.
  642. For example, if ``locked_domain`` is set to ``example.org``, then the user
  643. ``johnny@example.org`` can log in with only ``johnny``.
  644. Additionally, only users registered on the ``example.org`` host can log in, no
  645. other users are allowed to log in.
  646. locked_muc_domain
  647. -----------------
  648. * Default: ``false``
  649. * Allowed values: ``false``, ``true``, ``'hidden'``
  650. By setting this value to something truthy, you restrict the multi-user chat (MUC) domain to only the value
  651. specified in `muc_domain`_.
  652. If the value is set to `'hidden'` (which is also truthy), then the MUC domain
  653. will not be shown to users.
  654. locked_muc_nickname
  655. -------------------
  656. * Default: ``false``
  657. This setting allows you to restrict the multi-user chat (MUC) nickname that a
  658. user uses to a particular value.
  659. Where the nickname value comes from depends on other settings.
  660. The `nickname`_ configuration setting takes precedence ahead of any other
  661. nickname value. If that's not set, then the "nickname" value from the user's
  662. VCard is taken, and if that is not set but `muc_nickname_from_jid`_ is set to
  663. ``true``, then the node of the user's JID (the part before the ``@``) is used.
  664. If no nickame value is found, then an error will be raised.
  665. muc_hats
  666. -------------------
  667. * Default: ``['xep317']``
  668. Since version 7 Converse now has rudimentary support for `XEP-0317 Hats <https://xmpp.org/extensions/xep-0317.html>`_.
  669. It is also possible to display VCard roles, MUC affiliation and MUC role along with hats.
  670. By default only XEP-0317 hats are considered.
  671. For the inclusion of VCard roles ``'vcard_roles'`` must be added to the list.
  672. For the inclusion of MUC affiliation and MUC role, the specific affiliations and roles
  673. to be used must be added to the list e.g. ``'owner','participant'``.
  674. Example:
  675. For XEP-0317 hats and VCard roles this setting should be set to:
  676. ``'muc_hats': ['xep317', 'vcard_roles']``
  677. For VCard roles, admin MUC affiliation and moderator MUC role:
  678. ``'muc_hats': ['vcard_roles', 'admin', 'moderator']``
  679. And to prevent the displaying of anything, an empty list must be used:
  680. ``'muc_hats': []``
  681. muc_mention_autocomplete_min_chars
  682. -----------------------------------
  683. * Default: ``0``
  684. The number of characters that need to be entered before the auto-complete list
  685. of matching nicknames is shown.
  686. muc_mention_autocomplete_filter
  687. -------------------------------
  688. * Default: ``contains``
  689. The method used for filtering MUC participants when using auto-complete.
  690. Valid values are ``contains`` and ``starts_with``.
  691. muc_mention_autocomplete_show_avatar
  692. ------------------------------------
  693. * Default: ``true``
  694. Show avatars of MUC participants when using auto-complete.
  695. message_archiving
  696. -----------------
  697. * Default: ``undefined``
  698. Provides support for `XEP-0313: Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_,
  699. whereby messages are archived in the XMPP server for later retrieval.
  700. Note, your XMPP server must support XEP-0313 MAM for this to work.
  701. This option sets the default archiving preference.
  702. Valid values are ``undefined``, ``never``, ``always`` and ``roster``.
  703. ``undefined`` means that any existing MAM configuration, as set by the user or
  704. the server administrator, will be used.
  705. ``roster`` means that only messages to and from JIDs in your roster will be
  706. archived. The other two values are self-explanatory.
  707. message_archiving_timeout
  708. -------------------------
  709. * Default: ``20000``
  710. The amount of time (in milliseconds) to wait when requesting archived messages
  711. from the XMPP server.
  712. Used in conjunction with ``message_archiving`` and in context of `XEP-0313: Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_.
  713. message_carbons
  714. ---------------
  715. * Default: ``true``
  716. Support for `XEP-0280: Message Carbons <https://xmpp.org/extensions/xep-0280.html>`_
  717. In order to keep all IM clients for a user engaged in a conversation,
  718. outbound messages are carbon-copied to all interested resources.
  719. This is especially important with Converse, where each browser
  720. tab serves as a separate IM client.
  721. XEP-0280 requires server support, so make sure that message carbons are enabled
  722. on your server.
  723. message_limit
  724. -------------
  725. * Default: ``0``
  726. Determines the allowed amount of characters in a chat message. A value of zero means there is no limit.
  727. Note, this limitation only applies to the Converse UX code running in the browser
  728. and it's trivial for an attacker to bypass this restriction.
  729. You should therefore also configure your XMPP server to limit message sizes.
  730. modtools_disable_assign
  731. -----------------------
  732. * Default: ``false``
  733. * Possible Values: ``true``, ``false``, ``['owner', 'admin', 'member', 'outcast', 'none', 'moderator', 'participant', 'visitor']``
  734. This setting allows you to disable (either completely, or fine-grained) which affiliations and or roles
  735. may be assigned in the moderator tools modal.
  736. modtools_disable_query
  737. ----------------------
  738. * Default: ``[]``
  739. * Possible Values: ``['owner', 'admin', 'member', 'outcast', 'none', 'moderator', 'participant', 'visitor']``
  740. This setting allows you to disable which affiliations or roles may be queried in the moderator tools modal.
  741. If all roles or all affiliations are disabled, then the relevant tab won't be
  742. showed at all.
  743. muc_disable_slash_commands
  744. --------------------------
  745. * Default: ``false``
  746. Allows you to disable the moderator commands such as ``/kick`` or ``/ban``.
  747. Ìf set to ``true`` all commands will be disabled.
  748. You can also selectively disable some moderator commands by setting it to an
  749. array of commands you don't want.
  750. The following example will disable 'mute' and 'voice' command:
  751. .. code-block:: javascript
  752. muc_disable_slash_commands: ['mute', 'voice'],
  753. muc_domain
  754. ----------
  755. * Default: ``undefined``
  756. The default MUC (multi-user chat) domain that should be used.
  757. When setting this value, users can only enter the name when opening a new MUC,
  758. and don't have to add the whole address (i.e. including the domain part).
  759. Users can however still enter the domain and they can still open MUCs with
  760. other domains.
  761. If you want to restrict MUCs to only this domain, then set `locked_muc_domain`_ to
  762. ``true``.
  763. muc_fetch_members
  764. -----------------
  765. * Default: ``true``
  766. * Possible values: Array containing any of the following: ``['member', 'admin', 'owner']``
  767. Determines whether Converse.js will fetch the member lists for a MUC
  768. (multi-user chat) when the user first enters it.
  769. Here's the relevant part from the MUC XEP: https://xmpp.org/extensions/xep-0045.html#getmemberlist
  770. The MUC service won't necessarily allow any user to fetch member lists,
  771. but can usually be configured to do so.
  772. The member lists consists of three lists of users who have the affiliations
  773. ``member``, ``admin`` and ``owner`` respectively.
  774. By fetching member lists, Converse.js will always show these users as
  775. participants of the MUC, giving them a permanent "presence" in the MUC.
  776. muc_history_max_stanzas
  777. -----------------------
  778. * Default: ``undefined``
  779. This option allows you to specify the maximum amount of messages to be shown in a
  780. chatroom when you enter it. By default, the amount specified in the room
  781. configuration or determined by the server will be returned.
  782. Please note, this option is not related to
  783. `XEP-0313 Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_,
  784. which also allows you to show archived chatroom messages, but follows a
  785. different approach.
  786. If you're using MAM for archiving chatroom messages, you might want to set
  787. this option to zero.
  788. muc_instant_rooms
  789. ------------------
  790. * Default: ``true``
  791. Determines whether 'instant' (also called 'dynamic' in OpenFire) rooms are created.
  792. Otherwise rooms first have to be configured before they're available to other
  793. users (so-called "registered rooms" in `MUC-0045 <https://xmpp.org/extensions/xep-0045.html#createroom>`_).
  794. From a UX perspective, if this settings is `false`, then a configuration form will
  795. render, that has to be filled in first, before the room can be joined by other
  796. users.
  797. muc_nickname_from_jid
  798. ---------------------
  799. * Default: ``false``
  800. When set to ``true``, then users will not be prompted to provide nicknames for
  801. chatrooms. Instead, the node part of a user's JID (i.e. JID = node@domain/resource)
  802. will be used. If the user's nickname is already taken by another user in the
  803. chatroom, then an integer will be added to make it unique.
  804. So, for example, if john@example.com joins a chatroom, his nickname will
  805. automatically be "john". If now john@differentdomain.com tries to join the
  806. room, his nickname will be "john-2", and if john@somethingelse.com joins, then
  807. his nickname will be "john-3", and so forth.
  808. muc_send_probes
  809. ---------------
  810. * Default: ``false``
  811. If set to ``true``, then whenever Converse receives a MUC message with an author for which we don't have
  812. any information (i.e. because that user is currently not in the MUC), then Converse will send out a ``<presence>``
  813. stanza of type ``probe`` in order to request the authors presence data.
  814. Prosody has some experimental support in it's contrib branch (hopefully soon to
  815. be merged to trunk).
  816. The point of sending out presence probes is in order to receive
  817. presence-related metadata, such as `XEP-0317 Hats <https://xmpp.org/extensions/xep-0317.html>`_.
  818. .. note::
  819. Although this behavior is described in the `presence business rules of XEP-0045, section 17.3 point 4 <https://xmpp.org/extensions/xep-0045.html#bizrules-presence>`_,
  820. few XMPP servers support this.
  821. .. note::
  822. If member lists are fetched via muc_fetch_members, then the occupants created
  823. based on those member lists won't be probed again later (given that the
  824. occupants are already created). Certain metadata like XEP-0317 hats are not
  825. included in the member lists, which means that this metadata will be missing for
  826. those occupants.
  827. muc_respect_autojoin
  828. --------------------
  829. * Default; ``true``
  830. Determines whether Converse will respect the autojoin-attribute of bookmarks. Per default
  831. all MUCs with set autojoin flag in their respective bookmarks will be joined on
  832. startup of Converse. When set to ``false`` no MUCs are automatically joined based on
  833. their bookmarks.
  834. muc_roomid_policy
  835. -----------------
  836. * Default: ``null``
  837. This option defines the regular expression that a room id must satisfy to allow the
  838. room creation. Server administrators may want to impose restrictions on the minimum
  839. and maximum length and the allowed character set allowed for room ids. Otherwise
  840. users might create rooms which are difficult to handle.
  841. However, restricting that on the server only leads to bad UX as users might learn of
  842. the servers policy only after they have tried to create a room. Furthermore error
  843. messages from XMPP-servers might not be self-explanatory.
  844. Therefore this option allows converse to already check the policy and disallow the
  845. user from even trying to entering/creating such a room.
  846. As this only makes sense on your own server, the check is applied only if the domain
  847. part equals `muc_domain`_. If `muc_domain`_ is unset, then this check is disabled
  848. completely.
  849. Example:
  850. .. code-block:: javascript
  851. muc_roomid_policy: /^[a-z0-9._-]{5,40}$/,
  852. See also: `muc_roomid_policy_hint`_
  853. muc_roomid_policy_hint
  854. ----------------------
  855. * Default: ``null``
  856. This option can be used in conjuction with `muc_roomid_policy`_ in order to give
  857. a written explanation of the imposed room id policy. You can use the html-tags
  858. ``<br>``, ``<b>``, and ``<em>`` to allow some basic styling.
  859. Example:
  860. .. code-block:: javascript
  861. muc_roomid_policy_hint: '<br><b>Policy for groupchat id:</b><br>- between 5 and 40 characters,<br>- lowercase from a to z (no special characters) or<br>- digits or<br>- dots (.) or<br>- underlines (_) or<br>- hyphens (-),<br>- no spaces<br>',
  862. muc_show_join_leave
  863. -------------------
  864. * Default; ``true``
  865. Determines whether Converse will show info messages inside a chatroom
  866. whenever a user joins or leaves it.
  867. muc_show_logs_before_join
  868. -------------------------
  869. * Default: ``false``
  870. If set to ``true``, when opening a MUC for the first time (or if you don't have
  871. a nickname configured for it), you'll see the message history (if the
  872. server supports [XEP-0313 Message Archive Management](https://xmpp.org/extensions/xep-0313.html))
  873. and the nickname form at the bottom.
  874. .. _`nickname`:
  875. nickname
  876. --------
  877. * Default: ``undefined``
  878. This setting allows you to specify the nickname for the current user.
  879. The nickname will be included in presence requests to other users and will also
  880. be used as the default nickname when entering MUC chatrooms.
  881. This value will have first preference ahead of other nickname sources, such as
  882. the VCard ``nickname`` value.
  883. notify_all_room_messages
  884. ------------------------
  885. * Default: ``false``
  886. By default, sound and desktop notifications will only be made when you are
  887. mentioned in a room. If you set this setting to `true`, then you will be
  888. notified of all messages received in a room.
  889. You can also pass an array of room JIDs to this option, to only apply it to
  890. certain rooms.
  891. notification_delay
  892. ------------------
  893. * Default: ``5000``
  894. Desktop notifications will be shown for a time of ``notification_delay``
  895. ms. Setting this to ``0`` will make the notification stay until dismissed by
  896. the user (requires browser support).
  897. notification_icon
  898. -----------------
  899. * Default: ``'logo/conversejs-filled.svg'``
  900. This option specifies which icon is shown in HTML5 notifications, as provided
  901. by the ``src/converse-notification.js`` plugin.
  902. notify_nicknames_without_references
  903. -----------------------------------
  904. * Default: ``false``
  905. Enables notifications for nicknames in messages that don't have associated
  906. XEP-0372 references linking them to the JID of the person being mentioned.
  907. In Converse, these would be nicknames that weren't mentioned via the ``@`` sign.
  908. oauth_providers
  909. ---------------
  910. * Default: ``[]``
  911. Allows you to specify a list of OAuth providers that the user may use to log in
  912. with.
  913. .. note::
  914. Your XMPP server will have to support Oauth logins
  915. .. code-block:: javascript
  916. converse.initialize({
  917. oauth_providers: {
  918. 'github': {
  919. 'client_id': '1338d9f7ff52b1309b29',
  920. 'host': 'chat.example.org',
  921. 'class': 'fa-github-alt',
  922. 'id': 'github',
  923. 'name': 'Github'
  924. },
  925. 'twitter': {
  926. 'client_id': '0332d98cff83b1999b22',
  927. 'host': 'chat.example.org',
  928. 'class': 'fa-twitter',
  929. 'id': 'twitter',
  930. 'name': 'Twitter'
  931. }
  932. },
  933. });
  934. omemo_default
  935. -------------
  936. * Default: ``false``
  937. Use OMEMO encryption by default when the chat supports it.
  938. ping_interval
  939. -------------
  940. * Default: ``60``
  941. Make ping to server in order to keep connection with server killing sessions after idle timeout.
  942. The ping are sent only if no messages are sent in the last ``ping_interval`` seconds
  943. You need to set the value to any positive value to enable this functionality.
  944. If you set this value to ``0`` or any negative value, il will disable this functionality.
  945. .. _`play-sounds`:
  946. play_sounds
  947. -----------
  948. * Default: ``false``
  949. Plays a notification sound when you receive a personal message or when your
  950. nickname is mentioned in a chatroom.
  951. Inside the ``./sounds`` directory of the Converse repo you'll see MP3 and Ogg
  952. formatted sound files. We need both, because neither format is supported by all browsers.
  953. You can set the URL where the sound files are hosted with the `sounds_path`_ option.
  954. Requires the `src/converse-notification.js` plugin.
  955. .. _`prebind_url`:
  956. prebind_url
  957. -----------
  958. * Default: ``null``
  959. * Type: URL
  960. See also: :ref:`session-support`
  961. This setting should be used in conjunction with ``authentication`` set to `prebind`.
  962. It allows you to specify a URL which Converse will call when it needs to get
  963. the RID and SID (Request ID and Session ID) tokens of a BOSH connection, which
  964. Converse will then attach to.
  965. The server behind ``prebind_url`` should return a JSON encoded object with the
  966. three tokens::
  967. {
  968. "jid": "me@example.com/resource",
  969. "sid": "346234623462",
  970. "rid": "876987608760"
  971. }
  972. priority
  973. --------
  974. * Default: ``0``
  975. * Type: Number
  976. Determines the priority used for presence stanzas sent out from this resource
  977. (i.e. this instance of Converse).
  978. The priority of a given XMPP chat client determines the importance of its presence
  979. stanzas in relation to stanzas received from other clients of the same user.
  980. In Converse, the indicated chat status of a roster contact will be taken from the
  981. presence stanza (and associated resource) with the highest priority.
  982. If multiple resources have the same top priority, then the chat status will be
  983. taken from the most recent present stanza.
  984. For more info you can read `Section 2.2.2.3 of RFC-3921 <https://xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2.3>`_.
  985. providers_link
  986. --------------
  987. * Default: ``https://xmpp.net/directory.php``
  988. The hyperlink on the registration form which points to a directory of public
  989. XMPP servers.
  990. .. _`assets_path`:
  991. assets_path
  992. -----------
  993. * Default: ``'/dist/'`` or the `publicPath <https://webpack.js.org/guides/public-path/>`_ value as configured in the relevant Webpack configuration.
  994. Since version 5.0.0, Converse serves a smaller bundle by extracting various
  995. resources (for example emojis and translations) into separate files (aka
  996. "chunks") which are loaded asynchronously on demand.
  997. The URL path at which these resources are loaded is normally set by the ``publicPath``
  998. setting of Webpack but this means that it's hardcoded to a particular value at
  999. compile time.
  1000. This configuration seting allows this value to be set at runtime as well.
  1001. persistent_store
  1002. ----------------
  1003. * Default: ``localStorage``
  1004. * Valid options: ``localStorage``, ``IndexedDB``
  1005. Determines which store is used for storing persistent data.
  1006. From version 6.0.0 onwards, Converse supports storing data in
  1007. `IndexedDB <https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Basic_Concepts_Behind_IndexedDB>`_.
  1008. IndexedDB is not subjected to the same space constraints as localStorage and is
  1009. also a requirement for progressive web apps which don't need persistent a
  1010. internet connectivity to be functional.
  1011. push_app_servers
  1012. ----------------
  1013. * Default: ``[]``
  1014. This option lets you enable or disable so-called push notification "App Servers"
  1015. (as per `XEP-0357 <https://xmpp.org/extensions/xep-0357.html>`_).
  1016. For each "App Server" an object needs to be passed in. When enabling, you need
  1017. to specify ``jid`` and ``node`` values. You can also provide a
  1018. ``secret``, if required by your App Server.
  1019. When disabling, you need to specify at least a ``jid`` and set ``disabled`` to
  1020. ``true``. This will disable notifications to all pubsub nodes on that "App
  1021. Server". If you want to disable only a particular node, then specify a ``node``
  1022. value as well.
  1023. For example:
  1024. .. code-block:: javascript
  1025. converse.initialize({
  1026. 'push_app_servers': [{
  1027. 'jid': 'push-4@client.example',
  1028. 'node': 'yxs32uqsflafdk3iuqo',
  1029. 'disable': true
  1030. }, {
  1031. 'jid': 'push-5@client.example',
  1032. 'node': 'yxs32uqsflafdk3iuqo',
  1033. }]
  1034. });
  1035. .. _`roomconfig_whitelist`:
  1036. roomconfig_whitelist
  1037. --------------------
  1038. * Default: ``[]``
  1039. A list of room config-option names. If this list is non-empty, only the corresponding room
  1040. config-options will be shown in the room configuration form. The default will show all options.
  1041. In the following example the user can only see (and thus change) the roomname and nothing else:
  1042. .. code-block:: javascript
  1043. roomconfig_whitelist: ['muc#roomconfig_roomname'],
  1044. root
  1045. ----
  1046. * Default: ``window.document``
  1047. When using Converse inside a web component's shadow DOM, you will need to set this settings'
  1048. value to the shadow-root of the shadow DOM.
  1049. For example:
  1050. .. code-block:: javascript
  1051. class CustomChatComponent extends HTMLElement {
  1052. constructor() {
  1053. super();
  1054. const shadowRoot = this.attachShadow({mode: "open"});
  1055. this.initConverse(shadowRoot);
  1056. }
  1057. initConverse(shadowRoot) {
  1058. window.addEventListener("converse-loaded", function(event) {
  1059. converse.initialize({
  1060. root: shadowRoot,
  1061. // Other settings go here...
  1062. });
  1063. });
  1064. }
  1065. }
  1066. roster_groups
  1067. -------------
  1068. * Default: ``true``
  1069. If set to ``true``, Converse will show any roster groups you might have configured.
  1070. .. note::
  1071. It's currently not possible to use Converse to assign contacts to groups.
  1072. Converse can only show users and groups that were previously configured
  1073. elsewhere.
  1074. send_chat_state_notifications
  1075. -----------------------------
  1076. * Default: ``true``
  1077. Determines whether chat state notifications (see `XEP-0085 <https://xmpp.org/extensions/xep-0085.html>`_) should be sent out or not.
  1078. Can also be set to an Array in order to allow only certain types of chat state notifications.
  1079. For example:
  1080. .. code-block:: javascript
  1081. converse.initialize({
  1082. 'send_chat_state_notifications': ['composing']
  1083. });
  1084. Valid values are ``'active', 'composing', 'gone' 'inactive', 'paused'``
  1085. show_chat_state_notifications
  1086. -----------------------------
  1087. * Default: ``false``
  1088. Specifies whether chat state (online, dnd, away) HTML5 desktop notifications should be shown.
  1089. show_client_info
  1090. ----------------
  1091. * Default: ``true``
  1092. Specifies whether the info icon is shown on the controlbox which when clicked opens an
  1093. "About" modal with more information about the version of Converse being used.
  1094. show_controlbox_by_default
  1095. --------------------------
  1096. * Default: ``false`` (``true`` when the ``view_mode`` is set to ``fullscreen``)
  1097. The "controlbox" refers to the special chatbox containing your contacts roster,
  1098. status widget, chatrooms and other controls.
  1099. By default this box is hidden and can be toggled by clicking on any element in
  1100. the page with class *toggle-controlbox*.
  1101. If this options is set to true, the controlbox will by default be shown upon
  1102. page load.
  1103. However, be aware that even if this value is set to ``false``, if the
  1104. controlbox is open, and the page is reloaded, then it will stay open on the new
  1105. page as well.
  1106. .. _`show-desktop-notifications`:
  1107. show_desktop_notifications
  1108. --------------------------
  1109. * Default: ``true``
  1110. Should HTML5 desktop notifications be shown?
  1111. If set to ``true``, notifications will be shown in the following cases:
  1112. * the browser is not visible nor focused and a private message is received.
  1113. * the browser is not visible nor focused and a groupchat message is received which mentions you.
  1114. * ``auto_subscribe`` is set to ``false`` and a new contact request is received.
  1115. If set to ``all``, notifications will be shown even if the above conditions are
  1116. not fulfilled.
  1117. Requires the `src/converse-notification.js` plugin.
  1118. show_message_avatar
  1119. -------------------
  1120. * Default: ``true``
  1121. Whether chat messages should also render the author's avatar.
  1122. show_images_inline
  1123. ------------------
  1124. * Default: ``true``
  1125. If set to ``false``, images won't be rendered in chats, instead only their links will be shown.
  1126. It also accepts an array strings of whitelisted domain names to only render images that belong to those domains.
  1127. E.g. ``['imgur.com', 'imgbb.com']``
  1128. show_retraction_warning
  1129. -----------------------
  1130. * Default: ``true``
  1131. From `XEP-0424: Message Retraction <https://xmpp.org/extensions/xep-0424.html>`_:
  1132. ::
  1133. Due to the federated and extensible nature of XMPP it's not possible to remove a message with
  1134. full certainty and a retraction can only be considered an unenforceable request for such removal.
  1135. Clients which don't support message retraction are not obligated to enforce the request and
  1136. people could have seen or copied the message contents already.
  1137. By default Converse shows a warning to users when they retract a message, to
  1138. inform them that they don't have a guarantee that the message will be removed
  1139. everywhere.
  1140. This warning isn't applicable to all deployments of Converse and can therefore
  1141. be turned off by setting this config variable to ``false``.
  1142. show_send_button
  1143. ----------------
  1144. * Default: ``true``
  1145. Adds a button to the chat which can be clicked or tapped in order to send the
  1146. message.
  1147. singleton
  1148. ---------
  1149. * Default: ``false``
  1150. If set to ``true``, then only one chat (one-on-one or groupchat) will be allowed.
  1151. The chat must be specified with the `auto_join_rooms`_ or `auto_join_private_chats`_ options.
  1152. This setting is useful together with `view_mode`_ set to ``embedded``, when you
  1153. want to embed a chat into the page.
  1154. Alternatively you could use it with `view_mode`_ set to ``overlayed`` to create
  1155. a single helpdesk-type chat.
  1156. smacks_max_unacked_stanzas
  1157. --------------------------
  1158. * Default: ``5``
  1159. This setting relates to `XEP-0198 <https://xmpp.org/extensions/xep-0198.html>`_
  1160. and determines the number of stanzas to be sent before Converse will ask the
  1161. server for acknowledgement of those stanzas.
  1162. sounds_path
  1163. -----------
  1164. * Default: ``${assets_path}/sounds/``
  1165. This option only makes sense in conjunction with the `play_sounds`_ option and
  1166. specifies the URL of the sound files to be played (exluding the file names
  1167. themselves).
  1168. In order to support all browsers we need both an MP3 and an Ogg file. Make sure
  1169. to name your files ``msg_received.ogg`` and ``msg_received.mp3``.
  1170. sticky_controlbox
  1171. -----------------
  1172. * Default: ``false`` (``true`` when the ``view_mode`` is set to ``fullscreen``).
  1173. If set to ``true``, the control box (which includes the login, registration,
  1174. contacts and rooms tabs) will not be closeable. It won't have a close button at
  1175. all.
  1176. The idea behind this setting is to provide a better experience on mobile
  1177. devices when the intent is to use Converse as a web app. In this case
  1178. it doesn't make sense to close the control box, as there's often then nothing
  1179. "behind" it that's relevant to the user.
  1180. .. _`strict_plugin_dependencies`:
  1181. strict_plugin_dependencies
  1182. --------------------------
  1183. * Default: ``false``
  1184. When set to ``true`` and a plugin tries to override an object which doesn't
  1185. exist (for example because the plugin which provides that object is not
  1186. loaded), then an error will be raised.
  1187. Otherwise a message will simply be logged and the override instruction ignored.
  1188. The Converse plugins architecture can have an :ref:`dependencies`
  1189. plugin attribute. This enables you to specify an array of other plugins which
  1190. this one depends on.
  1191. Converse (more specifically, `pluggable.js <https://jcbrand.github.io/pluggable.js/>`_)
  1192. will first load these dependencies before executing the plugin's overrides and
  1193. calling its ``initialize`` method.
  1194. This is especially important if you register event handlers in your plugin for
  1195. events that fire in other plugins. In this case, you want to specify those
  1196. other plugins as dependencies.
  1197. If ``strict_plugin_dependencies`` is set to ``false``, an error won't be raised
  1198. if the optional dependencies aren't found.
  1199. synchronize_availability
  1200. ------------------------
  1201. * Default: ``true``
  1202. * Valid options: ``true``, ``false``, ``a resource name``.
  1203. This option lets you synchronize your chat status (`online`, `busy`, `away`) with other chat clients. In other words,
  1204. if you change your status to ``busy`` in a different chat client, your status will change to ``busy`` in Converse as well.
  1205. If set to ``true``, Converse will synchronize with all other clients you are logged in with.
  1206. If set to ``false``, this feature is disabled.
  1207. If set to ``a resource name``, Converse will synchronize only with a client that has that particular resource assigned to it.
  1208. theme
  1209. -----
  1210. * Default: ``default``
  1211. * Valid options: ``default``, ``concord``
  1212. Let's you set a color theme for Converse.
  1213. trusted
  1214. -------
  1215. * Default: ``true``
  1216. This setting determines whether the default value of the "This is a trusted device"
  1217. checkbox in the login form.
  1218. When the current device is not trusted, then the cache will be cleared when
  1219. the user logs out.
  1220. Additionally, it determines the type of `browser storage <https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage>`_
  1221. (``localStorage`` or ``sessionStorage``) used by Converse to cache user data.
  1222. If ``trusted`` is set to ``false``, then ``sessionStorage`` is used instead of
  1223. ``localStorage``.
  1224. The main difference between the two is that ``sessionStorage`` only persists while
  1225. the current tab or window containing a Converse instance is open. As soon as
  1226. it's closed, the data is cleared (as long as there aren't any other tabs with
  1227. the same domain open).
  1228. Data in ``localStorage`` on the other hand is kept indefinitely.
  1229. The data that is cached includes your sent and received messages, which chats you had
  1230. open, what features the XMPP server supports and what your online status was.
  1231. Clearing the cache makes Converse much slower when the user logs
  1232. in again, because all data needs to be fetch anew.
  1233. If ``trusted`` is set to ``on`` or ``off`` the "This is a trusted device"
  1234. checkbox in the login form will not appear at all and cannot be changed by the user.
  1235. ``on`` means to trust the device as stated above and use ``localStorage``. ``off``
  1236. means to not trust the device (cache is cleared when the user logs out) and to use
  1237. ``sessionStorage``.
  1238. time_format
  1239. -----------
  1240. * Default: ``HH:mm``
  1241. Examples: ``HH:mm``, ``hh:mm``, ``hh:mm a``.
  1242. This option makes the time format for the time shown, for each message, configurable. Converse uses `DayJS <https://github.com/iamkun/dayjs>`_
  1243. for showing time. This option allows the configuration of the format in which ``DayJS`` will display the time for the messages. For detailed
  1244. description of time-format options available for ``DayJS`` you can check the
  1245. `default formatting options <https://github.com/iamkun/dayjs/blob/dev/docs/en/API-reference.md#displaying>`_ and the
  1246. `advanced options <https://github.com/iamkun/dayjs/blob/master/docs/en/Plugin.md#advancedformat>`_.
  1247. use_system_emojis
  1248. -----------------
  1249. * Default: ``true``
  1250. Determines whether emojis should be rendered by the user's system.
  1251. Not all operating systems support (all) emojis. So alternatively you can let
  1252. Converse render the emojis with `Twemoji <https://twemoji.twitter.com/>`_.
  1253. See also `emoji_image_path`_.
  1254. visible_toolbar_buttons
  1255. -----------------------
  1256. * Default:
  1257. .. code-block:: javascript
  1258. {
  1259. call: false,
  1260. spoiler: false,
  1261. emoji: true,
  1262. toggle_occupants: true
  1263. }
  1264. Allows you to show or hide buttons on the chatboxes' toolbars.
  1265. * *call*:
  1266. Provides a button with a picture of a telephone on it.
  1267. When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.
  1268. .. code-block:: javascript
  1269. converse.listen.on('callButtonClicked', function(data) {
  1270. console.log('Strophe connection is', data.connection);
  1271. console.log('Bare buddy JID is', data.model.get('jid'));
  1272. // ... Third-party library code ...
  1273. });
  1274. * *emoji*:
  1275. Enables rendering of emoji and provides a toolbar button for choosing them.
  1276. * *spoiler*:
  1277. Shows a button for showing`XEP-0382 <https://xmpp.org/extensions/xep-0382.html>`_ spoiler messages.
  1278. * *toggle_occupants*:
  1279. Shows a button for toggling (i.e. showing/hiding) the list of occupants in a chatroom.
  1280. .. _`websocket-url`:
  1281. websocket_url
  1282. -------------
  1283. * Default: ``undefined``
  1284. Example: ``ws://xmpp.example.com:5280/ws/``
  1285. Example with reverse-proxy and TLS: ``wss://xmpp.example.com/ws/``
  1286. This option is used to specify a
  1287. `websocket <https://developer.mozilla.org/en/docs/WebSockets>`_ URI to which
  1288. Converse can connect to.
  1289. Websockets provide a more modern and effective two-way communication protocol
  1290. between the browser and a server, effectively emulating TCP at the application
  1291. layer and therefore overcoming many of the problems with existing long-polling
  1292. techniques for bidirectional HTTP (such as `BOSH <https://en.wikipedia.org/wiki/BOSH>`_).
  1293. Please refer to your XMPP server's documentation on how to enable websocket
  1294. support.
  1295. .. _`view_mode`:
  1296. view_mode
  1297. ---------
  1298. * Default: ``overlayed``
  1299. * Allowed values: ``overlayed``, ``fullscreen``, ``mobile``, ``embedded``
  1300. The ``view_mode`` setting configures Converse's mode and resulting behavior.
  1301. * ``overlayed`` is the original mode, in which the chats appeared as small boxes overlaying a webpage which can contain arbitrary content.
  1302. * ``fullscreen`` is for a fullpage and single-page app.
  1303. * ``embedded`` is used to embed a single chat into a DOM element in the page. The DOM element must have the id ``#conversejs``.
  1304. * ``mobile`` is for smaller viewports. Converse is responsive, and the other views will also resize to fit a smaller viewport, but certain behavioural changes won't be made. For example, when using ``overlayed`` in a mobile view, Converse won't know which chat is currently visible and therefore won't be able to properly show notifications for chats that are obscured.
  1305. .. note::
  1306. Before the introduction of this setting (in version 3.3.0), there were there
  1307. different builds, each for the different modes.
  1308. These were:
  1309. * ``converse-mobile.js`` for the ``mobile`` mode
  1310. * ``converse-muc-embedded.js`` for embedding a single MUC room into a DOM element with id ``conversejs``
  1311. * ``converse.js`` for the ``overlayed`` mode
  1312. * ``inverse.js`` for the ``fullscreen`` mode
  1313. Besides having different builds, certain plugins had to be whitelisted
  1314. and blacklisted for the different modes.
  1315. ``converse-singleton`` had to be whitelisted for the ``mobile`` and ``fullscreen``
  1316. modes, additionally ``converse-inverse`` had to be whitelisted for the
  1317. ``fullscreen`` mode.
  1318. For both those modes the ``converse-minimize`` and ``converse-dragresize``
  1319. plugins had to be blacklisted.
  1320. When using ``converse-muc-embedded.js`` various plugins also had to manually be
  1321. blacklisted.
  1322. Since version 3.3.0 it's no longer necessary to blacklist any plugins (except
  1323. for ``converse-muc-embedded.js``, which is from version 3.3.3).
  1324. Blacklisting now happens automatically.
  1325. Since version 3.3.0, the ``inverse.js`` and ``converse-mobile.js`` builds no
  1326. longer exist. Instead the standard ``converse.js`` build is used, together with
  1327. the appropriate ``view_mode`` value.
  1328. Since version 4.0.0, there is now also only one CSS file to be used for all
  1329. the different view modes, ``converse.css``.
  1330. The ``converse-muc-embedded.js`` build can still be built, because it's smaller
  1331. than ``converse.js`` due to unused code being removed. It doesn't however contain
  1332. any new code, so the full ``converse.js`` build could be used instead, as long
  1333. as ``view_mode`` is set to ``embedded``.
  1334. Furthermore, it's no longer necessary to whitelist or blacklist any plugins
  1335. when switching view modes.
  1336. .. _`whitelisted_plugins`:
  1337. whitelisted_plugins
  1338. -------------------
  1339. * Default: ``[]``
  1340. A list of plugin names that are whitelisted and will therefore be
  1341. initialized once ``converse.initialize`` is called.
  1342. From Converse 3.0 onwards most of the API is available only to plugins and
  1343. all plugins need to be whitelisted first.
  1344. This is done to prevent malicious scripts from using the API to trick users or
  1345. to read their conversations.
  1346. By default all the core plugins are already whitelisted.
  1347. These are::
  1348. converse-bookmarks
  1349. converse-chatboxes
  1350. converse-chatview
  1351. converse-controlbox
  1352. converse-core
  1353. converse-disco
  1354. converse-dragresize
  1355. converse-fullscreen
  1356. converse-headline
  1357. converse-mam
  1358. converse-minimize
  1359. converse-muc
  1360. converse-muc-embedded
  1361. converse-notification
  1362. converse-ping
  1363. converse-profile
  1364. converse-register
  1365. converse-roomslist
  1366. converse-rosterview
  1367. converse-singleton
  1368. converse-spoilers
  1369. converse-vcard'
  1370. .. note::
  1371. If you are using a custom build which excludes some core plugins, then you
  1372. should blacklist them so that malicious scripts can't register their own
  1373. plugins under those names. See `blacklisted_plugins`_ for more info.
  1374. Example:
  1375. .. code-block:: javascript
  1376. require(['converse-core', 'converse-muc-embedded'], function (converse) {
  1377. converse.initialize({
  1378. // other settings removed for brevity
  1379. whitelisted_plugins: ['myplugin']
  1380. });
  1381. });
  1382. xhr_user_search_url
  1383. -------------------
  1384. .. note::
  1385. XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
  1386. * Default: ``null``
  1387. There are two ways to add users.
  1388. * The user inputs a valid JID (Jabber ID, aka XMPP address), and the user is added as a pending contact.
  1389. * The user inputs some text (for example part of a first name or last name),
  1390. an XHR (Ajax Request) will be made to a remote server, and a list of matches are returned.
  1391. The user can then choose one of the matches to add as a contact.
  1392. By providing an XHR search URL, you're enabling the second mechanism.
  1393. *What is expected from the remote server?*
  1394. A default JSON encoded list of objects must be returned. Each object
  1395. corresponds to a matched user and needs the keys ``jid`` and ``fullname``.
  1396. .. code-block:: javascript
  1397. [{"jid": "marty@mcfly.net", "fullname": "Marty McFly"}, {"jid": "doc@brown.com", "fullname": "Doc Brown"}]
  1398. .. note::
  1399. Make sure your server script sets the header `Content-Type: application/json`.
  1400. This is the URL to which an XHR GET request will be made to fetch user data from your remote server.
  1401. The query string will be included in the request with ``q`` as its key.
  1402. The data returned must be a JSON encoded list of user JIDs.
  1403. .. note::
  1404. Converse will construct the XHR get URL by simply appending
  1405. ``q=<query string entered>`` to the URL given by ``xhr_user_search_url``.
  1406. It is therefore important that the necessary question mark (``?``) preceding the
  1407. URL's query component or necessary delimiters (``&``) are included. See valid
  1408. examples below.
  1409. Examples:
  1410. .. code-block:: javascript
  1411. xhr_user_search_url: 'https://some.url/some_path?',
  1412. xhr_user_search_url: 'https://some.url/some_path?api_key=somekey&',