Boîte à outils Telegram

La boîte à outils Telegram permet aux agents et workflows d’interagir avec les bots Telegram. Elle prend en charge l’envoi et la modification de messages, l’envoi de médias, la gestion des membres de discussion, la génération de liens d’invitation et l’enregistrement de webhooks pour déclencher des workflows à partir de messages entrants. Les bots Telegram et leurs identifiants sont gérés via un bot Telegram appelé @BotFather — il n’existe pas de console de développement web.

Prérequis

Prérequis	Détail
Compte Telegram	Requis pour interagir avec @BotFather

Étape 1 — Créer un bot Telegram

Ouvrez @BotFather

Ouvrez Telegram et lancez une conversation avec @BotFather.

Créez un nouveau bot

Envoyez la commande /newbot et suivez les instructions :

Invite	Détail
Nom du bot	Un nom d’affichage lisible (par ex. `My App`)
Nom d’utilisateur	Doit être unique et se terminer par `bot` (par ex. `myapp_bot`)

Copiez votre token de bot

BotFather répondra avec un message de succès contenant votre token de bot — il ressemble à 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ. Copiez-le et conservez-le en lieu sûr.

Définissez une photo de profil correspondant au logo de votre application à l’aide de la commande /setuserpic dans BotFather. Une image reconnaissable donne à votre bot une apparence professionnelle et digne de confiance pour les utilisateurs.

Étape 2 — Ajoutez le token à EK

Workflow Builder
Agent Builder

Dans le workflow, ajoutez une étape de boîte à outils Telegram.
Cliquez sur Select a Connection → Create a Connection.
Saisissez un Connection Name et collez votre token de bot.
Cliquez sur Save.

Gestion de votre token

Votre token de bot est la clé maître de votre bot. Ne le partagez pas, ne le commitez pas dans des dépôts publics et ne l’exposez pas dans du code côté client.

Si votre token est accidentellement divulgué, révoquez-le immédiatement :

Envoyez un message à @BotFather
Envoyez /mybots
Sélectionnez votre bot
Appuyez sur API Token → Revoke current token

Un nouveau token sera généré. Mettez à jour la connexion dans EK avec la nouvelle valeur.

Outils disponibles

Outil	Description
New Message (Trigger)	Démarre un workflow lorsqu’un message est envoyé à votre bot
Send Text Message	Envoie un message texte de votre bot à n’importe quelle discussion
Send Media	Envoie une photo, une vidéo, un sticker ou un GIF animé
Edit Message Text	Met à jour le texte d’un message précédemment envoyé
Delete Message	Supprime un message d’une discussion
Get Chat Info	Récupère les métadonnées d’une discussion
Get Chat Member	Recherche le statut de membre d’un utilisateur dans une discussion
Create Invite Link	Génère un lien d’invitation pour un groupe ou une chaîne
Register Webhook	Indique à Telegram de transférer les messages du bot vers votre workflow
Deregister Webhook	Supprime le webhook et arrête la livraison des messages

Trigger — New Message

Démarre automatiquement un workflow chaque fois qu’un utilisateur envoie un message à votre bot Telegram. Configuration :

Ajoutez le déclencheur

Ajoutez un trigger New Message comme première étape de votre workflow. Copiez l’URL /tool-webhook/{workflow-id} depuis le panneau de configuration du déclencheur.

Enregistrez le webhook

Utilisez l’étape Register Webhook pour indiquer à Telegram de livrer les messages à cette URL. Exécutez-le une seule fois — voir Register Webhook ci-dessous.

Testez

Envoyez un message de test à votre bot. Le workflow se déclenche et toutes les données du message sont disponibles en tant que variables.

Variables de déclencheur disponibles :

Variable	Description
`{{ trigger.body.message.text }}`	Le texte du message envoyé par l’utilisateur
`{{ trigger.body.message.chat.id }}`	L’ID de discussion — utilisez-le comme Chat ID dans toutes les étapes d’envoi
`{{ trigger.body.message.from.id }}`	L’ID utilisateur Telegram de l’expéditeur
`{{ trigger.body.message.from.first_name }}`	Le prénom de l’expéditeur
`{{ trigger.body.message.from.username }}`	Le nom d’utilisateur de l’expéditeur (peut être vide)
`{{ trigger.body.message.message_id }}`	L’ID du message entrant
`{{ trigger.body.update_id }}`	L’ID de mise à jour unique de Telegram

Actions de messagerie

Send Text Message

Envoie un message texte de votre bot à n’importe quelle discussion Telegram. Entrées principales :

Entrée	Description
Chat ID	La discussion destination. Pour la personne qui a déclenché le workflow, utilisez `{{ trigger.body.message.chat.id }}`. Pour un groupe ou une chaîne fixe, collez son ID numérique.
Message	Le texte à envoyer. Combinez du texte statique avec des variables, par ex. `Bonjour {{ trigger.body.message.from.first_name }}, votre demande a été reçue.`
Format	Laisser vide pour du texte brut. Définir sur `HTML` pour `<b>gras</b>` / `<i>italique</i>`. Définir sur `MarkdownV2` pour du Markdown (les caractères spéciaux sont automatiquement échappés).
Disable Web Page Preview	Définir sur `true` pour supprimer les aperçus de liens
Message Thread ID	Optionnel — uniquement pertinent pour les supergroupes Forum
Reply Markup	Optionnel — un objet JSON pour les claviers en ligne ou les claviers de réponse personnalisés

Référencement de la sortie dans les étapes suivantes :

ID du message (requis pour Edit ou Delete plus tard) : {{ step.output.message_id }}
ID de discussion : {{ step.output.chat_id }}

Send Media

Envoie une photo, une vidéo, un sticker ou un GIF animé dans une discussion Telegram. Entrées principales :

Entrée	Description
Chat ID	La discussion destination
Media Type	Doit être exactement l’une des valeurs suivantes : `photo`, `video`, `sticker`, `animation`
Media URL	Une URL HTTPS publiquement accessible vers le fichier — Telegram le récupère directement
Media ID	Alternativement, un `file_id` Telegram d’un fichier précédemment téléchargé. Fournissez soit Media URL, soit Media ID, pas les deux.
Caption	Texte optionnel affiché sous le média. Prend en charge HTML/MarkdownV2 via Format.
Format	Mode d’analyse de la légende
Message Thread ID	Optionnel — pour les sujets de supergroupes Forum

Si ni Media URL ni Media ID n’est fourni, l’étape retourne une erreur. L’URL doit être publiquement accessible — les URLs locales ou privées ne fonctionneront pas.

Edit Message Text

Met à jour le texte d’un message précédemment envoyé par votre bot. Entrées principales :

Entrée	Description
Chat ID	La discussion contenant le message original
Message ID	Le `message_id` de la sortie de Send Text Message — `{{ step.output.message_id }}`
Text	Le nouveau contenu du message
Format	Mode d’analyse du nouveau texte (vide = texte brut, `HTML` ou `MarkdownV2`)

Exemple de cas d’utilisation : Envoyez d’abord « Traitement de votre demande… ». Exécutez la logique du workflow. Puis modifiez ce message avec le résultat final — l’utilisateur voit un seul message au lieu de deux.

Delete Message

Supprime un message d’une discussion. Entrées principales :

Entrée	Description
Chat ID	La discussion contenant le message
Message ID	Le `message_id` du message à supprimer

Les bots ne peuvent supprimer que leurs propres messages, sauf si le bot est administrateur dans la discussion. Telegram impose également une limite de temps — les messages de plus de 48 heures ne peuvent généralement pas être supprimés par les bots.

Actions de discussion et de membres

Get Chat Info

Récupère les métadonnées d’une discussion. Entrées principales :

Entrée	Description
Chat ID	La discussion à consulter

Référencement des valeurs dans les étapes suivantes :

Titre de la discussion : {{ step.output.title }}
Description : {{ step.output.description }}
Lien d’invitation : {{ step.output.invite_link }}

Get Chat Member

Recherche un utilisateur spécifique dans une discussion et retourne son statut de membre et son rôle. Entrées principales :

Entrée	Description
Chat ID	La discussion à consulter
User ID	L’ID utilisateur Telegram à rechercher. Pour la personne qui a déclenché le workflow, utilisez `{{ trigger.body.message.from.id }}`.

Référencement des valeurs dans les étapes suivantes :

Statut : {{ step.output.status }}
Nom d’utilisateur : {{ step.output.username }}

Valeurs de statut possibles : creator, administrator, member, restricted, left, kicked Exemple de cas d’utilisation : Vérifiez {{ step.output.status }} — s’il est égal à left ou kicked, ignorez l’envoi du message et gérez l’erreur à la place.

Create Invite Link

Génère un nouveau lien d’invitation pour un groupe ou une chaîne.

Le bot doit être administrateur avec la permission « Invite Users » dans la discussion cible.

Entrées principales :

Entrée	Description
Chat ID	Le groupe ou la chaîne
Name	Étiquette optionnelle pour le lien (jusqu’à 32 caractères), visible dans le panneau d’administration Telegram
Expire Date	Optionnel. Une chaîne ISO-8601 indiquant quand le lien expire, par ex. `2026-12-31T23:59:59Z`. Converti en timestamp unix en interne.
Member Limit	Optionnel. Nombre maximal de personnes pouvant rejoindre via ce lien (1–99 999)

Référencement du lien dans les étapes suivantes :

URL d’invitation : {{ step.output.invite_link }}

expire_date dans la sortie est un timestamp unix (entier en secondes), pas au format ISO. creates_join_request sera true si la discussion requiert l’approbation d’un administrateur pour les nouveaux membres.

Actions de configuration de webhook

Ces deux étapes connectent un déclencheur New Message à votre bot. Exécutez-les une seule fois par workflow.

Register Webhook

Indique à Telegram de commencer à transférer les messages de votre bot vers l’URL de votre workflow. Entrées principales :

Entrée	Description
URL	L’URL `/tool-webhook/{workflow-id}` du panneau du déclencheur New Message
Allowed Updates	Définir sur `["message"]` pour recevoir uniquement les messages réguliers (recommandé). Laisser vide pour utiliser la même valeur par défaut.
Secret Token	Optionnel mais recommandé. N’importe quelle chaîne aléatoire (par ex. `my-secret-abc123`). Telegram l’inclut dans l’en-tête de chaque requête webhook afin que vous puissiez vérifier que les requêtes sont authentiques.
Drop Pending Updates	Définir sur `true` pour ignorer les messages arrivés avant l’enregistrement du webhook

Copiez l'URL du déclencheur

Créez un workflow avec un déclencheur New Message. Copiez l’URL /tool-webhook/{workflow-id} depuis le panneau du déclencheur.

Ajoutez Register Webhook

Dans un workflow ponctuel séparé ou un test manuel, ajoutez une étape Register Webhook et remplissez les entrées ci-dessus.

Exécutez-le une seule fois

Exécutez l’étape. Puis envoyez un message à votre bot — votre workflow principal devrait désormais se déclencher.

Alternativement, enregistrez via curl pour une configuration rapide et ponctuelle :

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/tool-webhook/<YOUR_WORKFLOW_ID>",
    "allowed_updates": ["message"],
    "secret_token": "my-secret-abc123"
  }'

Réponse en cas de succès :

{ "ok": true, "result": true, "description": "Webhook was set" }

Un bot Telegram ne peut avoir qu’un seul webhook actif à la fois. L’enregistrement d’une nouvelle URL remplace la précédente.

Deregister Webhook

Supprime le webhook et arrête la livraison des messages de Telegram vers votre workflow. Entrées principales :

Entrée	Description
Drop Pending Updates	Définir sur `true` pour rejeter les messages mis en file d’attente pendant que le webhook était actif

Désenregistrez le webhook lorsque vous mettez fin à un workflow ou l’archivez. Si vous laissez le webhook enregistré mais le workflow inactif, Telegram continuera d’envoyer des requêtes restant sans réponse.

Dépannage

Symptôme	Cause probable	Solution
Le workflow ne se déclenche pas sur les nouveaux messages	Webhook non enregistré ou pointant vers la mauvaise URL	Exécutez Register Webhook avec l’URL de déclencheur correcte
`401 Unauthorized`	Token de bot invalide ou révoqué	Vérifiez le token ou générez-en un nouveau via @BotFather
Média non livré	L’URL n’est pas publiquement accessible	Utilisez une URL HTTPS publique — les URLs locales ou privées ne fonctionneront pas
Impossible de supprimer un message	Le message a plus de 48 heures, ou le bot n’est pas administrateur	Les bots ne peuvent supprimer que les messages récents sauf s’ils disposent de privilèges d’administration
`creates_join_request: true` sur le lien d’invitation	La discussion requiert l’approbation d’un administrateur pour les nouveaux membres	Il s’agit d’un comportement normal — les utilisateurs doivent être approuvés avant de pouvoir rejoindre
D’anciens messages déclenchent le workflow	Mises à jour en attente non vidées lors de l’enregistrement du webhook	Réenregistrez avec `Drop Pending Updates` défini sur `true`

Get Started!

Offerings

Chat

Agents

Knowledge Base

Workflows

Interfaces

Public Chatbot

Project Settings

My Account

Platform Admin

SDK

General Information

Prérequis

Étape 1 — Créer un bot Telegram

Étape 2 — Ajoutez le token à EK

Gestion de votre token

Outils disponibles

Trigger — New Message

Actions de messagerie

Send Text Message

Send Media

Edit Message Text

Delete Message

Actions de discussion et de membres

Get Chat Info

Get Chat Member

Create Invite Link

Actions de configuration de webhook

Register Webhook

Deregister Webhook

Dépannage

​Prérequis

​Étape 1 — Créer un bot Telegram

​Étape 2 — Ajoutez le token à EK

​Gestion de votre token

​Outils disponibles

​Trigger — New Message

​Actions de messagerie

​Send Text Message

​Send Media

​Edit Message Text

​Delete Message

​Actions de discussion et de membres

​Get Chat Info

​Get Chat Member

​Create Invite Link

​Actions de configuration de webhook

​Register Webhook

​Deregister Webhook

​Dépannage

Prérequis

Étape 1 — Créer un bot Telegram

Étape 2 — Ajoutez le token à EK

Gestion de votre token

Outils disponibles

Trigger — New Message

Actions de messagerie

Send Text Message

Send Media

Edit Message Text

Delete Message

Actions de discussion et de membres

Get Chat Info

Get Chat Member

Create Invite Link

Actions de configuration de webhook

Register Webhook

Deregister Webhook

Dépannage