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 Nov 01, 2022
7.3k Nov 18, 2022
22 Aug 29, 2022
20 Oct 21, 2022
28 Aug 20, 2022
1 Dec 26, 2021
3 Oct 26, 2021
6 Jan 30, 2022
140 Dec 21, 2022
28 Oct 09, 2022
36 Nov 01, 2021
2 Jan 02, 2022
111 Oct 04, 2022
11 Jan 02, 2023
7 Nov 29, 2022
29 Dec 22, 2022
1 Dec 11, 2021
65 Nov 09, 2022
5.7k Jan 06, 2023
5 Oct 31, 2022