Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
The matrix-client
library provides a simple interface for interacting with Matrix servers.
This tutorial introduces how to use the matrix-client
library.
You will need a token to create a session, if you already have an account, you can get it with the element
client
by visiting the account Settings
page, Help & About
panel, then click Access Token
.
Alternatively, you can setup a test service by running these commands in a terminal:
git clone https://github.com/matrix-org/dendrite cd dendrite; ./build.sh; ./bin/generate-keys --private-key matrix_key.pem; cp dendrite-config.yaml dendrite.yaml ./bin/dendrite-monolith-server --config dendrite.yaml curl -XPOST http://localhost:8008/_matrix/client/r0/register -d'{"username": "tristanC", "password": "supersecret", "auth": {"type": "mlogin.dummy"}}
To avoid manipulating the token directly, put it in your environment:
export MATRIX_TOKEN="THE_ACCESS_TOKEN"
Synopsis
Introduction
To start using this library you need a haskell toolchain, on fedora run:
$ sudo dnf install -y ghc cabal-install && cabal update
Then get a copy of the library by running:
$ git clone https://github.com/softwarefactory-project/matrix-client-haskell $ cd matrix-client-haskell
Start a REPL:
$ cabal repl Prelude> import Network.Matrix.Client Prelude Netowrk.Matrix.Client> :set prompt "> " > :set -XOverloadedStrings > :type getTokenOwner getTokenOwner :: ClientSession -> MatrixIO WhoAmI
Create a session
Most functions require ClientSession
which carries the
endpoint url and the http client manager.
The only way to get the client is through the createSession
function:
> token <- getTokenFromEnv "MATRIX_TOKEN" > sess <- createSession "https://matrix.org" token > getTokenOwner sess Right (WhoAmI "@tristanc_:matrix.org")
Get messages
Create a filter to limit the sync result using the createFilter
function.
To keep room message only, use the messageFilter
default filter:
> Right userId <- getTokenOwner sess > Right filterId <- createFilter sess userId messageFilter > getFilter sess (UserID "@gerritbot:matrix.org") filterId Right (Filter {filterEventFields = ...})
Call the sync
function to synchronize your client state:
> Right syncResult <- sync sess (Just filterId) Nothing (Just Online) Nothing > putStrLn $ take 512 $ show (getTimelines syncResult) SyncResult {srNextBatch = ...}
Get next batch with a 300 second timeout using the since
argument:
> Right syncResult' <- sync sess (Just filterId) (Just (srNextBatch syncResult)) (Just Online) (Just 300000)
Here are some helpers function to format the messages from sync results, copy them in your REPL:
> import qualified Data.Text.IO as Text > :{ let printEvent re = Text.putStrLn $ case reContent re of EventRoomMessage (RoomMessageText mt) -> unAuthor (reSender re) <> ": " <> mtBody mt _ -> "" :} > let printRoomEvent room event = Text.putStr room >> putStr "| " >> printEvent event > let printRoomEvents (RoomID room, events) = traverse (printRoomEvent room) events > let printTimelines sr = mapM_ printRoomEvents (getTimelines sr) > printTimelines syncResult ...
Use the syncPoll
utility function to continuously get events,
here is an example to print new messages, similar to a tail -f
process:
> syncPoll sess (Just filterId) (Just (srNextBatch syncResult)) (Just Online) printTimelines room1| test-user: Hello world! ...
Lookup identity
To use the Identity api you need another token. Get it by running these commands:
$ MATRIX_OPENID=$(curl -XPOST https://matrix.org/_matrix/client/r0/user/${USER}/openid/request_token -H "Authorization: Bearer ${MATRIX_TOKEN}" -d '{}') $ export MATRIX_IDENTITY_TOKEN=$(curl -XPOST https://matrix.org/_matrix/identity/v2/account/register -d "${MATRIX_OPENID}" | jq -r '.access_token')
Then here is how to lookup a matrix identity:
> import Network.Matrix.Identity > tokenId <- getTokenFromEnv "MATRIX_IDENTITY_TOKEN" > sessId <- createIdentitySession "https://matrix.org" tokenId > Right hd <- hashDetails sessId > identityLookup sessId hd (Email "tdecacqu@redhat.com") Right (Just (UserID "@tristanc_:matrix.org"))