# 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 via the X API 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. Add the token to Supabase

In the Supabase dashboard → **Project Settings → Edge Functions → Secrets**, add:

```
TELEGRAM_BOT_TOKEN=<token from BotFather>
```

### 3. Point Telegram's webhook at the edge function

From a terminal (replace the placeholders):

```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://<project-ref>.supabase.co/functions/v1/telegram-webhook"
```

Telegram should reply `{"ok":true,...}`.

### 4. 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`:
   * Send any message in the group, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` in a browser
   * Look for `"chat":{"id":-100…}` — copy the **full** negative number (including the leading `-100`)

### 5. Allowlist the chat in TheContentForge

1. Sign in as an org admin → **Settings**
2. Scroll to **Telegram Bot Health** → click **Check bot** to confirm the token is valid and the webhook is set
3. Scroll to **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 → **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 to the webhook. Check **Settings → Bot Health** — the webhook URL and `last_error_message` are shown there |
| `/generate <URL>` replies "generation failed"            | The upstream function errored. Check `bot_commands` in the database or expand the row in **Bot History**                                      |

## Plan limits

`max_bot_channels` governs how many group chats an org can connect:

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

Super admins can override this per-org from **Super Admin → Organizations → Edit limits**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thecontentforge.gitbook.io/thecontentforge-docs/admin-guide/telegram-bot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.