Unthread Discord Bot 🤖 - Official Integration

The Unthread Discord Bot seamlessly connects your Discord community with Unthread's powerful ticket management system. This official integration transforms how you handle support requests by enabling users to create and manage tickets directly within Discord.

With simple commands and forum integration, support tickets automatically sync between both platforms, streamlining your workflow and improving response times. Whether you're managing a gaming community, running a business server, or supporting an open-source project, this bot provides the tools you need for efficient, organized customer support.

🤗 Special Thanks

💎 Platinum Sponsor
Unthread Streamlined support ticketing for modern teams.

🤔 How It Works

1. Users create tickets via the /support command or by posting in configured forum channels
2. The bot instantly creates a corresponding ticket in your Unthread dashboard
3. All replies and updates sync in real-time between Discord and Unthread
4. Support staff can manage tickets from either platform seamlessly

Ready to transform your Discord support experience? Get started in minutes with our one-click deployment!

✨ Key Features

• Seamless Ticket Creation: Create support tickets with the intuitive /support command or through configured forum channels
• Effortless Integration: Connect your Discord server to Unthread's powerful ticket management system in minutes
• Real-time Synchronization: All ticket updates and responses automatically sync between Discord and Unthread
• Forum Channel Support: Transform any forum post into a fully-managed support ticket without extra steps
• Advanced Caching: Redis-powered caching system for improved performance and reliability
• Permission Validation: Intelligent permission checking to prevent conflicts and ensure proper functionality
• Thread-based Management: Each ticket creates a dedicated thread for organized communication
• Webhook Notifications: Receive instant updates when ticket statuses change or new replies are added
• User-friendly Interface: Simple commands and clear notifications enhance the support experience for everyone
• Debug Mode: Comprehensive logging system for development and troubleshooting
• Retry Mechanism: Built-in retry logic for handling API failures and network issues
• Customer Management: Automatic customer profile creation and management integration

📥 Easy Deployment

You can use Railway to deploy this bot with just one click. Railway offers a seamless deployment experience without any configuration hassles.

Tip

When you deploy using the Railway button above, you're directly supporting the ongoing development and maintenance of this project. Your support helps keep this bot free and continuously improving with new features. Thank you for your contribution! 🙏✨

🕹️ Usage

Creating a Support Ticket

1. Using the /support Command:

   • Type /support in any text channel where the bot has access.
   • A modal will appear with fields for:
     • Ticket Title: A brief description of your issue
     • Summary: Detailed explanation of your problem
     • Contact Email (Optional): Your email address for notifications

2. Using Forum Channels:

   • Create a new post in any forum channel that has been configured for ticket creation.
   • Your post will automatically be converted to a support ticket.
   • A confirmation message will appear in the thread.

Managing Tickets

• Replying to Tickets:

  • Simply reply in the private thread or forum post created by the bot.
  • Your messages will be synced with the Unthread system.

• Viewing Ticket Status:

  • Status updates (open/closed) will be posted in the thread automatically.

Utility Commands

• /ping - Shows bot latency and API ping metrics.
• /server - Provides information about the Discord server.
• /user - Shows details about your user account.
• /version - Displays the current bot version.

📦 Manual Installation

Warning

This is an advanced installation method and is not recommended for beginners. If you're new to Discord bot development, consider using the Railway deployment method instead.

Prerequisites

• Node.js: Version 18.16.0 or higher
• Yarn: Version 4.9.2 (recommended package manager)
• Discord Application: Bot token and proper permissions
• Unthread Account: API access and configuration

1. Create a Discord Application

1. Go to the Discord Developer Portal.
2. Click on the "New Application" button.
3. Give your application a name and click "Create".

2. Setup Application Bot

1. In your newly created application, navigate to the "Bot" tab.
2. Click on the "Add Bot" button and confirm by clicking "Yes, do it!".
3. Under the "TOKEN" section, click "Copy" to copy your bot token. You will need this later.
4. Under "Privileged Gateway Intents", enable the "Message Content Intent".

3. Add the Bot to Your Discord Server

1. Navigate to the "OAuth2" tab and then to the "URL Generator" sub-tab.

2. Under "SCOPES", select bot and applications.commands.

3. Under "BOT PERMISSIONS", select the following required permissions:

   • Send Messages
   • Send Messages in Threads
   • Create Public Threads
   • Create Private Threads
   • Manage Threads
   • Embed Links
   • Read Message History
   • Use Slash Commands
   • View Channels

4. Use the generated URL to invite your bot to your server, or use this pre-configured link (replace YOUR_BOT_CLIENT_ID with your actual bot client ID):

   https://discord.com/oauth2/authorize?client_id=YOUR_BOT_CLIENT_ID&permissions=1084479760448&integration_type=0&scope=bot+applications.commands

Note: The bot requires these specific permissions to create and manage threads for ticket handling. Missing permissions may cause functionality issues.

4. Fill Out the Environment Files

1. Create a .env file in the root directory of your project.
2. Copy the contents of .env.example to .env.
3. Fill in the required information:
   • DISCORD_BOT_TOKEN: The token you copied from the "Bot" tab.
   • CLIENT_ID: Your application's client ID, found in the "General Information" tab.
   • GUILD_ID: The ID of the Discord server where you want to deploy the bot. How to Get Your Discord Server ID
   • UNTHREAD_API_KEY: Your Unthread API key.
   • UNTHREAD_TRIAGE_CHANNEL_ID: Your Unthread triage channel ID.
   • UNTHREAD_EMAIL_INBOX_ID: Your Unthread email inbox ID.
   • UNTHREAD_WEBHOOK_SECRET: Your Unthread webhook secret.
   • REDIS_URL: Redis connection URL for caching (optional but recommended for production).
   • FORUM_CHANNEL_IDS: Comma-separated list of forum channel IDs for automatic ticket creation.
   • DEBUG_MODE: Set to true for verbose logging during development (default: false).
   • PORT: Port for the webhook server (default: 3000).

5. Install and Run the Project Locally

1. Clone the repository and navigate to the project directory:

   git clone https://github.com/wgtechlabs/unthread-discord-bot.git
   cd unthread-discord-bot

2. Install the dependencies using Yarn:

   yarn install

   Note: This project uses Yarn 4.9.2. If you don't have Yarn installed, you can install it with npm install -g yarn.

3. Deploy the slash commands to your Discord server:

   yarn deploycommand

4. Start the bot:

   yarn start

   Or for development with auto-restart:

   yarn dev

5. The bot should now be running in your Discord server and the webhook server will be listening on the specified port.

6. Port Forwarding for Webhook (Development)

For local development, you'll need to expose your webhook endpoint to receive events from Unthread:

Option 1: Using VS Code Port Forwarding (Recommended for development)

1. Open your project in VS Code.
2. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac).
3. Type Ports: Focus on Ports View and select it.
4. In the Ports view, click on the + icon to add a new port.
5. Enter 3000 (or your configured PORT) as the port number and press Enter.
6. Click on the globe icon next to the port to make it publicly accessible.
7. Copy the generated public URL for use in the Unthread webhook configuration.

Option 2: Using ngrok (Alternative)

1. Install ngrok: https://ngrok.com/download

2. Run ngrok to expose your local port:

   ngrok http 3000

3. Copy the generated HTTPS URL for use in the Unthread webhook configuration.

Note: For production deployments, use the actual domain/IP of your server instead of port forwarding tools.

7. Configure Webhook in Unthread Dashboard

1. Log in to your Unthread dashboard.
2. Navigate to the "Settings" or "Integrations" section.
3. Under "Webhook Configuration", enter the following URL: https://<YOUR_PUBLIC_URL>/webhook/unthread
   • Replace <YOUR_PUBLIC_URL> with the public URL from your port forwarding setup
   • For production: Use your actual server domain (e.g., https://your-bot-server.com/webhook/unthread)
4. Set the webhook secret to match your UNTHREAD_WEBHOOK_SECRET environment variable.
5. Save the settings.

Your bot should now be able to receive events from Unthread and sync ticket updates in real-time.

8. Configure Forum Channels (Optional)

To enable automatic ticket creation from forum posts:

1. Add forum channel IDs to your .env file:

   FORUM_CHANNEL_IDS=123456789012345678,234567890123456789

   • Replace the IDs with the actual IDs of your forum channels.
   • You can find the channel ID by right-clicking on the channel name in Discord and selecting "Copy ID" (make sure Developer Mode is enabled in your Discord settings).

2. Each comma-separated ID represents a forum channel that will be monitored for new posts.

3. Any new forum posts in these channels will automatically create a corresponding ticket in Unthread.

4. Replies in the forum post will be synchronized with the Unthread ticket.

5. The bot includes validation to ensure only actual forum channels are processed, preventing conflicts with text channels.

Important: Only add actual forum channel IDs to this list. The bot will validate channel types to prevent issues.

How to Get Your Discord Server ID

1. Open Discord and go to your server.
2. Click on the server name at the top of the channel list to open the dropdown menu.
3. Select "Server Settings".
4. In the "Server Settings" menu, go to the "Widget" tab.
5. Enable the "Server Widget" option if it is not already enabled.
6. The "Server ID" will be displayed under the "Widget" settings.

Alternatively, you can enable Developer Mode to get the server ID:

1. Go to your Discord user settings.
2. Navigate to the "Advanced" tab under "App Settings".
3. Enable "Developer Mode".
4. Right-click on your server name in the server list.
5. Select "Copy ID" to copy the server ID to your clipboard.

💬 Community Discussions

Join our community discussions to get help, share ideas, and connect with other users:

• 📣 Announcements: Official updates from the maintainer
• 📸 Showcase: Show and tell your implementation
• 💖 Wall of Love: Share your experience with the bot
• 🛟 Help & Support: Get assistance from the community
• 🧠 Ideas: Suggest new features and improvements

🛟 Help & Support

Getting Help

Need assistance with the bot? Here's how to get help:

• Community Support: Check the Help & Support category in our GitHub Discussions for answers to common questions.
• Ask a Question: Create a new discussion if you can't find answers to your specific issue.
• Documentation: Review the usage instructions in this README for common commands and features.
• Known Issues: Browse existing issues to see if your problem has already been reported.

Common Troubleshooting

Bot not responding to commands:

• Ensure the bot has the required permissions in your server
• Check if the bot is online in your Discord server
• Verify that slash commands are deployed with yarn deploycommand

Forum channel tickets not creating:

• Confirm the channel IDs in FORUM_CHANNEL_IDS are actual forum channels (not text channels)
• Enable Debug Mode (DEBUG_MODE=true) to see detailed logs
• Check bot permissions in the specific forum channels

Webhook issues:

• Verify the webhook URL is accessible from the internet
• Check that the UNTHREAD_WEBHOOK_SECRET matches your Unthread configuration
• Ensure the Express server is running on the correct port

Redis connection problems:

• Verify your REDIS_URL is correctly formatted
• Test Redis connectivity independently
• Redis is optional for basic functionality but recommended for production

Reporting Issues

Please report any issues, bugs, or improvement suggestions by creating a new issue. Before submitting, please check if a similar issue already exists to avoid duplicates.

Security Vulnerabilities

For security vulnerabilities, please do not report them publicly. Follow the guidelines in our security policy to responsibly disclose security issues.

Your contributions to improving this project are greatly appreciated! 🙏✨

🎯 Contributing

Contributions are welcome, create a pull request to this repo and I will review your code. Please consider to submit your pull request to the dev branch. Thank you!

Read the project's contributing guide for more info.

🙏 Sponsor

Like this project? Leave a star! ⭐⭐⭐⭐⭐

There are several ways you can support this project:

• Become a sponsor and get some perks! 💖
• Buy me a coffee if you just love what I do! ☕
• Deploy using the Railway Template which directly supports the ongoing development! 🛠️

⭐ GitHub Star Nomination

Found this project helpful? Consider nominating me (@warengonzaga) for the GitHub Star program! This recognition supports ongoing development of this project and my other open-source projects. GitHub Stars are recognized for their significant contributions to the developer community - your nomination makes a difference and encourages continued innovation!

📋 Code of Conduct

I'm committed to providing a welcoming and inclusive environment for all contributors and users. Please review the project's Code of Conduct to understand the community standards and expectations for participation.

📃 License

This project is licensed under the GNU Affero General Public License v3.0. This license requires that all modifications to the code must be shared under the same license, especially when the software is used over a network. See the LICENSE file for the full license text.

📝 Author

This project is created by Waren Gonzaga under WG Technology Labs, with the help of awesome contributors.

---

💻 with ❤️ by Waren Gonzaga under WG Technology Labs, and Him 🙏