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.