MatrixTexter

v1.2: 2022-04-23

What?

This library allows you to easily send messages to matrix.org chat rooms from your PHP scripts.

I use it to send server cron job alerts to my devices, and it works beautifully.

Setup and usage

I'm using the Element Matrix client, but it really doesn't matter.

1. Create a Matrix account that'll be used to send the messages.
2. Create or join a chat room in which you want to send messages.
   Note the room ID (in Element, this is visible in the URL bar when you open the chat room. Looks something like !bAZNrHWkNobgqyTJiU:matrix.org).
   Make sure end-to-end encryption is turned off.
3. Include MatrixTexter.php in your script, and use as below:

require 'MatrixTexter.php';

$homeserver = "https://matrix.org";
$username = "USERNAME_GOES_HERE";
$password = "PASSWORD_GOES_HERE";
$roomID = "!ROOM_ID_GOES_HERE:matrix.org";

$accessToken = \MatrixTexter\login($homeserver, $username, $password);

$message = "Test Message!";

\MatrixTexter\sendMessage($homeserver, $accessToken, $roomID, $message);

Functions

If an action fails, the function will throw an exception with the error code received from the homeserver.

1. login($homeserver, $username, $password)

Authenticates with the homeserver and returns an access token that should be used while sending messages.

2. logout($homeserver, $accessToken)

Invalidates a user access token, so that it can no longer be used to send messages.

3. sendMessage($homeserver, $accessToken, $roomID, $message)

Sends the message to the specified chat room.

Notes

1. You can specify a PEM file for TLS requests at the top of MatrixTexter.php.
2. Access tokens do not expire (at least, not when the homesever is running Synapse), and should be cached. You do not need to call login() every time you want to send a message.

Relevant documentation: [1], [2].

---

Documentation updated: 2022-04-23.