matrix-xbox-bridge

A Matrix puppeting bridge for Xbox Live messages, built on mautrix-go bridgev2. Your Xbox inbox shows up as Matrix rooms: 1:1 conversations as DMs with a ghost user per player, group chats as group rooms, with backfill, read receipts, image attachments, message deletion and gamertag lookup (start-chat <gamertag>).

It talks to the same services the official Xbox app uses: xblmessaging.xboxlive.com for the inbox and sends, and the chat.xboxlive.com websocket for real-time delivery, with a slow inbox poll as a safety net.

Status

Works for text, links, images and voice-message transcripts in both directions of 1:1 and group chats. Not supported by the Xbox side: edits, reactions, replies, typing indicators, creating groups. Read receipts are bridged both ways (Matrix read markers set the Xbox read horizon).

Terms of use

Xbox Live has no public messaging API. This bridge stays inside Microsoft's terms by design, and the defaults reflect that:

• It signs in only to your own account, through the documented OAuth flow.
• Every message it sends is one a human typed in Matrix. It never originates, schedules or fans out messages, and outbound sends are rate limited (sends_per_minute).
• Inbound delivery is push (websocket); the poll fallback defaults to five minutes and refuses to go below one.
• It stores only what rendering needs (gamertags, avatars, the messages in rooms you are part of) and drops the credentials on logout.
• Send failures caused by blocks or privacy settings are surfaced as a notice in the room, never retried.

Do not run it for other people's accounts, do not use it to message players who have blocked you, and do not point it at a child account.

Login flows

azure (default, recommended). Register your own app in the Entra portal: App registrations, New registration, "Personal Microsoft accounts only", add a Mobile and desktop applications platform with the redirect URI https://login.live.com/oauth20_desktop.srf. No API permissions are needed; the bridge requests Xboxlive.signin Xboxlive.offline_access at login. Put the application (client) id in network.azure.client_id. Then in the bridge bot DM, login, open the link, sign in, and paste back the URL you land on. This is the same route Home Assistant's Xbox integration takes.

device. Uses the client id of Microsoft's own Xbox iOS app and the device-code prompt at microsoft.com/link, so it needs no registration. It impersonates a first-party app rather than one you registered, which is why it is behind network.allow_first_party_login: true.

Tokens refresh themselves: the XSTS token is re-minted roughly twice a day and the Microsoft refresh token rolls forward every time it is used, so a bridge that stays running never needs a fresh login unless the account's password changes or sessions are revoked.

Running

./build.sh
./matrix-xbox-bridge -e -c config.yaml   # write example config, then edit it
./matrix-xbox-bridge -g -c config.yaml -r registration.yaml
# install registration.yaml in your homeserver, then
./matrix-xbox-bridge -c config.yaml

Docker: the image runs docker-run.sh, which generates the config on the first start and the registration on the second, then runs the bridge as uid 1337 with /data mounted. Build with docker build -t matrix-xbox-bridge .. Tagged releases publish ghcr.io/312-dev/matrix-xbox-bridge:<tag> and static binaries for linux amd64/arm64/arm and macOS arm64 on the GitHub release page. Changes per release are in CHANGELOG.md.

The -tags goolm build uses mautrix's pure-Go Olm, so no libolm is needed in the image.

Layout

• pkg/xbl is a standalone client for the Xbox auth chain, request signing, messaging REST API, profile lookups and the chat websocket. It has no mautrix imports and can be reused on its own.
• pkg/connector is the bridgev2 network connector.

License

AGPL-3.0-or-later, like the mautrix bridges it is built on.