A Slack Bot for administering quizzes.

npm install quizzical@0.0.3



A Slack Bot for administering quizzes.


Install using the node package manager.

npm install -g quizzical


Slack Bot User

In order to use Quizzical, you'll need to create a Slack Bot User and take note of its token.

Plot.ly Account and API key

Optionally, you can configure Quizzical with Plot.ly information so that Quizzical can create summary graphs for quiz responses. The free plan is sufficient to run Quizzical.

Getting Started

Quizzical is a node application. Run it with:

quizzical [configuration options]


Configuration options can be passed via the command line or in a configuration file.

Command line

quizzical --slackToken abcd-123456 --botName "My Quizzical Bot" example_quiz.json

Configuration file

    "slackToken": "abcd-123456",
    "botName": "My Quizzical Bot"
quizzical --config example_config.json example_quiz.json

Configuration options

Option Required Default Description
slackToken x n/a Your slack bot user's API token
botName 'Quizzical' The name of the bot when seen in Slack
plotlyAPIKey n/a Your plot.ly API key, needed for graphing quiz results
plotlyUsername n/a Your plot.ly username, needed for graphing quiz results
config n/a Configuration file. Command line only.

Quiz files

You need to create quiz files for Quizzical in order to administer quizzes. You can add multiple quizzes by listing the files when running Quizzical.

quizzical --config example_config.json example_quiz.json quiz2.json quiz3.json

A quiz file looks like this:

    "id": "example-quiz",
    "name": "Example Quiz",
    "questions": [
            "q": "What shape is the earth?",
            "a": "a",
            "choices": {
                "a": "Round",
                "b": "Square",
                "c": "Triangular",
                "d": "Brown"
            "q": "There are ___ continents on earth",
            "a": "7"

Every quiz needs an id, name and a list of questions. Every question object must have a q (question) and a answer and, optionally, a map of choices for multiple choice questions. If no list of choices is provided, the question is free response. Note: free response questions should have simple one word or number answers because Quizzical is looking for exact answers.


In order to start a quiz, a Slack user (the instructor), needs to @ message the Quizzical bot in a public channel.

Start Quiz

Once the quiz is started, other Slack users (students) respond to it the Quizzical bot via direct message.

Answer Question

After everyone has had a chance to answer the first question, the instructor issues the next command to start the quiz in ernest. From now on, the quiz will automatically advance to the next question when all students have answered.

Next Question

Quizzical will report how students are doing in real time to the instructor.

Instructor Report

Finally, when the last question has been asked and answered, Quizzical will end the quiz, report the aggregate results in the public channel.

Quiz Summary

Quizzical will also report individual results via direct message.

Student Report