woltspace-setup-telegram

Telegram Bot Setup

Guide the human through connecting a Telegram bot to their wolt. Step by step, one at a time.

The bot code is baked into the woltspace platform — no code to write. Just config.

This skill is idempotent — safe to run again. If things are already configured, validate and skip.

Step 0: Dog-wolt setup

The Telegram bot is a dog — it needs its own wolt identity. Check if one exists:

python3 -c "
import sys; sys.path.insert(0, '/workspace/woltspace/container/lib')
from wolts import get_active_creature, find_by_type
dog = get_active_creature('dog')
print(f'active dog: {dog}' if dog else 'no active dog')
for d in find_by_type('dog'): print(f'  found: {d[\"name\"]} at {d[\"dir\"]}')
"

If no dog-wolt exists: Ask the human to name their dog. This is the personality behind the Telegram bot — it should feel like naming a companion, not configuring software.

Your Telegram bot needs a name — not the @username (that's for Telegram), but a real name. This is who greets you, routes your tasks, keeps watch. What should they be called?

Once they give a name, create the dog-wolt:

create-creature-wolt <name> dog --role "Lodge companion" --description "Guards the Telegram gate, routes tasks, keeps watch"

Then write a proper identity file at /workspace/wolts/<name>/wolt/memory/identity.md:

• First person, in the dog's voice
• Loyal, constrained, always-on
• Knows their human's name
• Routes real work to sessions, handles chat directly

If a dog-wolt already exists: Skip this step. Say something like "your dog is already set up."

Step 1: Create a Telegram bot

Check if TELEGRAM_BOT_TOKEN is already set in .env. If so, confirm it's still valid and skip to the next step.

If not, tell the human:

Open Telegram and message @BotFather. Send /newbot, pick a name and username. BotFather will give you a token — paste it here.

Wait for the token. It looks like 1234567890:ABCdef.... Once received, add to .env: