Quick Links: - Config file - Reference - Connector Modules - Database Modules - Logging - Installation Path - Parsers - Skills - Time Zone - Language - Web Server - Module Options - Install Location - Git Repository - Local Directory - Disable Caching - Disable dependency install - Environment Variables - Include Additional Yaml Files
For configuration, opsdroid uses a single YAML file named
configuration.yaml. When you run opsdroid it will look for the file in the following places in order:
- one of the default locations:
C:\<User>\<Application Data>\<Local Settings>\opsdroid\or
Note: If no file named
configuration.yaml can be found on one of these folders one will be created for you taken from the example configuration file
If you are using one of the default locations you can run the command
opsdroid -e or
opsdroid --edit-config to open the configuration with your favourite editor(taken from the environment variable
EDITOR) or the default editor vim.
The opsdroid project itself is very simple and requires modules to give it functionality. In your configuration file, you must specify the connector, skill and database* modules you wish to use and any options they may require.
Connectors are modules for connecting opsdroid to your specific chat service.
Skills are modules which define what actions opsdroid should perform based on different chat messages.
Database modules connect opsdroid to your chosen database and allow skills to store information between messages.
For example, a simple barebones configuration would look like:
connectors: - name: shell skills: - name: hello
In opsdroid all modules are git repositories which will be cloned locally the first time they are used. By default, if you do not specify a repository opsdroid will look at
https://github.com/opsdroid/<moduletype>-<modulename>.git for the repository. Therefore in the above configuration, the
skill-hello repositories were pulled from the opsdroid organisation on GitHub.
You are of course encouraged to write your own modules and make them available on GitHub or any other repository host which is accessible by your opsdroid installation.
A more advanced config would like similar to the following:
connectors: - name: slack token: "mysecretslacktoken" databases: - name: mongo host: "mymongohost.mycompany.com" port: "27017" database: "opsdroid" skills: - name: hello - name: seen - name: myawesomeskill repo: "https://github.com/username/myawesomeskill.git"
In this configuration we are using the slack connector with a slack auth token supplied, a mongo database connection for persisting data,
seen skills from the official repos and finally a custom skill hosted on GitHub.
Configuration options such as the
token in the slack connector or the
database options in the mongo database are specific to those modules. Ensure you check each module's required configuration items before you use them.
Opsdroid comes with some built-in connectors out of the box. A connector is a module which is either installed as a plugin or built-in that connect opsdroid to a specific chat service.
Note: More connectors will be added as built-in connectors into the opsdroid over time.
Config options of the connectors themselves differ between connectors, see the connector documentation for details.
connectors: - name: slack token: "mysecretslacktoken" # conceptual connector - name: twitter oauth_key: "myoauthkey" secret_key: "myoauthsecret"
Some connectors will allow you to specify a delay to simulate a real user, you just need to add the delay option under a connector in the
Thinking Delay: accepts a int, float or a list to delay reply by x seconds. Typing Delay: accepts a int, float or a list to delay reply by x seconds - this is calculated by the length of opsdroid response text so waiting time will be variable.
connectors: - name: slack token: "mysecretslacktoken" thinking-delay: <int, float or two element list> typing-delay: <int, float or two element list>
Note: As expected this will cause a delay on opsdroid time of response so make sure you don't pass a high number.
See module options for installing custom connectors.
Database modules which connect opsdroid to a persistent data storage service.
Skills can store data in opsdroid's "memory", this is a dictionary which can be persisted in an external database.
Config options of the databases themselves differ between databases, see the database documentation for details.
databases: - name: mongo host: "mymongohost.mycompany.com" port: "27017" database: "opsdroid"
See module options for installing custom databases.
Configure welcome message.
If set to true then a welcome message is printed in the log at startup. It defaults to true.
Configure logging in opsdroid.
path will configure where opsdroid writes the log file to. This location must be writeable by the user running opsdroid. Setting this to
false will disable log file output.
Note: If you forget to declare a path for the logs but have logging active, one of the default locations will be used.
All python logging levels are available in opsdroid.
level can be set to
You may not want opsdroid to log to the console, for example, if you are using the shell connector. However, if running in a container you may want exactly that. Setting
false will enable or disable console logging.
The default locations for the logs are:
If you are using one of the default paths for your log you can run the command
opsdroid -l or
opsdroid --view-log to open the logs with your favourite editor(taken from the environment variable
EDITOR) or the default editor vim.
logging: path: ~/.opsdroid/output.log level: info console: true connectors: - name: shell skills: - name: hello - name: seen
Set the path for opsdroid to use when installing skills. Defaults to the current working directory.
module-path: "/etc/opsdroid/modules" connectors: - name: shell skills: - name: hello - name: seen
When writing skills for opsdroid there are multiple parsers you can use for matching messages to your functions.
Config options of the parsers themselves differ between parsers, see the parser/matcher documentation for details.
parsers: - name: regex enabled: true # NLU parser - name: rasanlu url: http://localhost:5000 project: opsdroid token: 85769fjoso084jd min-score: 0.8
Some parsers will allow you to specify a min-score to tell opsdroid to ignore any matches which score less than a given number between 0 and 1. You just need to add the required min-score under a parser in the configuration.yaml file.
See the matchers section for more details.
Skill modules which add functionality to opsdroid.
Config options of the skills themselves differ between skills, see the skill documentation for details.
skills: - name: hello - name: seen
See module options for installing custom skills.
Configure the timezone.
Configure the language to use opsdroid.
To use opsdroid with a different language other than English you can specify it in your configuration.yaml. The language code needs to be in the standardized ISO 639-1.
Note: If no language is specified, opsdroid will default to English.
lang: <ISO 639-1 code - example: 'en'>
Configure the REST API in opsdroid.
By default, opsdroid will start a web server accessible only to localhost on port
8443 if ssl details are provided). For more information see the REST API docs.
web: host: '127.0.0.1' # set to '0.0.0.0' to allow all traffic port: 8080 ssl: cert: /path/to/cert.pem key: /path/to/key.pem
All modules are installed from git repositories. By default, if no additional options are specified opsdroid will look for the repository at
However, if you wish to install a module from a different location you can specify one of the following options.
A git URL to install the module from.
connectors: - name: slack token: "mysecretslacktoken" - name: mynewconnector repo: https://github.com/username/myconnector.git
Note: When using a git repository, opsdroid will try to update it at startup pulling with fast forward strategy.
A local path to install the module from.
skills: - name: myawesomeskill path: /home/me/src/opsdroid-skills/myawesomeskill
You can specify a single file.
skills: - name: myawesomeskill path: /home/me/src/opsdroid-skills/myawesomeskill/myskill.py
Or even an IPython/Jupyter Notebook.
skills: - name: myawesomeskill path: /home/me/src/opsdroid-skills/myawesomeskill/myskill.ipynb
A gist url to download and install the module from. This downloads the gist to a temporary file and then uses the single file local installer above. Therefore Notebooks are also supported.
skills: - name: ping gist: https://gist.github.com/jacobtomlinson/6dd35e0f62d6b779d3d0d140f338d3e5
Or you can specfiy the Gist ID without the full URL.
skills: - name: ping gist: 6dd35e0f62d6b779d3d0d140f338d3e5
no-cache to true to do a fresh git clone of the module whenever you start opsdroid.
databases: - name: mongodb repo: https://github.com/username/mymongofork.git no-cache: true
Disable dependency install
no-dep to true to skip the installation of dependencies on every start of opsdroid.
skills: - name: myawesomeskill no-cache: true no-deps: true
Note: This might be useful when you are developing a skill and already have the dependencies installed.
You can use environment variables in your config. You need to specify the variable in the place of a value.
skills: - name: myawesomeskill somekey: $ENVIRONMENT_VARIABLE
Note: Your environment variable names must consist of uppercase characters and underscores only. The value must also be just the environment variable, you cannot currently mix env vars inside strings.
Include additional yaml files
You can split the config into smaller modules by using the value
!include file.yaml to import the contents of a yaml file into the main config.
skills: !include skills.yaml
Note: The file.yaml that you wish to include in the config must be in the same directory as your configuration.yaml (e.g ~/.opsdroid)