Nio-Bot

Making Matrix bots simple

---

Installing

You can install the latest stable release from PyPi:

pip install nio-bot
# Or for cutting-edge releases:
# pip install --pre nio-bot

You may also want some extras:

• End-to-End encryption support: nio-bot[e2ee]
• The CLI (recommended): nio-bot[cli]
• Both: nio-bot[cli,e2ee]
• Development dependencies: nio-bot[dev]

Please note that e2ee uses olm, which depends on libolm. You can likely install this though your system package manager. To install the dev extra (for developing niobot itself), you will additionally need cmake, gcc, g++, python devel, and rustc.

Features

Nio-Bot extends matrix-nio, sitting on top of it, and simply providing a unified command interface, honing the base client to be more suited to bots and other automated applications.

Nio-Bot comes with a whole host of features to help make your development experience as easy as possible. Some features include, but are not limited to:

• A powerful commands framework (Modules, aliases, checks, easy extensibility)
• Custom argument parser support
• A flexible event system
• Simple end-to-end encryption
• Automatic markdown rendering when sending/editing messages
• Super simple to use Attachments system
• Very customisable monolithic client instance
• A simple, easy-to-use CLI tool for some on-the-go tasks
• Full attachment support (File, Image, Audio, Video), with encryption support
• In-depth, simple, clean documentation

Help

You can join our Matrix Room for help, or to just chat. You can also get the latest updates in development there, including having your say in how new things are implemented!

A quick example

# This example was written using version 1.1.0.
import niobot

client = niobot.NioBot(
    # Note that all of these options other than the following are optional:
    # * homeserver
    # * user_id
    # * command_prefix
    homeserver="https://matrix.example.org",  # it is important that you use the matrix server, not the delegation URL
    user_id="@example1:example.org",
    device_id="my-device-name",
    command_prefix="!",
    case_insensitive=True,
    owner_id="@example2:example.org",
    ignore_self=True  # default is True, set to false to not ignore the bot's own messages
)

@client.on_event("ready")
async def on_ready(sync_result: niobot.SyncResponse):
    print("Logged in!")


# A simple command
@client.command()
async def ping(ctx: niobot.Context):
    latency = ctx.latency
    await ctx.respond(f"Pong! {latency:.2f}ms")


# A command with arguments
@client.command()
async def echo(ctx: niobot.Context, *, message: str):
    await ctx.respond("You said: " + message)


client.run(access_token="...")

Using the CLI to get an access token

If you install the cli extras, you can use niocli to get an access token from a username and password (read this for why you'd want to use an access token):

niocli get-access-token -U '@example1:example.org' -D 'my-device-name'

After putting in your password, an access token will be printed to the console once the login is successful.

Further reading

Look at the docs for more information on how to use Nio-Bot, or the examples on GitHub.