Telegram

Connect a Telegram bot to ORQO so that Doorkeeper can receive and respond to messages in private chats, groups, and channels.

Category	Communication
Capabilities	Send + Receive
Adapter path	/telegram
Auth method	Bot token

Prerequisites

• A Telegram account
• Access to the ORQO Settings area

Setup

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. BotFather responds with a bot token — a long string like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz. Save this securely.

tip

You can customize your bot's profile picture, description, and about text through BotFather using /setuserpic, /setdescription, and /setabouttext.

2. Install the Telegram App in ORQO

1. Navigate to Settings > Apps in ORQO.
2. Find Telegram in the app catalog and click Install.
3. The app is created with the correct adapter URL and capabilities.

3. Add Credentials

After installation, the credentials checklist shows what's required:

Credential	Type	Description
TELEGRAM_BOT_TOKEN	api_key	The bot token from BotFather
TELEGRAM_WEBHOOK_SECRET	api_key	A secret string you choose for webhook verification (optional but recommended)

Create these credentials in Settings > Credentials, then assign them to the Telegram App. The credential dropdown is filtered to show only relevant credentials.

4. Configure the Webhook

Set the webhook URL using the Telegram Bot API. You can do this with a simple curl command:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-orqo-domain.com/api/v1/webhooks/:app_id",
    "secret_token": "your-webhook-secret"
  }'

Replace:

• <YOUR_BOT_TOKEN> with your bot token from BotFather
• :app_id with the App ID shown on the Telegram app card in ORQO
• your-webhook-secret with the same value you stored as TELEGRAM_WEBHOOK_SECRET

The secret_token is sent by Telegram in the X-Telegram-Bot-Api-Secret-Token header on every webhook request, and ORQO verifies it.

5. Add Contacts

For each person who should be able to message ORQO through Telegram:

1. Go to Settings > Contacts and create a Contact.
2. Add a Contact Channel linked to the Telegram App.
3. Set the channel address to the person's Telegram user ID (a numeric ID, e.g., 123456789).

tip

To find a Telegram user ID, have the person message your bot. The user ID appears in the webhook payload. You can also use bots like @userinfobot.

warning

Only registered Contacts can interact with Doorkeeper. Messages from unknown Telegram users are silently rejected.

6. Verify the Connection

Click Verify on the Telegram app card in ORQO. This tests the connection to the adapter.

Send a message to your Telegram bot from a registered Contact. Doorkeeper should respond.

Available Tools

The Telegram adapter exposes MCP tools that agents can use in workflows:

Tool	Description
send_telegram_message	Send a message to a Telegram chat
get_telegram_chat	Get information about a Telegram chat

These tools are discovered automatically when the App is verified and can be assigned to agents via Skills.

Platform-Specific Behavior

• Private chats — One-on-one conversations with the bot work like any messaging platform.
• Groups — Add the bot to a group to receive messages. The bot responds to messages that mention it or to all messages, depending on its privacy mode setting in BotFather (/setprivacy).
• Channels — The bot can post to channels where it is an admin.
• Signature verification — Every inbound webhook is verified via the X-Telegram-Bot-Api-Secret-Token header.
• Session reset — Send reset, new session, clear session, or start over to clear the conversation and start fresh.

What's Next

• Apps & Channels for the full architecture
• Configure Webhooks for detailed webhook setup
• Doorkeeper AI to understand what Doorkeeper can do