Skip to content


GitHub deployments Codacy grade Code Climate maintainability Read the Docs dependency status for GitHub repo
GitHub tag (latest by date) Security: bandit Code style: black License
Gitter first-timers-only Made with love in Glasgow Respect Open Source Powered by Boyd Bot

Facebook Messenger Behance

This repository is for the Flask version of the Boyd Bot - a chatbot helping university students with their timetable.

🔧 Setup


The first step is to clone the repository in your preferred directory using

$ git clone
$ cd boyd_bot_messenger

This requires Git installed; you can also download a ZIP instead.


All requirements have been listed in requirements.txt, they can be installed in your preferred environment using

$ pip install -r requirements.txt

Environment Variables

Access tokens, keys, etc. have been hidden from the repository for obvious reasons. These are used as environment variables.

import os

xyz = os.environ.get("XYZ_KEY")

You must replace these with your own. You can either just replace os.environ.get() with the value (this is discouraged), or use

$ set XYZ_KEY="random_key_value"

🏛️ Want to use this for your university? Fork it!

It's lovely to know that you're considering to use this for your university. This project aims to act a base for many other chatbots. You can also use this repository as a template. A good idea is to start development with the terminal / CLI version. The following are considerations / instructions that you should know about if you aren't aware:


This version uses some external services that should be easily replaceable.

  • Facebook Messenger: The idea for this project is to present the timetable without having to install another application. A large number of university students use Facebook and its messaging service - Messenger. Users are identified using their unique IDs generated by Facebook specific to the app.
  • Dialogflow: also known as API AI. This enables webhook, integration with Facebook Messenger (and also other messaging services if needed), intents and small talk.
  • mongoDB: This is to store user details to acquire their timetable while being fast and convenient.


The code is documented using docstrings on Read the Docs; make sure you go through it. Since this repository acts like a template, there is not much to change. Much of it is mentioned, for example

tmzn = pytz.timezone("Europe/London")   # Timezone
cal_url = "link/to/timetable.ics"       # University ICS link

Templates should also be tailored to your need. Go through the files in templates and static.


Be sure to do your research on where and how to deploy your code! Make sure that access tokens, keys, etc. are changed, and, along with the code & database, are secure.

🙌 Contributions & Thanks

Contributions are more than welcome in any form, they are all allowed under the MIT License! 😄

Issues & Enhancements

There may be some planned updates or issues for this project. They're listed in the issues section with a helpful description (hopefully). Feel free to help out in order to solve these.


Special Thanks