Introduction

Welcome to the gomuks docs!

Discussion

Matrix room: #gomuks:maunium.net

Installation

There is a demo instance of gomuks web compiled to wasm available at https://demo.gomuks.app. However, the performance is significantly worse than with a native backend, so the demo is only meant for testing with a small account.

The Android wrapper does not currently come with the backend, which means you have to run the backend elsewhere. Something like a Raspberry Pi plus Tailscale (or another Wireguard solution) for external connectivity usually works nicely.

New gomuks terminal currently requires the backend to be running separately. An embedded backend mode will be added later. It also doesn't support Matrix login yet, so the backend must be set up using the web frontend before the terminal frontend can be used.

Installing a package

The releases on GitHub contain binaries and debian packages for legacy gomuks terminal: https://github.com/gomuks/gomuks/releases. gomuks web doesn't have releases yet, only CI binaries are available.

GitLab CI builds binaries for each commit: https://mau.dev/gomuks/gomuks/-/pipelines

The release and CI binaries for Linux are statically built and have no hard dependencies. The binaries for macOS require installing libolm, either with brew install libolm or by placing libolm.3.dylib from the CI in the same directory as the gomuks binary.

The gomuks backend requires having ffmpeg and ffprobe in $PATH to generate metadata when sending video files.

Direct links to latest CI binaries:

• gomuks backend (includes web frontend): linux/amd64, linux/arm64, linux/arm, macos/arm64, windows/amd64
• gomuks terminal (frontend only): linux/amd64, linux/arm64, linux/arm, macos/arm64
• gomuks android (currently frontend wrapper only): arm64-v8a.apk, x86_64.apk

There are also community maintained packages for several distributions (gomuks legacy only). If you've made a new distro package, please add it to the list below.

• Arch Linux (AUR): gomuks, gomuks-bin, and gomuks-git
• NixOS: gomuks
• OpenSUSE (OBS): home:albino:matrix/gomuks
• Alpine Linux: gomuks
• Debian: gomuks
• macOS (Homebrew Tap): aaronraimist/tap/gomuks
• macOS (MacPorts): gomuks

Compiling from source

0. Install Go 1.24 or higher.
   • Compiling the frontend for gomuks web also requires the latest LTS of Node.js or higher (currently v22).
   • libolm-dev must also be installed for end-to-end encryption.
1. Clone the repo: git clone https://github.com/gomuks/gomuks.git && cd gomuks
   • To get legacy gomuks terminal, run git checkout master after cd.
2. Build: ./build.sh (build.sh will simply call go build with some additional flags).

Simply pull changes (git pull) and run ./build.sh again to update.

Common compilation issues

• fatal error: olm/olm.h: No such file or directory means you forgot to install libolm-dev, or that you installed it in a weird place which isn't in your default library lookup path.
  • In the latter case, set the LIBRARY_PATH and CPATH environment variables, e.g. export LIBRARY_PATH=/usr/local/lib CPATH=/usr/local/include.
• fatal error: olm/pk.h: No such file or directory means you installed libolm2 instead of libolm3.
• cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in $PATH means you forgot to install C/C++ compilers.
• //go:build comment without // +build comment means your Go version is slightly outdated.
• cannot load embed: malformed module path "embed" or package embed is not in GOROOT means your Go version is very outdated.
• cannot find package "maunium.net/go/gomuks/..." in any of: usually means your Go version is extremely outdated.

Docker (gomuks web)

The backend for gomuks web can also run in Docker. Docker images are available at dock.mau.dev/gomuks/gomuks.

On first run, gomuks will interactively ask for basic auth credentials, so you have to either run it with the -it flags, or create the config file yourself.

Keep in mind that the backend has all your encryption keys, which means it must be ran in a secure location.

FAQ

N.B. These only apply to gomuks legacy unless otherwise noted.

How do I verify the gomuks session?

To self-sign the device using your security key, use /cs fetch, enter your security key in the dialog that appears, then use /cs self-sign.

Alternatively, get your fingerprint and device ID from /fingerprint and pass them to the /verify command in an up-to-date Element Web or Desktop to do manual verification.

Why are old messages undecryptable?

gomuks currently doesn't support key backup and doesn't request keys automatically, so only messages sent after initial login will be decryptable. To see older messages, export keys to file from another client and use the /import command. After importing keys, you need to clear cache to have gomuks retry decrypting old messages.

How do I use a proxy?

Go's HTTP library reads the https_proxy environment variable by default (see https://pkg.go.dev/net/http#ProxyFromEnvironment for more info).

How do I copy text from gomuks?

Most terminals allow selecting text even when mouse mode is enabled by using shift+drag. However, that way doesn't work for copying multiline text, so you may prefer the /copy command for copying a single message, or Ctrl+L to enter plaintext mode where you can copy whatever you want.

Can I use gomuks with multiple accounts?

gomuks currently only supports one account at a time, but you can run multiple instances of gomuks with different data directories. See the entry below for details.

Debug logs

To get debug logs from gomuks, launch it with DEBUG=1 in the environment. Logs will be stored in ~/.local/state/gomuks by default. Prior to v0.3.1, the default path was /tmp/gomuks. The path can be changed using the DEBUG_DIR environment variable.

Where does gomuks store data?

By default, data is stored in the default config/cache/data directories using OS-specific conventions. To store all gomuks data in a custom directory, use the GOMUKS_ROOT environment variable.

You can also override individual directories using GOMUKS_THING_HOME (where THING is CONFIG, DATA or CACHE).

• Config contains the main local config file.
• Data contains encryption keys.
• Cache contains things that can be refetched from the server: message history, room state, automatically downloaded files, preferences that are synced to the server, etc.

The default directory for manual file downloads (using the /download command) is the same on all systems: $GOMUKS_DOWNLOAD_HOME, $(xdg-user-dir DOWNLOAD), or $HOME/Downloads.

Note that the environment variables only take effect before first startup. After first startup, everything except the config path is saved to the config and will be read from there. To move existing gomuks data to a different path, you must change the paths in the config file.

Storage in gomuks web

The GOMUKS_* environment variables work mostly the same way as gomuks legacy, with a few exceptions:

• There's no /download command and therefore no DOWNLOAD_HOME
• Data also contains message history and other Matrix state, not only encryption keys (but media is still in cache).
• Logs can be redirected using GOMUKS_LOG_HOME instead of DEBUG_DIR.
• Environment variables are read on every startup, the paths aren't baked into the config file, except for the log path.

System-specific defaults

These are the base directories for each OS, data will be stored in the gomuks directory inside each base directory.

*nix

• Config: $XDG_CONFIG_HOME or $HOME/.config
• Cache: $XDG_CACHE_HOME or $HOME/.cache
• Data: $XDG_DATA_HOME or $HOME/.local/share
• Logs: $XDG_STATE_HOME or $HOME/.local/state

macOS

• Config & Data: $HOME/Library/Application Support
• Cache: $HOME/Library/Caches
• Logs: $HOME/Library/Logs

Windows

• Config & Data: %AppData%
• Cache: %LocalAppData%
• Logs: %LocalAppData%

Commands

Most gomuks web commands can be discovered using autocompletion, with the exception of a few special-cased commands: /plain, /me, /notice, /rainbow, /html and /unencrypted will work even though they don't show up in autocomplete.

The rest of this page only applies to gomuks legacy.

General

• /help - View command list.
• /quit - Close gomuks.
• /clearcache - Clear room state and close gomuks.
• /logout - Log out, clear caches and go back to the login view.
• /fingerprint - Shows the Device ID and fingerprint, allowing verification of the session.
• /copy [register] - Copy the selected message to the specified clipboard register (defaults to clipboard).
• /toggle <thing> - Toggle user preferences.
  • rooms - Room list sidebar.
  • users - User list sidebar.
  • baremessages - Bare message mode where the sender name is inline with the messages.
  • images - Text image rendering.
  • typingnotif - Outgoing typing notifications.
  • emojis - :emoji: conversion when sending messages.
  • html - HTML input.
  • markdown - Markdown input.
  • downloads - Automatic downloads (this will also prevent images from working).
  • notifications - Desktop notifications.
  • unverified - Sending (e2ee keys for) messages to unverified devices. You need to restart gomuks for this setting to take effect.
  • inlineurls - Inline URLs in text. May not be supported in all terminals. You need to restart gomuks for this setting to take effect.

Media

Tab-completing file paths is supported in all these commands.

• /download [path] - Downloads file from selected message. If path is not specified, it defaults to <download_dir>/<message.body>. download_dir defaults to $HOME/Downloads.
• /open [path] - Download file from selected message and open it with xdg-open. If path is not specified, the file will be downloaded to the media cache.
• /upload <path> - Upload the file at the given path to the current room. Note that to include audio/video file metadata (dimensions and duration), you must have ffprobe installed.

Sending special messages

• /me <text> - Send an emote.
• /notice <text> - Send a notice (generally used for bot messages).
• /rainbow <text> - Send rainbow text.
• /rainbowme <text> - Send rainbow text in an emote.
• /rainbownotice <text> - Send rainbow text in a m.notice message.
• /reply [text] - Reply to the selected message. If text is not specified, the next message will be used.
• /react <reaction> - React to the selected message.
• /redact [reason] - Redact (delete) the selected message.
• /edit - Edit the selected message.

Encryption

These commands support tab-completing file paths and user/device IDs using the displaynames of users/devices.

Accepting incoming interactive verification requests is not yet supported, only outgoing requests via /verify work.

• /fingerprint - View the fingerprint of your device (for legacy/non-interactive verification).
• /devices <user id> - View the device list of a user.
• /device <user id> <device id> - Show info about a specific device.
• /unverify <user id> <device id> - Un-verify a device.
• /blacklist <user id> <device id> - Blacklist a device. Message keys are never sent to blacklisted devices.
• /verify <user id> <device id> [fingerprint] - Verify a device. If the fingerprint is not provided, interactive emoji verification will be started.
• /export <path> - Export all message decryption keys to the given path.
• /export-room <path> - Export message decryption keys for the current room to the given path.
• /import <path> - Import message decryption keys from the given path.
• /cross-signing <subcommand> [...] - Cross-signing commands. Somewhat experimental. (alias: /cs).
  • status - Check the status of your own cross-signing keys.
  • generate [--force] - Generate and upload new cross-signing keys. This will prompt you to enter your account password. If you already have existing keys, --force is required.
  • self-sign - Sign the current device with cached cross-signing keys. (or in other words, verify the current device).
  • fetch [--save-to-disk] - Fetch your cross-signing keys from SSSS and decrypt them. If --save-to-disk is specified, the keys are saved to disk.
  • upload - Upload your cross-signing keys to SSSS.
• /ssss <subcommand> [...] - Secure Secret Storage (and Sharing) commands. Very experimental.
  • status [key ID] - Check the status of your SSSS.
  • generate [--set-default] - Generate a SSSS key and optionally set it as the default.
  • set-default <key ID> - Set a SSSS key as the default.

Rooms

Creating

• /pm <user id> [...] - Start a private chat with the given user(s).
• /create [room name] - Create a new room.

Joining

• /join <room> [server] - Join the room with the given room ID or alias, optionally through the given server.
• /accept (in a room you're invited to) - Accept the invite.
• /reject (in a room you're invited to) - Reject the invite.

Existing

• /invite <user id> - Invite the given user ID to the room.
• /roomnick <name> - Change your per-room displayname.
• /tag <tag> <priority> - Add the room to <tag>. <tag> should start with u. and <priority> should be a float between 0 and 1. Rooms are sorted in ascending priority order.
• /untag <tag> - Remove the room from <tag>.
• /tags - List the tags the room is in.
• /powerlevel [thing] [level] - View or change power levels in rooms.

Leaving

• /leave - Leave the current room.
• /kick <user id> [reason] - Kick a user.
• /ban <user id> [reason] - Ban a user.
• /unban <user id> - Unban a user.

Aliases

• /alias add <localpart> - Add #<localpart>:your.server as an address for the current room.
• /alias remove <localpart> - Remove #<localpart>:your.server (can be ran in any room).
• /alias resolve <alias> - Resolve <alias> or #<alias>:your.server and reply with the room ID.

Raw events

• /send <room id> <event type> <content> - Send a custom event.
• /setstate <room id> <event type> <state key/-> <content> - Change room state.
• /msend <event type> <content> - Send a custom event to the current room.
• /msetstate <event type> <state key/-> <content> - Change room state in the current room.
• /id - Get the current room ID.

Debugging

• /hprof - Create a heap profile and write it to gomuks.heap.prof in the current directory.
• /cprof <seconds> - Profile the CPU usage for the given number of seconds and write it to gomuks.cpu.prof.
• /trace <seconds> - Trace calls for the given number of seconds and write traces to gomuks.trace.

Shortcuts

This page only applies to gomuks legacy.

Keyboard

Ctrl and Alt are interchangeable in most keybindings, but the other one may not work depending on your terminal emulator.

• Switch rooms: Ctrl + ↑, Ctrl + ↓
• Scroll chat (page): PgUp, PgDown
• Jump to room: Ctrl + K, type part of a room's name, then Tab and Enter to navigate and select room
• Plaintext mode: Ctrl + L
• Newline: Alt + Enter
• Autocompletion: Tab (emojis, usernames, room aliases and commands)

Editing messages

↑ and ↓ can be used at the start and end of the input area to jump to edit the previous or next message respectively.

Selecting messages

After using commands that require selecting messages (e.g. /reply and /redact), you can move the selection with ↑ and ↓ confirm with Enter.

Mouse

• Click to select message (for commands such as /reply that act on a message)
• Ctrl + click on image to open in your default image viewer (xdg-open)
• Click on a username to insert a mention of that user into the composer

Customizing keybindings

This page only applies to gomuks legacy.

Keybindings can be customized to some extent by creating a file called keybindings.yaml in the config directory (see the FAQ for the location of the config directory).

The file should have the same format as the default keybindings.yaml file, but you only need to specify the bindings you want to override.

For example, to use enter for newline, you'd want something like this. Note that terminals can't detect shift+enter, and usually only either ctrl or alt works.

main:
  'Enter': add_newline
  'Ctrl+Enter': unbind
  'Alt+Enter': unbind

room:
  'Enter': unbind
  'Ctrl+Enter': send
  'Alt+Enter': send

Debugging

This page only applies to gomuks legacy.

If something doesn't work but it doesn't crash, check the /tmp/gomuks/debug.log file for any errors. You can override the location of this file with the DEBUG_DIR environment variable.

Developing

Set DEBUG=1 to enable partial deadlock detection and to write panics to stdout instead of a file.

To build and run with race detection, use go install -race and set GORACE='history_size=7 log_path=/tmp/gomuks/race.log' when starting gomuks, then check /tmp/gomuks/race.log.<pid>. Note that race detection will use a lot of extra resources.

Proper debuggers are too fancy, but normal prints won't work in a TUI application. To write to the debug log mentioned previously, use the maunium.net/go/gomuks/debug package:

package foo

import (
	"maunium.net/go/gomuks/debug"
)

func Foo() {
	debug.Print("WHY ISN'T IT WORKING?!?!?")
	debug.PrintStack()
}

RPC API

Envelope

All RPC messages (requests, responses and events) use the same envelope format:

• command (string): the command/event name.
• request_id (integer): incrementing (or decrementing) message ID. Responses will always contain the same ID. Requests without an ID will never be replied to. For events, the backend will start at -1 and go backwards.
• data (any): payload for the command/event, type depends on the command.

Responses

For every request with request_id set, the backend replies exactly once with the same request_id and one of:

• command: "response" with data containing the command-specific return value.
• command: "error" with data being the error message string.

Cancellation

Requests can be canceled by sending a cancel request with the target request_id inside data, plus an optional reason string. Cancellation is best-effort: some operations may not stop immediately and there is no guarantee of rollbacks.

Websocket

The main method of connecting is using the websocket. The websocket is at _gomuks/websocket and requires standard cookie authentication.

However, the RPC API is intentionally just JSON, so it can be sent over other transports as well. In particular, when bundling the backend with the frontend, it is recommended to use a direct in-process channel rather than the websocket.

Compression

If the compress query param is set to 1, the websocket will use a connection-wide deflate compression similar to how Discord's gateway works. Only messages sent by the backend are compressed; client messages are not.

Enabling compression will also enable batched messages in a single frame, i.e. multiple JSON objects may be concatenated together using a newline (\n) as the separator if the backend detects that the connection isn't keeping up. There is currently no option to turn off batching when compression is enabled.

Compression is recommended for lower bandwidth networks like mobile data. It can save up to 70% of bandwidth. The primary downside is that standard developer tools will no longer understand the websocket messages.

Event buffering

The backend will buffer events that the client hasn't acknowledged yet to allow faster resuming in case the websocket is interrupted. To use session resumption, the client has to handle the run_id command and store the run_id field inside the data. When reconnecting, the client should include the run ID as well as the most recent negative request ID it received in the run_id and last_received_event query params respectively.

The event buffer is entirely in-memory, which means resumption will fail if the backend has been restarted. For non-resumed inits, the first sync_complete event will have the clear_state flag set to true. For successful resumes, the client will only get missed events rather than the full initial sync.

The init_complete event is always sent once the client is caught up regardless of whether the resume succeeded or not.

Keepalive pings and event acknowledgement

Clients MUST send periodic pings to keep the connection alive. The backend will kill connections that don't send any data for over 60 seconds. Clients SHOULD implement similar timeouts and reconnect if they don't receive any data from the backend. The recommended ping interval is 15 seconds.

Unlike normal requests, pings are exclusive to the websocket layer and will result in "command": "pong" instead of "command": "response".

In addition to keeping the connection open, pings are used to acknowledge received events so that the backend can remove them from its in-memory cache. Clients should include the most recent negative request ID they received in the last_received_id field inside the data of the ping.

Example

Request:

{
  "command": "ping",
  "request_id": 123,
  "data": {
    "last_received_id": -456
  }
}

Response:

{
  "command": "pong",
  "request_id": 123
}

Commands

get_state

Get current client state (login/verification/session info). Note that state is also emitted as client_state events, so you usually don't need to request it manually.

• Request data: N/A
• Response data: ClientState
  • is_initialized (bool)
  • is_logged_in (bool)
  • is_verified (bool)
  • user_id (string, optional)
  • device_id (string, optional)
  • homeserver_url (string, optional)

cancel

Cancel an in-flight request.

• Request data:
  • request_id (int, required): request ID to cancel.
  • reason (string): optional cancellation reason.
• Response data: bool
  • true if a request with that ID was found and cancellation was triggered.
  • false if no in-flight request with that ID exists.

send_message

Send a Matrix message into a room. This is a higher-level helper around sending m.room.message (and related) content. This will always perform an asynchronous send, which means the returned event won't have an ID yet. Listen for the send_complete event to get the final result.

• Request data:
  • room_id (string, required)
  • base_content (object): non-text m.room.message event content. Only standard fields in mautrix-go's MessageEventContent are allowed here. This should be used for things like media attachments, as well as MSC4332 bot commands.
  • extra (object): non-standard fields for content.
  • text (string): text to send. If set, this will be used to fill the message body, formatted_body, format and msgtype fields. Media captions should be put here even when using base_content for the rest of the media.
  • relates_to (object): Standard m.relates_to data.
  • mentions (object): Standard m.mentions data.
  • url_previews (array): Beeper link preview objects (MSC4095).
• Response data: database.Event

send_event

Send an arbitrary event into a room.

• Request data:
  • room_id (string, required)
  • type (string, required)
  • content (object, required)
  • disable_encryption (bool): if true, don’t encrypt the event even if the room is encrypted.
  • synchronous (bool): if true, perform sending synchronously (returned DB event will have the event ID set, unless the send fails).
• Response data: database.Event

resend_event

Retry sending a previously failed outgoing event.

• Request data:
  • transaction_id (string, required)
• Response data: database.Event

report_event

Report an event to the homeserver.

• Request data:
  • room_id (string, required)
  • event_id (string, required)
  • reason (string)
• Response data: N/A

redact_event

Redact an event.

• Request data:
  • room_id (string, required)
  • event_id (string, required)
  • reason (string)
• Response data: mautrix.RespSendEvent

set_state

Send a state event into a room.

• Request data:
  • room_id (string, required)
  • type (string, required)
  • state_key (string)
  • content (object, required)
  • delay_ms (int): optional unstable delayed-event send (milliseconds).
• Response data: event_id (string)

update_delayed_event

Update or cancel an unstable delayed event (MSC4140/unstable delay API).

• Request data:
  • delay_id (string, required)
  • action (string, required)
• Response data: mautrix.RespUpdateDelayedEvent

set_membership

Invite, kick, ban or unban a user.

• Request data:
  • action (string, required): one of invite, kick, ban, unban.
  • room_id (string, required)
  • user_id (string, required)
  • reason (string)
  • msc4293_redact_events (bool): if true, the ban event will set a flag to suggest that clients hide all the user's messages.
• Response data: empty object

set_account_data

Set global or per-room account data.

• Request data:
  • room_id (string): omit to set global account data.
  • type (string, required)
  • content (object, required)
• Response data: N/A

mark_read

Send a read receipt / mark room as read.

• Request data:
  • room_id (string, required)
  • event_id (string, required)
  • receipt_type (string, required): Matrix receipt type (e.g. m.read).
• Response data: N/A

set_typing

Set typing notification state.

• Request data:
  • room_id (string, required)
  • timeout (int): typing timeout in milliseconds. Set to 0 to stop typing.
• Response data: N/A

get_profile

Fetch a Matrix user profile.

• Request data:
  • user_id (string, required)
• Response data: The raw profile data of the user.

set_profile_field

Set one profile field for the current user.

• Request data:
  • field (string, required)
  • value (any, required)
• Response data: N/A

get_mutual_rooms

Get rooms shared with a user.

• Request data:
  • user_id (string, required)
• Response data: string[] (array of room IDs)

track_user_devices

Start tracking a user’s devices if they're not already tracked, then return encryption info (same result as get_profile_encryption_info).

• Request data:
  • user_id (string, required)
• Response data: ProfileEncryptionInfo

get_profile_encryption_info

Get the device list and trust state information for a user.

• Request data:
  • user_id (string, required)
• Response data: ProfileEncryptionInfo
  • devices_tracked (bool)
  • devices (array of ProfileDevice)
    • device_id (string)
    • name (string)
    • identity_key (string)
    • signing_key (string)
    • fingerprint (string)
    • trust_state (string)
  • master_key (string)
  • first_master_key (string)
  • user_trusted (bool)
  • errors (string[])

get_event

Fetch an event from a room.

• Request data:
  • room_id (string, required)
  • event_id (string, required)
  • unredact (bool): if true, fetch an unredacted copy when possible.
• Response data: database.Event

get_related_events

Get events related to a given event (e.g. reactions, edits, replies depending on relation type).

• Request data:
  • room_id (string, required)
  • event_id (string, required)
  • relation_type (string, required)
• Response data: database.Event[] (array of events)

get_event_context

Fetch context around an event (before/after timeline slices) from the homeserver. This is used for jumping to a specific point on the timeline. Note that there is currently no safe way to merge back into the main timeline, so jumping has to be implemented as a separate view.

• Request data:
  • room_id (string, required)
  • event_id (string, required)
  • limit (int)
• Response data: https://pkg.go.dev/go.mau.fi/gomuks/pkg/hicli/jsoncmd#EventContextResponse
  • start (string)
  • end (string)
  • before (database.Event[])
  • after (database.Event[])
  • event (database.Event)

paginate_manual

Manually paginate messages from the homeserver using a pagination token. This is used to paginate after jumping to a specific event using get_event_context and for normal pagination in the thread view.

• Request data:
  • room_id (string, required)
  • thread_root (string): root event ID for thread pagination.
  • since (string): next_batch token from previous request or the start/end fields of get_event_context.
  • direction (string): b or f.
  • limit (int)
• Response data: ManualPaginationResponse
  • events (database.Event[])
  • next_batch (string)

get_room_state

Get room state, optionally after fetching it from the homeserver.

• Request data:
  • room_id (string, required)
  • refetch (bool): force refetch the entire state from the homeserver.
  • fetch_members (bool): fetch membership events from homeserver. The client should always set this when opening a room if has_member_list is false in the room metadata.
  • include_members (bool): whether to include the member list in the response. This can be used with fetch_members to tell the backend to fetch the list in the background rather than waiting for it.
• Response data: database.Event[] (array of state events)

get_specific_room_state

Get specific state events by database GUID keys.

• Request data:
  • keys (array, required): array of database.RoomStateGUID.
    • room_id (string, required)
    • type (string, required)
    • state_key (string)
• Response data: database.Event[] (array of state events)

get_receipts

Get cached read receipts for a set of event IDs.

• Request data:
  • room_id (string, required)
  • event_ids (string[], required)
• Response data: map event_id → Receipt[]

paginate

Paginate up in the timeline. This will return locally cached timelines if available and fetch more from the homeserver if needed.

• Request data:
  • room_id (string, required)
  • max_timeline_id (number): the oldest known timeline row ID. All returned values will be lower than this (hence max ID).
  • limit (int)
  • reset (bool): if true, the backend will throw away any locally cached timeline state and reload it from the server.
• Response data: PaginationResponse
  • events (database.Event[])
  • receipts (map event_id → Receipt[])
  • related_events (database.Event[])
  • has_more (bool)
  • from_server (bool)

get_space_hierarchy

Fetch a space hierarchy, which may include rooms the user isn't in yet. This should only be used for rendering the space index page. For the room list, space edge information is automatically pushed in syncs.

• Request data:
  • room_id (string, required)
  • from (string)
  • limit (int)
  • max_depth (int|null)
  • suggested_only (bool)
• Response data: mautrix.RespHierarchy

get_room_summary

Fetch the basic metadata of a room, such as name, topic, avatar and member count. This should be used for previewing rooms before joining. For joined rooms, metadata is automatically pushed in the sync payloads.

• Request data:
  • room_id_or_alias (string, required)
  • via (string[])
• Response data: mautrix.RespRoomSummary

join_room

Join a room by room ID or alias.

• Request data:
  • room_id_or_alias (string, required)
  • via (string[])
  • reason (string)
• Response data: mautrix.RespJoinRoom
  • room_id (string)

knock_room

Knock on a room by room ID or alias.

• Request data:
  • room_id_or_alias (string, required)
  • via (string[])
  • reason (string)
• Response data: mautrix.RespKnockRoom
  • room_id (string)

leave_room

Leave a room or reject an invite.

• Request data:
  • room_id (string, required)
  • reason (string)
• Response data: empty object

create_room

Create a new room.

• Request data: mautrix.ReqCreateRoom
• Response data: mautrix.RespCreateRoom
  • room_id (string)

mute_room

Mute or unmute a room by manipulating push rules.

• Request data:
  • room_id (string, required)
  • muted (bool)
• Response data: N/A

ensure_group_session_shared

Ensure the encryption group session for a room has been shared to devices. This should be called when the user first starts typing to make sending more efficient.

• Request data:
  • room_id (string, required)
• Response data: N/A

send_to_device

Send an arbitrary to-device event. Meant for widgets, not needed otherwise.

resolve_alias

Resolve a room alias.

• Request data:
  • alias (string, required)
• Response data: mautrix.RespAliasResolve
  • room_id (string)
  • servers (string[])

request_openid_token

Request an OpenID token from the homeserver. OpenID tokens are used to authenticate with various external services. Widgets also need this method.

To log into css.gomuks.app, use the response data to form the following URL and open it in a browser: https://css.gomuks.app/login?token=${access_token}&server_name=${matrix_server_name}

• Request data: N/A
• Response data: mautrix.RespOpenIDToken
  • access_token (string)
  • expires_in (int)
  • matrix_server_name (string)
  • token_type (string)

discover_homeserver

Discover the homeserver URL from a Matrix user ID using .well-known delegation.

• Request data:
  • user_id (string, required)
• Response data: mautrix.ClientWellKnown

get_login_flows

Fetch supported login flows from a homeserver.

• Request data:
  • homeserver_url (string, required)
• Response data: mautrix.RespLoginFlows

login

Log in using a homeserver URL, username, and password. After a successful login, the client_state event will be dispatched. The frontend should use the event rather than the response to update its state.

• Request data:
  • homeserver_url (string, required)
  • username (string, required)
  • password (string, required)
• Response data: N/A

login_custom

Log in using a fully custom Matrix login request object.

• Request data:
  • homeserver_url (string, required)
  • request (object, mautrix.ReqLogin, required)
• Response data: bool (always true on success)

verify

Verify the session using a recovery key or recovery phrase. Like login, the frontend should update its state based on the client_state event rather than the response here.

• Request data:
  • recovery_key (string, required)
• Response data: N/A

logout

Log out the current session.

• Request data: N/A
• Response data: N/A

register_push

Register a gomuks-specific pusher Register (store) push configuration in gomuks’ local database.

• Request data: database.PushRegistration
  • device_id (string, required): An arbitrary (but stable) device identifier.
  • type (string, required): One of web, fcm.
  • data (any, required): Type-specific data.
    • If type is fcm, data is a string containing the FCM push token.
    • If type is web, data is an object with the following fields:
      • endpoint (string, required)
      • keys (object, required)
        • p256dh (base64 string, required)
        • auth (base64 string, required)
  • encryption (object): An optional gomuks-specific encryption configuration. Mostly relevant for FCM (and APNs in the future), as web push has built-in encryption.
    • key (base64 string): 32 random bytes used as the static AES-GCM key.
  • expiration (int64, required): Unix timestamp (seconds) when the registration should be considered stale. The frontend should re-register well before this time.
• Response data: N/A

listen_to_device

Enable or disable including to-device messages in sync data. Only relevant for widgets.

• Request data: bool
• Response data: bool (previous value before this request)

get_turn_servers

Fetch TURN server configuration.

• Request data: N/A
• Response data: mautrix.RespTurnServer

get_media_config

Fetch media repository configuration.

• Request data: N/A
• Response data: mautrix.RespMediaConfig

calculate_room_id

Calculate a room ID locally from a timestamp and creation content. This is only relevant when creating v12+ rooms with the fi.mau.origin_server_ts extension that allows the client to pre-calculate the room ID.

• Request data:
  • timestamp (int64, required)
  • content (object, required): room creation content JSON.
• Response data: string

Events (backend → client)

Events are messages sent by the backend when new data is available. The request IDs will always be negative. The client MUST NOT respond to events.

sync_complete

A sync batch has been fully processed and stored. This is also used for sending the room list to the client when first connecting.

• Event data: SyncComplete
  • since (string): The Matrix sync token. Not particularly relevant.
  • clear_state (bool): If set, the frontend should clear all local state before applying the sync. This is only set for the very first sync payload after connecting if resuming didn't succeed.
  • account_data (map type → DBAccountData)
  • rooms (map room_id → SyncRoom)
  • left_rooms (string[]): List of room IDs that the user is not in anymore. The frontend should delete the rooms from its store.
  • invited_rooms (DBInvitedRoom[]): List of new invites to rooms.
  • space_edges (map room_id -> DBSpaceEdge[])
  • top_level_spaces (string[]): List of room IDs that should be considered top-level spaces. The frontend should replace the entire list when this field is set.
  • to_device (object[]): List of new to-device events. Only sent if opted in with listen_to_device. Only relevant for widgets.

SyncRoom:

• meta (DBRoom): Room metadata. If set, the frontend should replace the entire cached metadata object with the one sent here.
• events (DBEvent[]): events that the frontend needs to process the new data in the state and timeline fields. Note that this is just raw events and may include old events as well. The frontend should just put these in its event cache.
• state (map event type -> state key -> event row ID): new state events for the room. This map should be merged with the existing cached state.
• timeline (TimelineRowTuple[]): a list of event row IDs that should be appended to the timeline.
  • timeline_rowid (int64): timeline row ID to sort the timeline.
  • event_rowid (int64): event row ID to look up the event.
• reset (boolean): If true, the cached timeline should be reset before the new timeline is appended.
• receipts (map event_id → DBReceipt[]): new read receipts.
• dismiss_notifications (boolean): if true, the frontend should clear all notifications that were previously emitted for the room.
• notifications (SyncNotification[]): list of new notifications for the room.
  • event_rowid (int64)
  • sound (boolean)
  • highlight (boolean)

DBAccountData:

• user_id (string): the current user's ID.
• room_id (string): if present, this is per-room account data.
• type (string): the account data type.
• content (object): the raw account data content.

DBInvitedRoom:

• room_id (string): Room ID of the invited room.
• created_at (int64, unix ms): Timestamp when the invite was sent, or if the invite timestamp is missing, then the time when the invite was received.
• invite_state (object[]): List of state events in the invite.

DBSpaceEdge:

• space_id (string): Room ID of the space.
• child_id (string): Room ID of the child room.
• child_event_rowid (int64): Event row ID of the m.space.child event.
• order (string): Order string from the m.space.child event.
• suggested (boolean): Whether the child is suggested by the space.
• parent_event_rowid (int64): Event row ID of the m.space.parent event.
• canonical (boolean): Whether the parent is the canonical parent of the room.

DBReceipt:

• user_id (string): User ID of the user who sent the receipt.
• receipt_type (string): Receipt type, e.g. m.read.
• thread_id (string): Thread root event ID if the receipt is for a thread.
• event_id (string): Event ID the receipt is for.
• timestamp (int64, unix ms): Timestamp of the receipt.

sync_status

Sync status update.

• Event data:
  • type (string, required): ok, waiting, erroring, permanently-failed
  • error (string)
  • error_count (int)
  • last_sync (number, unix milliseconds)

events_decrypted

One or more events were decrypted after initially failing to decrypt.

• Event data:
  • room_id (string, required)
  • preview_event_rowid (number): If the preview event of the room changed, the new rowid to preview.
  • events (database.Event[], required)

typing

Typing notifications for a room.

• Event data:
  • room_id (string)
  • user_ids (string[])

send_complete

A previously started send finished (success or failure).

• Event data:
  • event (database.Event)
  • error (string|null)

client_state

Client state changed.

• Event data: ClientState (same as get_state response)

image_auth_token (websocket only)

Authentication token for image/media requests. The token is valid for an hour and a new one is sent every 30 minutes.

• Event data: string

init_complete

Emitted after client initialization completes (either after initial sync or after catching up on resume).

• Event data: {}

run_id

Metadata about the currently running backend process.

• Event data:
  • run_id (string): The run ID to use for resuming connections (event buffering is in-memory, so connections can't be resumed across backend restarts).
  • etag (string): Used by the frontend to force reload if it detects it's an outdated cached copy.
  • vapid_key (string): VAPID public key for web push subscriptions.

HTTP API

_gomuks/auth is used to acquire or refresh cookies. If an existing gomuks_auth cookie is provided, it's validity is extended. Otherwise, basic auth credentials will be checked.

Available query parameters:

• output - can be json (JSON in response body) or omitted (Set-Cookie header)
• no_prompt - if set to true, the WWW-Authenticate header will not be set when credentials are missing or invalid.
• insecure_cookie - if set to true, the cookie will not have the Secure flag set.

TODO other endpoints