Halcyon
Halcyon is a Matrix bot library with the goal of being easy to install and use. The library takes inspiration from discord.py and the Slack libraries. Encryption is on the roadmap, and with the goal of being transparent to the user. Check the roadmap in notes.md, and see information of the token format in tokenFormat.md
Ask questions in the matrix chat #halcyon:blackline.xyz or in GitHub issues.
Current features
- A nice CLI tool to generate Halcyon tokens
- Login with token or username/password
- Fetch for new messages every x seconds using await
- Event hooks for
- on_ready()
- on_message(message)
- on_message_edit(message)
- on_room_invite(room)
- on_room_leave(roomID)
- Action hooks
- send_message(roomID, body, textFormat, replyTo, isNotice)
- send_typing(roomID, seconds)
- change_presence(presence, statusMessage)
- join_room(roomID)
- download_media(mxc)
- upload_media(fileBuffer, fileName)
- Room and message objects for incoming events events
- Basic documentation (Check usage.md)
Getting started
- Create a matrix account for the bot
- Install Halcyon using
python3 -m pip install halcyonor download it from the Releases tab in Github - Generate a token using
python3 -m halcyon -s homeserver.xyz -u @user:homeserver.xyz -p yourP@$$w0rd - Start with the demo code below
Example bot code
See more example and message object info in usage.md
import halcyon
import requests, json
client = halcyon.Client()
@client.event
async def on_room_invite(room):
"""On room invite, autojoin and say hello"""
print("Someone invited us to join " + room.name)
await client.join_room(room.id)
await client.send_message(room.id, body="Hello humans")
@client.event
async def on_message(message):
"""If we see a message with the phrase 'give me random', do a reply message with 32 random characters"""
print(message.event.id)
if "give me random" in message.content.body:
await client.send_typing(message.room.id) # This typing notification will let the user know we've seen their message
body = "This looks random: " + requests.get("https://random.wesring.com").json()["value"]
await client.send_message(message.room.id, body=body, replyTo=message.event.id)
@client.event
async def on_ready():
print("Online!")
await client.change_presence(statusMessage="indexing /dev/urandom")
if __name__ == '__main__':
client.run(halcyonToken="eyJ0eXAiO...")
CLI usage
halcyon can be called from the CLI to do some management of the account.
See the help message with python3 -m halcyon -h Right now it can be used to
- generate a new token
- decode an existing token
- revoke a single token
- revoke all tokens
usage: halcyon [-h] [-s SERVER] [-u USERNAME] [-p PASSWORD] [--include-password] [--decode DECODE] [--pretty] [--revoke REVOKE] [--revoke-all-tokens REVOKE_ALL_TOKENS]
By this, you can generate a halcyonToken for your project, for example python3 -m halcyon -s matrix.org -u @kevin:matrix.org -p on&on&on1337
optional arguments:
-h, --help show this help message and exit
-s SERVER, --server SERVER
Homeserver the user belongs to ex: matrix.org
-u USERNAME, --username USERNAME
Your full username ex: @kevin:matrix.org
-p PASSWORD, --password PASSWORD
Your full password for your matrix account
--include-password Save your username and password in the token for reauth (Not required right now since matrix tokens do not expire)
--decode DECODE Decode an existing token that you pass in
--pretty Pretty print the decoded token
--revoke REVOKE Revoke an existing token
--revoke-all-tokens REVOKE_ALL_TOKENS
Revoke an all existing token for the account
Have fun creating
1 Dec 12, 2021
2 Dec 16, 2021
2 Sep 15, 2022
542 Dec 17, 2022
24 Sep 21, 2022
109 Dec 20, 2022
7 Nov 18, 2022
3 Jul 14, 2022
5 Dec 9, 2022
1 Jan 26, 2022
2 Jan 11, 2022
4 Sep 03, 2022
4.7k Jan 02, 2023
1 Oct 09, 2022
1 Nov 02, 2021
1 Nov 01, 2021
33 Dec 31, 2022
12 Dec 28, 2022
12 Dec 27, 2022
0 Feb 16, 2022
11 Jun 30, 2022
0 Jan 20, 2022
50 Dec 20, 2022
14 Nov 12, 2022
4 Aug 18, 2022
22 Sep 19, 2022
1.7k Jan 03, 2023
32 Oct 01, 2022
19 Dec 01, 2022