Telegram: connect your own bot
Talk to Codumentor from your phone or desktop through a private Telegram bot.
Your Codumentor server must stay running and be able to reach Telegram; you do
not need a public server address or a webhook.
Before you start
You need a Telegram account and a working Codumentor instance with a model
configured. Telegram and User Secrets must be enabled, with Telegram in
per_user mode. The default plugin mode is technical_user (a shared bot),
so adding a personal token alone does not switch modes.
For Community, you administer your own instance. Ask the
configuration assistant:
Enable Telegram and User Secrets for my personal bot. Set Telegram to
per_user mode with periodic bot discovery and first-message owner binding.
Keep voice disabled for now. Show me the changes before applying them.
Review and approve the proposed configuration. If you manage configuration
manually, use the per-user configuration reference.
In a managed deployment, ask your administrator to enable this mode.
Security: Telegram turns automatically allow tool permission prompts;
global deny rules still apply. Do not expect the browser's approval dialog to
protect operations initiated from Telegram. The bot acts as your Codumentor
user, with your secrets and repository context. Keep it private.
1. Create a bot in Telegram
- Open @BotFather and send
/newbot. - Follow the prompts: choose a display name and a unique username ending in
bot. - Copy the bot token. Treat it as a password: do not paste it into a chat with the assistant, commit it, or share it.
2. Save the token in Codumentor
- Sign in to Codumentor as the account you want the bot to use.
- Open Settings → Extensions → User Secrets → Add.
- Use the name
telegram_bot_tokenand paste the token as its value. If your instance uses a differenttoken_secret_name, use that name instead. - Save. With periodic discovery, the bot is picked up at the next rescan (every 60 seconds by default); no server restart is needed.
3. Send the first message yourself
Open your new bot in Telegram and send a short text message **before sharing
its username**. With the default first-message owner binding (per_user_authz:), the first Telegram account to message the bot becomes its owner;
tofu
other accounts are rejected. Wait for Codumentor's reply.
To make sure nobody else can claim your bot, store your numeric Telegram user
ID (from @userinfobot) in the
telegram_allowed_ids user secret. Your bot then answers only that ID, even
if someone else messaged it first. If the secret holds no valid ID, the bot rejects everyone.
For a stricter setup, configure per_user_authz: allowlist before messaging
the bot. Store your numeric Telegram user ID in the telegram_allowed_ids
user secret (multiple IDs can be comma- or space-separated). You can find
your ID through @userinfobot. An empty allowlist
rejects everyone.
Everyday use and voice
Send text messages as you would in the browser. Each Telegram chat maps to a
Codumentor conversation. Wait for a reply before sending another request:
messages arriving while a turn is running are dropped with a “Still working”
notice. Refresh the browser to see Telegram updates in its transcript.
Send /new to start a fresh conversation; the old one stays in the browser.
A chat left idle for 30 days starts a new conversation by itself. /start,
which Telegram sends when you first open the bot, only gets a greeting.
Text works without a speech service. For voice notes, configure the shared
speech: service and enable Telegram's voice_reply; ask the configuration
assistant or follow the voice configuration reference
(English). Voice input then receives both a spoken reply and the full text.
If the bot does not reply
- Check that Codumentor is running, has a working model, and can reach Telegram.
- Wait for the discovery interval. With
bot_discovery: startup, restart the server after adding the token instead. - Check that Telegram is enabled in
per_usermode and the secret is saved under the correct Codumentor account and name. A shared bot uses a different setup; see the administrator reference. - If access is denied, check whether another Telegram account sent the first message, or whether the configured allowlist includes your numeric ID.
- If User Secrets is missing from Settings, check that the User Secrets plugin is enabled.
To disconnect your private bot, remove its telegram_bot_token secret (or the
custom name your instance uses). Periodic discovery stops it on the next
rescan. If the token is exposed, revoke it through @BotFather and store the
replacement in User Secrets.