Easily send Sonarr notifications to Telegram

2 years after


Build Status Go Report Card License

Easily send Sonarr notifications to Telegram.

Table of Contents


Sonagram is a Custom Post-Processing Script for Sonarr that allows you to use Telegram's Bot API to send messages to a Telegram account when a file is downloaded.

Installation & Usage

  1. Download the notifier binary for your platform

    Go to the releases page and download the latest binary for your particular platform.

    Save it a location that your Sonarr installation can access.

  2. Download the default config.json file

    Download the default config.json file and save it to a location that your Sonarr installation can access.

    The default config file looks like this:

    "telegram_token": "",
    "telegram_chat_id": "",
    "telegram_message_format": "*{{sonarr_series_title}}*\nSeason: *{{sonarr_episodefile_seasonnumber}}* Episode: *{{sonarr_episodefile_episodenumbers}}*\nQuality: *{{sonarr_episodefile_quality}}*\nScene: *{{sonarr_episodefile_scenename}}*"

    In the next steps we will fill out the telegram_token and telegram_chat_id fields.

  3. Create a Telegram Bot

    Follow this link to find instructions for creating a Telegram Bot. You will eventually be given an API token.

    The token is a string along the lines of 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw that will be required to authorize the bot and send requests to the Telegram Bot API.

    Modify the config.json file that you downloaded in Step 2 and replace the value for the telegram_token field with the token given to you from this step.

  4. Talk to your Telegram Bot

    You must first manually initiate a conversation with the bot you created. You can do this using any Telegram client. Once you have initiated a converstation with your bot and sent the /start command, you can now aquire the next piece of information you'll need, the Chat ID.

  5. Retrieve Chat ID from the Telegram API

    Next, execute the sonarr-notify executable you downloaded in Step 1. The first and only arguement for the utility is the path to its config file.

    Here is an example of what this would look like on Windows:

    C:\Scripts\sonagram.exe C:\Scripts\config.json
    > Config file is missing telegram_chat_id
    > Querying Chat IDs for Bot...
    > ChatID: 10023234 - Username: madmax
    > Please add one of the above to your Config file

    The sonarr-notify utility will detect that you are missing your Chat ID in your config.json and query the Telegram Bot API for all the Chat IDs available to that bot. These will include all the people who have initiated conversations with your bot (which you should have done yourself in Step 4).

    Replace the telegram_chat_id property in the config.json with the numeric Chat ID that the utility gives you.

  6. Modify the Message Format (Optional)

    The config.json comes with a default telegram_message_format. This field defines a template for the messages that will be sent to your Telegram account

    Each item in the {{ }} is an environment variable that Sonarr provides when executing Custom Scripts.

    Here is a table of some of the variables available for the different events (see this link for an up-to-date list):

    Sonarr Provided Variables
    Variable Details
    sonarr_eventtype Download
    sonarr_series_id Internal ID of the series
    sonarr_series_title Title of the series
    sonarr_series_path Full path to the series
    sonarr_series_tvdbid TVDB ID for the series
    sonarr_episodefile_id Internal ID of the episode file
    sonarr_episodefile_relativepath Path to the episode file relative to the series' path
    sonarr_episodefile_path Full path to the episode file
    sonarr_episodefile_seasonnumber Season number of episode
    sonarr_episodefile_episodenumbers Comma separated list of episode numbers
    sonarr_episodefile_episodeairdates Air date from original network
    sonarr_episodefile_episodeairdatesutc Air Date with Time in UTC
    sonarr_episodefile_quality Quality name from Sonarr
    sonarr_episodefile_qualityversion 1 is the default, 2 for proper, 3+ could be used for anime versions
    sonarr_episodefile_releasegroup Release group, will not be set if it is unknown
    sonarr_episodefile_scenename Original release name
    sonarr_episodefile_sourcepath Full path to the episode file that was imported
    sonarr_episodefile_sourcefolder Full path to the folder the episode file was imported from

    In addition, I've provided a couple variables that Sonarr does not:

    Custom Variables
    Variable Details
    sonarr_episodefile_friendlysize Friendly File Size
    sonarr_episodefile_size File Size
  7. Configure Sonarr

    Navigate to the Settings page from within Sonarr. Select the "Connect" tab and click the "+" button to add another connection. Then choose the "Custom Script" option from the modal dialog.

    Edit the "Path" field to be the absolute path to the sonarr-notify executable. Then edit the "Arguements" field to be an absolute path to the config.json.


    Note: Hitting the "Test" button does not execute the script. It simply verifies that it exists. If you want to really test it you'll have to execute it yourself in a command prompt, or trigger a new episode to download.

  8. Enjoy!

    You should now start receiving Sonarr notifications to your Telegram account!


  • go-humanize - formatters for units to human friendly sizes


This project is licensed under the MIT License


Top Contributors



-   v1.1.0 zip tar
-   v1.0.0 zip tar