# Telegram setup

Use Telegram when you want a published workflow to answer messages sent to a Telegram bot. The recommended starting point is the workflow preview embedded on this page.

## What the sample does

The sample builds this flow:

1. **Telegram Webhook** receives Telegram updates on `POST /telegram/updates`.
2. **Telegram Reply Agent** reads `event.body.message.text` and writes the reply text.
3. **Load Telegram bot token** loads the private `TELEGRAM_BOT_TOKEN` deployment secret.
4. **Send Telegram reply** calls Telegram Bot API `sendMessage`.
5. **Acknowledge Telegram** returns `{"ok": true}` to the webhook.

Only one **Respond webhook** node is used. Telegram gets the HTTP acknowledgement from that node, while the actual user reply is sent by the HTTP request node.

## Prerequisites

- A Telegram bot token created with BotFather.
- Your production AgentBuilder HTTPS backend URL.
- The workflow imported, saved, and published.
- A webhook secret value that only AgentBuilder and Telegram know.

## Create the Telegram bot

1. Open Telegram and search for **@BotFather**.
2. Start the chat and send `/newbot`.
3. Choose the display name users will see, for example `Support Assistant`.
4. Choose a unique username ending in `bot`, for example `acme_support_bot`.
5. Copy the token returned by BotFather and store it securely. Treat it like a password.
6. Optional: use `/setdescription`, `/setabouttext`, and `/setuserpic` in BotFather to make the bot profile clear for users.

Use that token as the value of the AgentBuilder deployment secret `TELEGRAM_BOT_TOKEN`.

## Use the workflow from this page

The workflow preview below can create a copy in your workspace. Click **Open in editor**, save the workflow, then publish or activate it before testing from Telegram.

The sample assumes the workflow public id is available in the final webhook URL:

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

## Configure secrets

Create a deployment secret named:

```text
TELEGRAM_BOT_TOKEN
```

Its value is the bot token from BotFather. Do not paste the token directly into the HTTP Request node URL. The sample uses:

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

Then configure the Telegram webhook trigger node:

| Field | Value |
| ----- | ----- |
| Method | `POST` |
| Path | `/telegram/updates` |
| Auth type | `Header` |
| Header name | `X-Telegram-Bot-Api-Secret-Token` |
| Header secret | Your webhook secret, for example `replace-with-a-random-secret` |
| Response mode | `Respond node` |

## Register the webhook in Telegram

Set these environment variables locally before running the command:

```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'
```

Register the 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\"]
  }"
```

Check what Telegram has stored:

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

## Test without Telegram

You can simulate a Telegram update before messaging the 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"
    }
  }'
```

A correct webhook acknowledgement returns:

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

The simulated `chat.id` is not a real Telegram chat, so the downstream `sendMessage` call may fail unless you use a real chat id. For the full test, send a message directly to your bot in Telegram.

## Update the bot after editing

After changing the workflow, save and publish it again. You do not need to run `setWebhook` again unless the public backend URL, webhook path, or workflow public id changed.

## Troubleshooting

| Symptom | Check |
| ------- | ----- |
| Telegram does not call AgentBuilder | `getWebhookInfo` has the expected HTTPS URL and zero or explainable pending updates |
| Webhook returns `401` | The trigger header secret matches the `secret_token` used in `setWebhook` |
| Webhook returns `404` | The workflow public id and path in the URL are correct |
| Webhook returns `405` | You opened the webhook URL with GET; Telegram uses POST |
| Telegram receives no reply | The workflow is published, `TELEGRAM_BOT_TOKEN` exists, and the HTTP Request node points to `sendMessage` |
| Reply generation fails | Check the Agent node model/API configuration and production run logs |

---

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