How it works — detailed use case

For Meta App Review · permission-by-permission walkthrough

This page mirrors the use case description submitted in the Meta App Review form, permission by permission, with the exact Graph API calls and the data flow. Reviewers can cross-reference this document against the screen recordings.

Permission 1 — instagram_content_publish

What the operator does

The operator (Vivek Pujari, sole user) produces a video locally in a separate editing pipeline. The operator opens the Learn3D Studio dashboard, selects a connected Instagram Business account, picks a media file, writes a caption, and chooses a schedule time.

What the tool does with the permission

1. Uploads the media to a private cloud storage bucket and generates a pre-signed URL.
2. At the scheduled time, calls POST /<ig_user_id>/media with media_type=REELS and the pre-signed video URL.
3. Polls GET /<container_id>?fields=status_code until the container reports FINISHED.
4. Calls POST /<ig_user_id>/media_publish with the container id.
5. Records the returned ig_media_id in the dashboard.

What the data is NOT used for

• No content is published to any account that is not owned and administered by the operator.
• No content is auto-generated by the tool — every post originates from the operator’s manual upload.
• No data is shared with third parties or resold.

Permission 2 — instagram_manage_messages

What the operator does

The operator authors per-account brand voice documents (a markdown file per Instagram Business account) describing tone, FAQs, and topics the bot may address. The operator enables auto-reply per account via the dashboard.

What the tool does with the permission

1. A person on Instagram sends a DM to the operator’s Instagram Business account.
2. Meta delivers a webhook POST to the tool’s HTTPS callback URL. The X-Hub-Signature-256 header is HMAC-verified against the Meta App Secret before any processing.
3. The inbound message runs through 13 safety gates: HMAC signature, content moderation (OpenAI moderation endpoint), denylist match, per-sender rate limit (max 10 replies per sender per hour), inbound length cap, intent-skip classifier (skips obvious spam/sales pitches), and burst-batching (collapses rapid follow-ups into one reply within a 10-second window).
4. The tool loads the operator’s brand voice document for the receiving account into the LLM prompt as system context, then asks gpt-5-mini to generate a single reply ≤ 1000 characters.
5. The generated reply is sent via POST /<ig_user_id>/messages using the Send API with aMESSAGE_TAG of RESPONSE (i.e., within the 24-hour standard messaging window). The HUMAN_AGENT tag is never used.
6. The reply text and timing are recorded in the operator’s dashboard.

What the data is NOT used for

• No proactive outbound messaging. The tool only replies to messages a person has sent first.
• No data sharing with third parties (other than the operator’s LLM provider, which receives the message text + brand voice context only).
• No retargeting, advertising, or behavioral profiling.
• No long-term retention of message content beyond the operator’s 365-day audit window.

Permission 3 — instagram_manage_comments

What the operator does

Same as messages — the operator enables comment auto-reply per account in the dashboard.

What the tool does with the permission

1. A person comments on a post published from the operator’s Instagram Business account.
2. Meta delivers a webhook on the comments field. Signature verified via HMAC-SHA256.
3. The comment runs through the same 13 safety gates as DMs, plus the tool fetches the source post’s caption via GET /<media_id>?fields=caption and injects it into the LLM prompt as post_context so replies can reference the post topic.
4. A reply is posted via POST /<comment_id>/replies (truncated to ≤ 280 characters per Instagram’s display recommendations).

Permission 4 — instagram_manage_insights

What the operator does

Opens the dashboard’s Insights tab to review post performance.

What the tool does with the permission

1. After each successful publish, a worker schedules four Insights snapshots at +1h, +24h, +7d, and +30d.
2. Each snapshot calls GET /<ig_media_id>/insights?metric=reach,likes,comments,saves,shares,views (the exact metrics vary by post type).
3. Snapshots are stored as time-series rows in Postgres and rendered on the operator’s dashboard as a per-post leaderboard.

What the data is NOT used for

• Insights are visible only to the operator on the password-protected dashboard.
• No insights data is exported, shared, or used for advertising decisions.

Security and access controls

• Access tokens encrypted at rest. Page Access Tokens are encrypted with Fernet (AES-128-CBC + HMAC-SHA256) using a key stored separately from the database.
• Webhook signature verification. Every inbound webhook is HMAC-SHA256 verified against the Meta App Secret before any side-effect; mismatches are persisted to an audit table and never invoke the reply pipeline.
• Dashboard auth. HTTP Basic Auth gates all dashboard pages; the operator’s credentials are stored only in the deployment environment.
• Single-tenant database. One Postgres instance serves only the operator; there is no multi-tenant row-level filtering needed because no other users exist.
• Inter-service auth. The dashboard frontend (Vercel) signs every request to the backend API (Railway) with a shared HMAC secret; unsigned requests are rejected.

Annual Data Use Checkup commitment

The operator commits to completing Meta’s annual Data Use Checkup on schedule for this app. If the checkup is missed, the resulting permission revocation is accepted and the tool will re-submit through App Review.