loc0CoreMatrixClient
A Limited Matrix Client Built With .Net Core
This is a limited client for interacting with the Matrix.org API. It can be used to create simple bots that recieved and send text/formatted messages, images, accept invites etc. I made this for personal use after I had to port a Discord bot of mine over to Riot. Also, still a pretty newb programmer so if you want to improve this in anyway feel free.
Current Progress
- Login with username/password
- Join Rooms
- Figure out syncing
- Create a listener for messages
- Create a class for interacting with rooms
- Upload content
- Allow joining rooms from invites
Todo
- Allow encryption to be used - Biggest task
- Whatever the future tells me to do!
Example Code
private static readonly MatrixClient MatrixClient = new MatrixClient();
public static void Main()
{
Example().GetAwaiter().GetResult();
}
private static async Task Example()
{
MatrixCredentials matrixCredentials = new MatrixCredentials("Username", "Password", "DeviceID" " DeviceName");
Console.WriteLine("Logging in...");
if (await MatrixClient.Login("hostServer", matrixCredentials))
{
Console.WriteLine("Success");
List<string> roomsToJoin = new List<string>
{
"#room1:host",
"!IDOfRoom:host"
};
List<string> joinResults = await MatrixClient.JoinRooms(roomsToJoin, true);
foreach (var joinResult in joinResults)
{
Console.WriteLine(joinResult);
}
MatrixClient.MessageReceived += MessageReceivedHandlerExample;
MatrixClient.StartListener();
await Task.Delay(-1);
}
else
{
Console.WriteLine("Failed");
}
}
private static async void MessageReceivedHandlerExample(MessageReceivedEventArgs args)
{
MatrixRoom messageRoom = MatrixClient.GetMatrixRoomObject(args.RoomId);
if (args.SenderId == "a" && args.Message.StartsWith("ping"))
{
MatrixTextMessage message = new MatrixTextMessage
{
Body = "pong"
};
var sendResult = await messageRoom.SendMessage(message);
}
}
Documentation
Format: method(type:parameterName):returnType
MatrixClient
Usage: MatrixClient matrixClient = new MatrixClient();
Methods
MatrixClient(int:messageLimit=10)
messageLimit is optional and defaults to 10
Login(string:hostServer, MatrixCredentials:credentials):bool
Login to a Matrix account through a MatrixCredentials object
Returns bool to indicate success
Logout():bool
Logout of the Matrix account currently in use
Will reset all properties of MatrixClient
JoinRooms(List<string>:roomsToJoin, bool:retryFailure):List<string>
Takes a list of rooms to join; retry failure will auto-retry any failed connects
Returns a list of strings containing success/failure messages
JoinRoom(string:roomsToJoin, bool:retryFailure):string
Takes a single room to join
Returns a single string containing a success/failure message
GetMatrixRoomObject(string:roomId):MatrixRoom
Accesses a dictionary which contains MatrixRoom objects for each room you've joined
Room ID acts as the key
I'd recommend you use this to create a new MatrixRoom instance though it's not required
StartListener():void
Starts a listener task for events in any rooms you've joined
StopListener():void
Cancels the listener task
Upload(string:filePath):string
Uploads any file to Matrix and returns the mxc url
Properties
string:AccessToken
Your access token
string:DeviceId
The device ID in use
string:HomeServer
The homeserver being used by the account
string:UserId
The user ID in use
string:FilterId
Id for filter being used in syncing
Events
MessageReceived:MessageReceivedEventArgs
An event for recieved messages
Passes a MessageReceivedEventArgs to your handler
InviteReceived:InviteReceivedEventArgs
An event for recieved invites
Passes a InviteReceivedEventArgs to your handler
MatrixCredentials
Usage: MatrixCredentials matrixCredentials = new MatrixCredentials(string:Username, string:Password, string:DeviceID string:DeviceName);
Properties
string:Username
Username of account
string:DeviceName
Device name client should use, if one is not supplied it will be auto-generated
string:Password
Password of account
string:DeviceId
Device ID client should use, if one is not supplied it will be auto-generated
MatrixRoom
Usage: MatrixRoom room = new MatrixRoom(string:homeServer, string:accessToken, string:roomId, string:roomAlias);
Methods
MatrixRoom(string:homeServer, string:accessToken, string:roomId, string:roomAlias)
Can take either a roomId or roomAlias
SendMessage(MatrixTextMessage:textMessage):bool
Sends a text message to the room, can be either a simple plain text message or HTML formatted
Returns a bool to indiciate success
SendMessage(MatrixFileMessage:fileMessage):bool
Sends an uploaded file to the room via a MxcUrl
Returns a bool to indiciate success
Properties
string:RoomId
roomId in use by the MatrixRoom instance
string:RoomAlias
roomAlias in use by the MatrixRoom instance
MatrixTextMessage
Usage: MatrixTextMessage matrixTextMessage = new MatrixTextMessage();
Properties
string:Body
Plain text body of the message
string:FormattedBody
HTML formatted text body of the message, you do not need both, only one or the other
string:Format
Format of the message, should be left empty unless the message is formatted, will be auto changed anyway
string:MsgType
MsgType, should always be m.text
MatrixFileMessage
Usage: MatrixFileMessage matrixFileMessage = new MatrixFileMessage();
Properties
string:Filename
Filename to be used when sending the file, this does not change the filename if someone downloads the file
string:Description
Description to be used for the file, defaults to the filename
string:Type
Type of the message being sent I.E. m.image, m.file etc.
string:MxcUrl
Mxc url of the uploaded file