# Jokes Bot — Complete Setup Guide (Non-Developer Friendly)

This bot turns a joke you send on **Telegram** into a clean Instagram-ready image + caption, then lets you post to Instagram via **Make.com**.

**Cost:** $0 for images (templates, no AI image generation). Gemini is only used to split joke → hook + caption (very cheap on Tier 1).

---

## What you are building

```
You (Telegram) → Namecheap PHP bot → Gemini (split text) → Image template
                                                              ↓
                                         "Post to Instagram" button
                                                              ↓
                                    Make.com webhook → Instagram post
```

---

## Part 1 — Create your Telegram bot (5 minutes)

1. Open Telegram and search for **@BotFather**
2. Send: `/newbot`
3. Choose a display name, e.g. `My Jokes Bot`
4. Choose a username ending in `bot`, e.g. `raghav_jokes_bot`
5. BotFather gives you a **token** like `7123456789:AAH...` — save it somewhere safe

---

## Part 2 — Get your Telegram user ID (2 minutes)

1. Open this URL in your browser (replace `YOUR_TOKEN`):
   ```
   https://api.telegram.org/botYOUR_TOKEN/getUpdates
   ```
2. Send `/start` to your new bot in Telegram first
3. Refresh the browser page
4. Find `"id": 123456789` inside `"from"` — that number is **your user ID**

Only you will be allowed to use the bot.

---

## Part 3 — Get your Gemini API key (3 minutes)

1. Go to [Google AI Studio](https://aistudio.google.com/apikey)
2. Click **Create API key**
3. Copy the key — you will paste it into `config.php`

---

## Part 4 — Upload files to Namecheap (15 minutes)

### 4a. Log into Namecheap

1. Go to [namecheap.com](https://www.namecheap.com) → **Sign In**
2. **Hosting List** → **Manage** next to your hosting
3. Open **cPanel**

### 4b. Create the folder

1. In cPanel, open **File Manager**
2. Go to `public_html` (or wherever `raghavkapoor.org` points)
3. Create folders:
   ```
   instagram-bots
   instagram-bots/jokes-bot
   ```

### 4c. Upload the bot files

Upload **everything** from this `jokes-bot` folder **except** `.venv` if you have one locally:

| Upload | Purpose |
|--------|---------|
| `webhook.php` | Main bot |
| `setup.php` | One-time setup page |
| `config.example.php` | Template for secrets |
| `lib/` folder | Bot logic |
| `assets/fonts/` | Text on images |
| `generated/` | Output images (empty is fine) |
| `data/` | Sessions (empty is fine) |
| `.htaccess` | Security |

### 4d. Create config.php

1. In File Manager, **Copy** `config.example.php` → rename copy to `config.php`
2. Edit `config.php` and fill in:

```php
'telegram_bot_token' => 'PASTE_BOTFATHER_TOKEN',
'allowed_telegram_user_ids' => [ YOUR_TELEGRAM_ID ],
'gemini_api_key' => 'PASTE_GEMINI_KEY',
'make_instagram_webhook_url' => 'PASTE_LATER_FROM_MAKE',
'public_base_url' => 'https://raghavkapoor.org/instagram-bots/jokes-bot',
'instagram_account_name' => '@your_instagram_handle',
```

### 4e. Enable PHP GD (required for images)

1. cPanel → **Select PHP Version** (or **MultiPHP INI Editor**)
2. Ensure **GD** extension is **enabled**
3. PHP **8.0+** recommended

### 4f. Folder permissions

Set these folders to **755** (writable by PHP):
- `generated/`
- `data/`

In File Manager: right-click folder → **Change Permissions** → check **Write** for Owner.

---

## Part 5 — Register the Telegram webhook (2 minutes)

1. Visit in your browser:
   ```
   https://raghavkapoor.org/instagram-bots/jokes-bot/setup.php
   ```
2. All checks should show **OK**
3. Click **Register Telegram webhook**
4. You should see `"url": "https://raghavkapoor.org/instagram-bots/jokes-bot/webhook.php"`
5. **Delete `setup.php`** from the server when done (security)

---

## Part 6 — Test the bot (2 minutes)

1. Open your bot in Telegram
2. Send `/start` — you should get help text
3. Send a joke, for example:
   ```
   Why don't scientists trust atoms?
   Because they make up everything!
   ```
4. You should receive:
   - A square image with the **setup/hook** text
   - Buttons: **Post to Instagram**, **New split**, color templates, **Discard**

If nothing happens:
- Check `data/logs/bot.log` on the server
- Re-visit setup checks (GD, fonts, permissions)

---

## Part 7 — Make.com for Instagram posting

Make.com handles Meta/Instagram APIs so you don't have to.

See the full walkthrough: **[make-com/INSTAGRAM-SETUP.md](../make-com/INSTAGRAM-SETUP.md)**

Quick summary:

1. Create free account at [make.com](https://www.make.com)
2. Connect **Instagram for Business** (requires Facebook Page linked to IG)
3. Create scenario:
   - **Webhook** (Custom) → receives JSON from bot
   - **HTTP: Get a file** → downloads `image_url`
   - **Instagram: Create a Photo Post** → uses file + `caption`
4. Copy webhook URL into `config.php` → `make_instagram_webhook_url`
5. Turn scenario **ON**

When you tap **📸 Post to Instagram** in Telegram, Make receives:

```json
{
  "bot": "jokes-bot",
  "instagram_account": "@your_page",
  "image_url": "https://raghavkapoor.org/instagram-bots/jokes-bot/generated/joke_....jpg",
  "caption": "Full joke + CTA + hashtags",
  "image_text": "Hook shown on image"
}
```

---

## Part 8 — Instagram account requirements

Instagram posting via API only works if:

1. Instagram account is **Business** or **Creator**
2. It is linked to a **Facebook Page**
3. In Make.com, you connect the **Facebook + Instagram** app with posting permissions

Convert in Instagram app: **Settings → Account type and tools → Switch to professional account**

---

## How engagement split works

| On image | In caption |
|----------|------------|
| Setup / first half only | Punchline + "Tag someone..." + hashtags |
| Creates curiosity | People expand caption → algorithm boost |

Gemini writes this split. If Gemini fails, the bot uses a simple fallback.

---

## Bot buttons explained

| Button | What it does |
|--------|----------------|
| 📸 Post to Instagram | Sends to Make.com webhook |
| 🔄 New split | Asks Gemini for a different hook/caption split |
| 🎨 Cream / Slate / Mint / Blush / Dark | Changes background template |
| ❌ Discard | Clears this preview |

---

## Future bots (History, FIFA, Facts…)

Duplicate the `jokes-bot` folder:

```
instagram-bots/history-bot/
instagram-bots/fifa-bot/
```

Change in each `config.php`:
- `instagram_account_name`
- `default_hashtags`
- `make_instagram_webhook_url` (separate Make scenario per bot, or one scenario with a router)

The `bot` field in the webhook payload lets Make route to different Instagram accounts.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Bot doesn't reply | Webhook not set — run setup.php again |
| "This bot is private" | Add your Telegram ID to `allowed_telegram_user_ids` |
| No image / GD error | Enable GD in cPanel PHP settings |
| Font missing error | Re-upload `assets/fonts/` folder |
| Make.com fails | Check scenario is ON; test webhook in Make manually |
| Instagram post fails | IG must be Business + linked to Facebook Page |
| Image URL not loading | Ensure `generated/` is public; check `.htaccess` |

---

## Security checklist

- [ ] Never share `config.php` or bot token
- [ ] Delete `setup.php` after setup
- [ ] Only your Telegram ID in `allowed_telegram_user_ids`
- [ ] `config.php` is blocked by `.htaccess`

---

## Files reference

```
jokes-bot/
├── webhook.php          ← Telegram talks to this
├── setup.php            ← Delete after setup
├── config.php           ← Your secrets (create from example)
├── lib/                 ← Bot code
├── assets/fonts/        ← Text rendering
├── generated/           ← Images (auto-cleaned after 48h)
├── data/sessions/       ← Temporary preview data
└── data/logs/bot.log    ← Error log
```

You are ready. Send a joke and ship it to Instagram.