The telegram component can do two things:
- First, it can send detection videos (and thumbnails) to a chat when a detection occurs.
- Second, it can be used to control the PTZ (pan-tilt-zoom) for the ONVIF component from the chatbot directly, with commands like
/home,/left,/right(see available commands below).
Configuration
Configuration example
/config/config.yaml
telegram:
telegram_bot_token: <bot_token_from_BotFather>
telegram_chat_ids:
- <your_chat_id>
detection_label: person
send_detection_thumbnail: true
send_detection_video: true
send_detection_message: false
cameras:
camera_1:
camera_2:
telegrammap required
Telegram bot to control cameras.
How to create a bot and get your chat ID:
Create a bot
- In Telegram, open @BotFather.
- Send
/newbot, choose a name and a unique username. - Copy the token it returns (use this as
telegram_bot_token).
Start a conversation
- Private chat: open your bot and press Start, then send any message.
- Group: add your bot to the group and send a message in the group.
- If the bot does not receive group messages, disable privacy via @BotFather: /setprivacy → select your bot → Disable.
Find your chat ID
You can get your chat_id by sending a message to the GetIDs bot.
Configure Viseron
- Put the numeric ID(s) in
telegram_chat_ids. - You can list multiple IDs to notify several chats.
For more thorough instructions, see the Home Assistant Telegram docs: https://www.home-assistant.io/integrations/telegram/
Available commands
To find the available commands you can use, send /help to your bot in Telegram. As of the time of writing this documentation, the available help commands are described as follows:
info
Use /help <command> to get more information about a command. For commands starting from number 1 to 13, they only apply to cameras that have ONVIF component.
| No | Commands | Description | Notes |
|---|---|---|---|
| 1 | /home or /h | Move the camera to its home position. | If supported by the camera. |
| 2 | /left or /l | Pan the camera to the left. | Using the RelativeMove operation. And will use ContinuousMove as a fallback if it is not supported. |
| 3 | /right or /r | Pan the camera to the right. | Using the RelativeMove operation. And will use ContinuousMove as a fallback if it is not supported. |
| 4 | /up or /u | Tilt the camera up. | Using the RelativeMove operation. And will use ContinuousMove as a fallback if it is not supported. |
| 5 | /down or /d | Tilt the camera down. | Using the RelativeMove operation. And will use ContinuousMove as a fallback if it is not supported. |
| 6 | /zo or /o | Zoom the camera out. | Using the RelativeMove operation. And will use ContinuousMove as a fallback if it is not supported. |
| 7 | /zi or /i | Zoom the camera in. | Using the RelativeMove operation. And will use ContinuousMove as a fallback if it is not supported. |
| 8 | /pos | Get the current (PTZ) position of the camera. | If supported by the camera. |
| 9 | /preset or /pr | Change the camera to a preset position. | Will display user-defined presets and presets that are already in the ONVIF camera. |
| 10 | /repeat | Presets are paths when names are reused. | - |
| 11 | /patrol or /p | Swings the camera from left to right and back. | The default duration is 60 seconds. It will not work properly if your camera does not support GetStatus, RelativeMove, and AbsoluteMove operations. |
| 12 | /lissa | Perform Lissajous curve swing patrols. | Must be stopped manually with the /stop command. It will not work properly if your camera does not support GetStatus, RelativeMove, and AbsoluteMove operations. |
| 13 | /stop or /st | Stop the patrol. | - |
| 14 | /record or /r | Record a video with the camera. | - |
| 15 | /stop_recorder or /sr | Stop an ongoing manual recording. | - |
| 16 | /list or /li or /select | List all available cameras. | - |
| 17 | /which or /w | Get the currently active camera. | It is important to know which camera to execute. |
| 18 | /toggle or /t | Toggle the camera on or off. | - |
| 19 | /snapshot | Take a snapshot with the camera. | - |
| 20 | /help | Display a list of commands and their description. | - |
Troubleshooting
To enable debug logging for
telegram, add the following to your config.yaml/config/config.yaml
logger:
logs:
viseron.components.telegram: debug