> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altitut-sma-center.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Bot: Generate Content Packs from Reels

> Set up the optional Altitut Telegram bot to instantly transform Instagram reel URLs into AI-generated content packs saved to your workspace.

The Altitut Telegram bot gives your team a fast, chat-native way to feed content into the system. Send any Instagram reel URL to the bot, and it automatically scrapes the reel, transcribes the audio, analyzes the content with GPT-4o-mini, and saves a ready-to-use content pack — no dashboard interaction required.

## How the Bot Works

**1. Send a reel URL to the bot**

Open your Telegram conversation with the bot and paste an Instagram reel URL. The bot accepts one URL per message.

**2. Webhook receives the message**

Telegram delivers the update to your server. Altitut validates the request using `TELEGRAM_WEBHOOK_SECRET` (if configured) and processes each message exactly once.

**3. Apify scrapes the reel**

Altitut calls the **Apify `instagram-scraper`** actor with the provided URL to download the reel's video and metadata.

**4. OpenAI Whisper transcribes the audio**

The reel audio is sent to **OpenAI Whisper** for speech-to-text transcription, producing a full text transcript.

**5. GPT-4o-mini analyzes the content**

The transcript and metadata are passed to **GPT-4o-mini**, which identifies key topics, extracts insights, and structures the raw material into a content pack.

**6. Content pack saved to your workspace**

The finished content pack is saved and immediately appears in the **Content Creation** tab inside the Altitut dashboard.

**7. Bot replies with a TL;DR**

The bot sends a concise TL;DR summary of the generated content pack back to the Telegram conversation so you know the job is done.

## Prerequisites

Before configuring the Telegram bot, make sure you have:

> [card] Telegram Bot Token
>
> Create a bot via [@BotFather](https://t.me/BotFather) on Telegram to obtain a `BOT_TOKEN`.

> [card] Publicly Reachable Server
>
> Telegram webhooks require an HTTPS endpoint. Use your production URL or a tunnel (e.g., ngrok) during local development.

> [card] Apify API Token
>
> An Apify account and API token are needed to run the `instagram-scraper` actor.

> [card] OpenAI API Key
>
> Required for Whisper transcription and GPT-4o-mini analysis.

## Setup

**1. Create a bot with @BotFather**

Open Telegram and start a conversation with [@BotFather](https://t.me/BotFather). Send `/newbot`, follow the prompts to name your bot, and copy the **token** it provides. You'll use this as `TELEGRAM_BOT_TOKEN`.

**2. Set environment variables**

Add the following variables to your server environment:

```bash theme={null}
# .env.local
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
TELEGRAM_WEBHOOK_SECRET=your_random_secret_here   # optional but recommended
```

**TELEGRAM\_BOT\_TOKEN** `string` *required*

The token issued by @BotFather. Altitut uses this to authenticate requests to the Telegram Bot API.

**TELEGRAM\_WEBHOOK\_SECRET** `string`

An arbitrary secret string. When set, Altitut validates the `x-telegram-bot-api-secret-token` header on every incoming webhook request and rejects requests that do not match.

> [!WARNING]
>
> Keep `TELEGRAM_BOT_TOKEN` strictly server-side. Exposing it would allow anyone to send messages as your bot or intercept updates.

**3. Deploy or expose your server**

Ensure your Altitut server is accessible over HTTPS. Telegram requires a valid TLS certificate on the webhook endpoint — self-signed certificates are not supported for production use.

For local development you can use a tunneling tool:

```bash theme={null}
# Example using ngrok
ngrok http 3000
# Copy the https:// forwarding URL for the next step
```

**4. Register the webhook URL**

Run the provided helper script, passing your public HTTPS deployment URL as an argument:

```bash theme={null}
npm run telegram:webhook -- https://your-app.example.com
```

The script registers the following webhook endpoint with the Telegram Bot API:

```
https://<your-domain>/api/telegram
```

If you set `TELEGRAM_WEBHOOK_SECRET`, the script also passes it as the `secret_token` parameter so Telegram includes it in every delivery.

> [!TIP]
>
> Re-run the script any time your domain changes (e.g., after moving to a new hosting provider or updating a tunnel URL).

**5. Verify the webhook**

Send a test Instagram reel URL to your bot in Telegram. Within a few seconds you should receive a TL;DR reply, and the new content pack should appear in the **Content Creation** tab of the dashboard.

## Webhook Endpoint Reference

| Property | Value |
| - | - |
| Method | `POST` |
| Path | `/api/telegram` |
| Auth header | `x-telegram-bot-api-secret-token: <TELEGRAM_WEBHOOK_SECRET>` |
| Payload | Standard [Telegram Update](https://core.telegram.org/bots/api#update) object (JSON) |

## Viewing Generated Content Packs

Content packs created through the Telegram bot appear alongside packs created manually in the **Content Creation** tab. Each pack includes the source transcript, extracted insights, and AI-suggested post drafts ready for editing and publishing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.