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
206 Jan 03, 2023
58 Apr 13, 2021
3 Oct 31, 2022
1 Nov 13, 2021
2.1k Dec 31, 2022
1 Jan 30, 2022
6 Apr 28, 2022
18 Dec 14, 2022
254 Jan 05, 2023
3 Nov 12, 2021
6 Dec 25, 2022
5 Dec 30, 2021
10 Dec 30, 2022
4 Feb 28, 2022
1 Nov 21, 2021
6 Sep 22, 2022
21 Aug 12, 2022
171 Dec 27, 2022
33 Nov 13, 2022
124 Nov 23, 2022