Skip to content

DEPLOY.md

Latest commit

 

History

History
308 lines (207 loc) · 9.57 KB

DEPLOY.md

File metadata and controls

308 lines (207 loc) · 9.57 KB
Raw

FunnyNewsBot — Deployment Guide

A Cloudflare Worker that fetches top Hacker News stories daily, uses Gemini AI to pick the funniest one, and posts it to Telegram chats/channels in any language with a customizable writing tone.

Prerequisites

  • A Cloudflare account (free tier works)
  • Node.js + npm installed (npx wrangler requires it)
  • A Telegram bot token from @BotFather
  • A Gemini API key from Google AI Studio
  • Your Telegram User ID (to gate the bot to you only)

Step 1: Create a Telegram Bot

  1. Open Telegram and message @BotFather.
  2. Send /newbot, give it a name (e.g. "FunnyNewsBot") and a username ending in bot (e.g. funnynews_bot).
  3. Save the token BotFather gives you. Format: 123456789:ABCdefGhIJKlmnOPQRstUVwxyz

Get your Telegram User ID

  1. Message @userinfobot in Telegram.
  2. Copy the numeric Id it returns (e.g. 123456789). This is your OWNER_TELEGRAM_USER_ID.

Step 2: Install Wrangler CLI

npm install -g wrangler

Verify:

npx wrangler --version

Step 3: Login to Cloudflare

npx wrangler login

Step 4: Create a KV Namespace

The bot uses KV to store per-chat language and tone settings.

npx wrangler kv namespace create "FUNNYNEWS_KV"

You'll see output like:

Add the following to your wrangler.toml:
kv_namespaces = [
  { binding = "KV", id = "abc123def456..." }
]

Copy that ID and update wrangler.toml — replace PLACEHOLDER_KV_ID with the real ID:

kv_namespaces = [
  { binding = "KV", id = "abc123def456..." }
]

Step 5: Set Secrets

These are encrypted at rest — never put them in wrangler.toml.

npx wrangler secret put GEMINI_API_KEY
# paste your Gemini key, press Enter

npx wrangler secret put TELEGRAM_BOT_TOKEN
# paste your bot token, press Enter

npx wrangler secret put OWNER_TELEGRAM_USER_ID
# paste your numeric Telegram User ID from @userinfobot, press Enter

Important: Only the user with this ID can issue commands to the bot (/setlang, /settone, /now, /status). The cron job still posts to all registered chats regardless of ownership.

Optional: Change the model

The default model is gemini-3.1-flash-lite. To use a different Gemini model, update wrangler.toml:

[vars]
MODEL = "gemini-2.5-flash"   # or gemini-2.5-pro, gemini-2.0-flash, etc.

Step 6: Deploy the Worker

From the project directory (E:\funnynewsbot):

npx wrangler deploy

Wrangler will output your worker URL, e.g.:

https://funnynewsbot.your-subdomain.workers.dev

Step 7: Set the Telegram Webhook

Visit your worker's /init route once:

https://funnynewsbot.your-subdomain.workers.dev/init

This calls Telegram's setWebhook API to point all bot updates to your worker's /webhook route. You should see:

{"ok":true,"result":true,"description":"Webhook was set"}

Step 8: Test Everything

8.1 — Test in a DM with the bot

Open Telegram, find your bot, and send:

/start

You should see the help message. Then:

/setlang Japanese
/settone deadpan and dry
/now

The bot will fetch HN stories, call Gemini, and post the result directly to you in Japanese with a deadpan tone.

8.2 — Add bot to a Telegram channel

  1. Create a Telegram channel (or use an existing one).
  2. Add your bot as an administrator (needs "Post messages" permission).
  3. In that channel (as the owner user), send: 
    /setlang English
/settone over-the-top sensationalist
/now
  4. The bot will post the funny news in the channel with that tone.

Important: The bot must be an admin in the channel to send messages via the Bot API. Commands only work when sent by the owner user (the one whose OWNER_TELEGRAM_USER_ID you set).

8.3 — Check the daily cron

The worker's wrangler.toml is configured to run at 07:10 AM UTC daily:

[triggers]
crons = ["10 7 * * *"]

How Cron Triggers work (important): A [triggers] cron entry does NOT make an HTTP request to your worker. Cloudflare invokes a scheduled(event, env, ctx) handler on the worker's default export. The worker exports both fetch (for HTTP/webhooks) and scheduled (for the cron); scheduled runs the same runPipeline the /cron route uses, wrapped in ctx.waitUntil() so the runtime doesn't terminate it early. Do NOT remove the scheduled handler — if you export default app only, the cron will silently stop firing. See workers.js at the bottom for the export shape.

The cron expression uses UTC (no timezone override). Change it to any 5-field cron expression:

# 9 AM UTC:
crons = ["0 9 * * *"]

# Every 6 hours (at minute 0):
crons = ["0 */6 * * *"]

# Twice a day (9 AM + 9 PM UTC):
crons = ["0 9,21 * * *"]

# 8:30 AM UTC, weekdays only:
crons = ["30 8 * * 1-5"]

Redeploy after changing:

npx wrangler deploy

Deploying updates does NOT require re-registering channels. Cloudflare KV is separate from the worker code — npx wrangler deploy replaces the worker but leaves KV data untouched. Channels you registered with /setlang stay registered and will continue receiving the daily post. You only need to re-run /setlang / /settone when:

  • Adding the bot to a new channel (to register it in KV), or
  • Changing the language/tone for an existing channel, or
  • Recreating the KV namespace with a different ID in wrangler.toml (this wipes all registrations — don't do this unless intended).

8.4 — Test the cron without waiting

You don't need to wait for 07:10 UTC to verify the schedule works. Two ways to trigger a run immediately:

Option A — Wrangler local cron trigger (tests the scheduled handler directly):

# Fires the first cron entry (index 0) immediately in the local dev runtime
npx wrangler triggers cron 0

This invokes your scheduled handler exactly as Cloudflare would at 07:10 UTC, so it's the most faithful test. If runPipeline posts to your registered channels, the cron path is working.

Option B — Hit the /cron HTTP route (tests the same runPipeline via fetch):

https://funnynewsbot.kianooshshakeri99.workers.dev/cron

Open it in a browser, or:

curl https://funnynewsbot.kianooshshakeri99.workers.dev/cron

The response includes the chosen headline, URL, and the number of chats it was sent to. This route is a manual trigger kept for convenience — the daily run goes through scheduled, not this route.

8.5 — Verify a deploy is live

After npx wrangler deploy, confirm the new code is running before tomorrow's cron fires. Either method above exercising runPipeline successfully confirms the deploy is live. You can also check the deploy hash in Cloudflare's dashboard (Workers → your worker → Deployments) against the hash wrangler deploy printed.

Commands Reference

Command Where What it does
/start DM / channel Shows welcome + help
/help DM / channel Shows all commands
/setlang French Any chat Sets output language for that chat
/settone deadpan Any chat Sets writing tone/style for that chat
/now Any chat Forces immediate news run (owner only)
/test Any chat Same as /now (owner only)
/status Any chat Shows current language, tone, chat ID (owner only)

Owner-only: /now, /test, /status, /setlang, /settone only respond when sent by the user whose ID matches OWNER_TELEGRAM_USER_ID. Other users are silently ignored.

Tone Examples

Tone string Effect
funny and sarcastic Default — witty, irreverent
deadpan and dry Understated, matter-of-fact
over-the-top sensationalist ALL CAPS, EXCLAMATION POINTS!!!
Gen Z internet slang "no cap", "skrrt", "iykyk"
Shakespearean drama "Hark! Good sir, this tidings doth..."
passive-aggressive corporate memo "Per my last email regarding the absurdity..."
enthusiastic tabloid "SHOCKING: You WON'T BELIEVE what happened!"

Any free-form description works — it's passed directly to Gemini as a style instruction.

Troubleshooting

"No registered chats" error

Send /setlang English in the chat first (as the owner). This registers the chat in KV so the cron knows about it.

Bot doesn't post in channel

Make sure the bot is a channel admin with "Post messages" permission.

Commands don't work / bot ignores me

  • Verify your OWNER_TELEGRAM_USER_ID secret is set correctly (must be numeric string).
  • Only that specific Telegram user can issue commands.

Gemini API errors

  • Check your GEMINI_API_KEY secret: npx wrangler secret list
  • Verify the MODEL name in wrangler.toml — must be a valid Gemini model like gemini-3.1-flash-lite
  • Check Gemini API quota at Google AI Studio

Webhook not receiving updates

Visit /init again. Check https://api.telegram.org/bot<TOKEN>/getWebhookInfo in a browser.

Cloudflare Worker 30s timeout

The worker fetches HN top stories with a concurrency limit of 5. If it still times out, reduce TOP_STORIES_LIMIT in workers.js (line 20).

Cost

  • Cloudflare Workers: Free tier = 100,000 requests/day
  • Cloudflare KV: Free tier = 1,000 reads + 1,000 writes/day
  • Gemini API: gemini-3.1-flash-lite / gemini-2.5-flash free up to ~1,500 requests/day on Google AI Studio. Two calls per daily run = ~60/month.
  • Hacker News API: Free, no limits

Total cost: $0/month if you stay within free tiers.