Skip to main content

​
Setup Telegram app integration on your local machine

Please follow the steps if you are trying to work with the Telegram integration on your local machine.

​
Prerequisites

  • Telegram Bot Token from BotFather
  • Ngrok or similar tunneling service
  • Running Chatwoot development environment

​
Setup Steps

​
1. Start Ngrok Server

Start a Ngrok server listening at port 3000 or the port you will be running the Chatwoot installation: 
# Install ngrok if you haven't already
# Download from https://ngrok.com/download

# Start ngrok tunnel
ngrok http 3000

​
2. Update Environment Variables

Update the .env variable FRONTEND_URL in Chatwoot with the https version of the Ngrok URL: 
# In your .env file
FRONTEND_URL=https://your-ngrok-subdomain.ngrok.io

​
3. Start Chatwoot Server

Start the Chatwoot server and create a new Telegram channel with the token obtained from Telegram BotFather. 
# Start the development server
make run
# or
foreman start -f Procfile.dev

​
4. Create Telegram Channel

  1. Access Chatwoot: Go to your Chatwoot instance (http://localhost:3000)
  2. Navigate to Settings → Inboxes → Add Inbox
  3. Select Telegram as the channel type
  4. Enter Bot Token: Paste the token you received from BotFather
  5. Configure Channel: Set up the channel name and other settings

​
Verify Webhook Registration

While creating the channel, Chatwoot should have registered a webhook callback URL in Telegram for your Bot. You can verify whether this URL registration was done successfully by calling the Telegram API: 
GET https://api.telegram.org/bot{your_bot_token}/getWebhookInfo

​
Testing the Integration

If the webhook is registered correctly with Telegram, your Ngrok server should receive events for new Telegram messages, and new conversations will be created in Chatwoot.

​
Test Steps

  1. Send a message to your Telegram bot
  2. Check Ngrok logs to see if the webhook request is received
  3. Check Chatwoot to see if a new conversation is created
  4. Reply from Chatwoot to test bidirectional communication

​
Troubleshooting

Problem: Telegram webhook registration failsSolution:
  • Ensure your Ngrok URL is accessible publicly
  • Check that FRONTEND_URL is set correctly in your .env file
  • Verify the bot token is correct
  • Restart Chatwoot after updating environment variables
Problem: Telegram messages don’t create conversations in ChatwootSolution:
  • Check Ngrok logs for incoming webhook requests
  • Verify the webhook URL in Telegram using the API call above
  • Check Chatwoot logs for any error messages
  • Ensure the channel is properly configured and enabled
Problem: SSL certificate issues with webhookSolution:
  • Use the https version of your Ngrok URL
  • Ensure Ngrok is running properly
  • Try restarting Ngrok and updating the webhook

​
Next Steps

After successful setup:
  1. Test message flow between Telegram and Chatwoot
  2. Configure agent assignments for Telegram conversations
  3. Set up automated responses if needed
  4. Review webhook logs for debugging

​
Getting Help

If you encounter issues:
Your Telegram integration is now ready for development and testing! 📱
⌘I