Recoup Telegram Bot 🎵

Meet Your New AI Record Label on Telegram! This bot connects musicians with Recoup's AI-powered music industry assistant directly through Telegram.

🎯 What Does This Bot Do?

This Telegram bot gives you your own personal instance of the Recoup AI, powered by the Recoup Chat API. The AI has access to real music industry data and tools to help you:

🎵 Music Platform Analytics

• Spotify Integration - Search artists, get album data, track top songs
• Streaming Insights - Analyze play counts and listener demographics
• Catalog Management - Access and organize your song catalogs

📱 Social Media Intelligence

• Instagram Analytics - Profile insights, comment analysis, engagement metrics
• X/Twitter Trends - Track trending topics, search conversations
• Multi-Platform Posts - Retrieve and analyze posts across social networks

👥 Fan Engagement & Audience

• Fan Segmentation - Identify and categorize your fanbase
• Audience Insights - Understand listener demographics and behaviors
• Comment Management - Track and respond to fan interactions

🎨 AI-Powered Content

• Image Generation - Create promotional artwork and visuals
• Content Strategy - Get personalized marketing recommendations
• Industry Insights - Real-time music industry trends and data

🚀 Career Growth

• Artist Analytics - Comprehensive artist profile data and socials
• Release Planning - Strategic guidance for launches
• Marketing Automation - AI-powered promotional strategies

🤖 Try the Official Bot First

Before setting up your own bot, try the official Recoup AI bot: 👉 @recoup_ai_bot

🚀 Quick Start

Prerequisites

• Node.js 18+ installed on your machine
• A Telegram Bot Token (get one from @BotFather)
• Recoup API Credentials (https://recoupable.com)

1. Create Your Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow the instructions
3. Choose a name and username for your bot
4. Save the bot token you receive - you'll need it!

2. Clone & Install

# Clone this repository
git clone https://github.com/Recoupable-com/Recoup-Telegram-Bot.git
cd Recoup-Telegram-Bot

# Install dependencies
npm install

3. Configure Environment Variables

Create a .env file in the project root:

# Your Telegram Bot Token from @BotFather
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# Recoup API Credentials (contact Recoup for these)
RECOUP_ACCOUNT_ID=your_account_id
RECOUP_ARTIST_ID=your_artist_id
RECOUP_ROOM_ID=your_room_id

Note: visit Recoup to get your API credentials (RECOUP_ACCOUNT_ID, RECOUP_ARTIST_ID, and RECOUP_ROOM_ID).

4. Run Your Bot

# Start the bot
npm start

That's it! Your bot is now running. Find it on Telegram and start chatting! 🎉

📁 Project Structure

Recoup-Telegram-Bot/
├── bot.js                           # Main entry point
├── lib/
│   ├── const.js                     # Application constants
│   ├── checkEnvVariables.js         # Environment validation
│   ├── handleMessage.js             # Message orchestration
│   ├── recoup/
│   │   └── generateChatResponse.js  # Recoup API client
│   └── telegram/
│       └── splitMessage.js          # Telegram utilities
├── .env                             # Your environment variables (create this)
├── package.json                     # Dependencies
└── README.md                        # This file

🔧 Configuration

Environment Variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	✅ Yes	Your bot token from @BotFather
RECOUP_ACCOUNT_ID	✅ Yes	Your Recoup account ID
RECOUP_ARTIST_ID	✅ Yes	Your artist ID in Recoup
RECOUP_ROOM_ID	❌ No	Chat room ID (optional, for conversation history)

🚀 Deployment

Deploy to Production

For production deployment, this bot uses PM2 for process management:

# Install PM2 globally
npm install -g pm2

# Start the bot with PM2
pm2 start ecosystem.config.cjs

# View logs
pm2 logs recoup-telegram-bot

# Restart the bot
pm2 restart recoup-telegram-bot

# Stop the bot
pm2 stop recoup-telegram-bot

The bot automatically restarts every 12 hours to ensure optimal performance.

Deploy to DigitalOcean

This repository includes a GitHub Actions workflow for automated deployment to DigitalOcean. See .github/workflows/deploy.yaml for details.

📚 API Documentation

This bot uses the Recoup Chat API which gives the AI access to multiple music industry data sources and tools.

Available API Endpoints (Accessible via Chat)

The AI can automatically use these tools when you ask questions:

Music Platforms:

• 🎵 Spotify - Search, albums, top tracks, artist data
• 🎼 Music Catalogs - Song management and organization

Social Media:

• 📸 Instagram - Profiles, posts, comments, engagement
• 🐦 X/Twitter - Search, trends, sentiment analysis
• 📱 Social Posts - Cross-platform content analysis

Audience & Fans:

• 👥 Fan Segments - Audience categorization and insights
• 💬 Comments - Track and analyze fan interactions across platforms

Content Creation:

• 🎨 Image Generation - AI-powered promotional artwork
• 📊 Artist Analytics - Comprehensive performance metrics

For complete API documentation, visit: docs.recoupable.com

Bot Features

• ✅ Handles long messages (auto-splits messages over Telegram's 4096 character limit)
• ✅ Stateless design (conversation history managed by Recoup API)
• ✅ ES Modules for modern JavaScript
• ✅ Modular architecture following SOLID principles
• ✅ Production-ready with PM2 process management

🎵 For Musicians

This bot is designed specifically for musicians and music industry professionals. Unlike generic AI assistants, Recoup AI has direct access to:

Real Music Industry Data

• Live Spotify, Instagram, and X/Twitter data
• Your actual streaming numbers and social metrics
• Real-time industry trends and insights

Actionable Tools

• Fan segmentation and audience analysis
• AI image generation for promo materials
• Multi-platform social media intelligence
• Catalog and release management

Industry Expertise

The AI is trained on music industry knowledge and has access to the Recoup API suite, giving you insights powered by real data from streaming platforms, social networks, and fan engagement metrics.

Example questions you can ask:

• "What are the trending topics on X/Twitter related to my genre?"
• "Analyze my Spotify listener demographics"
• "Generate promotional images for my next release"
• "Show me engagement metrics from my latest Instagram posts"
• "Help me segment my fanbase for targeted marketing"

🛠️ Development

Run in Development Mode

npm start

Code Structure

The codebase follows the Single Responsibility Principle with clear separation of concerns:

• bot.js - Entry point and configuration
• lib/checkEnvVariables.js - Environment validation
• lib/handleMessage.js - Message handling orchestration
• lib/recoup/generateChatResponse.js - Recoup API integration
• lib/telegram/splitMessage.js - Telegram message utilities
• lib/const.js - Centralized constants

📝 License

MIT License - see LICENSE file for details.

Copyright (c) 2025 sweetman.eth

🔗 Links

• 🌐 Recoup Website
• 🤖 Official Recoup AI Bot
• 📖 Recoup API Documentation
• 💬 Create Your Own Telegram Bot

🤝 Support

Need help?

• Try the official Recoup AI bot first
• Check the API documentation
• Contact Recoup for API access

---

Made with ❤️ by sweetman.eth for the music community