Halcyon is a Matrix bot library created with the intention of being easy to install and use. Inspired by discord.py

Overview

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

  1. Create a matrix account for the bot
  2. Install Halcyon using python3 -m pip install halcyon or download it from the Releases tab in Github
  3. Generate a token using python3 -m halcyon -s homeserver.xyz -u @user:homeserver.xyz -p yourP@$$w0rd
  4. 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

  1. generate a new token
  2. decode an existing token
  3. revoke a single token
  4. 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
You might also like...
A simple Discord Bot created for basic functionality and fun chat commands for use in a private server.

LoveAndChaos-Bot v0.1.0 LoveAndChaos-Bot is a Discord Bot specifically designed for a private server; this bot is merely a test and a method to expose

Discord bot for name verifying. Created for TinkerHubGCEK discord server. Tinky is now deployed in heroku

Custom Discord bot This custom discord-python bot assigns roles to members joined at discord server. It looks and compares a list before verifying the

Satoshi is a discord bot template in python using discord.py that allow you to track some live crypto prices with your own discord bot.

Satoshi ~ DiscordCryptoBot Satoshi is a simple python discord bot using discord.py that allow you to track your favorites cryptos prices with your own

Twitter bot that turns comment chains into ace attorney scenes. Inspired by and using https://github.com/micah5/ace-attorney-reddit-bot

Ace Attorney twitter Bot Twitter bot that turns comment chains into ace attorney scenes. Inspired by and using https://github.com/micah5/ace-attorney-

Easy to use reaction role Discord bot written in Python.
Easy to use reaction role Discord bot written in Python.

Reaction Light - Discord Role Bot Light yet powerful reaction role bot coded in Python. Key Features Create multiple custom embedded messages with cus

Step by Step Guide To Install Discord Py Master Branch on Replit
Step by Step Guide To Install Discord Py Master Branch on Replit

Guide to Install Discord Py Master Branch on Replit Step 1 Create an empty repl on replit Step 2 Add this Basic Code to the file main.py so as to chec

Anime-Discord-Bot - Lightweight anime searching Discord bot supported by the AnilistPython library (anilist.co APIv2 wrapper))
Easy-apply-bot - A LinkedIn Easy Apply bot to help with my job search.

easy-apply-bot A LinkedIn Easy Apply bot to help with my job search. Getting Started First, clone the repository somewhere onto your computer, or down

Comments
  • `NameError: name 'idReturn' is not defined` when attempting to start a Halcyon-based bot after a small amount of use

    `NameError: name 'idReturn' is not defined` when attempting to start a Halcyon-based bot after a small amount of use

    I am running halcyon-stock-bot. I invited it to one room to tested it (it sent its welcome message and responded to a ticker symbol). I invited it to another and it joined and then crashed with a traceback similar to this one. It did not send its welcome message. I restarted the bot process and it's now always producing the following traceback:

    Traceback (most recent call last):
        File "/app/bot.py", line 63, in <module>
            client.run(halcyonToken=keys["halcyon"], longPollTimeout=1)#make sure you set it back to 30sec once your done debugging
        File "/usr/local/lib/python3.10/site-packages/halcyon/halcyon.py", line 482, in run
            self._roomcacheinit()
        File "/usr/local/lib/python3.10/site-packages/halcyon/halcyon.py", line 119, in _roomcacheinit
            self.roomCache["rooms"][roomID] = room(rawEvents=self.restrunner.getRoomState(roomID), roomID=roomID)
        File "/usr/local/lib/python3.10/site-packages/halcyon/room.py", line 81, in __init__
            self.predecessor = self.roomPredecessor(event["content"].get("predecessor"))
        File "/usr/local/lib/python3.10/site-packages/halcyon/room.py", line 155, in __init__
            self._parseRawContent(rawContent)
        File "/usr/local/lib/python3.10/site-packages/halcyon/room.py", line 164, in _parseRawContent
            self.event = idReturn(rawContent.get("event_id"))
    NameError: name 'idReturn' is not defined
    

    and failing to start.

    I am running inside a docker container I built myself in Kubernetes. That container is built from this base dockerfile and this stock bot specific dockerfile.

    Happy to provide whatever other detail you need to help troubleshoot.

    opened by jeffcasavant 2
Releases(1.1.1)
Owner
Wes Ring
Infosec & random things
Wes Ring
42-event-notifier - 42 Event notifier using 42API and Github Actions

42 Event Notifier 42서울 Agenda에 새로운 이벤트가 등록되면 알려드립니다! 현재는 Github Issue로 등록되므로 상단

6 May 16, 2022
asyncio client for Deta Cloud

aiodeta Unofficial client for Deta Clound Install pip install aiodeta Supported functionality Deta Base Deta Drive Decorator for cron tasks Examples i

Andrii Leitsius 19 Feb 14, 2022
Python bindings for ArrayFire: A general purpose GPU library.

ArrayFire Python Bindings ArrayFire is a high performance library for parallel computing with an easy-to-use API. It enables users to write scientific

ArrayFire 402 Dec 20, 2022
The best discord.py template with a changeable prefix

Discord.py Bot Template By noma4321#0035 With A Custom Prefix To Every Guild Function Features Has a custom prefix that is changeable for every guild

Noma4321 5 Nov 24, 2022
Change Discord HypeSquad in few seconds!

a simple python script that change your hypesquad to what house you choose

Ho3ein 5 Nov 16, 2022
S3-cleaner - A Python script attempts to delete the all objects/delete markers/versions from specific S3 bucket

Remove All Objects From S3 Bucket This Python script attempts to delete the all

9 Jan 27, 2022
This is my Discord-Bot named priamoryki-bot based on python.

This is my Discord-Bot named priamoryki-bot based on python. It's a public repository without private information, so you need to correct some code for everything to be working.

priamoryki 2 Dec 14, 2022
The Social-Engineer Toolkit (SET) is specifically designed to perform advanced attacks against the human element.

The Social-Engineer Toolkit (SET) The Social-Engineer Toolkit (SET) is specifically designed to perform advanced attacks against the human element. SE

Professor 6 Nov 28, 2022
Python-based Snapchat score booster using pyautogui module

Snapchat Snapscore Botter Python-based Snapchat score booster using pyautogui module. Click here to report bugs. Usage Download ZIP here and extract t

477 Dec 31, 2022
Light weight Scripts and Apps for checking availability of Covid Vaccines in India. Notifies when vaccine becomes avialable in your area.

vaccine-checker Light weight Scripts and Apps for checking availability of Covid Vaccines in India. Notifies when vaccine becomes avialable in your ar

Abishek V Ashok 8 Jun 16, 2021
livestream-chat: Overlay para chats de livestreams

livestream-chat Overlay para chats de livestreams. Inicialmente para rodar dentro do browser do obs-studio. TODO: Issues iniciais Suporte a API do You

Eduardo Mendes 10 Dec 16, 2022
NFT Generator - A NFT Generator created using Python

NFT_Generator v1 An NFT Generator created using Python. This NFT Generation tool

3 Dec 02, 2022
A Telegram Filter Bot, Support Unlimited Filter. Also, The Bot can auto-filter telegram File | video

A Telegram Filter Bot, Support Unlimited Filter. Also, The Bot can auto-filter telegram File | video

Hash Minner 3 Nov 27, 2021
Telegram Bot that's allow you to play Video & Music on Telegram Group Video Chat

WAR MUSIC / VIDEO PLAYER Bot Bot Link: 🧪 Get SESSION_NAME from below: Pyrogram 🎭 Preview ✨ Features Music & Video stream support MultiChat support P

Abhishek singh 11 Dec 25, 2022
Image-Bot-Discord - This Is a discord bot that shows the specific image you search from Google

Advanced Discord.py Image Bot CREDITS Made by RLX and Mathiscool README by Milrato Installation Guide in .env Adjust the TOKEN python main.py to start

RLX 3 Jan 16, 2022
An API Client package to access the APIs for NBA.com

nba_api An API Client package to access the APIs for NBA.com Development Version: v1.1.9 nba_api is an API Client for www.nba.com. This package is mea

Swar Patel 1.4k Jan 01, 2023
Live Coding - Mensageria na AWS com Amazon SNS e Amazon SQS

Live Coding - Mensageria na AWS com Amazon SNS e Amazon SQS Repositório para o Live Coding do dia 08/12/2021 Serviços utilizados Amazon SNS Amazon SQS

Cassiano Ricardo de Oliveira Peres 3 Mar 01, 2022
A Discord bot that generates inspirational quotes & motivating messages whenever a user is sad

Encourage bot is a discord bot that allows users to randomly get Inspirational quotes messages and gives motivational encouragements whenever someone says that he's sad/depressed.

1 Nov 25, 2021
This is a telegram bot built using the Oxford Dictionary API

Oxford Dictionaries Telegram Bot This is a telegram bot built using the Oxford Dictionary API Source: Oxford Dictionaries API Documentation Install En

Abhijith N T 2 Mar 18, 2022
A Bot To Get Info Of Telegram messages , Media , Channel id Group ID etc.

Info-Bot A Bot To Get Info Of Telegram messages , Media , Channel id Group ID etc. Get Info Of Your And Messages , Channels , Groups ETC... How to mak

Vɪᴠᴇᴋ 23 Nov 12, 2022