# Setup Telegram

Utilisez Telegram quand vous voulez qu'un workflow publié réponde aux messages envoyés à un bot Telegram. Le meilleur point de départ est le preview workflow intégré dans cette page.

## Ce que fait l'exemple

L'exemple construit ce flow :

1. **Telegram Webhook** reçoit les updates Telegram sur `POST /telegram/updates`.
2. **Telegram Reply Agent** lit `event.body.message.text` et génère le texte de réponse.
3. **Load Telegram bot token** charge le secret privé de déploiement `TELEGRAM_BOT_TOKEN`.
4. **Send Telegram reply** appelle `sendMessage` de la Telegram Bot API.
5. **Acknowledge Telegram** retourne `{"ok": true}` au webhook.

Il n'y a qu'un seul nœud **Respond webhook**. Telegram reçoit l'accusé HTTP depuis ce nœud, tandis que la vraie réponse utilisateur est envoyée par le nœud HTTP request.

## Prérequis

- Un token de bot Telegram créé avec BotFather.
- L'URL HTTPS du backend AgentBuilder en production.
- Le workflow importé, sauvegardé et publié.
- Un secret webhook connu uniquement par AgentBuilder et Telegram.

## Créer le bot Telegram

1. Ouvrez Telegram et cherchez **@BotFather**.
2. Lancez la conversation et envoyez `/newbot`.
3. Choisissez le nom visible par les utilisateurs, par exemple `Support Assistant`.
4. Choisissez un username unique qui se termine par `bot`, par exemple `acme_support_bot`.
5. Copiez le token retourné par BotFather et stockez-le de manière sécurisée. Traitez-le comme un mot de passe.
6. Optionnel : utilisez `/setdescription`, `/setabouttext` et `/setuserpic` dans BotFather pour rendre le profil du bot plus clair pour les utilisateurs.

Utilisez ce token comme valeur du secret de déploiement AgentBuilder `TELEGRAM_BOT_TOKEN`.

## Utiliser le workflow depuis cette page

Le preview workflow ci-dessous peut créer une copie dans votre workspace. Cliquez sur **Ouvrir dans l'éditeur**, sauvegardez le workflow, puis publiez ou activez-le avant de tester depuis Telegram.

L'exemple suppose que l'id public du workflow est utilisé dans l'URL finale du webhook :

```text
https://<backend-public-url>/api/v1/wh/<workflow_public_id>/telegram/updates
```

## Configurer les secrets

Créez un secret de déploiement nommé :

```text
TELEGRAM_BOT_TOKEN
```

Sa valeur est le token fourni par BotFather. Ne collez pas le token directement dans l'URL du nœud HTTP Request. L'exemple utilise :

```text
https://api.telegram.org/bot{secret.telegram_bot_token}/sendMessage
```

Configurez ensuite le nœud trigger Telegram Webhook :

| Champ | Valeur |
| ----- | ------ |
| Method | `POST` |
| Path | `/telegram/updates` |
| Auth type | `Header` |
| Header name | `X-Telegram-Bot-Api-Secret-Token` |
| Header secret | Votre secret webhook, par exemple `replace-with-a-random-secret` |
| Response mode | `Respond node` |

## Enregistrer le webhook dans Telegram

Définissez ces variables d'environnement localement avant d'exécuter la commande :

```bash
export TELEGRAM_BOT_TOKEN='replace-with-your-bot-token'
export TELEGRAM_WEBHOOK_SECRET='replace-with-a-random-secret'
export TELEGRAM_WEBHOOK_URL='https://<backend-public-url>/api/v1/wh/<workflow_public_id>/telegram/updates'
```

Enregistrez le webhook :

```bash
curl -fsS -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -H 'Content-Type: application/json' \
  -d "{
    \"url\": \"${TELEGRAM_WEBHOOK_URL}\",
    \"secret_token\": \"${TELEGRAM_WEBHOOK_SECRET}\",
    \"allowed_updates\": [\"message\", \"edited_message\"]
  }"
```

Vérifiez ce que Telegram a enregistré :

```bash
curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"
```

## Tester sans Telegram

Vous pouvez simuler un update Telegram avant d'envoyer un vrai message au bot :

```bash
curl -fsS -X POST "$TELEGRAM_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "X-Telegram-Bot-Api-Secret-Token: ${TELEGRAM_WEBHOOK_SECRET}" \
  -d '{
    "update_id": 999002,
    "message": {
      "message_id": 1,
      "chat": { "id": 123456, "type": "private" },
      "from": { "id": 123456, "is_bot": false, "first_name": "Test" },
      "date": 1783330000,
      "text": "ping"
    }
  }'
```

Un accusé webhook correct retourne :

```json
{"ok": true}
```

Le `chat.id` simulé n'est pas un vrai chat Telegram, donc l'appel `sendMessage` en aval peut échouer si vous n'utilisez pas un vrai chat id. Pour le test complet, envoyez un message directement à votre bot dans Telegram.

## Redémarrer après modification

Après une modification du workflow, sauvegardez puis publiez à nouveau. Vous n'avez pas besoin de relancer `setWebhook` sauf si l'URL publique du backend, le path webhook ou l'id public du workflow a changé.

## Dépannage

| Symptôme | À vérifier |
| -------- | ---------- |
| Telegram n'appelle pas AgentBuilder | `getWebhookInfo` contient la bonne URL HTTPS et un nombre d'updates en attente nul ou explicable |
| Le webhook retourne `401` | Le secret du header trigger correspond au `secret_token` utilisé dans `setWebhook` |
| Le webhook retourne `404` | L'id public du workflow et le path dans l'URL sont corrects |
| Le webhook retourne `405` | Vous avez ouvert l'URL webhook en GET ; Telegram utilise POST |
| Telegram ne reçoit aucune réponse | Le workflow est publié, `TELEGRAM_BOT_TOKEN` existe, et le nœud HTTP Request pointe vers `sendMessage` |
| La génération de réponse échoue | Vérifiez la configuration modèle/API du nœud Agent et les logs de run en production |

---

*Source: https://agentbuilder.systalink.sn/docs/telegram — human documentation.*
*Other language: [/docs-md/en/telegram.md](/docs-md/en/telegram.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*