Hexabot Telegram Channel Extension

hexabot-channel-telegram adds webhook-based Telegram Bot API support to Hexabot v3. The channel is registered as telegram and is discovered after the app is built because Hexabot scans dist/extensions/channels/**/*.channel.js.

Features

• Telegram webhook verification with X-Telegram-Bot-Api-Secret-Token.
• Inbound private chat text, commands, callback query buttons, locations, and common media attachments.
• Group and supergroup gating by bot command or @botUsername mention.
• Outbound text, inline quick replies, postback buttons, URL buttons, attachments, lists, and carousels.
• Attachment download through Telegram getFile.
• Optional auto-webhook setup for active sources.
• Typing indicators through sendChatAction.

Setup

1. Create a bot with Telegram @BotFather and copy the bot token.
2. Create two Hexabot credentials:
   • one for the bot token;
   • one for a random webhook secret token.
3. Create a Hexabot source with channel telegram.
4. Set bot_token and webhook_secret_token to the credential IDs.
5. Use this webhook URL in Telegram:

https://<your-domain>/api/webhook/<sourceId>

For local development, expose the API with an HTTPS tunnel and set API_ORIGIN to the public API URL if you want auto_set_webhook to configure Telegram for you.

Source Settings

• bot_token: credential containing the Telegram bot token.
• webhook_secret_token: credential containing the value Telegram must send in X-Telegram-Bot-Api-Secret-Token.
• allowed_chat_ids: optional comma-separated Telegram chat IDs.
• enable_private_chats: enables private conversations.
• enable_group_mentions: enables group/supergroup messages that target the bot.
• auto_set_webhook: calls setWebhook from the active source lifecycle.
• drop_pending_updates: passed to Telegram when auto-setting or deleting the webhook.
• thread_inactivity_hours: Hexabot v3 thread rollover window.

Groups

In groups and supergroups, the channel ignores ambient traffic. A message is processed only when it starts with a bot command, uses /command@botUsername, or mentions @botUsername. The mention is stripped before the message reaches the workflow.

Supported Messages

Inbound:

• text and commands;
• callback query data from inline keyboards;
• locations;
• photo, document, audio, video, voice, animation, sticker, and video note attachments.

Outbound:

• text via sendMessage;
• quick replies and postback buttons via inline keyboard callback_data;
• URL buttons via inline keyboard url;
• image, audio, video, and document attachments by public URL;
• lists and carousels as one message per item with inline keyboard buttons.

Limitations

• Long polling is not implemented.
• Business messages, inline mode, payments, polls, chat-member updates, and custom reply keyboards are out of scope for this first version.
• Telegram callback_data is limited to 64 bytes; oversized payloads are rejected.