Telegram Setup

Connect your CCCC working group to Telegram for mobile access.

Overview

Telegram is the easiest platform to set up. It's ideal for:

• Personal use
• Quick prototyping
• Individual developers

Prerequisites

• A Telegram account
• CCCC installed and running

Step 1: Create a Bot

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Choose a display name (e.g., "My CCCC Bot")
   • Choose a username (must end in bot, e.g., my_cccc_bot)
4. BotFather will give you a token like:

   123456789:ABCdefGHIjklMNOpqrsTUVwxyz

5. Save this token — you'll need it in the next step

Recommended: Disable Group Privacy

If you plan to use the bot in group chats, disable group privacy so the bot can see all messages:

1. Send /mybots to BotFather
2. Select your bot → Bot Settings → Group Privacy
3. Set to Disabled

The bot still stays silent on unrelated group traffic while the chat is unauthorized or paused. Use a bot command such as /subscribe or /resume, or explicitly @mention the bot, when you need feedback.

Step 2: Configure CCCC

Option A: Via Web UI (Recommended)

1. Open the CCCC Web UI at http://127.0.0.1:8848/
2. Go to Settings (gear icon in header)
3. Navigate to the IM Bridge tab
4. Select Telegram as the platform
5. Enter your bot token:
   • Paste the token directly (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
   • Or enter an environment variable name (e.g., TELEGRAM_BOT_TOKEN)
6. Click Save Config

Security Best Practice

For production use, store the token in an environment variable instead of pasting it directly:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export TELEGRAM_BOT_TOKEN="your-token-here"

Then enter TELEGRAM_BOT_TOKEN in the Web UI. Never commit tokens to git.

Option B: Via CLI

# Using environment variable name
cccc im set telegram --token-env TELEGRAM_BOT_TOKEN

# Verify configuration
cccc im config

Both methods save the configuration to your group's group.yaml:

im:
  platform: telegram
  token_env: TELEGRAM_BOT_TOKEN

Step 3: Start Bridge & Subscribe

Start the Bridge

Via Web UI: Click Save Config to save configuration, then click Start Bridge to start and show Running status.

Via CLI:

cccc im start

Verify it's running:

cccc im status

Authorize in Telegram

New chats must be authorized before they can use the bot:

1. Open Telegram and find your bot (search by username)
2. Start a chat with the bot
3. Send /subscribe — the bot replies with a one-time binding key:

   abc123xyz

4. Authorize the chat (choose one):
   • Web (recommended): Open CCCC Web → Settings → IM Bridge, find it in Pending Requests, and click Approve (or paste the key in Bind)
   • Foreman-assisted: If foreman is online, send the key to foreman and ask foreman to bind it
   • CLI: Run cccc im bind --key <key> on the server
5. Once authorized, the chat can immediately send and receive messages — no further commands needed

For group chats:

1. Add the bot to your group
2. Follow the same authorization flow above
3. All authorized chats receive messages from CCCC

Usage

Sending Messages to Agents

Telegram supports two ways to send messages:

In group chats — @mention the bot and type your message directly:

@YourBotName Please implement the login feature

Or use the explicit /send command:

@YourBotName /send @all Status update please

In direct messages — just type your message:

Please implement the login feature

Implicit Send

When you @mention the bot (in groups) or send a direct message, plain text is automatically treated as /send to the foreman. You only need the explicit /send command when targeting specific agents like @all or @peers.

Recognized CCCC commands such as /send, /status, and /subscribe may be sent in a group without @mentioning the bot. Commands for other bots or unknown integrations remain ignored unless the CCCC bot is explicitly addressed.

Targeting Specific Agents

Use @mention syntax with the /send command:

/send @foreman Please review the PR
/send @peer-1 Run the tests
/send @all Status update please

Receiving Messages

After authorization, you will automatically receive:

• Agent responses
• Status updates
• Error notifications

Use /verbose (or /verbose on) to receive agent-to-agent messages, and /verbose off to stop receiving them.

Agent output is updated progressively in one Telegram message when possible. Completed replies longer than Telegram's single-message limit are delivered in lossless 4,096-character chunks. Topic subscriptions retain message_thread_id, so replies and outbound files stay in the topic where /subscribe was approved.

File Attachments

Attach files to your message. They're downloaded and stored in CCCC's blob storage, then forwarded to agents. Agent-generated images and files are also uploaded back to every authorized Telegram target.

Commands Reference

Command	Description
/subscribe	Start authorization flow — generates a one-time binding key
/unsubscribe	Stop receiving messages
/send <message>	Send to foreman (default)
/send @<actor> <message>	Send to a specific agent
/send @all <message>	Send to all agents
/send @peers <message>	Send to non-foreman agents
/status	Show group and agent status
/pause	Pause delivery for this chat or topic
/resume	Resume delivery for this chat or topic
/verbose [on|off]	Enable verbose delivery, or disable it with off
/help	Show available commands

Troubleshooting

Bot not responding

1. Check if the bridge is running:

   cccc im status

2. Check logs for errors:

   cccc im logs -f

3. Verify token is correct — re-check with BotFather (/mybots → select bot → API Token)

"Unauthorized" error

Your token is invalid. Get a new one from BotFather:

1. Send /mybots to BotFather
2. Select your bot
3. Click API Token → Revoke current token
4. Update your token in CCCC Settings (Web UI) or environment variable

Messages not delivered

1. Ensure the chat is authorized (run /subscribe → bind the key via Web, foreman-assisted bind, or CLI)
2. Check that the CCCC daemon is running
3. Verify the bridge status in Web UI or via cccc im status

Rate limiting

Telegram has rate limits. If you're sending many messages:

• Messages may be delayed
• Use /verbose off to disable verbose mode and reduce traffic

Security Notes

• Keep your bot token secret
• Consider enabling 2FA on your Telegram account
• Review who has access to chats where the bot is subscribed
• The bot can see all messages in groups where it's added
• New chats require key-based authorization before they can interact with the bot — send /subscribe to generate a one-time key, then confirm it from the server side (Web Settings > IM Bridge, foreman-assisted bind, or CLI); once bound, the chat is fully authorized
• Binding keys expire after 10 minutes; generate a new one with /subscribe if it lapses
• The bind operation must be performed via CCCC Web Settings (IM Bridge), foreman-assisted bind, or cccc im bind --key on the server — Telegram users cannot self-authorize