[How To] How to enable websockets (xmpp-websocket) and smacks for Prosody

This topic will help you enable websockets and smacks for your self-hosted meeting server.

This websocket is used for signaling data between the client and your XMPP Prosody server. It can replace BOSH on desktops but since the mobile Jitsi-meet apps cannot use a websocket, you will need to support both in your server config.

:fire:This websocket should not be confused with the websocket used between the client and the video bridge.

To increase tolerance for network blips or disconnects you should also enable smacks (mod_smacks). which “can allow a client to resume a disconnected session, and prevent message loss.” Learn more mod_smacks.

1. Upgrade Prosody to 0.11.7

2. Update your Prosody config to enable websockets and smacks

In /etc/prosody/conf.avail/meet.domain.com.cfg.lua add websocket and smacks to modules_enabled.

Also add the websocket options: cross_domain_websocket and consider_websocket_secure to true:

       cross_domain_websocket = true;
       consider_websocket_secure = true;

        VirtualHost "meet.domain.com"
         modules_enabled = {

         smacks_max_unacked_stanzas = 5;
         smacks_hibernation_time = 60; 
         smacks_max_hibernated_sessions = 1;
         smacks_max_old_sessions = 1;

:pushpin: If you are using Jibri, make sure you enable smacks in that VirtualHost section as well.

3. Update your nginx config to map xmpp-websocket

In /etc/nginx/sites-available/meet.domain.com.conf add a section to map the location /xmpp-websocket. Note: This should match BOSH. If /http-bind points to 5280 then /xmpp-websocket should too:

Update: 2021-05-11T04:00:00Z Add the x-jitsi-shard and Access-Control-Expose-Headers headers to avoid the Detected that shard changed from ... to null error

# ...

    listen meet.domain.com:443 ssl http2;
    server_name meet.domain.com;

# ...

    location = /xmpp-websocket
        proxy_pass http://localhost:5280/xmpp-websocket;
        #shard & region that matches config.deploymentInfo.shard/region -  See [note 1] below
        add_header 'x-jitsi-shard' 'shard';
        add_header 'x-jitsi-region' 'us-east-2a';
        add_header 'Access-Control-Expose-Headers' 'X-Jitsi-Shard, X-Jitsi-Region';

        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $http_host;

        proxy_http_version 1.1;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size  256k;
        proxy_set_header Connection "upgrade";
        tcp_nodelay on;
# ...

[Note 1] See config.deploymentInfo.shard & config.deploymentInfo.region

4. Enable Websockets in your config.js

Edit your /etc/jitsi/meet/meet.domain.com-config.js and uncomment the Websocket URL:

     // BOSH URL
    bosh: '//meet.domain.com/http-bind',

    // Websocket URL
    websocket: 'wss://meet.domain.com/xmpp-websocket',

5. Restart Services

service nginx restart && service prosody restart && service jicofo restart

:white_check_mark: All Done! Retest meetings with the impacted users. They should no longer see similar disconnects.

:pushpin: Other Notes:

  1. If you are running Prosody 0.11.7, no manual patching is necessary as you may see in other posts.
  2. Verify that mod_websocket.lua is found in /usr/lib/prosody/modules/
  3. Verify that mod_smacks.lua is found in /usr/share/jitsi-meet/prosody-plugins/

Other useful links:

  1. State of XMPP connection : Bosh or websocket?
  2. configure xmmp framework to support both websocket and BOSH
  3. WebSockets – Prosody IM

Other keywords: bosh, D.Bosh._onRequestStateChanged, UnhandledError: null Script: null Line: null, “Detected that shard changed from undefined to null”


@corby as I read that smack allows a client to resume a disconnected session, and prevent message loss.
have you noticed any performance benefits after enabling websockets and smacks?

Can you please share what other benefits we will get after this configuration?

may time in jitsi video quality drops frequently,

forcing resolution by providing min value for the resolution and decreasing frame rate in config .js doesn’t do any significant improvements, disabling simulcast will lead to more bandwidth usage from the server-side. any advice for that?

surprisingly when I visit from the jitsi’s mobile app to jitsi web app then from mobile app it’s give awesome result but when I visit mobile browser to desktop browser then not that much good result.

This is strictly a connection stability improvement setting. We found it addressed the following issue:

[Issue] Why do some users drop randomly on Chrome and how to fix it using xmpp-websocket

I haven’t noticed impacts on performance or video quality.

1 Like

@corby thanks for this post,
in secure domain do we need also add this config to guest virtual host as well? I see you mentioned jibri!
I’m planning to implement this feature and test it. because also my instance suffers from this issue people get disconnected many times during the conference.

How can I test if xmpp-websocket is used or not by my server?

I see this massage on my browser:

I cannot get a response from the websocket within Jitsi-meet javascript.
web_1 | - - [09/Feb/2021:18:11:38 +0100] “GET /xmpp-websocket?room=test HTTP/1.1” 403 284 “-” “Mozilla/5.0 (Windows NT 10.0; rv:78.0) Gecko/20100101 Firefox/78.0”

However a http/2 call from the browser works:

web_1 | - - [09/Feb/2021:18:12:19 +0100] “GET /xmpp-websocket HTTP/2.0” 200 152 “-” “Mozilla/5.0 (Windows NT 10.0; rv:78.0) Gecko/20100101 Firefox/78.0”

My conclusion is that the javascript cannot open a http/2 connection to the websocket.

why is this working for you? old browsers? mine is firefox 85 or chrome 88 which are stuck on http/2

the nginx rule for /xmpp-websocket contains proxy_http_version 1.1;


I have same problem. I can enable smack for auth user. Also I add Smack pluging at guest domain to.

VirtualHost “guest.meet.com
authentication = “anonymous”
modules_enabled = {

At that point I can see smacks messages at websocket when i join the room as guest user. However, I can not resume conference if there is a connection failure. I get that error

<resume h=‘25’ previd=‘db78152f-fdf8-47db-b0b2-75d61fc9138f’ xmlns=‘urn:xmpp:sm:3’
Tried to resume non-existent session with id db78152f-fdf8-47db-b0b2-75d61fc9138f

with the smacks config inside the virtualhost definition I got error messages on the client side in the browser console that smacks is not working.
After moving the smacks config to the global prosody.cfg.lua the error messages vanished and smacks seems to work.

Yes I can manage to work when i move smacks config to global side… But still can not resume for guest users. I explain situation here → How to use Smacks Plugin + Websocket with Anonymous Domains

Hi @engesin , you get xmpp-websocket and smacks working?

hi @Yassine

Yes I can. All details are as follows

I set “smack” to global plugin of prosody rather than virtual host plugin.

could you share the steps and tips? thank you in advance!

@engesin you mean you enabled the the plugings websocket and smaks in /etc/prosody/prosody.cfg.lua right?

-- This is the list of modules Prosody will load on startup.
-- It looks for mod_modulename.lua in the plugins folder, so make sure that exists too.
-- Documentation for bundled modules can be found at: https://prosody.im/doc/modules
 modules_enabled = {

        -- Generally required
                "roster"; -- Allow users to have a roster. Recommended ;)
                "saslauth"; -- Authentication for clients and servers. Recommended if you want to log in.
        -- HTTP modules
                --"bosh"; -- Enable BOSH clients, aka "Jabber over HTTP"
                "websocket"; -- XMPP over WebSockets
                --"http_files"; -- Serve static files from a directory over HTTP

Yes exactly :+1:

Thanks Bro!

also these variables I guess should be added on /etc/prosody/prosody.cfg.lua :

modules_enabled = {
smacks_max_unacked_stanzas = 5;
smacks_hibernation_time = 60;
smacks_max_hibernated_sessions = 1;
smacks_max_old_sessions = 1;

Yes true,

However I set

smacks_max_unacked_stanzas = 3;
smacks_hibernation_time = 60;
smacks_max_hibernated_sessions = 100;
smacks_max_old_sessions = 100;

especially setting session to 1 is weird. there may multiple failure at the same time so I set session values as 100. If anyone figure out effect of that, welcomed…

1 Like

You can have problems with jibri as they use the same username, same jid. The values mentioned, I think, are those running on meet.jit.si for an year now and we haven’t seen problems (except jibri and we adjusted the values). I can double check later …

could you confirm if these values are ok?

smacks_max_hibernated_sessions = 100;
smacks_max_old_sessions = 100


1 Like

smacks_max_hibernated_sessions = 1 in general section (default for all).

For the recorder.your.domain virtualhost you can set smacks_max_hibernated_sessions = 1000 if you have less than 1000 jibris.

smacks_max_old_sessions = 1; is fine.

I applied these variables on the global config : /etc/prosody/prosody.cfg.lua not on mydomain-config.lua.
is this make a sense? or in each virtual host, main one, guest and recoder I need put these variables?

Big thanks :slight_smile: