fb-comment-automation

name

fb-comment-automation

description

Work on Facebook/Messenger comment automation — the feature that auto-replies to, likes, or hides comments on Facebook Page posts. Use when changing the comment webhook path, the automation matching/filter logic, reply dispatch (text/flow/AI agent), hide rules, post targeting, or the fb-comments builder feature. Read this BEFORE editing anything under comment-automation to avoid the silent-failure traps.

Facebook Comment Automation

Full reference: docs/fb-comment-automation.md. Read it before non-trivial changes. This skill is the quick map + the traps.

Where things live

Concern	Path
Automation loop, filters, dispatch	apps/worker/src/integration/handlers/comment-automation/index.ts
AI-agent reply (generate + deliver)	apps/worker/src/integration/handlers/comment-automation/ai-reply.ts
Attachment info (image/video for hide)	apps/worker/src/integration/handlers/comment-automation/comment-attachment.ts
Receive comment + enqueue automation	apps/worker/src/integration/handlers/received-message.ts (receiveComment)
Webhook parse + enqueue	integrations/messenger/src/handlers/webhook.ts
Webhook value schema	integrations/messenger/src/schema.ts (messengerFeedCommentValueSchema)
DB queries (match/dedup/schedule)	packages/business/src/fb-comment-automation/service.ts
Schema + option/reply Zod partials	packages/database/src/schema/fb-comment-automation.ts, .../partials/fb-comment-automation.ts
Dedup ledger	packages/database/src/schema/fb-comment-automation-reply.ts
Job types	packages/worker-config/src/queues/integration/index.ts
Builder feature (form, actions)	apps/builder/src/features/fb-comments/
Tests	apps/worker/__tests__/comment-automation.test.ts

Data-flow in one line

feed webhook (verb "add") → incomingComment → receiveComment → processCommentAutomation → (AIAgent) commentAIReply.

The traps (read before editing)

1. parent_id is ALWAYS present and equals post_id for top-level comments. A truthy parentId does NOT mean "reply." Use isCommentReply(parentId, postId) (parentId !== postId). Breaking this + default ignoreCommentReplies: true silently drops every top-level comment.

2. Post ids are composite {pageId}_{storyId}; the picker stores 3 different formats (published/ads composite, reels bare id, manual free-text). Always compare through normalizePostId (trailing story id). Never post.value.includes(rawPostId).

3. Every skip must log. The loop uses logAutomationSkipped(..., reason) before each continue. processCommentAutomation returns void → BullMQ always logs returnValue: null, so a skip with no log is undebuggable in production. Add a skip log for any new filter.

4. AIAgent reply ≠ DM auto-responder. publicReply/privateReply of type AIAgent store the selected agent id in value. Generation uses generateAIReplyText (tools + rich OFF, returns text only); the comment handler routes public → public comment reply (type:"comment" + replyToCommentId), private → DM. Do NOT route through processAutomatedResponse — it uses the workspace default agent and always sends a DM.

5. Dedup ledger is dual-purpose. fbCommentAutomationReplyModel rows (automationId, contactId, postId) are written after every successful reply and read by both replyOncePerUserPerPost (same post) and replyToUsersWhoCommentedOnOtherPosts (other post). The unique index FBCommentAutomationReply_dedup_idx already serves (automationId, contactId) + postId != ? queries — no new index needed; use a LIMIT 1 existence check, not $count.

6. Instagram is not implemented. Builder never sets type, so it defaults to messenger. Don't add IG-only behavior expecting it to run. IG private-DM text is out of scope.

7. options.trackUserTags is a no-op (defined, not implemented). Every other option (including replyToUsersWhoCommentedOnOtherPosts) IS enforced — see the option table in the docs.

Adding a new filter option (recipe)

1. Add the field to fbCommentOptionsSchema (partials) + DB default in the schema file (jsonb default string).
2. If it needs a DB lookup, add a method to fbCommentAutomationService (reuse the dedup table + its index where possible; prefer LIMIT 1 existence checks).
3. Add the guard inside the loop in processCommentAutomation, with a logAutomationSkipped(..., reason) before continue.
4. Surface the toggle in apps/builder/src/features/fb-comments/components/fb-comment-form.tsx and add i18n keys to apps/builder/messages/en.json + vi.json.
5. Extend apps/worker/__tests__/comment-automation.test.ts.

Adding a new reply type (recipe)

1. Extend fbCommentReplySchema.type (partials).
2. Handle it in BOTH executePublicReply and executePrivateReply (index.ts). Public = message type:"comment" + replyToCommentId via sendChannelMessage; private = sendPrivateReply (messenger only).
3. Update willSendReply so dedup/repliesCount only count when a reply is actually dispatchable (e.g. require value).
4. If it needs async work (like AIAgent), add a dedicated job in worker-config, a handler, and a case in apps/worker/src/integration/worker.ts (the never exhaustiveness guard forces this — type + dispatch + handler land together).

Verify

pnpm --filter worker vitest run __tests__/comment-automation.test.ts
pnpm --filter worker check-types
pnpm lint

Production sanity after deploy: comment on (a) a normal post, (b) a reel, (c) a comment with a bare-domain link + hide-link on, (d) an automation with reply = AI Agent — and confirm each fires or logs a clear skip reason.