Telegram Bot

Access your lore, run AI actions, and generate content directly from Telegram — including voice messages.

Setup

Step 1: Create a Bot with BotFather

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. BotFather will give you a bot token (a long string like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).
4. Copy this token — you will need it in the next step.

Step 2: Configure LoreForge

There are two ways to configure the Telegram bot:

Option A: Environment Variables

Add these to your .env file:

# Telegram Bot
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_WEBHOOK_URL=https://your-domain.com/telegram/webhook
TELEGRAM_ALLOWED_USERS=12345678,87654321

Option B: Settings UI (Cloud)

Go to Settings → Telegram in the LoreForge web app and enter your bot token and webhook URL.

Step 3: Set the Webhook URL

The webhook URL must be publicly accessible over HTTPS. It should point to your LoreForge API's Telegram webhook endpoint:

https://your-domain.com/telegram/webhook

LoreForge will automatically register the webhook with Telegram on startup if both TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_URL are configured. You can also trigger registration manually:

curl -X POST https://your-domain.com/telegram/setup \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/telegram/webhook"}'

Step 4: Restrict Access (Recommended)

Set TELEGRAM_ALLOWED_USERS to a comma-separated list of Telegram user IDs that are allowed to use the bot. If left empty, anyone who finds your bot can use it.

To find your Telegram user ID, message @userinfobot on Telegram.

Step 5: Verify

Check the bot status via the API:

curl https://your-domain.com/telegram/status

This returns the bot username, webhook URL, and allowed users list.

---

Slash Commands

The bot supports these slash commands. For entry-based commands, use the entry name as the argument.

Entry Actions

Command	Description	Example
/expand <name>	Expand an entry's lore with AI-generated content that stays consistent with your canon.	/expand Eldara
/summarize <name>	Get a concise summary of an entry.	/summarize The Battle of Iron Gate
/dialogue <name>	Generate in-character dialogue for a character entry.	/dialogue Captain Voss
/connections <name>	Discover potential relationships between an entry and other canon entries.	/connections The Silver Order
/contradictions <name>	Check an entry for inconsistencies with the rest of your world.	/contradictions Thornwall

World Tools

Command	Description	Example
/names <description>	Generate 10 culturally-consistent names based on your description and existing canon.	/names elven noble family names
/generate <prompt>	Bulk-generate 3 new entries from a freeform description.	/generate the three guilds of Ashenmere
/consistency	Run a world-wide consistency check across all canon entries.	/consistency

General

Command	Description
/help	Show all available commands.
/start	Welcome message and command overview (same as /help).

---

Voice Message Support

Send a voice message to the bot and it will:

1. Transcribe the audio using Whisper STT.
2. Echo the transcription back to you for confirmation.
3. Route the transcribed text through the same command/intent detection as typed messages.

This means you can say “expand Eldara” or “generate names for a dwarven mining clan” and the bot will understand the intent and execute the right action.

---

Natural Language Routing

You don't have to use slash commands. The bot uses LLM-based intent detection to understand natural language requests:

• “Tell me about Eldara” → answers as a Q&A about your lore
• “Can you expand on the Silver Order?” → runs the /expand action
• “I need some names for desert nomad tribes” → runs the /names action
• “Are there any contradictions in Thornwall's entry?” → runs /contradictions
• “What's the history of the Iron Gate?” → Q&A with canon context

If the bot can't determine a specific tool intent, it defaults to the general Q&A flow: searching your canon for relevant entries and answering your question using that context.

---

Automatic Writing Prompts

When you ask a question that the canon doesn't fully cover, LoreForge saves it as a Writing Prompt. Each prompt is tagged with a canon coverage level:

• Full — the canon fully answers the question
• Partial — some established lore exists, but the AI filled gaps with inference
• None — this area hasn't been developed yet

Review writing prompts in the LoreForge web app to discover gaps in your worldbuilding and prioritize what to write next.

---

Tips

• Entry names are matched with fuzzy case-insensitive search. You don't need the exact name — a partial match works.
• The /generate command creates entries in the AI's response but does not auto-save them. Open LoreForge to review and import.
• The /consistency command examines up to 20 canon entries. For very large worlds, it focuses on the most recently updated entries.
• Slash commands work with bot mentions too (e.g., /expand@YourBot Eldara), which is useful in group chats.