ig-reply-bot

Reply to your Instagram comments automatically. When someone comments a keyword you choose (like "RECIPE" or "LINK") on one of your posts, this sends them a direct message with whatever you want — a link, a discount code, a welcome note. The messages can be more than plain text, too: add a photo, tappable buttons, or quick-reply options to make them stand out. It can also reply to the comment publicly and tidy it away, all on its own.

It runs entirely on Cloudflare's free tier, so there's nothing to pay — no monthly bill, no per-message fees. Tools that do roughly the same thing typically charge around $30 a month; this is a free alternative you host yourself.

The Deploy button creates the Worker + D1 in your Cloudflare account and prompts for secrets; then finish DEPLOY.md steps 3–7. It does not run D1 migrations, deploy the admin GUI (separate Pages deploy), set up Cloudflare Access, or do any of the Meta-side setup (creating the Meta app, OAuth redirect, webhook subscription, publishing the app) — there is no API for those. Plan ~30–45 min total. (The button also requires this repo to be public, and a fork's button still points here unless you edit its URL.)

Self-hosted Instagram comment-to-DM automation, running on the Cloudflare free tier. Configure trigger keywords per post → the bot DMs commenters who hit a keyword, optionally posts a public reply, optionally hides the triggering comment. Multi-account from day one.

Built for operators managing one or more Instagram Business accounts they own or manage. Meta's app review is not required for this use case (see DEPLOY.md for details). It is not a SaaS — one Meta app, one Cloudflare account, one admin, the IG accounts you connect.

Stack

• Cloudflare Workers (Hono) — webhook receiver + JSON API
• Cloudflare D1 — accounts, posts, rules, events (audit log)
• SvelteKit on Cloudflare Pages — admin GUI
• Cloudflare Access (optional) — admin auth via Zero Trust

Everything stays on the free tier. No Queues, no Durable Objects, no paid services.

What it does

1. You connect an IG Business account via OAuth in the admin.
2. You pick a post and add one or more trigger rules (contains "RECIPE" → DM "Here's the link: …").
3. When someone comments on that post, Meta hits your webhook → the worker matches rules → sends the DM (and optional public reply / comment hide) via the IG Graph API.
4. Every step lands in the events table for auditing and debugging.

Rate-limit aware (700/hr per account, 7% under Meta's 750/hr cap), dedupes on (commenter, rule), and refreshes long-lived tokens daily via a cron.

Prerequisites

• node 22+, npm, git, and openssl on your machine. (The admin GUI's build deps require Node 22+; the worker alone runs on 20+, but 22+ keeps both halves on one version.)
• A Cloudflare account (free tier is fine).
• A Meta developer account (free) — https://developers.facebook.com.
• One or more Instagram Business accounts you own or manage. Personal and Creator accounts won't work — Meta requires Business.
• (Optional, recommended) a domain managed by Cloudflare. Without one, the worker still runs at its default *.workers.dev URL.

Deploy

The fastest path is the manual walkthrough in DEPLOY.md. It covers:

1. Creating the Meta app (Instagram Login flow, the right scope family)
2. Creating D1 + (optionally) Pages and Cloudflare Access in your Cloudflare account
3. Setting wrangler secrets + replacing the placeholders in wrangler.toml
4. Publishing the Meta app (required for real webhooks to fire)
5. Connecting your first IG account and adding a rule

A "Deploy to Cloudflare" button is provided for the Cloudflare-side provisioning, but the Meta-side setup (~15 min) still has to be done manually — there's no API for it.

Local development

npm install
npx wrangler login
npm run db:create                # paste returned database_id into wrangler.toml
npm run db:migrate:local
cp .dev.vars.example .dev.vars   # then fill in the 4 secrets (see comments in the file)
#   ENCRYPTION_KEY            — openssl rand -base64 32
#   META_WEBHOOK_VERIFY_TOKEN — any random string (reuse it in Meta's dashboard)
#   META_APP_ID / META_APP_SECRET — from your Meta app dashboard
npm run dev                      # worker on :8787 (wrangler auto-loads .dev.vars)

In another shell, run the admin GUI against the worker:

cd gui
npm install
npm run dev                      # http://localhost:5173/accounts

For the OAuth + webhook flow to actually round-trip with Meta in dev, you need a public HTTPS URL for the worker — cloudflared tunnel --url http://127.0.0.1:8787 gives an ephemeral one (paste it into Meta's app dashboard each time it changes). For a stable URL, set up a Cloudflare named tunnel.

Testing

npm run typecheck                # tsc --noEmit
npm test                         # worker tests (Cloudflare workers pool)
cd gui && npm run check          # svelte-check
cd gui && npm test               # gui tests (jsdom pool)

Troubleshooting

• No webhooks arriving — check (1) the Meta app is published, not unpublished; (2) per-account subscription is active (scripts/check-subscription.mjs <ig_user_id>); (3) the scope family is instagram_business_* not instagram_* (CLAUDE.md has a section on this).
• Webhooks arriving but routed to "Unknown ig_user_id" — your stored ig_user_id doesn't match the entry[].id Meta sends; see "store user_id, not id" in CLAUDE.md.
• Internal Server Error on a PATCH/POST — usually a missing D1 migration. wrangler deploy doesn't auto-apply them; run npm run db:migrate:remote.
• Live logs — npx wrangler tail ig-reply-bot --format=pretty.
• Forensics on a specific comment — SELECT * FROM events ORDER BY id DESC LIMIT 20 (via npx wrangler d1 execute ig-reply-bot --remote --command "…") or the /events page in the admin.

Architecture

See CLAUDE.md — it's the engineer-facing architecture doc and covers things you can't infer by reading the code (why waitUntil instead of Queues, the ig_user_id gotcha, scope-family pitfalls, the test-mocking patterns required by @cloudflare/vitest-pool-workers, etc.).

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.