Connect Cue to Telegram

Use Telegram when you want the fastest DM-first setup for talking to your assistant from macOS or iPhone.

Before You Start

• You need a Telegram account and access to @BotFather.
• Cue Telegram runtime currently runs in the background worker for the target agent.
• For first-time setup, start with DMs. Group setup is possible, but DM validation is shorter and easier to debug.

Fastest Setup

Replace <agent> with the agent you actually run.

If you already use a local dev agent such as main-localhost, use that same agent here.

export TELEGRAM_BOT_TOKEN='<BOT_TOKEN>'

cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy open \
  --json

cue --agent <agent> client restart --json
cue --agent <agent> telegram status --validate --json
cue --agent <agent> channel status --provider telegram --json

What you want to see:

• telegram status shows enabled: true
• channel status shows Telegram running: true

Step 1: Create the Bot

In Telegram:

1. Open @BotFather.
2. Run /newbot.
3. Pick a display name and username.
4. Copy the bot token.

Treat the token like a password. Do not commit it or paste it into public docs.

Step 2: Configure Cue

The command above is the recommended setup path because it:

• validates the bot token with Telegram
• writes agent-scoped config
• stores the env var name, not the raw token

Non-Interactive CLI

Fastest first test:

cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy open \
  --json

Safer DM allowlist setup:

cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy allowlist \
  --dm-user <YOUR_TELEGRAM_USER_ID> \
  --json

Useful follow-up commands:

cue --agent <agent> telegram status --validate --json
cue --agent <agent> channel status --provider telegram --json
cue --agent <agent> client restart --json
cue --agent <agent> telegram disable --json

Equivalent agent.json

If you prefer to inspect or edit the config directly, Cue writes agent-scoped config into ~/.cue/agents/<agent>/agent.json.

Open DM test setup:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "account": {
        "botTokenEnv": "TELEGRAM_BOT_TOKEN"
      },
      "dm": {
        "policy": "open"
      }
    }
  }
}

Safer allowlist setup:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "account": {
        "botTokenEnv": "TELEGRAM_BOT_TOKEN"
      },
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["<YOUR_TELEGRAM_USER_ID>"]
      }
    }
  }
}

Important: enabled: true alone is not enough. dm.policy and group.policy default to disabled unless you set them.

Step 3: Send the First DM

Telegram bots cannot message you first.

You must open the bot chat yourself:

https://t.me/<bot_username>

Then:

1. Tap Start
2. Send hello

If Telegram search does not find the bot, the direct t.me link is the reliable path.

Step 4: Validate the Runtime

Use these checks:

cue --agent <agent> telegram status --validate --json
cue --agent <agent> channel status --provider telegram --json

Optional outbound test:

1. Send one DM to the bot first.
2. Read the chat id from Telegram:

curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates"

3. Look for message.chat.id, then send a test message:

cue --agent <agent> channel send --provider telegram --to <CHAT_ID> --text "telegram outbound test" --json

Group Setup

Start with DMs first. When that works:

1. Add the bot to a Telegram group
2. Enable group policy
3. Restart the worker

cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy allowlist \
  --dm-user <YOUR_TELEGRAM_USER_ID> \
  --group-policy open \
  --json

cue --agent <agent> client restart --json

By default, Cue requires group activation by:

• mentioning the bot with @botusername, or
• replying to one of the bot's messages

Troubleshooting

• channel status says the worker is unavailable: Run cue --agent <agent> client restart --json. If it still fails, check cue --agent <agent> auth --json. Backend-connected agents need valid auth before the channel runtime can start.
• telegram status looks right but channel status is not running: The config is saved, but the background worker has not restarted with it yet.
• channel status briefly shows runtime_not_initialized right after restart: Wait a moment and run cue --agent <agent> channel status --provider telegram --json again. The worker may still be starting the provider runtime.
• Bot exists but you cannot message it: Open the direct https://t.me/<bot_username> link and tap Start.
• Another tool already uses the same token: Telegram long polling and webhooks cannot both own the same bot token at the same time. Use one consumer only.
• DMs work but groups do not: Check group.policy and make sure you mentioned the bot or replied to a bot message.