Examples
A Basic Echo Bot
"""
Example Usage:
random_user
!echo something
echo_bot
something
"""
import simplematrixbotlib as botlib
creds = botlib.Creds("https://home.server", "user", "pass")
bot = botlib.Bot(creds)
PREFIX = '!'
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and match.command(
"echo"):
await bot.api.send_text_message(room.room_id,
" ".join(arg for arg in match.args()))
bot.run()
An Echo Bot with Encryption and Verification Support
"""
Example Usage:
random_user
*emoji verification or one-sided verification
random_user
!echo something
echo_bot
something
"""
import simplematrixbotlib as botlib
config = botlib.Config()
# config.encryption_enabled = True # Automatically enabled by installing encryption support
config.emoji_verify = True
config.ignore_unverified_devices = True
creds = botlib.Creds("https://home.server", "user", "pass")
bot = botlib.Bot(creds, config)
PREFIX = '!'
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot()\
and match.prefix()\
and match.command("echo"):
await bot.api.send_text_message(room.room_id,
" ".join(arg for arg in match.args()))
bot.run()
A “High-Five” Bot
"""
Example Usage:
random_user
!count
echo_bot
The bot has been high-fived 10 times!
random_user
!high_five
echo_bot
random_user high-fived the bot!"
random_user
!count
echo_bot
The bot has been high-fived 11 times!
"""
import simplematrixbotlib as botlib
creds = botlib.Creds("https://example.org", "hight_five_bot", "secretpassword")
bot = botlib.Bot(creds)
PREFIX = '!'
try:
with open("high_fives.txt", "r") as f:
bot.total_high_fives = int(f.read())
except FileNotFoundError:
bot.total_high_fives = 0
@bot.listener.on_message_event
async def bot_help(room, message):
bot_help_message = f"""
Help Message:
prefix: {PREFIX}
commands:
help:
command: help, ?, h
description: display help command
give high fives:
command: high_five, hf
description: high-five the bot!
count:
command: count, how_many, c
description: show amount of high fives
"""
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and (
match.command("help") or match.command("?") or match.command("h")):
await bot.api.send_text_message(room.room_id, bot_help_message)
@bot.listener.on_message_event
async def high_five(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and (
match.command("high_five") or match.command("hf")):
bot.total_high_fives += 1
with open("high_fives.txt", "w") as f:
f.write(str(bot.total_high_fives))
await bot.api.send_text_message(
room.room_id, f"{message.sender} high-fived the bot!")
@bot.listener.on_message_event
async def high_five_count(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and (
match.command("count") or match.command("how_many")
or match.command("c")):
await bot.api.send_text_message(
room.room_id,
f"The bot has been high-fived {str(bot.total_high_fives)} times!")
bot.run()
A Rock Paper Scissors Bot
import simplematrixbotlib as botlib
import os
import random
creds = botlib.Creds("https://example.org", "echo_bot", "secretpassword")
bot = botlib.Bot(creds)
PREFIX = '!'
@bot.listener.on_message_event
async def help_message(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if not (match.is_not_from_this_bot() and match.prefix()
and match.command("help")):
return
message = (f"""
Help
============================
What is this bot?
Rock Paper Scissors Bot is a Matrix bot that plays rock paper scissors with room members and is written in Python using the simplematrixbotlib package.
Commands?
{PREFIX}help - show this message
{PREFIX}play <rock/paper/scissors> - play the game by making a choice
""")
await bot.api.send_text_message(room.room_id, message)
@bot.listener.on_message_event
async def make_choice(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if not (match.is_not_from_this_bot() and match.prefix()
and match.command("play")):
return
temp = True
if not match.args():
temp = False
elif "rock" == match.args()[0]:
choice = "rock"
elif "paper" == match.args()[0]:
choice = "paper"
elif "scissors" == match.args()[0]:
choice = "scissors"
else:
temp = False
victory_table = {"rock": "scissors", "scissors": "paper", "paper": "rock"}
if temp:
bot_choice = random.choice(["rock", "paper", "scissors"])
await bot.api.send_text_message(room.room_id, f"You choose {choice}.")
await bot.api.send_text_message(room.room_id,
f"The bot chose {bot_choice}.")
if choice == bot_choice:
await bot.api.send_text_message(room.room_id, "You Tied!")
if bot_choice == victory_table[choice]:
await bot.api.send_text_message(room.room_id, "You Won!")
if choice == victory_table[bot_choice]:
await bot.api.send_text_message(room.room_id, "You Lost!")
else:
await bot.api.send_text_message(
room.room_id,
"Invalid choice. Please choose \"rock\", \"paper\", or \"scissors\"."
)
bot.run()
A Reaction Echo Bot
"""
Example Usage:
random_user
!echo something
random_user2
*reacts with 👍️
echo_reaction_bot
Reaction: 👍️
"""
import simplematrixbotlib as botlib
creds = botlib.Creds("https://example.com", "echo_reaction_bot", "password")
bot = botlib.Bot(creds)
@bot.listener.on_reaction_event
async def echo_reaction(room, event, reaction):
resp_message = f"Reaction: {reaction}"
await bot.api.send_text_message(room.room_id, resp_message)
bot.run()
Echo Bot within a Docker Container
FROM python:latest
RUN python -m pip install simplematrixbotlib
ADD echo.py echo.py
CMD [ "python", "echo.py" ]
Echo Bot using Config Files
"""
Example Usage:
random_user
!echo something
echo_bot
something
"""
import simplematrixbotlib as botlib
creds = botlib.Creds("https://home.server", "user", "pass")
config = botlib.Config()
config.load_toml("config.toml")
bot = botlib.Bot(creds, config)
PREFIX = '!'
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and match.command(
"echo"):
await bot.api.send_text_message(room.room_id,
" ".join(arg for arg in match.args()))
bot.run()
Bot Config File in TOML format
[simplematrixbotlib.config]
join_on_invite = false
Echo Bot with Allow/Blocklist Config File
#Used with Bot Config File in TOML format
"""
Example Usage:
admin1
!echo something
echo_bot
something
admin3
!echo something
user1
!echo something
"""
import simplematrixbotlib as botlib
creds = botlib.Creds("https://home.server", "user", "pass")
config = botlib.Config()
config.load_toml("config.toml")
bot = botlib.Bot(creds, config)
PREFIX = '!'
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() \
and match.is_from_allowed_user() \
and match.prefix() \
and match.command("echo"):
await bot.api.send_text_message(room.room_id,
" ".join(arg for arg in match.args()))
bot.run()
Bot Config File in TOML format
[simplematrixbotlib.config]
allowlist = ['@admin.*:example\.org']
blocklist = ['@admin3:example\.org']
Using Allow/Blocklist Interactively + Config File
"""
Example Usage:
note the escaped dot (\.)
user1
!allow @user2:example\.org
admin1
!allow @user1:example\.org, @admin2:example\.org
echo_bot
allowing @user1:example\.org, @admin2:example\.org
user1
!allow @user2:example\.org
echo_bot
allowing @user2:example\.org
admin2
!disallow @user1:example\.org
"""
import simplematrixbotlib as botlib
creds = botlib.Creds("https://home.server", "user", "pass")
config = botlib.Config()
config.load_toml("config_allow_interactive.toml")
bot = botlib.Bot(creds, config)
PREFIX = '!'
@bot.listener.on_message_event
async def echo(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() \
and match.is_from_allowed_user() \
and match.prefix():
if match.command("allow"):
bot.config.add_allowlist(set(match.args()))
await bot.api.send_text_message(
room.room_id,
f'allowing {", ".join(arg for arg in match.args())}')
if match.command("disallow"):
bot.config.remove_allowlist(set(match.args()))
await bot.api.send_text_message(
room.room_id,
f'disallowing {", ".join(arg for arg in match.args())}')
bot.run()
Bot Config File in TOML format
[simplematrixbotlib.config]
allowlist = ['@admin1:example\.org']
Bot using Custom Option Config File
"""
Example Usage:
random_user
!get
echo_bot
something
"""
import simplematrixbotlib as botlib
from dataclasses import dataclass
@dataclass
class MyConfig(botlib.Config):
_my_setting: str = "Hello"
@property
def my_setting(self) -> str:
return self._my_setting
@my_setting.setter
def my_setting(self, value: str) -> None:
self._my_setting = value
creds = botlib.Creds("https://home.server", "user", "pass")
config = MyConfig()
config.load_toml('config_custom.toml')
bot = botlib.Bot(creds, config)
PREFIX = '!'
@bot.listener.on_message_event
async def get(room, message):
match = botlib.MessageMatch(room, message, bot, PREFIX)
if match.is_not_from_this_bot() and match.prefix() and match.command(
"get"):
await bot.api.send_text_message(room.room_id, config.my_value)
bot.run()
Bot Config File in TOML format
[simplematrixbotlib.config]
my_value = 'Hello World'