A Discord bot for natural language surveys, inspired by and in the style of talk to the city.
Join the Discord server for discussing and developing this tool here.
-
Create a
.env.local
file with the following variables:DISCORD_TOKEN=XXXXXXXXX OPENAI_API_KEY=XXXXXXXXX # Redis host without port REDIS_HOST=XXXXXX REDIS_PORT=XXXXX REDIS_PASSWORD=XXXXXXX CLIENT_ID=XXXXXXXXX GUILD_ID=XXXXXXXXXX # Log Level, DEBUG, INFO, WARN etc. GSS_LOG_LEVEL=XXXXX SUMMARIZE_FREQUENCY_SECONDS=3600 # Discord forum channel id for posting channels. POST_CHANNEL_ID=XXXXX
-
Run
npm install
-
Fill in the REDIS_HOST, REDIS_PORT, and REDIS_PASSWORD for connecting your Redis DB:
- Go to Redis and create an account.
- Create a DB and click
connect
. Copy and paste your password, socket, and port into the.env.local
file. - You can see the Redis configuration in
config.js
.
-
Start the main bot script with
npm run bot
. -
Or start the main bot script with
npm run dev
to use nodemon in the development phase. -
Start the GPT summarization script with
npm run summarizer
.
Here is the section for the scripts in the README file:
The project includes several scripts to facilitate development and operations. Here is a brief explanation of each:
Runs the tests.
npm run test
Starts the main bot script.
npm run bot
Starts the main bot script in development mode using Nodemon to automatically restart the bot when changes are detected.
npm run dev
Starts the GPT summarization script.
npm run summarizer
Formats the codebase using Prettier.
npm run prettier
Resets the Redis database.
npm run reset
Use it to create single question surveys.
- SURVEY TITLE: Max 45 Char, cannot include "-"
- SURVEY DESCRIPTION:
- QUESTION: Max 45 Char
- SURVEY EXPIRE TIME: Must be
YYYY-MM-DD-HH-MM
format or can beinf
- SURVEY POSTING TO FORUM CONDITION:
true
orfalse
Use it to create multiple question surveys.
- SURVEY TITLE: Max 45 Char, cannot include "-"
- SURVEY DESCRIPTION:
- QUESTIONS: Each line separated "\n" or
enter
is one question. Each question must be maximum 45 Char for each line. Maximum question number ismaxResponsesForMultiResponsePerUser
in constants.ts. However it is strongly recommended to set is maximum 5 to prevent Modal UI based problems. - SURVEY EXPIRE TIME: Must be
YYYY-MM-DD-HH-MM
format or can beinf
- SURVEY POSTING TO FORUM CONDITION:
true
orfalse
You can use this if you want to post an active survey in another channel (bot must have access to post anything on that channel).
To view the responses with raw data txt file.
You can use this command to show people summaries of surveys. You can select summary type optionally: If "Yes", it will show high level summary of the survey. If "No", it will show general summary.
Edit survey name or questions, delete questions or add questions. Once submitted, if the survey was answered, the responses will be deleted. You can also set/edit a survey start and end date, or leave it infinite. Also, you can post the survey to forum channel making ``true` the last section.
Same restrictions in /create
command.
And if your survey in the forum channel. Do not change the title more than 2 times in 10 Minutes because of rate limit.
To activate or deactivate a survey.
To delete the survey.
To check the version.
To start auto-posting the responses view. It is working which channel that you used. For example, if you use it in forum channel, it will be activated in that channel.
To stop auto-posting the responses view. For example, if you use it in forum channel, it will be activated in that channel.
docker build -t <your-image-name>:<your-image-tag> .
The image has two operational modes: bot by default and summarizer.
To run the bot, use the bot
argument, and to run the summarizer, use summarizer
.
docker run -it -d --env-file ./.env <your-image-name>:<your-image-tag> bot
The --env-file
flag takes a filename as an argument and expects each line to be in the VAR=VAL format, mimicking the argument passed to --env
. Comment lines need only be prefixed with #
.
docker-compose up --build
TODO
- Sign up for a Discord account at Discord.
- Visit the Discord Developer Portal.
- Click on the "New Application" button.
- Name your application and create it.
- In your application settings, navigate to the "Bot" tab and click "Add Bot".
- Customize your bot as needed (username, icon).
- Still under the "Bot" tab, find your Token and click "Copy". Keep this safe; you'll need it later.
- Sign up with OpenAI: Create an account at OpenAI if you don't have one.
- Access your API key:
- Navigate to the API section and copy your API key for later use.
- Go to Redis and create an account.
- Create a DB and click
connect
. Copy and paste your password, socket, and port into the.env.local
file.
- Navigate to the Discord Developer Portal.
- Select your application: Click on the application you created for your bot.
- Locate the Client ID:
- Under the "Application" section (usually the first page you land on after selecting your application), you will find your Client ID. It's a long string of numbers.
- Click the "Copy" button next to the Client ID to copy it to your clipboard.
To get the Guild ID, you must ensure that "Developer Mode" is enabled in your Discord client settings.
- Open Discord Settings: Click on the gear icon next to your username at the bottom left corner of the Discord interface.
- Access Advanced Settings: In the left sidebar, scroll down and select "Advanced" under the "App Settings" section.
- Enable Developer Mode: Toggle the "Developer Mode" switch to the on position.
- Right-click your server icon:
- After enabling Developer Mode, go back to the server list on the left side of the Discord interface.
- Right-click the server (guild) where you intend to use the bot.
- Select 'Copy ID': At the bottom of the context menu, click "Copy ID" to copy the Guild ID to your clipboard.
- Use the Discord.js guide to register your slash commands either globally or to a specific guild for testing. The command registration can be part of your bot startup process or a separate script.
- Start your bot:
- In your terminal/command prompt, navigate to your project directory.
- Run
npm run bot
to start your bot.
- Invite your bot to your server:
- In the Discord Developer Portal, under your application's "OAuth2" settings, generate an invite link with the necessary bot permissions.
- Use the generated link to invite your bot to your server.
- Ensure Redis is running and accessible. If you installed Redis locally, it should be available at
redis://localhost:6379
. For remote instances, configure according to your provider's instructions.
- Test your bot on your Discord server by using the registered slash commands to create, list, and respond to surveys.
- Monitor the Redis database to ensure data is being saved and retrieved correctly.
- Ensure all environment variables are correctly set.
- Confirm that your bot has the necessary permissions on your Discord server to read messages, send messages, and manage interactions.
commands
folder for command related codes. can be used by importing@command/index
lib
folder for other functional codes.
└── 📁gptSurveySummarizer
└── .env.local
└── .gitignore
└── CODEOWNERS
└── Dockerfile
└── README.md
└── SETUP.md
└── docker-compose.yaml
└── dump.rdb
└── initial_notes.md
└── package-lock.json
└── package.json
└── settings.json
└── 📁src
└── bot.ts
└── 📁commands
└── commandBuilder.ts
└── handleAutoPost.ts
└── handleCreate.ts
└── handleDelete.ts
└── handleDeleteButton.ts
└── handleEdit.ts
└── handleInfo.ts
└── handleModals.ts
└── handleRespond.ts
└── handleRespondButton.ts
└── handleSetStatus.ts
└── handleSummary.ts
└── handleView.ts
└── index.ts
└── config.js
└── constants.ts
└── 📁lib
└── checkUpdateSurveys.js
└── createSurvey.js
└── deleteThreadPost.js
└── gptClient.js
└── index.ts
└── makeSurveyPost.js
└── startAutoPosting.js
└── surveyToText.js
└── threadPost.js
└── updateSurvey.js
└── updateThreadPost.js
└── logger.js
└── prompts.js
└── redisReset.ts
└── summarizer.js
└── 📁test
└── bot.test.js
└── summarizer.test.js
└── tsconfig.json
To make a contribution, follow these steps:
- Make an issue that includes a user story for what the user should be able to do (e.g., the user should be able to view the survey summary in their local language).
- Get that issue tested by: Cristina Echeverry.
- Get that issue approved by the product owners: es92 or Cristina Echeverry.
- Write a PR and get it approved by the code owners and Mina devops: Es92 (code owner), berkingurcan (developer & codeco-owner), johnmarcou (Mina devops). Each PR must correspond to an approved issue. By default, PRs should be merged by the PR submitter, though in some cases if changes are needed, they can be merged by code owners.