• See also Matrix Admin Tools

• https://matrix.org/docs/api/client-server/#/
• https://matrix.org/docs/spec/

• Using Riot (that's whats running on https://matrix.glasgow.social) - Click on your profile name at the top left corner and select Settings
• Click Help & About from the list then scroll down to the 'Advanced' section.
• You should see the bottom line that reads Access Token <click to reveal>
• Copy and paste that into the example below

• Click on the three dots at the edge of a room name and click Settings
• Choose Advanced to see the Internal Room ID
• #opensource on the server is !uVhYeryxRiaOwTlATT:glasgow.social

It can be very simple to post a message to a room on Matrix (note: you have to be a member of the room).

This script requires jq, the command line JSON processor.

sudo apt install jq

post_to_matrix.sh

#!/bin/bash
# Usage:
# echo "Hello world" | ./post_to_matrix.sh
msgtype=m.text
homeserver=glasgow.social
room=!BOrDFgeDdZZbUvfjjs:glasgow.social
access_token=put_your_user_access_token_here
 
curl -XPOST -d "$( jq -Rsc --arg msgtype "$msgtype" '{$msgtype, body:.}')" "https://$homeserver/_matrix/client/r0/rooms/$room/send/m.room.message?access_token=$access_token"

post_to_matrix.php

<?php
$msgtype = "m.text";
$homeserver = "glasgow.social";
$room = "!BOrDFgeDdZZbUvfjjs:glasgow.social";
$access_token="put_your_user_access_token_here"
$url = "https://$homeserver/_matrix/client/r0/rooms/$room/send/m.room.message?access_token=$access_token";
 
$msg = "Hello world";
 
$payload = json_encode(array("msgtype"=>$msgtype, "body"=>$msg));
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
 
?>

This is pretty straightforward. This is just how to see messages that are posted, but if you explore what is returned then you can see all sorts of things too (like joins, images, likes, invites etc). I run something like this on a terminal so I can see what's going on in all my rooms at a glance. Very cool.

get_messages.sh

#!/bin/bash
# Usage:
# ./get_messages.sh
msgtype=m.text
homeserver=glasgow.social
room=room_id_here
access_token=your_access_token_here
from=start_point_goes_here
 
curl -XGET "https://$homeserver/_matrix/client/r0/rooms/$room/messages?access_token=$access_token&from=$from"

ListenToMatrix.php

<?php
$homeserver = "glasgow.social";
$access_token = "access_token_goes_here";
 
// this is so you can start and stop the program, and it'll continue where it left off
$tracking_file "/tmp/listen_matrix.json";
 
while(true) {
$since = file_get_contents($tracking_file);
$messages = get_new_events($since);
if(!empty($messages['rooms']['join'] and is_array($messages['rooms']['join']))) {
   foreach($messages['rooms']['join'] as $room_id=>$data) {
      foreach($data['timeline']['events'] as $event_id=>$event) {
         if($event['type'] == "m.room.message") {
            $sender = $event['sender'];
            $content = "not text";
            if($event['content']['msgtype'] == "m.text")
               $content = $event['content']['body'];
            echo "$sender $room_id $content\n";
         }
      }
   }
}
$new_tracking_data = $messages['next_batch'];
file_put_contents($tracking_file, $new_tracking_data);
}
 
function get_new_events($since) {
   global $homeserver,$access_token;
   // timeout means the server will wait and only respond after 30 seconds, 
   // however if a message is returned before that time, it will return immediately
   $url = "https://$homeserver/_matrix/client/r0/sync?access_token=$access_token&timeout=30000";
   if(!empty($since))
      $url .= "&since=$since";
   $data = json_decode(file_get_contents($url), true);
   return $data;
}
 
 
?>

You can follow one particular room just using GET requests, by doing something like this:

function get_new_events($room) {
   $homeserver = "glasgow.social";
   $access_token = "access_token_goes_here"
   $url = "https://$homeserver/_matrix/client/r0/rooms/$room/messages?access_token=$access_token&from=$tracking_id";
   $data = json_decode(file_get_contents($url), true);
   return $data;
}

The basis of my bot's interaction with Matrix is bascially the above code. Replace the echo line with with whatever you want to do (in my case, I look up a list of rules [i.e. pairs of regexes and their response functions] I use in IRC from a database and act accordingly).

Media must first be uploaded to your homeserver, then you can send a new message, as above, using the m.image event type. Here is an example in PHP that works as a 'copy' command.

matrix_cp.php

#!/usr/bin/php
# Usage example: matrix_cp /tmp/test.jpg glasgow
# this will send the test.jpg to the glasgow room
# this also supports remote URLs
<?php
$usage = "Usage: ".$argv[0]." filename room_name alt_text[optional]\n";
$filename = "";
$room_name = "#pythia";
$alt_text = "Image attachment";
$homeserver = "glasgow.social";
$access_token = "access_token_goes_here"
// I have a lookup list of friendly room names to full IDs here
$channels["glasgow"] = "!BOrDFgeDdZZbUvfjjs:glasgow.social";
 
if(!empty($argv[2]))
   $room_name = $argv[2];
if(!empty($argv[3]))
   $alt_text = $argv[3];
 
$room = $channels[$room_name];
if(empty($room))
   die($room_name." not in room list");
 
if(empty($argv[1]))
   die("Filename is required. $usage");
 
$filename = $argv[1];
$image_data = file_get_contents($filename);
 
// this whole temporary file saving is all done to support mime_type lookups for remote URLs
$tmp_filename = "/tmp/".md5($argv[0].time());
 
if(empty($image_data))
   die("Unable to read file location");
file_put_contents($tmp_filename, $image_data);
$mime_type = mime_content_type($tmp_filename);
 
$url = "https://$homeserver/_matrix/media/r0/upload?access_token=$access_token";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: $mime_type"));
curl_setopt($ch, CURLOPT_POSTFIELDS, $image_data);
$response = curl_exec($ch);
 
if(!empty($response_json['content_uri'])) {
      $url = "https://$homeserver/_matrix/client/r0/rooms/$room/send/m.room.message?access_token=$access_token";
      $msgtype = "m.image";
      $mxc_url = $response_json['content_uri'];
      $ch = curl_init($url);
      $payload = json_encode(array("msgtype"=>$msgtype, "body"=>$alt_text, "url"=>$mxc_url));
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
      $response = curl_exec($ch);
      // SUCCESS.  No output.
   } else {
      echo "Error uploading $filename. ";
      echo implode(" : ", $response_json)."\n";
   }

You can copy this file to your bin directory and use it on the command line with:

matrix_cp /tmp/example.jpg glasgow "This is an example image"

The most feature rich server for Matrix is the Matrix.org Foundation's own Synapse server.

You can read installation instructions here: https://github.com/matrix-org/synapse/blob/master/INSTALL.md

The basic steps for a Debian/Ubuntu machine are:

sudo apt-get install build-essential python3-dev libffi-dev python3-pip python3-setuptools sqlite3 libssl-dev virtualenv libjpeg-dev libxslt1-dev

sudo apt install -y lsb-release wget apt-transport-https
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" |
    sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install matrix-synapse-py3

Then just edit your /etc/matrix-synapse/homeserver.yaml file and set your SSL certifcate, host name and port.