Adding support for protocol handler #3870

marcellintacite · 2025-10-01T08:04:30Z

Here's a draft for this issue : #1247
This merge request adds support for handling xmpp: protocol links in Converse.js, allowing users to click links like xmpp:[email protected] to automatically open a chat with the specified JID if logged in. This enhances user experience by enabling seamless integration with external XMPP links (e.g., from emails, websites, or other apps).

Before submitting your request, please make sure the following conditions are met:

Add a changelog entry for your change in CHANGES.md
When adding a configuration variable, please make sure to
document it in docs/source/configuration.rst
Please add a test for your change. Tests can be run in the commandline
with make check or you can run them in the browser by running make serve
and then opening http://localhost:8000/tests.html.

src/index.js

src/plugins/protocol-handler/index.js

…tion

src/headless/plugins/chat/utils.js

src/plugins/chatview/index.js

jcbrand · 2025-10-07T13:28:59Z

Looking good so far @marcellintacite!

Please also remember to update the DOAP file to mention support for the new XEP
https://github.com/conversejs/converse.js/blob/master/conversejs.doap

manifest.json

src/plugins/chatview/utils.js

src/plugins/chatview/index.js

Co-authored-by: JC Brand <[email protected]>

CHANGES.md

Co-authored-by: JC Brand <[email protected]>

conversejs.doap

marcellintacite · 2025-10-15T06:13:00Z

@jcbrand Hello, i would like your review for the test i wrote

manifest.json

src/plugins/chatview/utils.js

src/plugins/chatview/tests/query-actions.js

Co-authored-by: JC Brand <[email protected]>

src/plugins/chatview/utils.js

marcellintacite · 2025-11-03T05:48:59Z

@jcbrand i need your help on tests so i can get done with this PR. I am facing some errors

marcellintacite · 2025-11-10T11:14:21Z

Hello @jcbrand i have fixed test issue

src/plugins/chatview/tests/query-actions.js

src/plugins/chatview/utils.js

marcellintacite · 2026-01-07T07:26:10Z

Hi @jcbrand , could you please provide an update on this Pull Request? I'd like to know what's left to address so we can proceed with merging it.

jcbrand

Hi @marcellintacite

I took some time to review this PR. Thanks a lot for the work you've done on this so far.

Please have a look at this comment first:
https://github.com/conversejs/converse.js/pull/3870/changes#r2667473276

Since it's the most important one of my review.

It's important that we stick to the plugin architecture and separation of concerns, which is why I think you need to move the functionality to separate plugins.

The roster-related stuff should go into the rosterview plugin and the other actions can go into chatboxviews (which encompasses both MUC and 1:1 whereas chatview is only 1:1).

Let me know if you have any questions or if anything is unclear.

jcbrand · 2026-01-07T07:53:12Z

CHANGES.md

 - #3769: Various OMEMO fixes
 - #3791: Fetching pubsub node configuration fails
 - #3792: Node reconfiguration attempt uses incorrect field names
+- Adds support for opening XMPP URIs in Converse and for XEP-0147 query actions


This line is under an already released version, it should go under ## Next release.

I think you should also rebase this PR onto the latest commit in the master branch.

jcbrand · 2026-01-07T07:55:48Z

src/plugins/chatview/utils.js

+    // hash-based (#converse/action?uri=...)
+    if (location.hash.startsWith('#converse/action?uri=')) {
+        event?.preventDefault();
+        uri = location.hash.split('uri=').pop();


Have you tried splititng with the full string? If that works it will be safer.

Suggested change

uri = location.hash.split('uri=').pop();

uri = location.hash.split('#converse/action?uri=').pop();

jcbrand · 2026-01-07T07:57:06Z

src/plugins/chatview/utils.js

+
+    // Decode URI and remove xmpp: prefix
+    uri = decodeURIComponent(uri);
+    if (uri.startsWith('xmpp:')) uri = uri.slice(5);


When would it not start with xmpp: and would it then still be legitimate?

jcbrand · 2026-01-07T07:58:03Z

src/plugins/chatview/utils.js

+    const cleanUrl = `${window.location.origin}${window.location.pathname}`;
+    window.history.replaceState({}, document.title, cleanUrl);


We use snake_case for variable names.

Suggested change

const cleanUrl = `${window.location.origin}${window.location.pathname}`;

window.history.replaceState({}, document.title, cleanUrl);

const clean_url = `${window.location.origin}${window.location.pathname}`;

window.history.replaceState({}, document.title, clean_url);

jcbrand · 2026-01-07T08:16:40Z

src/plugins/chatview/utils.js

+
+        case 'add-roster':
+            await handleRosterAction(jid, query_params);
+            break;


Adding users to the roster is not the responsibility of the chatview plugin, which is mainly responsible with showing a UI for 1:1 chats.

We have a plugin architecture in Converse.js and we ideally want each plugin to be solely responsible for its domain.

So the rosterview plugin should be responsible for checking whether there is a roster-related query action.

And if we later have MUC related query actions, they should go into the muc_views plugin, and so on.

The main way in which we enable separation of concerns between the different plugins, is by triggering events and then letting those plugins listen for these events.

So, I think this function needs to be refactored and the roster specific code should be moved into a function in rosterview plugin. You can give it the same name, so there's a routeToQueryAction function here which is only responsible for opening chats and sending messages, and another routeToQueryAction function in rosterview/utils.js which is responsible for handling roster actions.

Then inside the rosterview plugin you also call routeToQueryAction.

Additionally, the other two actions, sending a message and opening a chat apply to both MUCs and 1:1 chats, right? So they should go out of this plugin and into the chatboxviews plugin, since that plugin encompasses both MUC and 1:1 and this particular plugin is only concerned with 1:1 chats.

That way, we avoid spaghetti code and plugins that do things outside of their scope.

jcbrand · 2026-01-07T08:19:39Z

src/plugins/chatview/index.js

+            } catch (error) {
+                console.warn('Failed to register protocol handler:', error);
+            }
+        }


This section of code is more low-level and not directly related to the chatview plugin, so it should go somewhere else.

I think a better place would be to put it inside src/entry.js.

jcbrand · 2026-01-07T08:20:29Z

src/plugins/chatview/tests/query-actions.js

+     * Test roster add functionality when action=add-roster
+     * This tests URI parsing and adding a contact to the roster
+     */
+    it("adds a contact to roster when action=add-roster",


This test should go into the rosterview plugin once you've done this:
https://github.com/conversejs/converse.js/pull/3870/changes#r2667473276

The other tests should go into the chatboxviews plugin, as explained in the above-linked comment.

Adding support for protocol handler

2ba6ada

marcellintacite marked this pull request as draft October 1, 2025 08:05

jcbrand reviewed Oct 1, 2025

View reviewed changes

src/index.js Outdated Show resolved Hide resolved

jcbrand reviewed Oct 1, 2025

View reviewed changes

src/plugins/protocol-handler/index.js Outdated Show resolved Hide resolved

src/plugins/protocol-handler/index.js Outdated Show resolved Hide resolved

Move protocol handler into chatView and update the route to chat func…

9c5f20d

…tion

jcbrand reviewed Oct 6, 2025

View reviewed changes

src/headless/plugins/chat/utils.js Outdated Show resolved Hide resolved

src/plugins/chatview/index.js Outdated Show resolved Hide resolved

Adding support for the XEP-0147 (Protocol handler)

5b41936

marcellintacite force-pushed the add-protocol-handler branch from 28e327a to 5b41936 Compare October 7, 2025 11:57

jcbrand reviewed Oct 7, 2025

View reviewed changes

marcellintacite and others added 4 commits October 7, 2025 16:01

Update src/plugins/chatview/utils.js

be0d75c

Co-authored-by: JC Brand <[email protected]>

Update src/plugins/chatview/utils.js

a32cec0

Co-authored-by: JC Brand <[email protected]>

Update src/plugins/chatview/utils.js

956b471

Co-authored-by: JC Brand <[email protected]>

Updating the DOAP, updating url

40f8f7f

jcbrand reviewed Oct 9, 2025

View reviewed changes

CHANGES.md Outdated Show resolved Hide resolved

marcellintacite and others added 3 commits October 13, 2025 06:56

Adding test for the routeToQuestionAction function

29af0c9

Merge branch 'conversejs:master' into add-protocol-handler

80114ef

Update CHANGES.md

40538e3

Co-authored-by: JC Brand <[email protected]>

jcbrand reviewed Oct 13, 2025

View reviewed changes

conversejs.doap Outdated Show resolved Hide resolved

Updating the doap file

71e9037

jcbrand requested changes Oct 15, 2025

View reviewed changes

marcellintacite and others added 3 commits October 15, 2025 09:29

Update manifest.json

baaced6

Co-authored-by: JC Brand <[email protected]>

Removing the protocol handler (?uri=...)

ff769df

Fix: Adding routeToQuery in the u object

0e3175b

github-advanced-security bot found potential problems Oct 28, 2025

View reviewed changes

src/plugins/chatview/utils.js Fixed Show fixed Hide fixed

Fix: Adding routeToQuery in the u object

a22c1a0

marcellintacite added 2 commits November 10, 2025 12:38

Fixing tests

8c91e48

chore: remove genkit metadata

cd88326

marcellintacite marked this pull request as ready for review November 10, 2025 10:47

marcellintacite force-pushed the add-protocol-handler branch 2 times, most recently from 67fa8c7 to cd88326 Compare November 10, 2025 10:55

jcbrand reviewed Dec 14, 2025

View reviewed changes

src/plugins/chatview/tests/query-actions.js Outdated Show resolved Hide resolved

jcbrand reviewed Dec 14, 2025

View reviewed changes

src/plugins/chatview/utils.js Outdated Show resolved Hide resolved

Fix : Updating test to It() and removing unecessary try catch block

c3efbe0

marcellintacite requested a review from jcbrand January 7, 2026 07:26

jcbrand requested changes Jan 7, 2026

View reviewed changes

	uri = location.hash.split('uri=').pop();
	uri = location.hash.split('#converse/action?uri=').pop();

		const cleanUrl = `${window.location.origin}${window.location.pathname}`;
		window.history.replaceState({}, document.title, cleanUrl);

Uh oh!

Adding support for protocol handler #3870

Are you sure you want to change the base?

Adding support for protocol handler #3870

Uh oh!

Conversation

marcellintacite commented Oct 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jcbrand commented Oct 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcellintacite commented Oct 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcellintacite commented Nov 3, 2025

Uh oh!

marcellintacite commented Nov 10, 2025

Uh oh!

Uh oh!

Uh oh!

marcellintacite commented Jan 7, 2026

Uh oh!

jcbrand left a comment

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

jcbrand Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants