> For the complete documentation index, see [llms.txt](https://thecontentforge.gitbook.io/thecontentforge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thecontentforge.gitbook.io/thecontentforge-docs/admin-guide/telegram-bot.md).

# Telegram Bot

The Telegram Bot lets your team generate on-brand posts without leaving Telegram. Generation happens via the bot; reviewing and publishing still take place in the web app.

## Commands

| Command             | Input                                   | What it does                                    |
| ------------------- | --------------------------------------- | ----------------------------------------------- |
| `/generate <input>` | Text prompt, X post URL, or article URL | Generates an on-brand post from the given input |
| `/cancel`           | -                                       | Cancels the active generation job               |
| `/help`             | -                                       | Lists available commands                        |

### How `/generate` routes input

The bot inspects the text after `/generate`:

| Input shape                                                        | What happens                                                          |
| ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| `https://x.com/.../status/…` or `https://twitter.com/.../status/…` | The tweet is fetched and used as a topic for a Post Helper generation |
| Any other `https://…` URL                                          | The article is fetched and summarised into a ready-to-post piece      |
| Plain text                                                         | Treated as a topic and passed to Post Helper                          |

The bot **only** responds in group chats that have been added to your org's allowlist. It **never** responds in DMs.

Deduplication is built in - sending the same request twice will not trigger a second generation.

Posts generated via the bot appear in Content Forge **History** with a Telegram source badge. Use **Recall** on any history entry to bring the input back into Content Forge for further editing.

## One-time setup

### 1. Create the bot with BotFather

1. Open Telegram → search for `@BotFather` → `/newbot`
2. Pick a display name and `_bot` username
3. Copy the token BotFather gives you - it looks like `123456:ABCdef...`
4. Send `/setcommands` to BotFather, choose your bot, and paste:

   ```
   generate - Generate a post from a topic, article URL, or X post URL
   cancel - Cancel the active generation job
   help - Show available commands
   ```

### 2. Connect the bot to TheContentForge

Provide the token from BotFather to TheContentForge to finish connecting the bot - reach out to your onboarding contact or support and we'll link it and set up its webhook. Once connected, **Settings → Telegram → Settings → Check bot** confirms the token is valid and the bot is live.

### 3. Add the bot to your group chat

1. In Telegram, add the bot as a member of your team's group chat
2. In group **Settings → Administrators → Add Admin**, grant the bot admin rights so it can read messages in topic-enabled groups
3. Get the group's `chat_id` - the bot tells you itself:
   * In the group, send `/start` (any command works)
   * Because the chat isn't linked yet, the bot replies with **"This chat's ID: `-100…`"**
   * Copy the **full** negative number (including the leading `-100`)

### 4. Allowlist the chat in TheContentForge

1. Sign in as an org admin → **Settings** → **Telegram** → **Settings** tab
2. Under **Telegram Bot Health**, click **Check bot** to confirm the token is valid and the webhook is set
3. Under **Allowlisted Chat IDs**, paste the chat ID and a friendly title → **Add**

That's it. Members of that chat can now run `/generate` and the other commands.

## Optional: user allowlist

If you want to restrict which Telegram users inside the allowlisted chat can use the bot:

1. **Settings → Telegram → Settings** → **Allowlisted User IDs** → enable the toggle
2. Add the Telegram user IDs (numeric) that should have access

When the user allowlist is disabled, any member of the allowlisted chat can use the bot.

## Troubleshooting

| Symptom                                                  | Likely cause                                                                                                                                                    |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bot replies "This chat is not linked to an organization" | The chat isn't in the allowlist, or the ID was pasted without the leading `-100`                                                                                |
| Bot doesn't respond at all in a group                    | Telegram didn't deliver the update. Check **Settings → Telegram → Settings → Telegram Bot Health** - the connection status and any recent error are shown there |
| `/generate <URL>` replies "generation failed"            | The generation errored. Open the command in **Bot History** to see details, or contact support                                                                  |

## Plan limits

Your plan sets how many group chats you can connect:

| Plan       | Bot channels |
| ---------- | ------------ |
| Starter    | 1            |
| Pro        | 5            |
| Enterprise | 25           |

If you need more bot channels than your plan includes, contact support.
