Skip to content
This repository has been archived by the owner on Mar 23, 2023. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Survey Bot for Cisco Spark


A self-hosted Cisco Spark bot for taking surveys.



Create surveys through a web-based user interface.

Screenshot of creating a new survey

Conducts surveys via Cisco Spark.

Screenshot of survey being conducted

Watch survey results update in real-time.

Screenshot of results

Setup & Configuration

  1. Create a new user on Cisco Spark to be the bot. Admittedly, it's untraditional to use a user account, but because of the way the bot works, it needs to be a user and cannot be a bot or an integration.

    1. Once you create a user, go log in at Cisco Spark for Developers

    2. Click on your avatar in the top right hand corner to show your Access Token.

      Screenshot of getting your Access Token

    3. Copy that token and use it as your ACCESS_TOKEN environment variable.

  2. As that new user, create an integration:

    1. App icon

      Feel free to use this image URL.

    2. Redirect URI(s)

      You'll want this to be the PUBLIC_ADDRESS environment variable with /auth/spark/callback at the end.


    3. Scopes

      Choose the following scopes:

      Scope Reason for needing it
      spark:people_read so OAuth can fetch user info (name, avatar, etc...)
      spark:rooms_read for letting you choose a room to survey
      spark:memberships_read for knowing who is in a room
      spark:messages_write for sharing survey results
      spark:teams_read for letting you choose a team room to survey
    4. Once you create the integration, grab the Client ID and Client Secret. These will be the environment variables SPARK_OAUTH__CLIENT_ID and SPARK_OAUTH__CLIENT_SECRET.

  3. Set the following environment variables. If developing locally, you can put these in the .env or .env.local files:

    Environment variable Description
    PUBLIC_ADDRESS the address at which your bot can be reached
    ACCESS_TOKEN the access token from the user you created
    SPARK_OAUTH__CLIENT_ID the client id of the integration you created
    SPARK_OAUTH__CLIENT_SECRET the client secret of the integration you created
    SPARK_SECRET secret for validating the origin of webhooks and for encrypting cookies. Generate a random string for this value. If you are using Heroku, this will be generated for you if you use the "Deploy to Heroku" button. In development, feel free to ignore this as one will be generated for you but it will be different every time your app starts.
    REDIS_URL URL of your Redis server. If you are using Heroku, this will be added for you.
    PORT the port to run the web server. If you are using Heroku, this will be added for you.
    RESTRICT_LOGINS_TO_DOMAINS only allow users to log in if they match certain domains. Set to a comma separated list of allowed domain names. E.g.,, Must provide the full domain-- e.g. will not be allowed to log in if your list is If not set, it will allow logins with any domain name.

Deploying on Heroku

Use the "Deploy to Heroku" button above from this repo or a fork of this repo.

Running the bot via Docker

A Dockerfile has been included to run the bot via Docker. Here are some additional instructions for running the bot via Docker locally.

Put your environment variables in .env.local and run via:

docker build -t my-survey-bot .
docker run -it --env-file .env.local my-survey-bot


Work on the bot

  1. Follow the instructions in Setup & Configuration above, with the following notes:

    • Set your PUBLIC_ADDRESS env variable to your ngrok URL, e.g.
    • The SPARK_SECRET is not needed in development.
    • Set the ALLOW_DEV_LOGIN to 1 to let you log into the app without needing an internet connection. This will let you create and modify surveys, but will not let you conduct surveys.
  2. Install dependencies

     yarn install
  3. Start the local development server & redis:

     yarn start

    If you already have Redis running as a deamon or aren't using a local Redis server, do:

     yarn server-dev
  4. If using Docker, you can run the image specifying the environment file and exposing port 3000:

     docker run -it --env-file .env.local --publish 3000:3000 my-survey-bot
  5. Run ngrok (or something like it).

    Because Spark uses webhooks to talk to bots, you must run something like ngrok locally to expose your server to the web. We've included a script to do this for you (requires ngrok).

     yarn ngrok
  6. Add a Redirect URI to your Spark Integration settings that uses your ngrok URI. E.g.


Run the tests:

yarn test

Run the linter:

yarn lint

Run the test watcher, which will re-run tests after every file change:

yarn test-watch


Cisco Spark bot for for conducting surveys







No releases published


No packages published