Instagram DM Auto-Reply Bot

An AI assistant that answers Instagram DMs in your own voice, qualifies leads, and quotes from your rate card, so enquiries get a fast, on-brand reply even when you're busy. Built on the Instagram Messaging API and Claude.

Originally built for a product photographer to handle pricing enquiries, but the business identity and rate card are fully configurable, so it works for any service business that fields quote requests over Instagram DMs.

What it does

• Replies as you. Tone and pricing come from a style_guide.md you write; the bot speaks in the first person as the business owner.
• Keyword-triggered. Only engages on relevant DMs (pricing/booking/enquiry keywords), so normal chats are left alone.
• Qualifies before quoting. Asks what it needs (quantity, usage, references, timeline) then gives a real quote from your rate card.
• Handles your outreach too. If you message a client first and they reply, the bot picks the conversation up. If you jump into a live bot chat, it backs off.
• Knows when to defer. Off-topic messages (spam, "who is this?") are left for you; tricky ones get a holding reply and an alert.
• Captures leads. After quoting it asks for an email and pings you a summary.
• Optional Telegram mirror. Every conversation mirrors to a Telegram chat, with alerts when the bot is unsure.
• Optional voice notes. Transcribes voice-note DMs via ElevenLabs.
• Catch-up tool. catchup.py drafts (and optionally sends) replies to your existing backlog of unreplied DMs.

How it works

Instagram DM
  -> Meta webhook (HTTPS)
    -> Flask app (app.py) verifies + routes
      -> keyword/engagement check (triggers.py, state.py)
        -> Claude drafts a reply in your voice (agent.py + style_guide.md)
          -> reply sent back via the Instagram API
             (+ optional Telegram mirror / ElevenLabs transcription)

Project layout

File	Purpose
app.py	Flask webhook server + message routing
agent.py	Claude prompt + reply/summarise logic
triggers.py	Keyword list that decides when to engage
state.py	Per-conversation memory (JSON file)
links.py	Your website pages the bot can share
notify.py	Telegram mirroring + alerts (optional)
transcribe.py	ElevenLabs voice-note transcription (optional)
catchup.py	Draft/send replies to existing unreplied DMs
style_guide.example.md	Template for your private voice + rate card
deploy/	launchd service template for 24/7 running

Setup

1. Prerequisites

• Python 3.9+
• An Instagram Business or Creator account
• A Meta developer app with the Instagram product added and the messages webhook subscribed
• An Anthropic API key
• A public HTTPS URL to your server (e.g. ngrok, Cloudflare Tunnel, or any host)

2. Install

git clone <your-fork-url> igbot && cd igbot
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

3. Configure

cp .env.example .env            # fill in your keys + business identity
cp style_guide.example.md style_guide.md   # write your voice + rate card

4. Run

python app.py                   # serves on :5000
# expose it, e.g.:  ngrok http 5000

Then set your Meta webhook callback URL to https://YOUR-PUBLIC-URL/webhook with the verify token from your .env, and subscribe to the messages field.

For 24/7 running on macOS, see deploy/com.example.igbot.plist.

Note: while your Meta app is in Development mode, only accounts with a role on the app can trigger it. Switch the app to Live to handle real customers. If you only build for your own account, you may not need full App Review.

Security notes

• Never commit secrets. .env, style_guide.md, state.json, and logs/ are gitignored. Double-check before pushing.
• Keep webhook signature verification ON (SKIP_SIG_VERIFY empty/0) in production.
• The bot only acts on Instagram DMs and never performs irreversible actions on its own.

License

MIT (see LICENSE). Provided as-is; you are responsible for complying with Meta's Platform Terms and Instagram's policies.