lucad87/frigate-telegram repository overview

⁠Frigate-Telegram

This project is a Telegram bot integration for Frigate, an open-source NVR (Network Video Recorder) software. It allows users to receive real-time alert notifications from their Frigate instance directly in Telegram.

⁠Table of Contents

• About⁠
• Features⁠
• Getting Started⁠
  • Environment Variables⁠
  • Frigate Authentication⁠
  • Volumes⁠
  • Docker Compose Configuration⁠
• Usage⁠
• Development⁠
• License⁠

⁠About

The application is written in Node.js and polls the Frigate API to fetch new events. When a new event is detected, it is forwarded to Telegram, including event details, a link that opens the event in the Frigate UI, a static thumbnail, and an animated preview GIF.

This project aims to retrieve events from Frigate using its API without relying on external tools like Home Assistant. MQTT is not supported.

The application polls Frigate every 60 seconds -by default- to fetch new alerts. The GET request to the Frigate API retrieves events from the last 60 seconds, filtered by the parameters specified in the docker-compose file (label, camera, and zones). You can customize it with POLLING_INTERVAL: it will set the same value for both application polling interval and frigate after.

⁠Docker hub

https://hub.docker.com/r/lucad87/frigate-telegram⁠

⁠Features

• Real-time Notifications: Receive instant alerts on your Telegram chat when Frigate detects specified objects.
• Rich Media: Each notification includes:
  • Event details (ID, timestamps)
  • Clickable link that opens the event at the right moment in the Frigate UI
  • Static thumbnail image
  • Animated preview GIF
• Authentication Support: Secure access to Frigate API using username and password, exchanged for a JWT token as Frigate requires.
• Bot Commands: Interact with the bot via Telegram commands. Use /help to see the available commands with their description, /status for the state of Frigate and its cameras, /events [n] for the most recent events, /enable_notifications to enable notifications, and /disable_notifications to disable them.
• Customizable: Configure the bot to monitor specific cameras, zones, and object labels.
• Retry Logic: Automatically retries fetching media if not immediately available.
• Debugging: Enable debug logging for troubleshooting and development purposes.
• Media URL Support: Optionally set a public URL for accessing Frigate media files.

⁠Getting Started

To get the Frigate-Telegram bot up and running, follow these steps:

⁠Environment Variables

These variables are essential for the bot's operation and should be configured in your docker-compose.yml file:

• FRIGATE_URL: The URL of your Frigate instance (e.g., http://frigate.local:5000 for the internal unauthenticated port, or https://frigate.local:8971 when authentication is enabled).
• FRIGATE_MEDIA_URL: (Optional) The base URL used for the links in the messages (e.g., https://your-media-frigate-instance.com). It must be the address of the Frigate UI as the recipients reach it, since the link opens the event there. It falls back on FRIGATE_URL.
• FRIGATE_UI_URL: (Optional) Overrides FRIGATE_MEDIA_URL for the links, when the UI lives at a different address (e.g., the UI on https://frigate.example.com and FRIGATE_MEDIA_URL pointing somewhere else).
• FRIGATE_USERNAME: (Optional) Username for Frigate authentication. Required if your Frigate instance has authentication enabled.
• FRIGATE_PASSWORD: (Optional) Password for Frigate authentication. Required if your Frigate instance has authentication enabled.
• FRIGATE_COOKIE_NAME: (Optional) Name of the Frigate session cookie holding the JWT, frigate_token by default. Only needed if you changed auth.cookie_name in your Frigate configuration.
• FRIGATE_CA_CERT: (Optional) Path to a PEM file holding the certificate (or CA) to trust for Frigate's HTTPS endpoint, e.g. /app/certs/frigate.pem. Needed when FRIGATE_URL points at the authenticated port 8971, which uses a self-signed certificate by default. The certificate chain is validated against the pinned file; the hostname check is skipped because Frigate's default certificate is issued for CN = *.
• FRIGATE_TLS_INSECURE: (Optional) Set to true to disable TLS certificate verification for Frigate. Use it as a last resort only, prefer FRIGATE_CA_CERT.
• TELEGRAM_BOT_TOKEN: The token for your Telegram bot.
• TELEGRAM_CHAT_ID: The chat ID where notifications will be sent.
• CAMERA: The name of the frigate camera to monitor.
• ZONES: The frigate zones to monitor for object detection (e.g., front,back,street).
• LABEL: The frigate object label to monitor (e.g., person).
• TIMEZONE: Your time zone, Europe/Rome is the default
• LOCALES: Your locales language according the timezone, it-IT is the default
• POLLING_INTERVAL: Interval in seconds to poll Frigate for new events (default: 60 seconds).
• DEBUG: (Optional) Set to true to enable debug logging.

⁠Frigate Authentication

Frigate authenticates its API with a JWT, not with HTTP Basic auth, and it behaves differently depending on the port you point FRIGATE_URL at:

Notes:

• Credentials are only used if both FRIGATE_USERNAME and FRIGATE_PASSWORD are set.
• The token is valid for Frigate's auth.session_length (24 hours by default) and is renewed automatically; if Frigate rejects it (for example after FRIGATE_JWT_SECRET changes), the bot authenticates again on the next request.
• A 401 in the logs means Frigate is answering unauthenticated: either set the credentials for port 8971, or move to port 5000.
• Port 8971 serves a self-signed certificate ("FRIGATE DEFAULT CERT") unless you configured TLS. Node refuses it by default, so pointing FRIGATE_URL at https://<frigate-host>:8971 needs FRIGATE_CA_CERT (preferred) or FRIGATE_TLS_INSECURE=true. Reverse proxies with a valid certificate (e.g. https://frigate.example.com) do not need either. To get the PEM: openssl s_client -connect <frigate-host>:8971 -servername <frigate-host> </dev/null 2>/dev/null | openssl x509 -outform PEM > frigate.pem.
• The link opens the event in the Frigate UI (/review?timestamp=<camera>_<timestamp>, the same format Frigate uses for its own recording share links) instead of the raw clip file, because /api/events/<id>/clip.mp4 requires authentication and a link cannot carry credentials — pointing at it returned 401 Authorization Required. Nothing needs to be published without authentication for the link to work: the viewer has to be logged into Frigate in their browser. Note that Frigate sends you to the Live view after a login, so a recipient without a session lands on the login page and then on the dashboard.

⁠Volumes

• ./logs:/app/logs: Mounts the logs directory to persist log files.

⁠Docker Compose Configuration

Below is an example docker-compose.yml configuration. Replace the placeholder values with your actual settings.

services:
  app:
    image: lucad87/frigate-telegram:latest
    environment:
      - FRIGATE_URL=<your-frigate-instance-url> # e.g. http://frigate:5000 (no auth) or https://frigate.example.com:8971 (JWT auth)
      - FRIGATE_MEDIA_URL=<your-public-media-frigate-instance-url> # (optional) Base URL for the links in the messages, it must be the Frigate UI as the recipients reach it. It fallbacks on FRIGATE_URL
      - FRIGATE_UI_URL=<your-frigate-ui-url> # (optional) Overrides FRIGATE_MEDIA_URL for the links, only needed if the UI is at a different address
      - FRIGATE_USERNAME=<your-frigate-username> # (optional) Required if Frigate has authentication enabled (port 8971)
      - FRIGATE_PASSWORD=<your-frigate-password> # (optional) Required if Frigate has authentication enabled (port 8971)
      - FRIGATE_COOKIE_NAME=<your-frigate-cookie-name> # (optional) Only if you changed auth.cookie_name in Frigate, frigate_token is the default
      - FRIGATE_CA_CERT=<path-to-pem> # (optional) Trust this certificate for Frigate's HTTPS endpoint, needed for port 8971 with its self-signed certificate
      - FRIGATE_TLS_INSECURE=true # (optional) Disable TLS verification instead of providing a certificate, last resort only
      - TELEGRAM_BOT_TOKEN=<your-telegram-token>
      - TELEGRAM_CHAT_ID=<your-telegram-chat-id>
      - CAMERA=<frigate-camera>
      - ZONES=<frigate-zones>
      - LABEL=<frigate-label>
      - TIMEZONE=<you_timezone> # (optional) Set to the timezone to use for the date and time in the messages, Europe/Rome is the default
      - LOCALES=<locales> # (optional) Set to the locale to use for the date and time in the messages, it-IT is the default
      - POLLING_INTERVAL=<seconds> # (optional) Set to the interval in seconds to poll Frigate for new events, 60 seconds is the default
      - DEBUG=false # (optional) Set to true to enable debug logging
    volumes:
      - <your-logs-volume-path>:/app/logs
    restart: unless-stopped

⁠Usage

1. Pull the Docker image:

   docker pull lucad87/frigate-telegram:latest
   

   Copy

2. Run the container using Docker Compose: Navigate to the directory containing your docker-compose.yml file and run:

   docker compose up -d
   

   Copy

3. Control the Bot via Telegram: Once the bot is running, you can interact with it by sending commands directly to your bot in Telegram:

   • /help: Show the available commands with their description. It also answers /start, which is what Telegram sends when a user presses START in the private chat.
   • /status: Show Frigate's version and uptime, the detector speed, each camera's detection state, fps and connection quality, free storage, and whether the bot is currently forwarding notifications.
   • /events [n]: List the n most recent events (default 5, maximum 10) with label, camera and time, each followed by the link that opens it in the Frigate UI.
   • /enable_notifications: Enable event notifications.
   • /disable_notifications: Disable event notifications.

   Commands work both in the private chat and in a group, with or without the @bot_username suffix that Telegram adds when you pick a command from the menu.

⁠Development

To set up the project for local development:

1. Clone the repository:

   git clone https://github.com/lucad87/frigate-telegram.git
   cd frigate-telegram
   

   Copy

2. Install dependencies:

   npm install
   

   Copy

3. Run the application: You will need to set up environment variables (e.g., in a .env file or directly in your shell) as described in the Environment Variables⁠ section.

   node app/index.js
   

   Copy

⁠License

This project is licensed under the MIT License — see LICENSE⁠.

This license also applies to all versions of the project published before the LICENSE file was added, and no claim is made for any use, modification or distribution that occurred before that date.