Skip to main content

Telegram integration for Gladys Assistant

Telegram integration for Gladys Assistant

Chat with Gladys from Telegram: ask about your home and receive your notifications.

View on GitHubAll external integrations

Chat with Gladys from Telegram: ask questions about your home, trigger your scenes, and receive the notifications Gladys sends you — all from the Telegram app on your phone or computer.

Overview​

This integration runs your own Telegram bot. Nothing goes through a shared Gladys bot: you create the bot with Telegram's official @BotFather, and the integration connects to it with the token it gives you.

Once a Gladys user has linked their Telegram account, whatever they write to the bot is routed to the Gladys brain with their identity — exactly as if they had typed it in the Gladys chat. Replies, and any notification Gladys sends them, come back in the same Telegram conversation.

Prerequisites​

  • A Telegram account.
  • A bot created with @BotFather (free, takes a minute — see below).

Create your bot​

  1. In Telegram, open a conversation with @BotFather.
  2. Send /newbot.
  3. Pick a display name (e.g. Gladys), then a username ending in bot (e.g. my_home_gladys_bot). Usernames are unique across Telegram, so you may have to try a few.
  4. @BotFather answers with a token that looks like 123456789:AAE.... Keep it secret: anyone holding it controls the bot.

Useful optional commands of @BotFather: /setuserpic to give your bot an avatar, /setdescription for the text shown before the first message, and /setprivacy (privacy stays enabled — this integration only answers in one-to-one conversations anyway).

Configuration​

  1. Open the Configuration tab of the Telegram integration in Gladys.
  2. Paste the token from @BotFather in the Telegram bot token field, and save.
  3. Click Test the bot token: Gladys checks the token against the Telegram API and displays the username of your bot when it works.

The connection status shown on the screen reflects the real state of the bot: if Telegram refuses the token, it says so instead of failing silently.

Each Gladys user links their own Telegram account, and only linked accounts can talk to Gladys:

  1. In the same Configuration tab, click Link my account. Gladys shows a short code, valid 15 minutes and usable once.
  2. Open the conversation with your bot in Telegram (search for its username, then press Start).
  3. Send the code to the bot. It confirms the link, and you can start asking questions right away.

You can revoke a link at any time from the same screen: the contact is unlinked and the bot stops answering it.

Troubleshooting​

The bot does not answer at all. Check the connection status in the Configuration tab, then click Test the bot token. A revoked or mistyped token is the usual cause; generate a new one with /token in @BotFather and paste it again.

"Your Telegram account is not linked yet". The message means the bot does not know your Telegram account: generate a fresh code from Gladys and send it to the bot. Codes expire after 15 minutes and only work once.

"This code is invalid or has expired". Same fix: generate a new code. Make sure you send it in the private conversation with the bot, not in a group.

Nothing happens in a group conversation. This is intentional: a linked contact speaks with the authority of its Gladys user, so the integration only answers in one-to-one conversations.

Two Gladys instances, one bot. A Telegram bot can only be polled by a single client at a time. Using the same token in two Gladys instances makes both of them miss messages: create a second bot instead.

For anything else, open the integration logs from the Gladys UI: the integration logs what it does, and LOG_LEVEL=debug gives the full detail.

Configuration settings​

These are the settings Telegram asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Telegram bot tokensecretYesCreate a bot with @BotFather on Telegram (/newbot) and paste the token it gives you here.

How to install Telegram in Gladys​

  1. In Gladys, open Integrations: Telegram appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/gladysassistant/gladys-telegram:1.1.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/GladysAssistant/gladys-telegram.

Telegram requires Gladys >=4.83.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Telegram is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by GladysAssistant, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on