Skip to main content
Integrate Dokploy with Telegram to receive instant notifications about deployments, build failures, backups, and system events directly in your Telegram chats or groups.

​
Prerequisites

  • A Telegram account
  • Admin access to your Dokploy organization
  • Basic familiarity with Telegram bots

​
Creating a Telegram Bot

1

Start Chat with BotFather

Open Telegram and search for @BotFather (the official bot for creating bots)
2

Create New Bot

Send the command:
/newbot
3

Choose Bot Name

BotFather will ask for a name for your bot:
Dokploy Notifications
This is the display name users will see.
4

Choose Bot Username

Choose a unique username ending in “bot”:
dokploy_notifications_bot
Usernames must be unique across all Telegram.
5

Save Bot Token

BotFather will provide a bot token. Save this securely:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
Treat the bot token like a password. Anyone with the token can control your bot.

​
Getting Your Chat ID

You need to know where the bot should send messages:

​
For Personal Chats

1

Start Chat with Your Bot

Search for your bot by username and click Start to begin a conversation
2

Send a Message

Send any message to your bot (e.g., “/start”)
3

Get Chat ID

Open this URL in your browser (replace BOT_TOKEN with your actual token):
https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
4

Find Chat ID

Look for the “chat” object in the response:
{
  "ok": true,
  "result": [{
    "message": {
      "chat": {
        "id": 123456789,  // This is your chat ID
        "type": "private"
      }
    }
  }]
}

​
For Groups

1

Add Bot to Group

Add your bot to the Telegram group where you want notifications
2

Send a Message

Send any message in the group mentioning the bot
3

Get Updates

Use the same getUpdates URL as above
4

Find Group Chat ID

Group chat IDs are negative numbers:
{
  "chat": {
    "id": -1001234567890,  // Group chat ID (negative)
    "type": "supergroup"
  }
}
For groups, you may also need to give the bot admin privileges if you want it to send messages in groups with restricted posting permissions.

​
Getting Thread ID (Optional)

For Telegram groups with topics/threads enabled:
1

Send Message in Thread

Send a message in the specific thread/topic where you want notifications
2

Check Updates

Call the getUpdates endpoint
3

Extract Thread ID

Look for message_thread_id in the response:
{
  "message": {
    "message_thread_id": 123,  // Thread/topic ID
    "chat": {
      "id": -1001234567890
    }
  }
}

​
Configuring Telegram in Dokploy

1

Navigate to Notifications

In Dokploy, go to Settings > Notifications
2

Add Telegram Notification

Click Add Notification and select Telegram
3

Enter Configuration

Provide the following details:
  • Name: A descriptive name for this notification (e.g., “Production Alerts”)
  • Bot Token: Paste the token from BotFather
  • Chat ID: Enter the chat ID where notifications should be sent
  • Message Thread ID: (Optional) Specify a thread ID for topic-based groups
4

Select Events

Choose which events should trigger Telegram notifications:
  • Application Deploy
  • Application Build Error
  • Database Backup
  • Volume Backup
  • Dokploy Restart
  • Docker Cleanup
  • Server Threshold Exceeded
5

Test Connection

Click Test Connection to send a test message:
Hi, From Dokploy 👋
Verify the message appears in your Telegram chat.
6

Save Configuration

Click Save to activate the notification channel

​
Configuration Schema

The Telegram notification configuration uses the following structure: 
{
  name: string,                 // Display name for the notification
  botToken: string,             // Bot token from BotFather (required)
  chatId: string,               // Chat ID where messages are sent (required)
  messageThreadId: string,      // Optional thread ID for topic groups
  appDeploy: boolean,           // Enable for deployment notifications
  appBuildError: boolean,       // Enable for build failure alerts
  databaseBackup: boolean,      // Enable for database backup notifications
  volumeBackup: boolean,        // Enable for volume backup notifications
  dokployRestart: boolean,      // Enable for Dokploy restart alerts
  dockerCleanup: boolean,       // Enable for cleanup notifications
  serverThreshold: boolean      // Enable for resource threshold warnings
}

​
Message Format

Telegram notifications from Dokploy are sent as plain text messages. The format includes:
  • Event Type: The type of event that triggered the notification
  • Details: Event-specific information
  • Timestamp: When the event occurred
  • Status: Success or failure indicator

​
Example Notification

🚀 Deployment Complete

Application: my-app
Environment: production
Status: Success
Time: 2024-02-28 10:30:00 UTC

​
Using Message Threads

For Telegram groups with topics (also called threads or forums):
  1. Enable Topics in your group settings
  2. Create topics for different notification types:
    • “Deployments”
    • “Errors”
    • “Monitoring”
  3. Get the thread ID for each topic
  4. Create separate Dokploy notifications for each thread
Message threads help organize notifications in busy groups. Each notification destination can target a specific thread within a group.

​
Troubleshooting

​
Test Connection Fails

Invalid bot token
  • Verify the bot token is correct and complete
  • Ensure you copied the entire token from BotFather
  • Check that the bot hasn’t been deleted
Invalid chat ID
  • Verify the chat ID is correct (positive for personal chats, negative for groups)
  • Ensure you sent at least one message to the bot before getting the chat ID
  • For groups, verify the bot is still a member
Bot can’t send messages to the chat
  • Start a conversation with the bot if it’s a personal chat
  • For groups, add the bot as a member
  • Check that the bot hasn’t been banned from the group
Thread ID not found
  • Verify topics are enabled in your group
  • Ensure the thread/topic still exists
  • Check that the thread ID is correct (should be a positive number)

​
Not Receiving Notifications

Check bot permissions
  • Verify the bot has permission to send messages
  • For restricted groups, ensure the bot has posting privileges
Verify event configuration
  • Confirm the notification is enabled for the events you want to receive
  • Check that events are being triggered in Dokploy
Bot blocked or deleted
  • Ensure you haven’t blocked the bot in Telegram
  • Verify the bot still exists in BotFather
If you revoke or regenerate your bot token in BotFather, the old token will stop working immediately. You must update the token in Dokploy.

​
Best Practices

​
Separate Bots by Environment

Create different bots for different purposes:
  • dokploy_prod_bot: Production alerts only
  • dokploy_staging_bot: Staging and development
  • dokploy_backups_bot: Backup notifications

​
Use Groups for Team Notifications

For team environments:
  1. Create a dedicated Telegram group for Dokploy notifications
  2. Add team members to the group
  3. Configure the bot to send notifications to the group chat ID

​
Organize with Topics

For large teams, use Telegram topics to separate:
  • Critical alerts
  • Deployment notifications
  • Backup reports
  • System monitoring

​
Privacy Considerations

  • Personal Chats: Only you receive notifications
  • Groups: All group members see notifications
  • Channels: Consider Telegram channels for read-only notification feeds

​
API Integration

Manage Telegram notifications programmatically using the Dokploy API: 
const notification = await api.notification.createTelegram({
  name: "Production Alerts",
  botToken: "1234567890:ABCdef...",
  chatId: "123456789",
  messageThreadId: "",
  appDeploy: true,
  appBuildError: true,
  serverThreshold: true,
  databaseBackup: false,
  volumeBackup: false,
  dokployRestart: true,
  dockerCleanup: false
});

​
Security Considerations

​
Bot Token Security

  • Never share your bot token publicly or in code repositories
  • Regenerate tokens if they are exposed or compromised
  • Use environment variables when storing tokens in code

​
Revoking Access

To revoke a bot’s access:
1

Open BotFather

Start a chat with @BotFather
2

Revoke Token

Send /revoke and select your bot, or send /deletebot to completely remove it
3

Update Dokploy

Remove or update the notification configuration in Dokploy

​
Telegram Limits

  • Message Length: 4096 characters maximum
  • Rate Limit: 30 messages per second per bot
  • Group Limit: Bots can be in up to 20 groups by default
  • Broadcast Limit: 30 different chats per second
Dokploy respects Telegram’s rate limits and will automatically queue notifications if limits are reached.

​
Next Steps

Slack Notifications

Set up Slack webhook integration

Discord Notifications

Configure Discord webhooks

Email Notifications

Set up SMTP email notifications

Notification Overview

Learn about all notification options