Twenty Telegram App

Telegram integration for Twenty CRM - bidirectional sync between Telegram bot and Twenty CRM.

Installation

npm install -g twenty-telegram-app

Usage

Setup Environment Variables

Create a .env file:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_WEBHOOK_URL=https://your-app-url.com/telegram/webhook

# Twenty CRM Configuration
TWENTY_URL=http://localhost:3000
TWENTY_API_KEY=your_twenty_api_key_here

# Server Configuration
PORT=3001
NODE_ENV=development

# Telegram Chat Configuration
TELEGRAM_CHAT_ID=your_telegram_chat_id_here
TELEGRAM_CHANNEL_USERNAME=@your_channel_username

# Webhook Secret
TELEGRAM_WEBHOOK_SECRET=your_webhook_secret_here

# Twenty SDK Configuration
TWENTY_SDK_VERSION=0.7.0

Create Telegram Bot

1. Create Bot with @BotFather

   • Start chat with @BotFather
   • Send /newbot
   • Follow instructions to create your bot
   • Copy the bot token

2. Get Chat ID

   • Start chat with your bot
   • Send any message
   • Use https://api.telegram.org/bot<TOKEN>/getUpdates to get chat ID

Start the App

# Development
npm run dev

# Production
npm run build
npm start

Features

• Bidirectional Sync - Telegram ↔ Twenty CRM
• Message Storage - Telegram messages saved as notes in Twenty
• Deal Notifications - New deals sent to Telegram chat/channel
• Person Creation - Telegram users automatically created in Twenty
• Webhook Support - Real-time updates from Twenty CRM
• Commands - /start, /help, /status
• Health Check - /health endpoint

API Endpoints

Telegram Webhook

POST /telegram/webhook

Receives updates from Telegram Bot API.

Twenty CRM Webhook

POST /twenty/webhook

Receives webhook events from Twenty CRM.

Health Check

GET /health

Returns application status.

Logic Functions

HTTP Route: POST /telegram/webhook

• Accepts Telegram updates
• Creates Person + Note in Twenty
• Handles commands and messages

DB Trigger: onDealCreated

• Sends notification to Telegram chat/channel
• Includes deal details and formatting

Acceptance Criteria

✅ Telegram Test Bot Integration

• Test Token: Works with @BotFather test token
• Message Flow: Telegram message → Person + Note in Twenty
• Local Testing: Full functionality with local Twenty CRM

✅ Deal Notification Flow

• Deal Creation: New deal in Twenty → Telegram notification
• Test Chat: Works with test Telegram chat
• Channel Support: Optional channel notifications

Webhook Configuration

Telegram Webhook

curl -X POST https://api.telegram.org/bot<TOKEN>/setWebhook \
  -d "url=https://your-app.com/telegram/webhook"

Twenty CRM Webhook

# Configure in Twenty CRM settings
# Webhook URL: https://your-app.com/twenty/webhook
# Events: deal.created, deal.updated, person.created, person.updated

Development

Local Development

# Clone repository
git clone https://github.com/deliveredbyai/twenty-telegram-app.git
cd twenty-telegram-app

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your credentials

# Start development server
npm run dev

Testing

# Run tests
npm test

# Test with local Telegram bot
# 1. Create test bot with @BotFather
# 2. Set TELEGRAM_BOT_TOKEN in .env
# 3. Start app: npm run dev
# 4. Send message to bot
# 5. Check Twenty CRM for person + note

Architecture

Telegram Bot API ←→ twenty-telegram-app ←→ Twenty CRM API
     ↓                    ↓                    ↓
  Messages           Web Server           Database
  Commands           Express.js           People/Notes
  Updates           Telegraf              Deals/Companies

Error Handling

• Telegram API Errors: Automatic retry with exponential backoff
• Twenty CRM Errors: Graceful degradation with logging
• Webhook Failures: Error logging and retry logic
• Authentication: Token validation and connection checks

Monitoring

Health Check

curl http://localhost:3001/health

Logs

• Application logs to console
• Error details for debugging
• Webhook event logging
• Telegram message tracking

Security

• Webhook Verification: HMAC signature verification
• Token Security: Environment variable storage
• Rate Limiting: Built-in Telegram rate limiting
• Input Validation: Message sanitization

Troubleshooting

Common Issues

"Bot token invalid"

• Check TELEGRAM_BOT_TOKEN in .env
• Verify bot is created with @BotFather
• Ensure token is copied correctly

"Twenty CRM connection failed"

• Check TWENTY_URL and TWENTY_API_KEY
• Verify Twenty CRM is running
• Test API connection manually

"Webhook not working"

• Check webhook URL is accessible
• Verify firewall allows incoming requests
• Check webhook secret configuration

"Messages not saving to Twenty"

• Check person creation logic
• Verify Twenty CRM API permissions
• Check error logs for details

Support

• Report Issues
• Discussions

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create feature branch
3. Make your changes
4. Run tests
5. Submit pull request

Acknowledgments

• Telegraf - Telegram Bot Framework
• Twenty CRM - Open-source CRM
• Express.js - Web Framework
• Twenty SDK - CRM SDK