Telegram Usage

Setup Your Telegram Bot

Below we explain how to create your Telegram Bot, and how to get your Telegram user id.

1. Create Your Telegram Bot

Start a chat with the Telegram BotFather

Send the message /newbot.

BotFather response:

Alright, a new bot. How are we going to call it? Please choose a name for your bot.

Choose the public name of your bot (e.g. Freqtrade bot)

BotFather response:

Good. Now let's choose a username for your bot. It must end in bot. Like this, for example: TetrisBot or tetris_bot.

Choose the name id of your bot and send it to the BotFather (e.g. "My_own_freqtrade_bot")

BotFather response:

Done! Congratulations on your new bot. You will find it at t.me/yourbots_name_bot. You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you've finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.

Use this token to access the HTTP API: 22222222:APITOKEN

For a description of the Bot API, see this page: https://core.telegram.org/bots/api

Copy the API Token (22222222:APITOKEN in the above example) and keep use it for the config parameter token.

Don't forget to start the conversation with your bot, by clicking /START button

2. Get Your Telegram User ID

Get Your User ID

Talk to the userinfobot

Get your "Id", you will use it for the config parameter chat_id.

Use Group ID

To get the group ID, you can add the bot to the group, start freqtrade, and issue a /tg_info command.

This will return the group id to you, without having to use some random bot.

While "chat_id" is still required, it doesn't need to be set to this particular group id for this command.

The response will also contain the "topic_id" if necessary - both in a format ready to copy/paste into your configuration.

{
    "enabled": true,
    "token": "********",
    "chat_id": "-1001332619709",
    "topic_id": "122"
}

For the Freqtrade configuration, you can then use the full value (including -) as string:

"chat_id": "-1001332619709"

Using Telegram Groups

When using telegram groups, you're giving every member of the telegram group access to your freqtrade bot and to all commands possible via telegram. Please make sure that you can trust everyone in the telegram group to avoid unpleasant surprises.

Group Topic ID

To use a specific topic in a group, you can use the topic_id parameter in the configuration. This will allow you to use the bot in a specific topic in a group.

Without this, the bot will always respond to the general channel in the group if topics are enabled for a group chat.

"chat_id": "-1001332619709",
"topic_id": "3"

Similar to the group-id - you can use /tg_info from the topic/thread to get the correct topic-id.

Authorized Users

For groups, it can be useful to limit who can send commands to the bot.

If "authorized_users": [] is present and empty, no user will be allowed to control the bot.

In the below example, only the user with the id "1234567" is allowed to control the bot - all other users will only be able to receive messages.

"chat_id": "-1001332619709",
"topic_id": "3",
"authorized_users": ["1234567"]

Configuration

Basic Configuration

{
    "telegram": {
        "enabled": true,
        "token": "your_telegram_token",
        "chat_id": "your_telegram_chat_id"
    }
}

Advanced Configuration

{
    "telegram": {
        "enabled": true,
        "token": "your_telegram_token",
        "chat_id": "your_telegram_chat_id",
        "allow_custom_messages": true,
        "notification_settings": {
            "status": "silent",
            "warning": "on",
            "startup": "off",
            "entry": "silent",
            "entry_fill": "on",
            "entry_cancel": "silent",
            "exit": {
                "roi": "silent",
                "emergency_exit": "on",
                "force_exit": "on",
                "exit_signal": "silent",
                "trailing_stop_loss": "on",
                "stop_loss": "on",
                "stoploss_on_exchange": "on",
                "custom_exit": "silent",
                "partial_exit": "on",
                "*": "off"
            },
            "exit_cancel": "on",
            "exit_fill": "off",
            "protection_trigger": "off",
            "protection_trigger_global": "on",
            "strategy_msg": "off",
            "show_candle": "off"
        },
        "reload": true,
        "balance_dust_level": 0.01
    }
}

Control Telegram Noise

Freqtrade provides means to control the verbosity of your telegram bot. Each setting has the following possible values:

• on - Messages will be sent, and user will be notified.
• silent - Message will be sent, Notification will be without sound/vibration.
• off - Skip sending a message-type all together.

Notification Settings

• entry notifications are sent when the order is placed, while entry_fill notifications are sent when the order is filled on the exchange.
• exit notifications are sent when the order is placed, while exit_fill notifications are sent when the order is filled on the exchange.
• Exit messages (exit and exit_fill) can be further controlled at individual exit reasons level, with the specific exit reason as the key.
• *_fill notifications are off by default and must be explicitly enabled.
• protection_trigger notifications are sent when a protection triggers and protection_trigger_global notifications trigger when global protections are triggered.
• strategy_msg - Receive notifications from the strategy, sent via self.dp.send_msg() from the strategy.
• show_candle - show candle values as part of entry/exit messages. Only possible values are "ohlc" or "off".
• balance_dust_level will define what the /balance command takes as "dust" - Currencies with a balance below this will be shown.
• allow_custom_messages completely disable strategy messages.
• reload allows you to disable reload-buttons on selected messages.

Custom Keyboard (Command Shortcut Buttons)

Telegram allows us to create a custom keyboard with buttons for commands. The default custom keyboard looks like this:

[
    ["/daily", "/profit", "/balance"],      # row 1, 3 commands
    ["/status", "/status table", "/performance"], # row 2, 3 commands
    ["/count", "/start", "/stop", "/help"]  # row 3, 4 commands
]

Custom Keyboard Configuration

You can create your own keyboard in config.json:

{
    "telegram": {
        "enabled": true,
        "token": "your_telegram_token",
        "chat_id": "your_telegram_chat_id",
        "keyboard": [
            ["/daily", "/stats", "/balance", "/profit"],
            ["/status table", "/performance"],
            ["/reload_config", "/count", "/logs"]
        ]
    }
}

Supported Commands

Only the following commands are allowed. Command arguments are not supported!

/start, /pause, /stop, /status, /status table, /trades, /profit, /performance, /daily, /stats, /count, /locks, /balance, /stopentry, /reload_config, /show_config, /logs, /whitelist, /blacklist, /help, /version, /marketdir

Telegram Commands

Per default, the Telegram bot shows predefined commands. Some commands are only available by sending them to the bot. The table below list the official commands. You can ask at any moment for help with /help.

System Commands

Command	Description
/start	Starts the trader
/pause / /stopentry / /stopbuy	Pause the trader. Gracefully handle open trades according to their rules. Do not enter new positions.
/stop	Stops the trader
/reload_config	Reloads the configuration file
/show_config	Shows part of the current configuration with relevant settings to operation
/logs [limit]	Show last log messages.
/help	Show help message
/version	Show version

Status Commands

Command	Description
/status	Lists all open trades
/status <trade_id>	Lists one or more specific trade. Separate multiple <trade_id> with a blank space.
/status table	List all open trades in a table format. Pending buy orders are marked with an asterisk (*) Pending sell orders are marked with a double asterisk (**)
/order <trade_id>	Lists orders of one or more specific trade. Separate multiple <trade_id> with a blank space.
/trades [limit]	List all recently closed trades in a table format.
/count	Displays number of trades used and available
/locks	Show currently locked pairs.
/unlock <pair or lock_id>	Remove the lock for this pair (or for this lock id).
/marketdir [long | short | even | none]	Updates the user managed variable that represents the current market direction. If no direction is provided, the currently set direction will be displayed.
/list_custom_data <trade_id> [key]	List custom_data for Trade ID & Key combination. If no Key is supplied it will list all key-value pairs found for that Trade ID.

Trade Modification Commands

Command	Description
/forceexit <trade_id> / /fx <tradeid>	Instantly exits the given trade (Ignoring minimum_roi).
/forceexit all / /fx all	Instantly exits all open trades (Ignoring minimum_roi).
/fx	alias for /forceexit
/forcelong <pair> [rate]	Instantly buys the given pair. Rate is optional and only applies to limit orders. (force_entry_enable must be set to True)
/forceshort <pair> [rate]	Instantly shorts the given pair. Rate is optional and only applies to limit orders. This will only work on non-spot markets. (force_entry_enable must be set to True)
/delete <trade_id>	Delete a specific trade from the Database. Tries to close open orders. Requires manual handling of this trade on the exchange.
/reload_trade <trade_id>	Reload a trade from the Exchange. Only works in live, and can potentially help recover a trade that was manually sold on the exchange.
/cancel_open_order <trade_id> / /coo <trade_id>	Cancel an open order for a trade.

Metrics Commands

Command	Description
/profit [<n>]	Display a summary of your profit/loss from close trades and some stats about your performance, over the last n days (all trades by default)
/profit_long [<n>] / /profit_short [<n>]	Display a summary of your profit/loss from close trades in one direction and some stats about your performance, over the last n days (all trades by default)
/performance	Show performance of each finished trade grouped by pair
/balance	Show bot managed balance per currency
/balance full	Show account balance per currency
/daily <n>	Shows profit or loss per day, over the last n days (n defaults to 7)
/weekly <n>	Shows profit or loss per week, over the last n weeks (n defaults to 8)
/monthly <n>	Shows profit or loss per month, over the last n months (n defaults to 6)
/stats	Shows Wins / losses by Exit reason as well as Avg. holding durations for buys and sells
/exits	Shows Wins / losses by Exit reason as well as Avg. holding durations for buys and sells
/entries	Shows Wins / losses by Exit reason as well as Avg. holding durations for buys and sells
/whitelist [sorted] [baseonly]	Show the current whitelist. Optionally display in alphabetical order and/or with just the base currency of each pairing.
/blacklist [pair]	Show the current blacklist, or adds a pair to the blacklist.

Telegram Commands in Action

Below, example of Telegram message you will receive for each command.

/start

Status: running

/pause | /stopentry | /stopbuy

Status: paused, no more entries will occur from now. Run /start to enable entries.

Prevents the bot from opening new trades by changing the state to paused. Open trades will continue to be managed according to their regular rules (ROI/exit signals, stop-loss, etc.).

Note that position adjustment remains active, but only on the exit side — meaning that when the bot is paused, it can only reduce the position size of open trades.

After this, give the bot time to close off open trades (can be checked via /status table). Once all positions are closed, run /stop to completely stop the bot.

Use /start to resume the bot to the running state, allowing it to open new positions.

Pause Signal Persistence

The pause/stopentry signal is ONLY active while the bot is running, and is not persisted anyway, so restarting the bot will cause this to reset.

/stop

Stopping trader ... Status: stopped

/status

For each open trade, the bot will send you the following message. Enter Tag is configurable via Strategy.

Trade ID: 123 (since 1 days ago)
Current Pair: CVC/BTC
Direction: Long
Leverage: 1.0
Amount: 26.64180098
Enter Tag: Awesome Long Signal
Open Rate: 0.00007489
Current Rate: 0.00007489
Unrealized Profit: 12.95%
Stoploss: 0.00007389 (-0.02%)

/status table

Return the status of all open trades in a table format.

ID L/S    Pair     Since   Profit
----    --------  -------  --------
  67 L   SC/BTC    1 d      13.33%
 123 S   CVC/BTC   1 h      12.95%

/profit

ROI: Closed trades
∙ 0.00485701 BTC (2.2%) (15.2Σ%)
∙ 62.968 USD
ROI: All trades
∙ 0.00255280 BTC (1.5%) (6.43Σ%)
∙ 33.095 USD

Total Trade Count: 138
First Trade opened: 3 days ago
Latest Trade opened: 2 minutes ago
Avg. Duration: 2:33:45
Best Performing: PAY/BTC: 50.23%

/balance

Currency: BTC
Available: 3.05890234
Balance: 3.05890234
Pending: 0.0

/daily

Daily Profit over the last 7 days:

Day         Profit BTC      Profit USD
----------  --------------  ------------
2018-01-01  0.00269130 BTC  34.986 USD
2018-01-02  0.00123451 BTC  16.068 USD
2018-01-03  0.00000000 BTC  0.000 USD
2018-01-04  -0.00036040 BTC -4.684 USD
2018-01-05  0.00102026 BTC  13.268 USD
2018-01-06  0.00045123 BTC  5.869 USD
2018-01-07  0.00013200 BTC  1.717 USD

Best Practices

Security

1. Keep your bot token secret - Never share your bot token publicly
2. Use authorized users - Limit who can control your bot in groups
3. Regular monitoring - Check bot activity regularly
4. Secure chat - Use private chats when possible

Notification Management

1. Start conservative - Begin with minimal notifications
2. Adjust gradually - Add notifications as you become comfortable
3. Use silent mode - For non-critical notifications
4. Group similar notifications - Organize by importance

Command Usage

1. Learn key commands - Master essential commands first
2. Use shortcuts - Utilize custom keyboard for frequent commands
3. Monitor regularly - Check status and performance frequently
4. Emergency procedures - Know how to quickly stop or exit trades

Troubleshooting

Common Issues

Bot not responding:

• Check if bot is running
• Verify Telegram token is correct
• Ensure chat_id is properly set
• Check network connectivity

Commands not working:

• Verify you're using correct command syntax
• Check if you're authorized to use commands
• Ensure bot has necessary permissions
• Try restarting the bot

Missing notifications:

• Check notification settings in config
• Verify Telegram token and chat_id
• Check if notifications are set to "off"
• Review bot logs for errors

Getting Help

• Discord: Join the Freqtrade Discord
• GitHub: Report Telegram issues
• Documentation: Configuration guide

Next Steps

After setting up Telegram:

1. Bot Usage - Learn to operate the bot
2. Configuration - Advanced configuration options
3. Strategy Development - Create trading strategies
4. Monitoring - Monitor bot performance

Resources

• Telegram Bot API - Official Telegram Bot documentation
• BotFather - Create and manage Telegram bots
• Configuration - Complete configuration options