ManyChat

Build a self-hosted Instagram/Messenger DM autoresponder called "dmflow". Node 20, TypeScript, Fastify, better-sqlite3, no ORM, no frontend framework.

Stack decisions are final, do not offer alternatives.

What it does:
1. POST /webhook receives Meta Messenger and Instagram messaging webhook events. GET /webhook handles the hub.challenge verification using VERIFY_TOKEN from .env.
2. Verify the X-Hub-Signature-256 header against APP_SECRET and reject anything that fails.
3. Store contacts (platform, psid, first_seen, last_inbound_at, tags) and a messages log in SQLite at ./data/dmflow.db. Create the schema on boot if missing.
4. Load flows from ./flows/*.json. A flow has: id, triggers (array of keyword strings, matched case-insensitively on the inbound text, plus an optional "default" fallback flow), and steps. Step types: send_text, send_buttons (title plus up to 3 postback buttons), wait (seconds), add_tag, set_field, goto (another flow id).
5. Run a small state machine per contact: current flow id, current step index, collected fields. Persist state so a restart resumes correctly.
6. Outbound sends go to the Graph API /me/messages with PAGE_ACCESS_TOKEN. Respect the 24 hour window: if last_inbound_at is older than 24 hours, refuse to send and log the reason instead of retrying forever.
7. Retry failed sends up to 3 times with exponential backoff, then dead-letter the message into a table.
8. Serve a single read-only HTML page at / rendering contacts, their tags, and the last 50 messages. Plain server-rendered HTML, no JS build step.

Out of scope: WhatsApp, SMS, email, a visual flow editor, multi-user auth, analytics dashboards, broadcast sending.

Secrets in .env only: VERIFY_TOKEN, APP_SECRET, PAGE_ACCESS_TOKEN, PORT. Ship .env.example. No telemetry, no third party services beyond Meta's Graph API.

Include two example flows in ./flows: a keyword flow for "price" and a default greeting flow.

Write a README that states plainly that until the Meta app passes review for advanced messaging permissions, this will only reply to accounts added as app testers, and that this is a limitation of Meta, not of the code.

# AGENTS.md — Build guide for ManyChat

## Project scope
A self-hosted webhook server that receives Instagram or Messenger events and runs your keyword-triggered reply flows from a JSON config, storing contacts and state in SQLite.

Catalogue verdict: no. The flow builder is the visible part and it is not the hard part: keyword triggers, branching, delays and tags are a weekend of CRUD and a state machine. The hard part is that every message goes through Meta, and Meta decides who gets to send it. To reply to arbitrary strangers who DM your Instagram account you need a reviewed app with advanced messaging permissions, a linked Facebook page, business verification, and compliance with the 24 hour window and human agent tag rules. ManyChat has already cleared all of that and maintains it as the APIs churn. A DIY bot works fine for accounts you personally control in dev mode, which is exactly the audience that does not need automation.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Meta developer app with a professional Instagram account linked to a Facebook page
- App review for advanced messaging permissions if you want to reply to non-testers
- Publicly reachable HTTPS endpoint for the webhook (tunnel or small VPS)
- Willingness to fix the integration whenever Meta changes the API

## Stack and architecture
- Build a self-hosted Instagram/Messenger DM autoresponder called "dmflow". Node 20, TypeScript, Fastify, better-sqlite3, no ORM, no frontend framework.
- Store contacts (platform, psid, first_seen, last_inbound_at, tags) and a messages log in SQLite at ./data/dmflow.db. Create the schema on boot if missing.
- Interface for this chat marketing / DM automation workflow: a focused chat marketing / DM automation input, review, and export interface.

## Security and data integrity
- Verify the X-Hub-Signature-256 header against APP_SECRET and reject anything that fails.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Pre-approved Meta Business Partner status, so your bot only talks to testers until review passes.

## Agent implementation rules
- Project rule, data: Store contacts (platform, psid, first_seen, last_inbound_at, tags) and a messages log in SQLite at ./data/dmflow.db. Create the schema on boot if missing.
- Project rule, behavior: Run a small state machine per contact: current flow id, current step index, collected fields. Persist state so a restart resumes correctly.
- Project rule, recovery: Verify the X-Hub-Signature-256 header against APP_SECRET and reject anything that fails.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this chat marketing / DM automation operation with sample or user-owned data: Run a small state machine per contact: current flow id, current step index, collected fields. Persist state so a restart resumes correctly.
- Show a concrete result or export: Visual flow builder for automated Instagram, Messenger, WhatsApp and SMS conversations.
- State the practical limit: Pre-approved Meta Business Partner status, so your bot only talks to testers until review passes.

## Engineering roadmap
1. Phase 1, architecture and data: Build a self-hosted Instagram/Messenger DM autoresponder called "dmflow". Node 20, TypeScript, Fastify, better-sqlite3, no ORM, no frontend framework. Store contacts (platform, psid, first_seen, last_inbound_at, tags) and a messages log in SQLite at ./data/dmflow.db. Create the schema on boot if missing.
2. Phase 2, implement: Run a small state machine per contact: current flow id, current step index, collected fields. Persist state so a restart resumes correctly.
3. Phase 3, implement: A self-hosted webhook server that receives Instagram or Messenger events and runs your keyword-triggered reply flows from a JSON config, storing contacts and state in SQLite.
4. Phase 4, review and output: Visual flow builder for automated Instagram, Messenger, WhatsApp and SMS conversations.
5. Phase 5, recovery and acceptance: Verify the X-Hub-Signature-256 header against APP_SECRET and reject anything that fails. Verify this invariant with a saved fixture: A failed platform call retains the draft and cannot be marked published; retries use a stable delivery key. State the practical limit: Pre-approved Meta Business Partner status, so your bot only talks to testers until review passes.

## Paid-product capabilities outside this build
- Pre-approved Meta Business Partner status, so your bot only talks to testers until review passes
- The visual flow editor that non-engineers can actually edit without touching JSON
- Multi-channel parity: WhatsApp, SMS and email in one contact record
- Comment-to-DM triggers, story reply triggers, ads-click entry points and other Meta surface coverage
- Deliverability guardrails: 24 hour window handling, message tags, broadcast policy compliance baked in

## Implementation prompt
Build a self-hosted Instagram/Messenger DM autoresponder called "dmflow". Node 20, TypeScript, Fastify, better-sqlite3, no ORM, no frontend framework.

Stack decisions are final, do not offer alternatives.

What it does:
1. POST /webhook receives Meta Messenger and Instagram messaging webhook events. GET /webhook handles the hub.challenge verification using VERIFY_TOKEN from .env.
2. Verify the X-Hub-Signature-256 header against APP_SECRET and reject anything that fails.
3. Store contacts (platform, psid, first_seen, last_inbound_at, tags) and a messages log in SQLite at ./data/dmflow.db. Create the schema on boot if missing.
4. Load flows from ./flows/*.json. A flow has: id, triggers (array of keyword strings, matched case-insensitively on the inbound text, plus an optional "default" fallback flow), and steps. Step types: send_text, send_buttons (title plus up to 3 postback buttons), wait (seconds), add_tag, set_field, goto (another flow id).
5. Run a small state machine per contact: current flow id, current step index, collected fields. Persist state so a restart resumes correctly.
6. Outbound sends go to the Graph API /me/messages with PAGE_ACCESS_TOKEN. Respect the 24 hour window: if last_inbound_at is older than 24 hours, refuse to send and log the reason instead of retrying forever.
7. Retry failed sends up to 3 times with exponential backoff, then dead-letter the message into a table.
8. Serve a single read-only HTML page at / rendering contacts, their tags, and the last 50 messages. Plain server-rendered HTML, no JS build step.

Out of scope: WhatsApp, SMS, email, a visual flow editor, multi-user auth, analytics dashboards, broadcast sending.

Secrets in .env only: VERIFY_TOKEN, APP_SECRET, PAGE_ACCESS_TOKEN, PORT. Ship .env.example. No telemetry, no third party services beyond Meta's Graph API.

Include two example flows in ./flows: a keyword flow for "price" and a default greeting flow.

Write a README that states plainly that until the Meta app passes review for advanced messaging permissions, this will only reply to accounts added as app testers, and that this is a limitation of Meta, not of the code.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.