Skip to content

Instantly share code, notes, and snippets.

Last active October 20, 2023 13:14
  • Star 31 You must be signed in to star a gist
  • Fork 6 You must be signed in to fork a gist
Star You must be signed in to star a gist
What would you like to do?
Testing curl to

Testing the client-server API

Matrix is:

an open standard for decentralised communication, providing simple HTTP APIs and open source reference implementations for securely distributing and persisting JSON over an open federation of servers.

It's pretty fantastic, if you think on the massive problem of fragmentation all across the web. They've created an easy to use API, and you can do a kludgy test using curl from the terminal (*nix, mac, win). See:

It's pretty straightforward to do a quick test. I have an account at /, so I used that to get a token.

curl -XPOST -d '{"type":"m.login.password", "user":"myuserid", "password":"mypass"}' ""

That returns the token in some json:


Now you have the access_token you can use in your curl command, when hitting the API, and I understand that this token does not expire. Also get the ID from a room you create at (get room properties via the web UI), which for me was !QaRABAkxDBNukDoCOY. The ! is problematic in shells so, escape it after you paste the room id into your curl command.

Think of the curl command as a really, really simple analogue to a proper client like, so, the URL of the API is that of your home server; in this case (Thanks @Half-Shot)

curl -XPOST -d '{"msgtype":"m.text", "body":"Hello from '"$USER"'"}' "\!"

You can use shell variables in your curl command, but you have to split the data part using single quotes. The json's structure makes this a little confusing, but it's basically:

... -d 'whatever'"$thevar"'whatever' "https..."

Now it should be working, and you could now shell script it, separating those long strings out into variables, and pulling in, say, a $1 arg to make it easy to ping a certain room with messages from your servers. I.e. something like:

> matrixlog "did a yum update"
Copy link

Thanks, this is helpful though I found you also now need a txnId in the URL now.!/Room32participation/sendMessage

Copy link

Copy link

bedawi commented Sep 25, 2019

Copy link

jasalt commented Jul 16, 2020

Seems they changed the POST to PUT. This is what I got to work today.

curl 'https://SERVER/_matrix/client/r0/rooms/ROOMNAME/send/'TOKEN' -X PUT --data '{"msgtype":"m.text","body":"hello world"}'


Copy link

Not sure if the original gist has been edited but it still works for me (didn't check out the comments here until after I tried it).

Copy link

I am able to send plaintext messages, thanks. Is it possible to send bold text using this API va curl? I do not see this documented anywhere, just curious... thanks.

Copy link

I would love to see if we could use curl to send stuff that looks as professional and nicely formatted as Discord notifications. Check below for an example. Anyone know if it is possible to accomplish the same thing using the Matrix API?

Copy link

Thanks for this summary!
I had to escape the ! and the : while sending a message differently, though. Otherwise the room was not recognized.
! = %21
: = %3A
Hope this helps.

Copy link

G2G2G2G commented Aug 12, 2021


Is it possible to send bold text using this API va curl? I do not see this documented anywhere, just curious... thanks.

uhh you're just sending json.. change the json to the correct json and it'll send anything you want...
-XPOST -d '{"msgtype":"m.text", "body":"**Hello**","format":"org.matrix.custom.html","formatted_body":"<strong>hello</strong>"}'

Copy link

huedaya commented Oct 19, 2022

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment