Instagram Comment-to-DM Automation with Meta API, Next.js and Supabase

-- Campaigns are managed by authenticated dashboard users.
create table public.instagram_campaigns (
  id uuid primary key default gen_random_uuid(),
  owner_id uuid not null references auth.users(id) on delete cascade,
  media_id text,
  reel_url text,
  keyword text not null check (char_length(trim(keyword)) between 1 and 80),
  dm_message text not null check (char_length(trim(dm_message)) between 1 and 1000),
  public_reply text check (public_reply is null or char_length(trim(public_reply)) between 1 and 300),
  enabled boolean not null default true,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

create unique index instagram_campaign_owner_media_keyword_key
on public.instagram_campaigns (
  owner_id,
  coalesce(media_id, '*'),
  lower(trim(keyword))
);

alter table public.instagram_campaigns enable row level security;
revoke all on table public.instagram_campaigns from anon, authenticated;
grant select, insert, update, delete on table public.instagram_campaigns to authenticated;

create policy "Owners can read campaigns"
on public.instagram_campaigns for select to authenticated
using ((select auth.uid()) = owner_id);

create policy "Owners can create campaigns"
on public.instagram_campaigns for insert to authenticated
with check ((select auth.uid()) = owner_id);

create policy "Owners can update campaigns"
on public.instagram_campaigns for update to authenticated
using ((select auth.uid()) = owner_id)
with check ((select auth.uid()) = owner_id);

create policy "Owners can delete campaigns"
on public.instagram_campaigns for delete to authenticated
using ((select auth.uid()) = owner_id);

-- Webhook delivery records make retries idempotent. Keep this table server-only.
create table public.instagram_delivery_events (
  id uuid primary key default gen_random_uuid(),
  event_key text not null unique,
  comment_id text not null,
  campaign_id uuid references public.instagram_campaigns(id) on delete set null,
  status text not null check (status in ('processing', 'sent', 'ignored', 'failed')),
  attempt_count integer not null default 1 check (attempt_count > 0),
  error_code text,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

alter table public.instagram_delivery_events enable row level security;
revoke all on table public.instagram_delivery_events from anon, authenticated;

-- Use a Supabase secret key only in trusted server code to access delivery records.
-- Do not add public policies to instagram_delivery_events.

META_APP_ID=
META_APP_SECRET=
META_VERIFY_TOKEN=
META_INSTAGRAM_ACCESS_TOKEN=
META_INSTAGRAM_ACCOUNT_ID=
META_GRAPH_API_VERSION=

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
SUPABASE_SECRET_KEY=

You are a Staff Software Engineer at Vercel.

Your task is to build ONLY the foundation for an Instagram Comment → DM automation service.

This is Phase 1 of a larger project.

DO NOT implement any Instagram logic yet.
DO NOT connect to Meta.
DO NOT connect to Supabase.
DO NOT add authentication.
DO NOT add Redis.
DO NOT add BullMQ.
DO NOT add Prisma.
DO NOT add Docker.
DO NOT add any unnecessary packages.

The only goal is to produce a clean, production-ready Next.js application that can be deployed to Vercel and is ready to become a Meta webhook receiver.

=========================================================
PROJECT
=========================================================

Project name:
instagram-comment-bot

Tech stack:
• Next.js 15+
• App Router
• TypeScript
• Tailwind CSS
• ESLint
• npm

Use the latest stable versions.

=========================================================
PROJECT GOALS
=========================================================

After completing this task I should be able to:

✅ Run locally
npm run dev

✅ Build successfully
npm run build

✅ Deploy to Vercel with zero changes

✅ Visit the homepage

✅ Visit the webhook endpoint

Nothing else.

=========================================================
PROJECT STRUCTURE
=========================================================

Use a clean architecture.

app/
    api/
        webhooks/
            meta/
                route.ts

lib/
config/
types/
public/

Do not create unnecessary folders.

=========================================================
HOMEPAGE
=========================================================

Create a clean homepage.

Title:
Instagram Comment Bot

Subtitle:
A lightweight webhook receiver for Instagram Comment → DM automation.

Display:

----------------------------
Instagram Comment Bot

Status
🟢 Ready

This project is currently running.

Current Phase
Foundation & Webhook Setup
----------------------------

No buttons.
No forms.
No authentication.
No dashboard.
No animations.
No unnecessary UI.

Keep it simple and professional.

=========================================================
WEBHOOK ROUTE
=========================================================

Create:
app/api/webhooks/meta/route.ts

Implement BOTH handlers.

GET

Return HTTP 200

Response:
{
    "status": "ok",
    "message": "Meta webhook endpoint is ready.",
    "phase": "foundation"
}

POST

Return HTTP 200

Response:
{
    "status": "received",
    "message": "Webhook request received.",
    "phase": "foundation"
}

Do NOT:
• verify tokens
• parse request body
• log payload
• save to database

Those belong to future phases.

=========================================================
CONFIG
=========================================================

Create an .env.example

Include only:
WEBHOOK_VERIFY_TOKEN=

Explain in comments that it will be used in the next phase.

Do not use it yet.

=========================================================
README
=========================================================

Generate a professional README.

Include:
• Project overview
• Tech stack
• Folder structure
• How to install
• How to run
• How to build
• How to deploy to Vercel
• Project roadmap

Roadmap should include:

Phase 1
✓ Foundation

Phase 2
Webhook Verification

Phase 3
Receive Comment Events

Phase 4
Keyword Matching

Phase 5
Send Instagram DM

Phase 6
Logging & Dashboard

=========================================================
CODE QUALITY
=========================================================

Requirements:
• strict TypeScript
• zero TypeScript errors
• zero ESLint warnings
• clean imports
• reusable architecture
• meaningful comments
• production-ready formatting

No placeholder junk.
No dead code.
No unused dependencies.

=========================================================
TESTING
=========================================================

Before finishing, run:
npm install
npm run lint
npm run build

Fix every issue until everything passes.

=========================================================
OUTPUT
=========================================================

After generating the project:

1. Explain the folder structure.
2. Explain every file.
3. Explain how Next.js API routes work.
4. Explain how GET requests differ from POST requests.
5. Explain how this webhook endpoint will later connect to Meta.
6. Provide the exact commands to:
   - install dependencies
   - run locally
   - initialize a Git repository
   - create the first commit
   - deploy to Vercel using the Vercel CLI

Do not implement anything beyond the scope of this prompt.

The application should be production-ready and immediately deployable to Vercel.

You are continuing the existing Next.js project from the previous phase.

DO NOT modify the existing project architecture.
DO NOT add authentication.
DO NOT add a database.
DO NOT add Supabase.
DO NOT add Redis.
DO NOT add BullMQ.
DO NOT add any Instagram business logic.
DO NOT send DMs.
DO NOT match keywords.

Your ONLY goal is to complete the next two commits.

=========================================================
PROJECT CONTEXT
=========================================================

The project already contains:
- Next.js 15
- App Router
- TypeScript
- Tailwind
- Homepage
- /api/webhooks/meta endpoint
- Successfully deployed to Vercel

We are now making the endpoint compatible with Meta Webhooks.

=========================================================
COMMIT 3 — META WEBHOOK VERIFICATION
=========================================================

Implement Meta's webhook verification flow.

Environment variable:
WEBHOOK_VERIFY_TOKEN

The GET endpoint must support these query parameters exactly as Meta sends them:
- hub.mode
- hub.verify_token
- hub.challenge

Logic:

1. Read hub.mode.
2. Read hub.verify_token.
3. Read hub.challenge.
4. If hub.mode == "subscribe" AND hub.verify_token == process.env.WEBHOOK_VERIFY_TOKEN, return HTTP 200 with hub.challenge.
5. Return ONLY the raw challenge string-not JSON or HTML.
6. If verification fails, return HTTP 403 with body: Forbidden

Validation example:

GET /api/webhooks/meta?hub.mode=subscribe&hub.verify_token=test123&hub.challenge=987654321

Expected response:
987654321

Status: 200

=========================================================
COMMIT 4 — RECEIVE WEBHOOK EVENTS
=========================================================

Implement POST support.

This endpoint must accept webhook events from Meta.

Requirements:
- Read the request body safely.
- Parse the JSON.
- For this temporary development phase only, pretty-print the payload to the server console using console.log(JSON.stringify(payload, null, 2)).
- Return immediately.
- Do NOT perform processing.
- Do NOT extract fields.
- Do NOT save anything.
- Do NOT send DMs.
- Do NOT verify signatures yet.

Return HTTP 200 JSON:
{
  "status": "ok",
  "message": "Webhook received."
}

=========================================================
ERROR HANDLING
=========================================================

If the request body cannot be parsed, return HTTP 400:
{
  "error": "Invalid JSON"
}

If an unexpected error occurs, return HTTP 500:
{
  "error": "Internal Server Error"
}

=========================================================
ENVIRONMENT
=========================================================

Update .env.example with:
WEBHOOK_VERIFY_TOKEN=replace_me_with_random_string

Add comments explaining:
- this value is chosen by us
- Meta never generates it
- the exact same value will later be entered into the Meta Developer Dashboard

=========================================================
CODE QUALITY
=========================================================

Requirements:
- Strict TypeScript
- No any types
- No ESLint warnings
- Reusable helper functions if appropriate
- Clean error handling
- Meaningful comments
- No dead code
- No unnecessary abstractions

=========================================================
README
=========================================================

Add a Webhook Verification section.

Explain:
- what a webhook is
- why Meta verifies ownership
- what the callback URL is
- what the verify token is
- why Meta sends a GET request first
- why it later sends POST requests

Explain the flow:

User comments
↓
Instagram
↓
Meta Webhook
↓
Our endpoint

=========================================================
LOCAL TESTING
=========================================================

Add instructions for:
- GET verification using the browser
- GET verification using curl
- POST requests using curl
- POST requests using Postman
- what should appear in the terminal

=========================================================
OUTPUT
=========================================================

After implementing everything, explain:

1. How Meta verifies ownership.
2. Why the verify token exists.
3. Why the challenge must be returned exactly.
4. How POST requests differ from GET requests.
5. Show an example Instagram webhook payload and explain every field.
6. Explain how keyword matching and DMs will build on this code.

Do not implement anything beyond this scope.

Important: this phase deliberately omits POST signature verification and logs full payloads for temporary debugging. Do not expose it to production traffic. Remove full-payload logging and add X-Hub-Signature-256 validation before enabling real automation.

You are a senior Next.js + TypeScript engineer.

I already have a working Meta Webhook integrated with my Next.js application. Instagram comments and messages are successfully reaching my webhook endpoint.

Your task is to implement the next stage of the automation.

Tech stack:
- Next.js App Router
- TypeScript
- Supabase
- Vercel
- Official Meta Graph API
- Existing Supabase client utilities (reuse them)
- Existing environment variable structure (reuse it)

Do not introduce new libraries unless absolutely necessary.

Implement both GET and POST handlers of the webhook route. Keep the route small and separate business logic into helper or service files.

WEBHOOK VERIFICATION

- Read hub.mode, hub.verify_token, and hub.challenge.
- Compare the verify token with the environment variable.
- Return the raw challenge when verification succeeds.
- Return HTTP 403 when it fails.

POST EVENT FLOW

- Validate X-Hub-Signature-256 against the exact raw request body with META_APP_SECRET before parsing JSON.
- Validate the webhook payload.
- Ignore unsupported event types and return HTTP 200 for them.
- Extract comment ID, comment text, Instagram user ID when available, username when available, and media ID in a dedicated parser.
- Normalize the comment with Unicode normalization, trim, and locale-independent lowercase.
- Use exact keyword matching only; do not use fuzzy or substring matching.

SUPABASE CAMPAIGN LOOKUP

Use the existing campaigns table and types. Find one campaign where:
- enabled = true
- normalized keyword exactly matches the normalized comment
- media ID matches when the campaign is scoped to specific media
- campaign belongs to the receiving Instagram account or authenticated owner

If no campaign exists, return HTTP 200 without further work.

PRIVATE REPLY

If a campaign exists, send an Instagram private reply using the comment ID and the documented private-reply form of the official Meta Graph API. Use campaign.message as the message content.

Implement this in a reusable server-only service such as sendInstagramPrivateReply(). Do not put Graph API code directly in the route.

PUBLIC COMMENT REPLY

Only after the private reply succeeds, optionally reply publicly to the original Instagram comment with:
Done! Check your DMs 📩

Implement this as a reusable function.

If the private reply fails, record and log a redacted error. Do not post a misleading success comment. Do not publicly expose internal failures unless the campaign explicitly configures a safe fallback reply.

IDEMPOTENCY AND ERRORS

- Claim a stable unique event key before calling Meta so webhook retries cannot send duplicate DMs.
- Treat duplicate and unsupported deliveries as successful no-ops.
- Log meaningful, redacted errors.
- Never expose internal errors or secrets in the HTTP response.
- Return the correct acknowledgement strategy for verified events, but do not silently discard failures that require a controlled retry.

MODULES

Use logical modules similar to:

app/api/webhooks/meta/route.ts
lib/instagram/webhook-parser.ts
lib/instagram/meta-client.ts
lib/instagram/send-private-reply.ts
lib/instagram/reply-to-comment.ts
lib/services/campaigns.ts
lib/services/delivery-events.ts

The exact names may differ, but keep responsibilities separate.

CODE QUALITY

- TypeScript only
- Strong typing
- No any
- Async/await
- Small reusable functions
- Good naming
- Comments only where useful
- Avoid duplicated code
- Follow Next.js App Router conventions
- Keep Meta tokens, app secrets, and Supabase secret keys server-only

Do not add analytics, Redis, BullMQ, background workers, or cron jobs in this phase.

Return production-quality code and explain the Meta endpoints, permissions, environment variables, tests, remaining dashboard steps, and any limits of inline processing.

You are a senior frontend engineer specializing in Next.js, TypeScript, Tailwind CSS, shadcn/ui and Supabase.

I already have an Instagram automation backend that:
- receives Instagram webhook events
- looks up campaigns in Supabase
- sends Instagram private replies
- replies to Instagram comments

Authentication and campaign Row Level Security already exist. Reuse them. Do not expose the dashboard or database mutations without server-enforced authorization.

Your task is to build a polished internal admin dashboard to manage campaigns using the existing project architecture and design system. Do not introduce unnecessary dependencies.

GOAL

Users should be able to:
- view campaigns they own
- search campaigns
- create campaigns
- edit campaigns
- delete campaigns
- enable or disable campaigns

Use the existing Supabase client utilities and types.

DATABASE

Use the existing campaigns table. Expected fields include:
- id
- owner_id
- media_id when supported
- reel_url when supported
- keyword
- message or dm_message
- public_reply when supported
- enabled
- created_at
- updated_at

Inspect the actual migration and generated types before coding. Do not invent a second schema or client.

PAGE

Create:
/dashboard/instagram

Use the existing authenticated dashboard layout.

Top section:
- page title
- short description
- New Campaign button

Below it, show a searchable campaign table with:
- Keyword
- Media scope
- Message Preview
- Status
- Created At
- Actions

Status badges:
- Green: Enabled
- Gray: Disabled

Message previews show the first 60 characters and end with ... when longer. A tooltip should expose the full message.

Actions include Edit and Delete, preferably using existing icons and accessible tooltips.

SEARCH

Add instant client-side keyword filtering over the already loaded owner-scoped campaigns.

EMPTY STATE

Show:
Instagram Campaigns

No campaigns yet.

Create your first automation to automatically send DMs when users comment specific keywords.

Include a prominent Create Campaign button.

CREATE AND EDIT

Use one responsive dialog for both operations.

Fields:
- Keyword: required, single-line, placeholder "guide"
- Message: required, multiline
- Media ID or Reel URL when the existing schema supports media scoping
- Optional public acknowledgement when supported
- Enabled: switch

Trim inputs and normalize the keyword consistently with the webhook matcher before saving.

Buttons:
- Cancel
- Create Campaign or Save Changes

Close after success and update local state immediately.

DELETE

Never delete immediately. Open an accessible confirmation dialog:

Are you sure you want to delete this campaign?
This action cannot be undone.

Buttons:
- Cancel
- Delete Campaign

Refresh local state after success.

ENABLE OR DISABLE

Allow status changes from the table using a Switch. Update Supabase immediately and revert optimistic state if the request fails.

UX

- Use optimistic UI where safe.
- Disable buttons while requests are pending.
- Prevent duplicate submissions.
- Show loading states and skeletons.
- Show success toasts for created, updated, deleted, enabled, and disabled states.
- Show meaningful, non-sensitive error toasts.
- Preserve keyboard navigation, visible focus, labels, and accessible dialog behavior.

COMPONENTS

Split the feature into focused components where useful, for example:

components/instagram/campaign-table.tsx
components/instagram/campaign-row.tsx
components/instagram/campaign-form-dialog.tsx
components/instagram/delete-dialog.tsx
components/instagram/status-switch.tsx
components/instagram/search-bar.tsx

Avoid large files and unnecessary abstractions.

DATA LAYER

Keep database logic outside visual components with functions such as:
- getCampaigns()
- createCampaign()
- updateCampaign()
- deleteCampaign()
- toggleCampaign()

Every mutation must verify the current user and constrain the operation by owner ID on the server. RLS remains enabled as defense in depth.

UI

Use existing shadcn/ui components when they are already installed, such as Card, Table, Dialog, Alert Dialog, Input, Textarea, Badge, Switch, Button, Tooltip, Dropdown Menu, and Skeleton.

Do not install the entire component library. Add only missing components that are necessary and consistent with the existing project.

The design should feel calm and polished, with generous spacing, rounded corners, subtle shadows, responsive dialogs, and a horizontally scrollable table when needed on mobile.

PERFORMANCE

- Fetch campaigns once on page load.
- Avoid unnecessary refetches.
- Update local state after successful CRUD operations.
- Do not leak campaigns between users through caching.

FUTURE EXTENSIBILITY

Keep the model and layout ready for future fields such as match type, delay, DM template, tags, analytics, and active hours. Do not implement them now.

CODE QUALITY AND TESTING

- TypeScript
- Server Components where appropriate
- Client Components only for interaction
- Strong typing
- Clean folder structure
- No duplicated logic
- Tests for authorization boundaries, validation, normalization, failed optimistic updates, and CRUD behavior
- Run lint, typecheck, tests, and production build

Return production-quality code plus a list of files changed, architectural decisions, security assumptions, environment requirements, and manual test steps.

Act as a senior full-stack engineer. Build a secure Instagram comment-to-DM automation dashboard in my existing Next.js App Router project using TypeScript, Supabase, Vercel, and Meta's Instagram API with Instagram Login.

Before editing code:
1. Inspect the project structure and existing auth, Supabase clients, validation, styling, tests, and conventions.
2. Explain the smallest implementation plan.
3. Do not mix Instagram Login with Facebook Login APIs. Use graph.instagram.com and the current instagram_business_* scopes for this implementation.
4. Ask before making an architectural change outside this feature.

FUNCTIONAL REQUIREMENTS
- Add an authenticated admin dashboard for campaigns.
- A campaign contains: optional Instagram media ID, optional Reel URL, keyword, DM message, optional public comment reply, enabled state, owner, and timestamps.
- Allow authenticated owners to create, edit, enable/disable, and delete only their campaigns.
- Normalize incoming comments with Unicode normalization, trim, and locale-independent lowercase.
- Default to an exact normalized keyword match. Do not use substring matching unless it is explicitly enabled later.
- If media_id is present, require the webhook media ID to match it.
- Ignore comments created by the professional account itself.

WEBHOOK ROUTE
- Create app/api/webhooks/meta/route.ts using the Node.js runtime.
- GET: verify hub.mode, hub.verify_token, and hub.challenge using META_VERIFY_TOKEN. Return the challenge only when verification succeeds; otherwise return 403.
- POST: read the raw request body exactly once with request.text().
- Validate X-Hub-Signature-256 using HMAC-SHA256 with META_APP_SECRET and a constant-time comparison before parsing JSON.
- Validate the payload shape. Never trust webhook fields blindly.
- Extract each Instagram comment event safely. Handle batched entries and changes.
- Build a stable event key from immutable event fields and claim it in instagram_delivery_events before making Meta API calls.
- Duplicate deliveries must return 200 without sending another DM or comment reply.
- Find one enabled campaign by normalized keyword, owner/account, and media ID when configured.
- Send one private reply using the comment ID through the documented private-reply form of the Instagram Messages endpoint.
- Only after the DM succeeds, optionally publish the configured public reply to the comment.
- Store sent, ignored, and failed outcomes without storing unnecessary commenter profile data or full webhook payloads.
- Return a successful acknowledgement for valid duplicate or ignored events. Use structured, redacted server logs.

META CLIENT
- Create a small server-only Meta client.
- Read the API version from META_GRAPH_API_VERSION; do not hardcode a version throughout the codebase.
- Use Authorization: Bearer rather than putting access tokens in URLs or logs.
- Add request timeouts and parse Meta error responses safely.
- Distinguish retryable errors such as timeouts and 5xx responses from permanent permission, policy, or validation errors.
- Never expose the app secret, access token, Supabase secret key, or raw webhook payload to the browser.

SUPABASE AND AUTH
- Reuse existing Supabase clients and authentication if present; do not create duplicates.
- Use the publishable key in the browser with Row Level Security.
- Use a separate server-only client with SUPABASE_SECRET_KEY only where elevated webhook access is required.
- Protect every dashboard route and mutation on the server. Hiding controls in the UI is not authorization.
- Validate all campaign input with the project's existing validation approach.

UX
- Match the existing design system exactly.
- Show empty, loading, success, and error states.
- Confirm destructive campaign deletion.
- Display whether a campaign applies to one media ID or all owned media.
- Explain that a private reply is limited by Meta policy and that further automated messages require user interaction and an allowed messaging window.

RELIABILITY
- Add tests for GET verification, invalid signatures, malformed payloads, exact keyword matching, media matching, self-comments, duplicate deliveries, Meta failure, DM success, and optional public reply behavior.
- Keep webhook processing idempotent.
- For an MVP, process inline and return promptly. Document when to move work to a durable queue; do not pretend a serverless fire-and-forget promise is reliable.

AFTER IMPLEMENTATION
- List every file created or changed.
- List environment variables without revealing values.
- List remaining Meta Dashboard, App Review, Supabase, and Vercel steps.
- Provide local and production verification steps.
- Note assumptions and security limitations.

Keep changes minimal, production-minded, and consistent with the existing codebase.