Comment intégrer Telegram dans une instance n8n auto‑hébergée ?

L’in­té­gra­tion de Telegram à une instance n8n auto-hébergée vous permet d’intégrer di­rec­te­ment des messages et des no­ti­fi­ca­tions à vos workflows d’au­to­ma­ti­sa­tion. Dans ce guide, vous dé­cou­vri­rez étape par étape comment connecter Telegram à n8n et créer vos premiers workflows simples pour gérer les messages entrants et sortants.

Quels sont les avantages de l’in­té­gra­tion de Telegram dans n8n ?

Telegram se prête par­ti­cu­liè­re­ment bien à l’in­té­gra­tion dans n8n, car l’ap­pli­ca­tion de mes­sa­ge­rie permet une com­mu­ni­ca­tion rapide et directe. Les messages sont gé­né­ra­le­ment délivrés en temps réel, ce qui vous permet d’être im­mé­dia­te­ment informé des évé­ne­ments dans vos workflows. Par rapport aux emails ou à d’autres systèmes de no­ti­fi­ca­tion comme Discord, qui peut également être connecté à n8n, les messages Telegram sont fa­ci­le­ment con­sul­tables sur les appareils mobiles. Telegram convient ainsi par­ti­cu­liè­re­ment bien aux alertes, aux messages de statut et aux con­fir­ma­tions.

Un autre avantage réside dans la structure simple de la com­mu­ni­ca­tion. Les messages, fichiers, images et liens peuvent être fa­ci­le­ment envoyés et traités dans vos workflows. Vous pouvez par exemple trans­mettre au­to­ma­ti­que­ment à Telegram des contenus provenant d’API, de bases de données ou d’autres outils comme Jira avec n8n, sans devoir dé­ve­lop­per d’in­ter­faces sup­plé­men­taires. À l’inverse, les messages entrants peuvent servir de dé­clen­cheurs pour d’autres au­to­ma­ti­sa­tions et permettre ainsi de mettre en place des processus in­te­rac­tifs.

Pour les instances n8n auto-hébergées, Telegram est pratique, car vous n’avez pas besoin d’in­fras­truc­ture de mes­sa­ge­rie sup­plé­men­taire pour envoyer des no­ti­fi­ca­tions. Vous pouvez connecter di­rec­te­ment vos workflows existants à une ap­pli­ca­tion de mes­sa­ge­rie que vous utilisez déjà au quotidien. La com­mu­ni­ca­tion en équipe peut aussi être mise en place en envoyant des messages à des groupes ou à des canaux. Plusieurs personnes peuvent ainsi garder si­mul­ta­né­ment une vue d’ensemble des évé­ne­ments im­por­tants.

Quelles sont les étapes à suivre pour intégrer Telegram à n8n ?

Étape 1 : remplir les prérequis

Avant de commencer la con­fi­gu­ra­tion pro­pre­ment dite, vérifiez ra­pi­de­ment que toutes les bases sont en place. Cela vous fera gagner du temps par la suite, car les erreurs les plus fré­quentes avec les dé­clen­cheurs Telegram dans n8n ne viennent pas du workflow lui-même, mais de prérequis manquants, comme une URL n8n inac­ces­sible pu­bli­que­ment ou un bot qui n’a pas encore été créé. Les con­di­tions suivantes doivent être remplies :

• Une instance n8n auto-hébergée : votre en­vi­ron­ne­ment n8n doit déjà fonc­tion­ner et être ac­ces­sible via le na­vi­ga­teur.
• Une URL publique pour n8n : pour recevoir les évé­ne­ments Telegram, n8n a besoin d’une adresse HTTPS ac­ces­sible depuis l’extérieur.
• Un compte Telegram et des iden­ti­fiants valides : vous avez besoin d’iden­ti­fiants à en­re­gis­trer dans n8n ainsi que d’un access token généré via BotFather.
• Accès à la con­fi­gu­ra­tion n8n : si votre instance fonc­tionne derrière un reverse proxy, vous devez pouvoir adapter des variables d’en­vi­ron­ne­ment comme WEBHOOK_URL, N8N_HOST et N8N_PROTOCOL.
• Un chat ou un groupe de test (optionnel) : vous pouvez ainsi essayer l’in­té­gra­tion di­rec­te­ment sans affecter les processus en pro­duc­tion.

Étape 2 : préparer les iden­ti­fiants d’accès Telegram

Pour intégrer Telegram à n8n, vous avez besoin d’iden­ti­fiants d’accès valides per­met­tant à n8n de s’au­then­ti­fier auprès de Telegram. Ces iden­ti­fiants per­met­tent à n8n d’envoyer des messages et, lorsqu’un trigger est utilisé, de recevoir les messages entrants.

Si vous possédez déjà un compte Telegram, vous disposez de l’élément de base né­ces­saire. Telegram n’établit aucune connexion directe avec n8n, mais fonc­tionne via une interface technique, la Bot API, pour laquelle un jeton d’accès (access token) est né­ces­saire. Ce token agit comme une clé unique per­met­tant à n8n de com­mu­ni­quer avec Telegram. Dans de nombreux cas, un tel accès existe déjà, par exemple si Telegram est utilisé dans d’autres outils ou au­to­ma­ti­sa­tions. Vous pouvez alors réu­ti­li­ser le token existant et l’en­re­gis­trer di­rec­te­ment dans n8n.

Si vous ne disposez pas encore de token, vous devez d’abord en créer un dans le cadre de la mise en place d’un bot Telegram avec n8n. Cette étape est rapide à effectuer. Traitez le jeton d’accès comme un mot de passe : toute personne qui y a accès peut envoyer ou traiter des messages au nom de votre in­té­gra­tion. Stockez-le donc dans un em­pla­ce­ment sûr et ne le diffusez jamais pu­bli­que­ment.

Étape 3 : rendre n8n ac­ces­sible pour les Webhooks

Si vous utilisez Telegram avec n8n uni­que­ment pour envoyer des messages, il suffit d’en­re­gis­trer les iden­ti­fiants d’accès dans n8n. Dans ce cas, l’outil d’au­to­ma­ti­sa­tion établit lui-même ac­ti­ve­ment la connexion à Telegram, de sorte qu’aucune con­fi­gu­ra­tion sup­plé­men­taire n’est né­ces­saire.

Dès que vous souhaitez traiter des messages entrants, c’est-à-dire utiliser Telegram comme trigger, votre instance n8n doit être ac­ces­sible depuis l’extérieur. En effet, Telegram envoie ac­ti­ve­ment les nouveaux messages à n8n. Pour cela, n8n utilise ce que l’on appelle des Webhooks, c’est-à-dire des URL publiques pouvant être appelées par des services externes.

n8n crée au­to­ma­ti­que­ment ces URL de Webhook à partir de votre con­fi­gu­ra­tion. Toutefois, si votre instance fonc­tionne derrière un reverse proxy, n8n ne connaît souvent que des adresses internes sans con­fi­gu­ra­tion sup­plé­men­taire. Les Webhooks sont alors bien créés, mais ne peuvent pas être utilisés depuis l’extérieur.

Un exemple simple avec Docker Compose montre comment con­fi­gu­rer votre instance n8n afin que des URL de Webhook publiques et correctes soient générées et que des services externes comme Telegram puissent y accéder de manière fiable :

services:
    n8n:
        image: n8nio/n8n:latest
        ports:
            - "5678:5678"
        environment:
            - N8N_HOST=n8n.example.com
            - N8N_PROTOCOL=https
            - WEBHOOK_URL=https://n8n.example.com/
            - N8N_PROXY_HOPS=1
        volumes:
            - ./n8n_data:/home/node/.n8n

Étape 4 : en­re­gis­trer les iden­ti­fiants Telegram dans n8n

À l’étape suivante, vous connectez Telegram à votre instance n8n. Pour cela, vous devez en­re­gis­trer une seule fois dans n8n les iden­ti­fiants d’accès préparés pré­cé­dem­ment. n8n les stocke sous forme de cre­den­tials, ce qui vous permet ensuite de les réu­ti­li­ser dans n’importe quel workflow sans devoir saisir à nouveau le token.

Procédez étape par étape :

1. Ouvrez l’interface n8n dans votre na­vi­ga­teur.
2. Créez un nouveau workflow pour con­fi­gu­rer ou tester l’in­té­gra­tion.
3. Ajoutez un nœud Telegram.
4. Cliquez sur « Create new cre­den­tial » dans la section « Cre­den­tials ».
5. Saisissez votre jeton d’accès existant dans le champ « Access Token ».

En­re­gis­trez la saisie. Une fois les cre­den­tials en­re­gis­trés, la connexion entre Telegram et n8n est im­mé­dia­te­ment dis­po­nible. Vous pouvez désormais sé­lec­tion­ner ces cre­den­tials dans n’importe quel autre workflow. Cette étape ne doit être effectuée qu’une seule fois. Vous pouvez ensuite intégrer Telegram autant de fois que vous le souhaitez dans vos workflows nouveaux ou existants.

Close

La connexion peut ensuite être testée di­rec­te­ment dans n8n. Le résultat du test s’affiche alors dans l’interface :

Close

Étape 5 : envoyer un premier message Telegram depuis n8n

Pour tester l’in­té­gra­tion, il est re­com­mandé de créer d’abord un workflow très simple qui envoie un message à Telegram. Vous pouvez ainsi vérifier ra­pi­de­ment si la connexion entre Telegram et n8n fonc­tionne cor­rec­te­ment, sans utiliser d’emblée des triggers ou des logiques plus complexes.

La structure de base du workflow se présente comme suit :

Manual Trigger → Telegram

Le workflow est ainsi démarré ma­nuel­le­ment, puis un message est envoyé via le nœud Telegram. Ajoutez d’abord un nœud Manual Trigger, qui permet d’exécuter le workflow en un clic. Ajoutez ensuite un nœud Telegram et reliez les deux nœuds en traçant une ligne entre eux.

Dans le nœud Telegram, sé­lec­tion­nez les cre­den­tials Telegram créés pré­cé­dem­ment afin que n8n sache avec quelles données d’accès envoyer le message. Con­fi­gu­rez ensuite le nœud en choi­sis­sant « Message » comme Resource et « Send Message » comme Operation. Indiquez également la des­ti­na­tion : saisissez soit un ID de chat, soit le nom d’un canal, par exemple « @canalnom ». Ce paramètre détermine où le message sera envoyé. Pour le test, vous pouvez utiliser n’importe quel texte ; dans notre exemple, nous utilisons Hello World! From n8n.

Close

Vous pouvez vérifier le fonc­tion­ne­ment de l’envoi en exécutant le nœud à l’aide du bouton « Execute Step » :

Close

Démarrez ensuite le workflow ma­nuel­le­ment. Si tout est cor­rec­te­ment configuré, le message s’affiche im­mé­dia­te­ment dans Telegram.

Close

Étape 6 : traiter les messages Telegram entrants

Si vous souhaitez utiliser Telegram non seulement pour l’envoi, mais aussi comme canal d’entrée, utilisez le Telegram Trigger. Ce nœud démarre au­to­ma­ti­que­ment votre workflow dès qu’un nouveau message arrive dans Telegram. Vous pouvez ainsi traiter et exploiter di­rec­te­ment les messages entrants.

Une structure simple se présente comme suit :

Telegram Trigger → Telegram

Dans notre exemple, le workflow répond im­mé­dia­te­ment à un message reçu. Ajoutez d’abord un nœud Telegram Trigger à votre workflow. Sé­lec­tion­nez ensuite les cre­den­tials Telegram créés pré­cé­dem­ment afin que n8n puisse accéder à Telegram. Dé­fi­nis­sez ensuite l’événement souhaité, par exemple la réception de nouveaux messages.

À l’étape suivante, ajoutez un nœud Telegram et connectez-le au trigger. Dans ce nœud, sé­lec­tion­nez à nouveau une opération d’envoi ap­pro­priée, par exemple « Send Message », pour envoyer une réponse.

Pour que la réponse arrive dans le bon chat, vous pouvez reprendre di­rec­te­ment l’ID de chat à partir des données du trigger. Le workflow répond ainsi au­to­ma­ti­que­ment dans le chat d’où provient le message initial. Vous n’avez donc pas besoin de saisir ma­nuel­le­ment l’ID du chat.

Après un test, n8n affiche dans la zone de sortie du nœud Telegram Trigger toutes les données reçues. Vous pouvez ainsi voir pré­ci­sé­ment quelles in­for­ma­tions sont dis­po­nibles, par exemple le texte du message, l’ID du chat ou d’autres mé­ta­don­nées.

Étape 7 : utiliser le workflow en pro­duc­tion

Dès que votre workflow fonc­tionne, vous pouvez l’activer. n8n traite alors les messages entrants en continu et envoie au­to­ma­ti­que­ment des réponses ou des no­ti­fi­ca­tions. Comme n8n a en­re­gis­tré votre workflow uni­que­ment comme brouillon, vous devez d’abord le publier. Cliquez pour cela sur le bouton « Publish » (dans les anciennes versions, utilisez à la place le bouton d’ac­ti­va­tion).

Telegram devient ainsi un élément permanent de votre au­to­ma­ti­sa­tion et peut servir d’interface de com­mu­ni­ca­tion au sein de l’ensemble de vos workflows n8n.

Quels workflows Telegram avec n8n pouvez-vous mettre en place ?

Telegram est par­ti­cu­liè­re­ment adapté aux no­ti­fi­ca­tions et aux in­te­rac­tions avec n8n. L’in­té­gra­tion est notamment utile lorsque les in­for­ma­tions doivent être dis­po­nibles ra­pi­de­ment ou lorsqu’il faut réagir di­rec­te­ment à certains évé­ne­ments.

Exemple 1 : signaler les pannes de serveur ou de site Web

Vous pouvez utiliser n8n pour vérifier ré­gu­liè­re­ment un site Web ou un serveur et recevoir au­to­ma­ti­que­ment une no­ti­fi­ca­tion via Telegram en cas de problème. Pour cela, con­fi­gu­rez un workflow qui s’exécute à in­ter­valles réguliers, par exemple toutes les cinq minutes. Un nœud HTTP Request appelle alors le site Web souhaité et vérifie s’il est ac­ces­sible. Un nœud IF évalue ensuite si le code de statut indique un problème, par exemple une erreur ou un timeout. En cas d’erreur, n8n envoie au­to­ma­ti­que­ment un message à Telegram, afin que vous soyez im­mé­dia­te­ment informé. Vous pouvez ainsi détecter les pannes à un stade précoce sans devoir sur­veil­ler les systèmes ma­nuel­le­ment.

Close

Exemple 2 : utiliser Telegram comme canal de saisie pour des requêtes

Telegram peut servir d’interface de saisie simple et directe pour vos workflows. Dans ce scénario, un message entrant déclenche au­to­ma­ti­que­ment un workflow dans n8n. Son contenu est ensuite analysé, par exemple avec un nœud IF ou Switch. En fonction du résultat, dif­fé­rentes actions peuvent être exécutées, comme récupérer des données depuis une API ou une base de données. Les résultats sont ensuite renvoyés à Telegram sous forme de message. Vous obtenez ainsi un processus in­te­rac­tif simple qui permet d’in­ter­ro­ger des in­for­ma­tions di­rec­te­ment depuis le chat, sans devoir vous connecter à d’autres systèmes.

Close

Exemple 3 : trans­fé­rer au­to­ma­ti­que­ment les nouvelles requêtes ou évé­ne­ments

Un autre cas d’usage fréquent consiste à rediriger au­to­ma­ti­que­ment vers Telegram des évé­ne­ments provenant d’autres systèmes. Dès qu’une nouvelle demande est soumise via un for­mu­laire ou qu’une commande est créée dans une boutique, n8n peut traiter cette in­for­ma­tion. Le workflow est déclenché soit par un Webhook, soit par un trigger spé­ci­fique à l’ap­pli­ca­tion. Les données per­ti­nentes sont ensuite préparées et trans­for­mées en un message com­pré­hen­sible, qui est au­to­ma­ti­que­ment envoyé à un chat ou à un groupe Telegram. Vous et votre équipe restez ainsi informés sans devoir vérifier en per­ma­nence dif­fé­rents systèmes. Cette au­to­ma­ti­sa­tion peut notamment aider les petites équipes à réagir ra­pi­de­ment et à conserver une meilleure vue d’ensemble.

Close