====== Matrix Command Line Tools ====== ===== Git ===== You can [[https://coding.openguide.co.uk/gitweb/?p=matrix-cli;a=summary|view the repository]] or clone the code directory from my repository:


git clone https://coding.openguide.co.uk/git/gemini-php/

===== Documentation ===== * https://matrix.org/docs/api/client-server/#/ * https://matrix.org/docs/spec/ ===== Getting your access token ===== * 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 '' * Copy and paste that into the example below ===== Getting a room ID ===== * Click on the three dots at the edge of a room name and click ''Settings'' * Choose ''Advanced'' to see the ''Internal Room ID'' * #glasgow on the server is ''!BOrDFgeDdZZbUvfjjs:glasgow.social'' ===== Posting messages to a room ===== It can be very simple to post a message to a room on Matrix (note: you have to be a member of the room). ==== Via bash/curl ==== This script requires ''jq'', the command line JSON processor.


sudo apt install jq

#!/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" ==== PHP example using Curl ==== $msgtype, "body"=>$msg)); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $payload); $response = curl_exec($ch); ?> ===== Listening to rooms ===== 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.


$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;
}

===== Matrix Bot ===== The basis of my bot's interaction with Matrix is basically 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). ===== Posting images to a room ===== 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.


#!/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
$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"