opsdroid_quickstart.md

A Super Rapid Introduction to opsdroid with Matrix

To follow this guide you will need a matrix account for your bot.

You can register using any client such as Element, make note of your full matrix id username in the form "@name:server" and password, as well as the homeserver you register on if it isn't matrix.org. Also you will want to create an unencrypted room (easiest to make it public for the moment) and give it an address, make a note of this as well (and invite your personal matrix account). If you register with Element, make sure you logout, so that there are no encryption-supporting devices on your account.

Next, you will need a working python env, preferably a virtual env or similar, then install opsdroid:

$ pip install opsdroid[connector_matrix]

Make an empty directory and write a new config file called configuration.yaml with the following contents, inserting your account info where you need it:

connectors:
  matrix:
    mxid: "@username:matrix.org"
    password: "mypassword"
    rooms:
      main: "#mytestroom:matrix.org"
    homeserver: "https://matrix.org"  # You can omit this if you are using matrix.org
    
skills:
  hello: {}

run opsdroid with:

$ opsdroid start

if you (as your personal account) send a message saying "hello" into your room, the bot should respond to you.

Writing your own skill

If you want to make your bot do something custom, you will need to write your own opsdroid "skill", a skill is a bit of Python code which can receive and send events, as well as do anything else you wish.

In the same directory as your configuration.yaml file, make a new file called flip_a_coin.py, put the following code in it:

import random

from opsdroid.matchers import match_regex

@match_regex('flip a coin')
async def flip_a_coin(opsdroid, config, message):
    if random.randint(0, 1):
        response = "Heads"
    else:
        response = "Tails"

    await message.respond(f"{response}")

This is a simple skill which will return a random choice of "Heads" or "Tails when a message saying "flip a coin" is sent.

The most important components of this code snippet are the following:

@match_regex: this is the simplest of opsdroid's matchers, these are things which determine when your function is called. This one works by matching all text messages against a regular expression and triggering the skill if it matches.

await message.respond: This method allows you to send back a simple text message, in this case the randomly selected "Heads" or "Tails".

The rest of the body of the function should be understandable if you have some beginner understanding of Python.

To make opsdroid run your skill, we need to edit the "skills" section of the configuration.yaml file, we can leave the matrix section alone:

skills:
  hello: {}
  flip-a-coin:
    path: "flip_a_coin.py"

And then re-run opsdroid again with opsdroid start.

Next steps

You can write more complex bots by using different matchers. The most powerful matcher is the event matcher which you can use to match any matrix event the bot recieves. There are a number of events which are used by all connectors in opsdroid as well as a number of matrix specific events for more advanced usage.