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
8 Aug 05, 2022
4 Mar 13, 2022
6 Jan 30, 2022
113 Jan 03, 2023
15 Oct 23, 2022
77 Jan 08, 2023
19 Dec 03, 2021
17 Oct 21, 2022
1.6k Jan 08, 2023
1 Mar 16, 2022
371 Dec 31, 2022
22 Aug 29, 2022
22 Dec 07, 2022
1 Jan 27, 2022
3 Jun 27, 2022
510 Dec 28, 2022
28 Dec 12, 2022
3 Oct 26, 2021
21 Nov 17, 2022
4 Feb 24, 2022