Telegram integration lets your Narakim bots receive messages and commands from Telegram users, and take actions like sending messages, photos, and documents. Telegram setup is simpler than Discord or Slack — you only need a single token from @BotFather.
Prerequisites
- Open Telegram and search for @BotFather.
- Send
/newbotand follow the prompts to name your bot and choose a username. - BotFather will give you an API Token in the format
123456789:ABCdef.... Copy it.
That's it — no app registration, no portal, no OAuth scopes.
Connecting Telegram
- Go to Bot Dossier → Configurations → Connect Platform.
- Select Telegram from the platform list.
- Select integration level Bot Level.
- Enter your Bot Token from @BotFather.
- Click Connect.
Narakim will register a webhook with Telegram and verify the connection. Once connected, all Telegram extensions appear in your bot's Node Palette.
Integration Level: Telegram connections use Bot Level — the automation operates as your Telegram bot's identity, a completely separate account from you. Account Level integration (operating as your personal Telegram account) is coming soon.
Trigger Extensions
| Studio name | Extension key | Fires when | Key outputs |
|---|---|---|---|
| Message | telegram_message | User sends a message | text, from, chat, message_id, date |
| Command | telegram_command | /command with optional args | command, args, from, chat, message_id |
| Callback Query | telegram_callback_query | Inline keyboard button pressed | data, from, message, callback_query_id |
| Inline Query | telegram_inline_query | User queries bot in inline mode | query, from, inline_query_id |
| Chat Member Updated | telegram_chat_member_updated | Member join/leave/promote | member update payload |
| Message Reaction | telegram_message_reaction | Reaction on a message | reaction payload |
| Chat Join Request | telegram_chat_join_request | User requests to join | join request payload |
Action Extensions
| Studio name | Extension key | Description |
|---|---|---|
| Send Message | telegram_send_message | Text to chatId (use chat.id from trigger) |
| Send Photo | telegram_send_photo | Photo + optional caption |
| Send Document | telegram_send_document | File/document upload |
| Edit Message | telegram_edit_message | Edit by chatId + messageId |
| Delete Message | telegram_delete_message | Delete by chatId + messageId |
| Answer Callback Query | telegram_answer_callback_query | Required after callback — dismisses loading spinner |
| Send Inline Keyboard | telegram_send_inline_keyboard | Message with inline keyboard buttons |
| Ban User | telegram_ban_user | Ban from chat |
| Unban User | telegram_unban_user | Remove ban |
| Restrict Member | telegram_restrict_member | Limit member permissions |
| Pin Message | telegram_pin_message | Pin in chat |
| Unpin Message | telegram_unpin_message | Unpin |
| Get Chat Member Count | telegram_get_chat_member_count | Member count for chat |
Full catalog for AI agents: platform-extensions-reference.md (Telegram section).
Required Secrets
| Secret Key | Description |
|---|---|
TELEGRAM_BOT_TOKEN | Your bot token from @BotFather (123456789:ABCdef...) |
Configure this in Bot Dossier → Configurations → Extension Secrets.
Common Patterns
Command → AI → Reply
[Command Trigger (/ask)] → [OpenRouter AI] → [Send Message]
Map args from the Command trigger to the AI's message input. Map the AI's response to Send Message's text. Use chat.id from the trigger for the chatId.
Message → If Condition → Different Responses
[Message] → [If Condition: text contains "hello"] → [Send Message: "Hi there!"]
→ [Send Message: "I didn't understand that."]
Inline Button → Acknowledge → Action
[Callback Query] → [Answer Callback Query] → [Send Message]
Always call Answer Callback Query immediately to dismiss the loading spinner on the button. Then send your follow-up message.
Tips
- Commands vs. Messages: Use the Command trigger for
/slashcommands and the Message trigger for free-form text. chat.idvs.from.id: Usechat.idto reply in the same conversation. Usefrom.idto send a private message to the user.- Inline keyboards: Set up inline keyboard buttons in the Send Message action's
reply_markupconfig to enable Callback Query triggers. - Webhook vs. Polling: Narakim uses webhooks (not polling) for Telegram. Ensure your server is accessible at the public webhook URL shown in the platform connection settings.