The Unthread Telegram Bot seamlessly connects your Telegram 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 Telegram.
With simple commands and intuitive interactions, support tickets automatically sync between both platforms, streamlining your workflow and improving response times. Whether you're managing a community group, running a business chat, or supporting an open-source project, this bot provides the tools you need for efficient, organized customer support.
Open source development is resource-intensive. These sponsored ads help keep Log Engine free and actively maintained while connecting you with tools and services that support open-source development.
The Unthread Telegram Bot creates a seamless bridge between your Telegram group chats and Unthread's ticket management system. Here's how it works:
- Users in group chats can create support tickets using the
/supportcommand - The bot guides them through a simple conversation to collect issue summary and email (optional)
- Tickets are automatically created in Unthread with proper customer and user association
- Agent → User: When agents respond via the Unthread dashboard, messages are delivered to Telegram in real-time through webhook processing
- User → Agent: Users can simply reply to agent messages naturally - no special commands needed
- Conversation Flow: Maintains complete conversation history across both platforms using message reply chains
- Webhook Server: Powered by
wgtechlabs/unthread-webhook-serverwhich processes Unthread webhooks and queues events in Redis for real-time delivery
- Automatically extracts customer company names from group chat titles (e.g., "Company X Relay" → "Company X")
- Creates customers in Unthread with
[Telegram]prefix for platform identification - Maps Telegram users to Unthread user profiles with fallback email generation
- Memory Layer (24h): Fast access for active conversations
- Redis Layer (3 days): Intermediate caching for recent activity
- PostgreSQL (permanent): Long-term storage with full conversation history
This bot works in conjunction with the wgtechlabs/unthread-webhook-server to enable real-time bidirectional communication. Here's how the complete system works:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Unthread │ │ Webhook │ │ Redis │ │ Telegram │
│ Dashboard │───▶│ Server │───▶│ Queue │───▶│ Bot │
│ │ │ (wgtechlabs/ │ │ unthread-events │ │ │
│ Agent Reply │ │ unthread- │ │ │ │ User receives │
│ │ │ webhook-server)│ │ │ │ agent message │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
- Agent responds in Unthread dashboard to a ticket
- Unthread webhook fires and sends event to the webhook server
- Webhook server processes the event and queues it in Redis with proper formatting
- Telegram bot polls the Redis queue and delivers the message to the appropriate group chat
- User replies in Telegram, and the bot sends it back to Unthread API
- Webhook Server: Must be deployed separately to receive Unthread webhooks
- Shared Redis: Both webhook server and bot must use the same Redis instance
- Queue Names: Both webhook server and bot use the standard queue name
unthread-events
For webhook server setup instructions, see the wgtechlabs/unthread-webhook-server repository.
- Create support tickets directly from Telegram group chats with
/supportcommand - Interactive ticket creation with guided prompts for summary and email
- Automatic ticket numbering and confirmation messages
- Smart customer extraction from group chat names
- Agent responses from Unthread dashboard delivered instantly to Telegram
- Users reply naturally to agent messages without special commands
- Complete conversation history maintained across both platforms
- Message reply chains preserve conversation context
- Automatic customer creation with
[Telegram]platform identification - Smart company name extraction from group chat titles (e.g., "Acme Corp x Support" → "Acme Corp")
- User profile mapping with automatic fallback email generation
- Duplicate prevention for customers and users
- Multi-layer storage: Memory (24h) → Redis (3d) → PostgreSQL (permanent)
- Webhook-based real-time event processing from Unthread via
wgtechlabs/unthread-webhook-server - Redis queue system for reliable webhook event processing and delivery
- Graceful degradation when services are unavailable
- Comprehensive error handling and recovery mechanisms
- Built with modern ES6+ modules and async/await patterns
- Structured logging with
@wgtechlabs/log-engineintegration - Auto-setup database schema on first run
- Clean separation of concerns with SDK architecture
- Environment variable based configuration
- Support for both basic mode (ticket creation only) and full mode (with webhooks)
- Configurable webhook polling intervals and queue names
- Optional Redis caching with PostgreSQL fallback
The bot is designed for easy deployment with minimal configuration. Here's the fastest way to get started:
Create a .env file with the following required variables:
# Required - Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# Required - Database Configuration
POSTGRES_URL=postgresql://user:password@host:port/database
# Required - Unthread API Configuration
UNTHREAD_API_KEY=your_unthread_api_key
UNTHREAD_CHANNEL_ID=your_unthread_channel_id
# Optional - Webhook Configuration (for real-time agent responses)
# Requires wgtechlabs/unthread-webhook-server to be deployed and configured
WEBHOOK_REDIS_URL=redis://user:password@host:port
WEBHOOK_POLL_INTERVAL=1000
# Optional - Platform Redis (for advanced caching)
PLATFORM_REDIS_URL=redis://user:password@host:port
# Optional - Company Configuration
COMPANY_NAME=YourCompany# Install dependencies (Yarn required)
yarn install
# Start the bot
yarn startThat's it! The database schema will be created automatically on first run.
Note
This is not yet available.
# Coming soon - Docker deployment support
docker-compose up -d- PostgreSQL 12+ (required)
- Redis 6+ (optional, for enhanced performance)
- Automatic schema setup on first connection
- No manual migration scripts needed
The bot provides several commands for users and administrators:
/start- Welcome message and bot introduction/help- Display available commands and usage instructions/support- Create a new support ticket (group chats only)/version- Show current bot version
- Initiate Ticket: Use
/supportin a group chat - Provide Summary: Describe your issue when prompted
- Email (Optional): Provide email or skip for auto-generated one
- Confirmation: Receive ticket number and confirmation message
User: /support
Bot: Let's create a support ticket. Please provide your issue summary:
User: Unable to login to my account
Bot: Please provide your email address or skip this step: [Skip Button]
User: [email protected]
Bot: 🎫 Support Ticket Created Successfully!
Ticket #TKT-001
Your issue has been submitted and our team will be in touch soon.
- New tickets appear in your Unthread dashboard
- Customer name shows as
[Telegram] GroupChatName - User information includes Telegram username and ID
- Reply to tickets in Unthread dashboard as normal
- Messages are automatically delivered to the original Telegram group
- Users receive agent responses in real-time
- Users can reply directly to agent messages in Telegram
- No special commands needed - natural conversation flow
- All replies are automatically sent back to Unthread
- Add your bot to the desired Telegram group chat
- Ensure the bot has permission to read and send messages
- Group chat title should ideally include customer company name
- Use descriptive group chat names (e.g., "Acme Corp Support", "ClientName x YourCompany")
- The bot automatically extracts customer names from chat titles
- Only group members can create support tickets (private chats are blocked)
- Customers are automatically created from group chat names
- Duplicate prevention ensures one customer per chat
- Customer names are prefixed with
[Telegram]for easy identification
- Each ticket maintains complete conversation history
- Reply chains preserve context across platforms
- Message metadata includes user information and timestamps
- Node.js 20+ (ES6 modules support required)
- Yarn 1.22.22+ (package manager - npm not supported)
- PostgreSQL 12+ (primary database)
- Redis 6+ (optional, for enhanced performance)
git clone https://github.com/wgtechlabs/unthread-telegram-bot.git
cd unthread-telegram-bot# Use Yarn only (npm not supported)
yarn install- Message @BotFather on Telegram
- Create new bot with
/newbotcommand - Save the bot token for environment configuration
- Log into your Unthread dashboard
- Navigate to Settings → API Keys
- Generate a new API key
- Find your channel ID in the dashboard URL
# PostgreSQL (required)
createdb unthread_telegram_bot
# Redis (optional - for enhanced performance)
# Install Redis locally or use cloud service# Copy example environment file
cp .env.example .env
# Edit .env with your configuration
nano .envRequired environment variables:
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
POSTGRES_URL=postgresql://user:password@localhost:5432/unthread_telegram_bot
UNTHREAD_API_KEY=your_unthread_api_key
UNTHREAD_CHANNEL_ID=your_unthread_channel_idOptional environment variables:
WEBHOOK_REDIS_URL=redis://localhost:6379
PLATFORM_REDIS_URL=redis://localhost:6379
COMPANY_NAME=YourCompanyName
WEBHOOK_POLL_INTERVAL=1000# Development mode (with auto-restart)
yarn dev
# Production mode
yarn start-
Look for successful startup logs:
[INFO] Database initialized successfully [INFO] BotsStore initialized successfully [INFO] Bot initialized successfully [INFO] Bot is running and listening for messages... -
Test basic functionality:
- Add bot to a test group
- Send
/startcommand - Try creating a support ticket with
/support
Common Issues:
- Import errors: Ensure you're using Yarn, not npm
- Database connection: Verify PostgreSQL is running and connection string is correct
- Bot not responding: Check bot token and ensure bot is added to group with proper permissions
- Webhook issues: Verify Redis connection if using webhook features
Debug Mode:
# Enable detailed logging
NODE_ENV=development yarn startJoin 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
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.
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.
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! 🙏✨
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.
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! 🛠️
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!
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.
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.
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 🙏
