feat: Matrix Integration for EmbeddedChat

[Aryan-Verma-999]

feat: Matrix Integration for EmbeddedChat

Acceptance Criteria fulfillment

• Integrate EmbeddedChat with the new Rocket.Chat native Matrix homeserver while keeping direct access to Rocket.Chat as an alternate option.
• EmbeddedChat has a configuration option (mode prop) to choose between using the native Matrix homeserver and direct Rocket.Chat access.
• When configured to use the native Matrix homeserver, EmbeddedChat can connect to a single configured channel, join it, and send and receive messages successfully.
• Documentation is added explaining how to configure EmbeddedChat for the native Matrix homeserver and how to switch between Matrix and direct Rocket.Chat modes.
  Fixes Epic: EmbeddedChat integration with Rocket.Chat native Matrix homeserver #1029

Video/Screenshots

PR Test Details

1. Run yarn storybook.
2. Go to the EmbeddedChat story.
3. In the Controls panel, switch mode to matrix.
4. Enter a valid Matrix host (e.g., https://matrix.org) and roomId.
5. Log in and verify message sending/receiving.

Note: The PR will be ready for live testing at https://rocketchat.github.io/EmbeddedChat/pulls/pr-1030 after approval. Contributors are requested to replace <pr_number> with the actual PR number.

[CLAassistant]

All committers have signed the CLA.

[Aryan-Verma-999]

Hi @Spiral-Memory , when you get time, could you take a quick look at this PR?

I've implemented the first pass for matrix integration

[Pratheek555]

Hey @Aryan-Verma-999!

If I am not wrong, there are some linting issues with the file packages/api/src/EmbeddedChatApi.ts, please do give it a check. If I am mistaken, ignore this message.

Thank you!

[Spiral-Memory]

Hi @Aryan-Verma-999,
Could you please format it using Prettier? Thanks!

[Aryan-Verma-999]

Hi @Spiral-Memory !,
Thanks for the review! I've applied prettier formatting and verified that all linting checks pass. The changes have been pushed.
Please let me know if you need any other changes!

[Spiral-Memory]

@Aryan-Verma-999 Could you please attach a demo video showcasing all the features you’ve implemented? This would help us understand it better. Great work, by the way!

[Aryan-Verma-999]

Hi @Spiral-Memory ,

I've recorded a demo video showcasing all the implemented features. Here's what's demonstrated:

Features Demonstrated

1. Authentication & Connection
   • Single-click login with Matrix credentials
   • Automatic connection to Matrix homeserver
   • Successful sync with server
2. Room Management
   • Auto-joining configured Matrix room
   • Room info display (name, avatar)
3. Message History
   • Loading existing messages on connect
   • Correct message ordering (newest at bottom)
   • Display names shown for all users
4. Real-time Messaging
   • Sending messages to Matrix room
   • Receiving messages in real-time
   • No duplicate messages
5. Mode Switching
   • Easy toggle between rocketchat and matrix modes via the mode prop

demo-pr-1030.mp4

All core functionality is working as expected for public, unencrypted Matrix rooms.
Note: Encrypted rooms show a placeholder message ("⚠️ [Encrypted Message]") as E2EE support is not yet implemented.

Please let me know if you'd like me to demonstrate any specific scenarios or if you have any questions!

[Spiral-Memory]

Thanks, @Aryan-Verma-999. I'll go through it and post the updates. Thanks a lot for your contribution.

[Spiral-Memory]

The video looks great. In the description, you mentioned it can display avatar images and room avatars, so please share a screenshot of this with some pictures. It would also be helpful if the video could demonstrate two-way communication for better understanding, with both users being different, to see if it renders correctly all other modes. One small suggestion: instead of having a separate folder for matrix mode, consider naming it like the others, such as WithMatrix.

Great job so far; this might take some time for review and a few iterations, so be sure to collaborate.

[Spiral-Memory]

I think you’re using the Matrix JS-SDK but we don’t want to log in directly with Matrix credentials. Instead, we want to use the Rocket.Chat-built homeserver. The current implementation might not correct, so please check the homeserver setup. I should be able to log in with Rocket.Chat credentials and still send messages to Matrix, with the homeserver possibly running on your system to make this work.

Please have a look at : https://github.com/RocketChat/homeserver

[Aryan-Verma-999]

Thanks for pointing this out. I’ll switch the implementation to use the Rocket.Chat homeserver instead of direct Matrix credential login. I’ll go through the homeserver repo, set it up locally, and adjust the flow so users authenticate with their Rocket.Chat credentials while still being able to send messages to Matrix rooms. I’ll update the PR once I have this aligned

[Spiral-Memory]

Hi @Aryan-Verma-999
Any update on it ?

[Aryan-Verma-999]

Hi @Spiral-Memory , sorry for the delay

i had university exams over the past few weeks, and during that time i also reassessed the approach for matrix integration. while working on it, i realized that with rocket.chat's shift towards native federation (which is still in alpha) and the homeserver, the intended integration flow isnt clear yet, especially around message send and receive endpoints

i also couldn't find any concrete documentation around the homeserver expected client side integration, which made it hard to validate assumptions. to clarify this, i tried reaching out to gazzo and diego as well to understand the intended setup, but im still waiting to hear back

before pushing further changes i wanted to align on the expected direction. ive been looking into the homeserver side to understand how embeddedchat is expected to interact with it at this stage

im actively back on this now and would appreciate guidance on the preferred approach so i can continue in the right direction

thanks for your patience
sorry again for the delay

[Spiral-Memory]

No worries, take your time

[Spiral-Memory]

Requesting changes as discussed

[Aryan-Verma-999]

Hi Zeeshan,

Quick update:

I've completed the implementation approach for integrating EmbeddedChat with Rocket.Chat's native federation.

However, during testing I discovered a server-side limitation in Rocket.Chat: when users self-join federated rooms (without being explicitly invited), they're not registered on the Matrix homeserver. This means their messages don't federate to remote Matrix users.

I've raised an issue in the Rocket.Chat repo explaining the problem and proposing solutions: issue

Once that's resolved on the RC side, I'll push the EmbeddedChat changes. The client-side work is ready and waiting.

Let me know if you have any questions or want to discuss alternative approaches in the meantime.

[Aryan-Verma-999]

Hi @Spiral-Memory, quick update
The federation self-join bug I found on the RC side (RocketChat/Rocket.Chat#38239) is moving along. ggazzo picked it up and I'm working with him to help get it fixed.
Will circle back and update this PR once the upstream fix lands :)

[Spiral-Memory]

Hi @Spiral-Memory, quick update The federation self-join bug I found on the RC side (RocketChat/Rocket.Chat#38239) is moving along. ggazzo picked it up and I'm working with him to help get it fixed. Will circle back and update this PR once the upstream fix lands :)

Sure, thanks @Aryan-Verma-999
Let me know once this is ready for review, i am marking it as draft

[Aryan-Verma-999]

pushed a major update to this pr
implementation has been completely rewritten to use RC's native federation, removing the matrix-js-sdk dependency entirely. users now authenticate with RC creds and RC handles the matrix federation layer transparently

keeping as draft until upstream self-join fix lands

[Spiral-Memory]

Please resolve the conflicts

[Aryan-Verma-999]

Conflicts resolved and rebased on latest develop.
While testing I also noticed image attachment previews returning 403 now, likely because of recent upload api change.
would you like me to open an issue + PR for this or wait until you clear the current backlog

[Pratheek555]

Conflicts resolved and rebased on latest develop. While testing I also noticed image attachment previews returning 403 now, likely because of recent upload api change. would you like me to open an issue + PR for this or wait until you clear the current backlog

Yep noticed the same issue with the attachment previews.

[Spiral-Memory]

Conflicts resolved and rebased on latest develop. While testing I also noticed image attachment previews returning 403 now, likely because of recent upload api change. would you like me to open an issue + PR for this or wait until you clear the current backlog

Pls raise that and tag me on that mentioning "critical fix"

[deepak0x]

Hey @Aryan-Verma-999 and @Spiral-Memory

While looking at the upstream self-join bug (RocketChat/Rocket.Chat#38239), I've been researching if there's a way we can work around it on the EmbeddedChat side — without waiting for the RC fix to land.

Found two approaches that could unblock this PR:

---

Option 1 — Self-Invite Pattern (no extra config needed)

The root cause of the bug is that channels.join sets inviter = null, which causes the federation hook to skip homeserver registration. But channels.invite always has an inviter (the caller), which satisfies the hook condition and triggers proper Matrix registration.

The trick: when a user opens a federated room in EmbeddedChat, instead of calling channels.join, we call channels.invite with the user's own userId in the invite list. This makes RC think the user was invited (by themselves), the federation hook fires, and they get registered on the Matrix homeserver — so their messages federate correctly.

Verified this by reading the RC source directly:

• beforeAddUserToRoom hook checks if (!inviter) return — this is the exact line that blocks self-joiners
• channels.invite passes the calling user as inviter → condition passes → homeserver registration happens

Implementation would be a small change in EmbeddedChatApi.ts — detect if the room is federated on mount, and use the invite endpoint instead of join.

---

Option 2 — Admin Bot Pre-Invite (opt-in, more reliable)

EmbeddedChat could accept an optional adminToken prop. When a user loads a federated room, EmbeddedChat uses the admin token to invite the user before they send any message. This is 100% reliable and matches how most production federated rooms would be managed anyway.

---

Option 1 is the cleanest since it requires zero extra setup from the developer embedding the chat. Happy to implement either if it sounds good to you both — would love your thoughts on whether Option 1 is a safe assumption about RC's invite flow behavior.

[Aryan-Verma-999]

Hey @deepak0x , thanks for diving into this

i actually tested option 1 earlier. the self-invite approach does pass the !inviter check, But there's another check in the same beforeAddUserToRoom federation hook that blocks it:

if (!isUserNativeFederated(user) && !(await FederationMatrix.canUserAccessFederation(user)))
  throw error-not-authorized-federation

isUserNativeFederated is always false for the users joining through self-invite so this check fails
the self-invite trick only bypasses the inviter check but not this authorization gate, so option 1 won't work.

option 2 with adminToken would work since the admin already is natively federated and has access-federation, so the full hook runs correctly.

i think the cleanest path is landing the server fix rather than adding client-side workarounds in EmbeddedChat

happy to pair on this if @Spiral-Memory wants to move forward with option 2

[deepak0x]

Sure would like to hear @Spiral-Memory thoughts too ;)
Also if you like i can help too in this. Have gone through the doc of rocket chat federation and got good understanding of it

[deepak0x]

Quick correction on Option 1 — it fails earlier than the federation hook. The actual blocker is in addUsersToRoomMethod: regular users don't have add-user-to-joined-room or add-user-to-any-c-room permission, so it throws error-not-allowed before federation logic is ever reached. Option 1 is out.

On Option 2 — I traced through the full code path and it works.

When an admin or bot account calls channels.invite, the inviter field is not null, which is the key condition the federation hook requires. canUserAccessFederation passes for regular users since the user role has access-federation by default. FederationMatrix.inviteUsersToRoom() fires, the user gets registered on the Matrix homeserver, and their messages federate correctly.

The only concern is security — passing an admin token as a browser-side prop exposes it in DevTools. The safe approach is a dedicated bot account with only add-user-to-any-c-room permission assigned manually.

Implementation would be a new optional adminToken prop in EmbeddedChat. On mount, if the room is federated, EmbeddedChat calls channels.invite using that token before the user sends their first message. Happy to implement this if it sounds good.