Slidge is an XMPP gateway designed to connect your account to third-party chat networks like WhatsApp, Telegram, or Matrix. It acts as a bridge, allowing you to send and receive messages with all your contacts directly from your single, preferred XMPP client.
This guide provides instructions to configure an Openfire XMPP server to work with Slidge and the Slidge WhatsApp plugin as an example.
Openfire requires configuration in its Admin Console to allow external components like Slidge to connect and to grant them the necessary permissions for features like file transfers.
Prerequisites
Before you begin, ensure you have:
- A running and accessible Openfire server.
- Administrative access to the Openfire Admin Console.
- Root or sudo access to the Debian/Ubuntu server where you will install Slidge.
- The Slidge Debian repository added to your system, as per the official Slidge installation instructions (Installation - Slidge documentation).
This guide used the below install method.
Step 1: Configure Openfire Services
You must configure Openfire to accept the bridge connection and handle file transfers before you configure Slidge.
1.1. Install and Configure HTTP File Upload Plugin
Slidge requires a working XEP-0363 HTTP File Upload component to send and receive images, videos, and other files.
- Log in to your Openfire Admin Console.
- Navigate to Server → Plugins → Available Plugins.
- Find the plugin named “HTTP File Upload” and click the green + icon to install it.
- After installation, navigate to Server → Server Settings → HTTP File Upload.
- Ensure the box for “Enable HTTP File Upload” is checked.
Take note of the configuration. For a standard setup behind a reverse proxy, your public URL might be https://upload.your.domain
while the internal service address is httpfileupload.your.domain
.
We will use this internal address later.
- Click Save Settings.
1.2. Enable External Component Connections
This step allows Openfire to listen for incoming connections from bridges.
In the Openfire Admin Console, navigate to Server → Server Settings → External Components.
- Ensure the service is Enabled.
- Under the “Allowed to Connect” section, define your new WhatsApp bridge:
- Subdomain:
whatsapp
(This will create the JIDwhatsapp.your.domain
). - Shared Secret: Create a new, strong, random password.
- Copy this shared secret to a safe place. You will need it for the Slidge configuration.
- Click “Add”.
Your Openfire server is now ready for Slidge.
Step 2: Install and Configure Slidge
Now, on your server’s command line, we will install and configure the Slidge packages.
2.1. Install Slidge Packages
As per these instructions: slidge/debian: Debian (unofficial) package bundling slidge-based gateways. - Codeberg.org
2.2. Configure common.conf
This file contains settings shared by all your bridges.
- Edit the file:
nano /etc/slidge/conf.d/common.conf
- Set the following parameters:
admins=admin@your.domain upload-service=httpfileupload.your.domain user-jid-validator=.*@your.domain server=localhost #port=5347 #(default slidge setting) port=5275 #(openfire default)
2.3. Configure whatsapp.conf
This file contains the settings for the WhatsApp bridge specifically.
- Create or edit the file:
nano /etc/slidge/whatsapp.conf
(I just didmv /etc/slidge/whatsapp.conf.example /etc/slidge/whatsapp.conf
) - Add the connection details to match what you configured in Openfire:
# The XMPP address of your bridge component jid = whatsapp.your.domain # The shared secret you created in the Openfire admin console secret = PASTE_YOUR_SHARED_SECRET_HERE legacy-module=slidge.plugins.whatsapp
Step 3: Start and Verify Slidge
Enable and start the Slidge WhatsApp service:
sudo systemctl enable --now slidge@whatsapp
Check the logs to ensure it started without errors:
sudo journalctl -u slidge@whatsapp -f
Step 4: User Registration and Login
From your XMPP client (e.g., Conversations, Gajim), discover the services on your server. You should see the “WhatsApp” bridge listed.
Register with the service.
The bridge (whatsapp.your.domain
) will be added to your contacts. Send it the message login or qr.
(I just started a conversation with a new chat to whatsapp.you.domain
and typed help
, it gives a list of commands, follow these e.g register
)
You may see warnings in the Slidge log about “IQ privileges not granted” for pubsub and bookmarks (XEP-0356).
Troubleshooting: Fixing Permission Warnings (not yet implemented in Openfire so can’t fix this just yet)
For good luck I also did this at the end.
sudo systemctl restart openfire
sudo systemctl restart slidge@whatsapp
1 post - 1 participant