The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

mx.api

A minimal-dependency client for the Matrix Client-Server HTTP API, suitable for talking to a Synapse or Conduit homeserver from R. Two Imports: curl and jsonlite. No tidyverse.

Pairs with mx.crypto, which handles Olm + Megolm; mx.api itself does no cryptography.

Install

# CRAN
install.packages("mx.api")

# GitHub (development version)
remotes::install_github("cornball-ai/mx.api")

Quick start: log in, send, sync

library(mx.api)

s <- mx_login(
    server   = "https://matrix.example",
    user     = "alice",
    password = "hunter2"
)

room <- mx_room_join(s, "#general:matrix.example")
mx_send(s, room, "hello from R")

batch <- mx_sync(s, timeout = 0)
str(batch$rooms$join)

mx_logout(s)

Create a private room with invites

room <- mx_room_create(
    s,
    name   = "project sync",
    topic  = "weekly check-in",
    preset = "private_chat",
    invite = c("@bob:matrix.example", "@carol:matrix.example")
)
mx_send(s, room, "kickoff in 5")

mx_room_create returns the new room id as a character string. Presets: "private_chat", "trusted_private_chat", "public_chat".

Sending rich-text (code blocks, bold, etc.)

mx_send’s body is plain text. Matrix clients that show rich text (Element, Cinny, Fractal, etc.) render the optional formatted_body field instead, fall back to body when it is absent. Markdown fences in plain body show as literal backticks; you have to send HTML in formatted_body to get a real code block.

Pass both via the extra argument:

plain <- "Build steps:\n\ndocker compose build\ndocker compose up -d"

html <- paste0(
    "<p>Build steps:</p>",
    "<pre><code>docker compose build\n",
    "docker compose up -d</code></pre>"
)

mx_send(
    s, room, plain,
    extra = list(
        format = "org.matrix.custom.html",
        formatted_body = html
    )
)

The format value "org.matrix.custom.html" is the only one the Matrix spec defines. Supported tags are listed in the Matrix client-server spec, section 11.2.1.7. Code blocks use <pre><code>…</code></pre>; inline code is <code>…</code>.

What’s covered

Area	Functions
Session	`mx_register`, `mx_login`, `mx_logout`, `mx_whoami`, `mx_session`
Rooms	`mx_rooms`, `mx_room_create`, `mx_room_join`, `mx_room_leave`, `mx_room_invite`, `mx_room_members`, `mx_room_name`, `mx_room_topic`
Messages	`mx_send`, `mx_send_event`, `mx_messages`, `mx_sync`, `mx_react`, `mx_redact`, `mx_read_receipt`, `mx_typing`
Room state	`mx_get_state`, `mx_set_state`
Media	`mx_upload` (streaming), `mx_download`, `mx_send_media` (+ `mx_send_file` / `mx_send_image` / `mx_send_audio` / `mx_send_video`), `mx_guess_mime`, `mx_media_config`
Profile	`mx_profile`, `mx_set_displayname`, `mx_set_avatar_url`
Account data	`mx_get_account_data`, `mx_set_account_data`
Devices	`mx_devices`, `mx_delete_device`
E2EE transport	`mx_keys_upload`, `mx_keys_query`, `mx_keys_claim`, `mx_send_to_device`
E2EE signing helper	`mx_canonical_json`

End-to-end cryptography is out of scope; pair with mx.crypto (or another crypto library) to sign and verify the payloads these endpoints carry. Helpful framing:

mx.api speaks Matrix HTTP. It does no signing, no key management, no key validation, and holds no state between calls.
mx.crypto speaks Olm + Megolm. It does no HTTP.
mx.client is the stateful layer that uses both: config persistence, sync cursors, and E2EE orchestration (its vignette("e2ee") walks the whole flow).

Canonical JSON

mx_canonical_json() is the byte-stable encoder Matrix’s signing rules require. It is hand-rolled (not a jsonlite wrapper) so the spec-sensitive choices — key ordering by UTF-8 byte sequence, integer range, NaN/Inf/NA rejection, duplicate-key rejection, control-char escaping — are visible and unit-tested rather than hidden in another package’s defaults.

mx_canonical_json(list(b = 2, a = 1))
#> [1] "{\"a\":1,\"b\":2}"

mx_canonical_json(1.5)
#> Error: mx_canonical_json: non-integer number 1.5 disallowed

107 assertions exercise the encoder (see inst/tinytest/test_canonical_json.R).

Status

0.3.0. Relative to 0.2.0 the delta is additive:

Generic event and state plumbing: mx_send_event, mx_set_state, mx_get_state (needed for m.room.encrypted / m.room.encryption).
Media messages: mx_send_media and the file/image/audio/video wrappers.
Bot lifecycle: mx_room_invite, mx_redact, mx_typing, mx_profile / mx_set_displayname / mx_set_avatar_url.
Account data: mx_get_account_data, mx_set_account_data.
Devices: mx_devices, mx_delete_device.
Classed error conditions (mx_error_<ERRCODE>) for programmatic handling; streamed uploads.

See NEWS.md for the full changelog.

CI

GitHub Actions via r-ci; macOS and Ubuntu runners cover every commit + PR.

License

MIT. See LICENSE.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.