Telegram

Connects a Telegram bot to an agent flow. Unlike the Twilio channels, the webhook is registered with Telegram automatically. There's nothing to paste into a provider console.

1. Prerequisites

One value to collect

1. Bot token from @BotFather

In the Telegram app, message @BotFather and send /newbot. Follow its prompts (bot name, then a unique username ending in bot). BotFather replies with the token, formatted like 123456789:ABCdefGhIJKlmNoPQRsTUVwXYZ.

2. Configuration

Three console routes:

Route	Purpose
/channels/telegram	List the organization's Telegram bots
/channels/telegram/create	Connect a bot
/channels/telegram/{id}/edit	Reconfigure or disable it

Create

/channels/telegram/create is one card, two fields:

Field	Required	Placeholder
Bot Token	Yes	123456789:ABCdefGhIJKlmNoPQRsTUVwXYZ
Agent Flow	Yes	Select an agent flow

If the org has no agent flows, an inline warning replaces normal validation and links to Create an Agent Flow (/agent-builder/create); the Connect Bot button is disabled until at least one flow exists.

Clicking Connect Bot validates client-side ("Bot Token is required.", "Agent Flow is required."), then calls POST /channels/telegram/integrations. Server-side this is where the real work happens: NeuraFlow calls Telegram's getMe to validate the token and read the bot's username/display name, generates a random webhook secret, saves the integration, then calls Telegram's setWebhook with {BASE_URL}/api/v1/webhooks/channels/telegram/{integration_id} and that secret. An invalid token fails the whole request with "Invalid Telegram bot token. Could not reach Telegram Bot API." (or "...getMe returned an error." if Telegram responds but rejects the token) before anything is saved. On success the console toasts "Telegram bot connected successfully!" and navigates to the edit page; on failure it toasts "Failed to connect Telegram bot" with the server's detail as the description.

Edit

/channels/telegram/{id}/edit has three cards, no tabs.

Status: Bot Enabled toggle, folded into the same Save Changes call as Configuration below. Off means the bot stops responding without disconnecting it from Telegram.

Bot Information, both fields read-only, disabled inputs sourced from the stored getMe result, not re-fetched on this page: Bot Name, Username (rendered with a leading @).

Configuration:

Field	Required	Notes
Agent Flow	Yes
Bot Token	No	Always loads blank. Leave blank to keep the current bot. Filling it in and saving re-validates via getMe, generates a new webhook secret, calls deleteWebhook on the old token and setWebhook again on the new one, and refreshes Bot Name/Username from the new bot's getMe response

Save Changes validates only "Agent Flow is required." client-side (Bot Token is optional here, unlike create), then calls PUT /channels/telegram/integrations/{id}, omitting bot_token from the request if it's still blank. On success it toasts "Bot configuration saved successfully." and clears the Bot Token field. On failure it toasts "Failed to save configuration." with the server's detail as the description.

Deleting the integration (from the list page, not this screen) calls deleteWebhook first, so Telegram stops sending updates before the row is removed.

3. Other

Each bot's webhook secret is checked against the X-Telegram-Bot-Api-Secret-Token header on every update. A mismatch is logged and the request is acknowledged with 200 OK anyway (Telegram retries non-200 responses), so a misconfigured secret fails silently from Telegram's side. Check the server logs.