Telegram

Connect a Telegram bot to ORQO so that Chief of Staff 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 Telegram in ORQO

1. Navigate to Settings → Integrations in ORQO.
2. Find the Telegram tile and click Install. ORQO creates the integration and adds the empty credentials below, already linked to it.

3. Add Credentials

1. Go to Settings → Credentials.
2. Fill in each value:

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

They're already linked to the Telegram integration, so you don't need to attach them manually.

4. Configure the Webhook

First, copy your Webhook URL: in Settings → Integrations, click the Telegram card and copy the Webhook URL field. It ends in a long per-organization token (not an app name or ID) — copy it whole.

Then register it with Telegram using the Bot API:

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

Replace:

• <YOUR_BOT_TOKEN> with your bot token from BotFather
• <PASTE_YOUR_ORQO_WEBHOOK_URL> with the full Webhook URL you copied from the Telegram card
• 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: choose Telegram as the app, and set the 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 Chief of Staff. 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. Chief of Staff 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.

Sending Files (Outbound)

Chief of Staff can send files through Telegram — documents and artifacts from a project's library, or files shared earlier in the conversation. Any file type is supported (up to ~50 MB): images, video, and audio are sent with inline previews, and everything else is delivered as a document with its original filename.

What's Next

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