Overview
The Telegram integration lets you deploy Nadoo AI agents as Telegram bots. Users interact through private chats, group chats, and inline commands. The integration supports inline keyboards, file attachments, location sharing, and rich media messages.
Setup
Create a Bot via BotFather
- Open Telegram and search for @BotFather.
- Send the
/newbot command.
- Follow the prompts:
- Enter a display name for your bot (e.g., “Nadoo AI Agent”)
- Enter a username for your bot (must end in
bot, e.g., nadoo_ai_agent_bot)
- BotFather will reply with your Bot Token (a string like
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11). Copy and save it securely.
Configure Bot Settings (Optional)
While still in the BotFather chat, you can configure additional settings:| Command | Purpose |
|---|
/setdescription | Set the bot’s description shown in its profile |
/setabouttext | Set the “About” text shown when users view bot info |
/setuserpic | Upload a profile picture for the bot |
/setcommands | Define the command menu (see below) |
/setcommands to BotFather, select your bot, and enter commands in this format:start - Start a conversation with the agent
ask - Ask a question
search - Search the knowledge base
help - Show available commands
Configure in Nadoo AI
In the Nadoo AI platform:
- Navigate to your workspace and open Channels.
- Click Add Channel and select Telegram.
- Enter the following:
| Field | Value |
|---|
| Bot Token | The token from BotFather |
| Workflow | Select the workflow to handle Telegram messages |
- Click Save and toggle the channel to Active.
Nadoo AI automatically registers the webhook URL with Telegram using the Bot API’s setWebhook method. No manual webhook configuration is required. Test the Integration
Open Telegram, search for your bot by its username, and send /start or a test message. The bot should respond using the configured workflow.
Webhook Configuration
When you activate the Telegram channel in Nadoo AI, the platform automatically calls the Telegram setWebhook API to register the webhook URL:
POST https://api.telegram.org/bot{token}/setWebhook
{
"url": "https://your-instance.example.com/api/v1/webhooks/handle/telegram",
"allowed_updates": ["message", "callback_query", "inline_query"]
}
Webhook Details
| Setting | Value |
|---|
| Endpoint | POST /api/v1/webhooks/handle/telegram |
| Verification | Telegram sends updates only to the registered URL. Nadoo AI validates the request source. |
| Secret Token | An optional secret token is set during webhook registration and verified in the X-Telegram-Bot-Api-Secret-Token header. |
| Auto-registration | Webhook is registered automatically when the channel is activated. |
If you need to change the webhook URL (e.g., after a domain change), deactivate and reactivate the Telegram channel in Nadoo AI. The platform will re-register the webhook with the new URL.
Supported Features
Message Types
| Feature | Description |
|---|
| Text messages | Standard text messages in private and group chats |
| Bot commands | Messages starting with / (e.g., /ask, /search) |
| Replies | Users can reply to bot messages to continue a conversation thread |
| Group chats | The bot responds when mentioned or when commands are used in group chats |
| Forwarded messages | Users can forward messages to the bot for processing |
Interactive Keyboards
Telegram supports two types of keyboards for interactive responses.
Inline Keyboards
Reply Keyboards
Inline keyboards appear directly below a bot message and allow users to interact without typing.{
"reply_markup": {
"inline_keyboard": [
[
{ "text": "Yes", "callback_data": "confirm_yes" },
{ "text": "No", "callback_data": "confirm_no" }
],
[
{ "text": "Learn More", "url": "https://docs.example.com" }
]
]
}
}
callback_query update to the webhook. The workflow receives the callback_data value and can branch accordingly. Reply keyboards replace the user’s default keyboard with predefined response options.{
"reply_markup": {
"keyboard": [
[{ "text": "Check order status" }, { "text": "Contact support" }],
[{ "text": "Browse products" }]
],
"resize_keyboard": true,
"one_time_keyboard": true
}
}
File Attachments
| Feature | Description |
|---|
| Photo messages | Users can send photos. The bot can process images using multimodal AI models. |
| Document messages | Users can send files (PDF, DOCX, etc.) for processing by the knowledge base. |
| Voice messages | Users can send voice recordings. The bot can transcribe audio using STT. |
| Location sharing | Users can share their location. The bot receives coordinates. |
| Contact sharing | Users can share contact cards. |
Bot Responses
| Feature | Description |
|---|
| Text with Markdown | Responses support Telegram’s MarkdownV2 formatting |
| Photos | The bot can send images as responses |
| Documents | The bot can send files (reports, exports) |
| Typing indicator | The bot shows “typing…” while processing the request |
Bot Commands
Define the commands that appear in Telegram’s command menu. Users can tap the / button to see available commands.
Recommended Commands
| Command | Description |
|---|
/start | Begin a conversation with the bot |
/help | Show available commands and usage instructions |
/ask [question] | Ask the AI agent a question |
/search [query] | Search the knowledge base |
/reset | Clear conversation history and start fresh |
Command Handling
Commands are detected by the Telegram adapter and routed to the configured workflow. The command name and arguments are passed as structured input:
{
"command": "ask",
"arguments": "How does the refund policy work?",
"user_id": "123456789",
"chat_id": "987654321",
"chat_type": "private"
}
Group Chat Configuration
When used in group chats, the bot can be configured to respond only to specific triggers.
| Mode | Behavior |
|---|
| Mention only | Bot responds only when mentioned by @username |
| Command only | Bot responds only to / commands |
| All messages | Bot responds to every message in the group (use with caution) |
{
"group_mode": "mention_only",
"privacy_mode": true
}
Set privacy_mode: true (the default) so the bot only receives messages that are directly addressed to it in group chats. This reduces unnecessary processing and respects user privacy.
Troubleshooting
| Issue | Solution |
|---|
| Bot does not respond | Verify the bot token is correct and the channel is Active in Nadoo AI |
| Webhook registration failed | Check that your Nadoo AI instance is accessible via HTTPS with a valid SSL certificate. Telegram requires HTTPS for webhooks. |
| Bot responds in private but not in groups | Enable group mode and ensure the bot has been added to the group. Check privacy_mode settings. |
| Keyboard buttons not working | Verify that callback_data values are being handled in your workflow’s condition nodes |
Next Steps
