Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Data Flow - Comment Automation: Private and Public Replies
Overview
An account owner writes a rule: keywords or any comment, which posts it covers, and how to answer. A rule can send the commenter a private reply (a direct message, with an optional link), post a public reply under the comment, or both; each is switched on and off on its own. When someone comments on a post or reel of a connected Instagram professional account and a rule answers the comment, Meta sends the comment to the Worker's webhook, and the Worker sends the private reply through Instagram's messages endpoint and posts the public reply through the comment's replies endpoint. A followers-only rule first asks the person to follow and reply, and sends the link once Instagram confirms the follow.
The two replies are separate jobs with separate statuses, retries, limits, cooldowns and reviews (ADR-044). A failure of one never repeats the other.
Instagram comment Instagram message (followers-only rules only)
-> Meta webhook POST /api/webhooks/instagram (signed with X-Hub-Signature-256)
-> verifyMetaWebhook 1 MB limit, HMAC-SHA256 over the raw body with the app secret
-> parseInstagramWebhook comments changes and messaging events; anything else is counted and dropped
-> automationWebhook.ingest rules for the account -> match -> store every comment with its public reply job
in one transaction (dedupe); messages from people a followers-only reply waits
for -> follow-up jobs
-> 200 {"success":true} only after both are stored; a failure answers 5xx and Meta retries for 36 hours
-> waitUntil: send the new private replies, then the new follow-ups, then the new public replies
claim -> check -> reserve within limits -> POST /<ig-id>/messages or /<comment-id>/replies -> finish
-> every minute (* * * * *): dispatch: due private replies, follow-ups and public replies, recovery of stopped runs
-> every 5 minutes, off the quarter: reconcile: expire overdue jobs, look for lost replies (conversations for private
ones, the comment's replies for public ones), report queue health
-> daily (0 0 * * *): token refresh, then retention in batches
The database is the queue: a matched comment's row in automation_comments is the job that sends its private reply, a row in automation_public_replies is the job that posts its public reply, and a row in automation_followups is the job that answers a person's reply to a followers-only message. There is no Cloudflare Queue (ADR-040, ADR-043, ADR-044).
What Instagram Allows
Checked against Meta's documentation on 2026-10-16:
| Rule | Value | Source |
|---|---|---|
| API setup | Instagram API with Instagram Login (graph.instagram.com), the setup Twiligent already connects with |
Instagram Platform overview |
| Permissions | instagram_business_basic, instagram_business_manage_comments (comments webhook, private replies, public replies and reading a comment's replies), instagram_business_manage_messages (messages webhook, follow-ups, follow checks, conversations); Twiligent's OAuth already asks for all three |
Private replies, webhook fields, User Profile API |
| Access level | Advanced Access for the comments and messages webhook fields; Business verification for production; the app must be Live |
Webhooks setup |
| Accounts | Professional (Business or Creator) accounts only; the account must be public, since private accounts get no comment notifications | Webhooks setup |
| Replies per comment | One private reply, text only in the documented request; a follow-up only after the person replies, within 24 hours | Private replies |
| Reply window | 7 days after the comment (Live comments: only during the broadcast, not supported here) | Private replies |
| Follow status | is_user_follow_business from the User Profile API, only after the person has sent the account a message (or tapped an icebreaker or persistent menu); before that Instagram answers "User consent is required to access user profile" |
User Profile API |
| Private reply rate | 750 an hour per professional account for posts and reels | Messenger Platform rate limits |
| Public replies | POST /<comment-id>/replies with message answers the new reply's id. Only top-level comments take replies; a reply to a reply lands in the top-level thread. Hidden comments and comments on live video cannot be replied to |
IG Comment Replies, Comment Moderation |
| Reading replies | GET /<comment-id>/replies lists a comment's replies; a deleted comment's cannot be read |
IG Comment Replies |
| Public reply rate | No separate number: comment calls count against the Business Use Case limit of 4,800 calls times the account's impressions in 24 hours, shared with insights. Instagram blocks accounts that comment like a bot (code 368) without publishing a threshold | Instagram Platform overview |
| Send API rate | 300 calls a second per account for text and links (follow-ups) | Messenger Platform rate limits |
| Conversations API rate | 2 calls a second per account | Messenger Platform rate limits |
| Message size | Text up to 1,000 bytes | Messaging API |
| Webhook retries | Retried with decreasing frequency for 36 hours until a 200; duplicates must be handled | Webhooks setup |
| Webhook fields | Every field selected for the app reaches every connected account; fields cannot be chosen per account | Webhooks setup |
The general Instagram Platform call quota is a different limit from the 750 private replies an hour, and neither is a daily DM allowance. Twiligent's own limits stay below them and are configurable. Because Meta publishes no safe pace for public replies, Twiligent keeps its own: 60 an hour per account by default, rotating wordings, and one public reply per person and post a day.
Setup: Getting Comments and Messages to the Worker
- The app-level webhook (Meta dashboard, Instagram, API setup with Instagram login, Configure webhooks): callback URL
https://<worker>/api/webhooks/instagram, the Verify Token fromINSTAGRAM_WEBHOOK_VERIFY_TOKEN, and thecommentsfield. Followers-only rules also need themessagesfield. Meta checks the URL withGET ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...;automationWebhook.challengeAnswer()compares the token in constant time and answers the bare challenge. - The account-level subscription: Instagram sends an account's events only after
POST /<ig-id>/subscribed_apps?subscribed_fields=...with that account's token. Twiligent asks forcomments, and forcomments,messageswhile an enabled followers-only rule of the account exists. It subscribes when a rule is turned on or the followers-only option changes, and from the "Turn on comment events" or "Turn on message events" button (POST /api/automations/accounts/:accountId/subscribe). The time and the fields Instagram confirmed are kept inautomation_accounts.subscribed_atandsubscribed_fields. If Instagram refusesmessages, Twiligent subscribes tocommentsalone and the account shows "Follow checks off". If Instagram refuses entirely, the rule is still saved and the page shows the account as not receiving comments.
Selecting messages in the Meta dashboard sends every direct message to every connected account to the Worker. Each one is a Worker request and one database call, so select it only when a followers-only rule is used.
Signatures: Instagram Login apps sign with the Instagram app secret (INSTAGRAM_APP_SECRET). META_APP_SECRET, the Meta app's own secret, is accepted as a second key because the dashboard shows both and developers report each in use.
Intake: POST /api/webhooks/instagram
verifyMetaWebhookrefuses a body over 1 MB, reads the raw bytes, and checksX-Hub-Signature-256against each configured secret withcrypto.subtle.verify(constant time). No secret configured answers 503; a bad signature 401, before any database work.parseInstagramWebhookrefuses a body whoseobjectis notinstagram(400). Inside it:- each
commentschange becomes an event (comment id fromidorcomment_id, author, text, media, the entry's account id andtime); - each
messagingevent with amessageor apostbackbecomes a message event (sender, message id, the event's timestamp). Its text is never read. The account's own echoes,is_selftest messages and deleted messages are skipped; - other fields and malformed entries are counted as unsupported and dropped.
- each
automationWebhook.ingest()groups the comments by Instagram account id and callsautomation_rules_for_ig_useronce per account: the enabled rules of every connected Twiligent account with thatigUserId, oldest account first. An account with no enabled rule stores nothing.- Each comment is classified:
- the account's own comment:
ignored, reasonown_comment. This also keeps the account's public replies, which Meta delivers back as comments, from being answered - no text:
ignored,no_text - no rule answers it:
ignored,no_match, stored without its text or author - a rule answers it:
queued(orskippedwith reasonprivate_reply_offwhen the rule sends no private reply), with the rule, the author and the text (at most 2,200 characters). When the rule posts a public reply, one of its texts is picked by a hash of the comment id, so every copy of the notification and every check agree on the words
- the account's own comment:
store()callsstore_automation_commentsonce: in one transaction it inserts the comments withon conflict do nothingon the unique(ig_user_id, comment_id), then a public reply job for each comment whose rule asks for one, joined to the comment as stored and only while the same rule answers it, withon conflict do nothingon the uniqueautomation_comment_id. A notification Meta delivers again inserts nothing; only the new comment ids and public reply ids come back.- Message events are grouped by account, and
automation_followups_for_messagesruns once per account. It makes a follow-up for a sender whose followers-only reply was accepted in the last 7 days and still waits for them (gate_status = 'awaiting_reply', a minute of slack for the two clocks). A message Meta delivers again inserts nothing (unique (ig_user_id, trigger_message_id)), and a second message while a follow-up is open inserts nothing (one open follow-up per comment). Messages from anyone else are not kept. - The controller answers
200 {"success":true}and hands the new private reply ids, the new follow-up ids and the new public reply ids, in that order, toinBackground(), which builds services with their own 25 second deadline (the request's signal ends with the response). The three runs share the background work's subrequests and its 20 seconds.
If storing fails, the request fails with 5xx, and Meta delivers the notification again later. Nothing is acknowledged that is not stored.
expires_at is the notification time plus 7 days. Meta's payload has no comment time, and a redelivered notification carries a later time, so the window can be a little generous; a reply sent after Instagram's window is refused there and recorded as failed.
Matching (backend/lib/automationMatching.ts)
- Text is normalised with NFKC (full-width letters fold to plain ones) and runs of spaces collapse; matching ignores case unless the rule says otherwise.
contains: the keyword appears as whole words (a letter or digit on either side breaks the match, so GUIDE never matches GUIDELINES). Phrases work across spaces; regular expression characters are literal.exact: the whole comment equals the keyword once spaces, punctuation and emoji at its edges are removed.any: every comment with text answers, emoji included. Such a rule has no keywords (keywordsProbleminlib/automationRules.ts, and a check constraint).- A rule covers every post when
media_idsis empty, or only the listed posts. A comment never triggers a rule meant for another post. - When several rules could answer, the most specific one does: rules for this post before rules for every post, and in each group keyword rules before any-comment rules; then the oldest. One rule answers a comment, and a comment is one row, so a comment never gets two private replies.
- One rule answers a comment, with its private reply, its public reply or both; a comment never gets two public replies.
POST /api/automations/testruns the same matching on a sample comment and returns the composed first private message; it stores and sends nothing.
Delivery of Private Replies (backend/services/automationProcessor.ts)
run({ ids?, limit?, subrequests?, timeBudgetMs? }) returns at once when AUTOMATION_PAUSED is true. Otherwise it claims up to the batch size and settles each job in turn, so each account's replies keep their order and the run never opens more than one connection to Instagram at a time. It reports the subrequests it used, so the dispatch can give the rest to follow-ups.
- Claim (
claim_automation_comments): due jobs (queuedorretry_waitwithnext_attempt_at <= now) and jobs whose run stopped (processingfor more than 20 minutes).- Accounts with waiting jobs are found with a loose index scan, one probe per account, however long one account's queue is.
- Accounts that are paused, cooling down or at their hourly limit are left out, so their jobs wait in place instead of being claimed and handed back on every run.
- Each account's oldest due jobs are locked as they are read (
FOR UPDATE SKIP LOCKED), so runs at the same moment take different jobs. - Accounts take turns: each account's oldest job first, then each one's second, until the batch is full. An account alone can fill the batch; a busy one cannot hold back another.
- The same call turns any
sendingjob older than 20 minutes intoneeds_review. It returns the rule's reply, its followers-only fields and the account's token with each job.
- Check (
readinessPlan): an expired comment becomesexpired, a rule that was turned off or removedskipped, an account without a tokenfailed. No limit is spent on these. - Reserve (
reserve_automation_send): one transaction under an advisory lock, so every Worker sees the same counts and two jobs cannot both take the last free send. In order: a paused account holds the job; an account cooldown waits for it; the commenter already got the daily number of replies from this account (counting other comments, not retries of this one) skips it; then the rule's, account's, user's and instance's hourly limits, counting private replies only. When a scope is full, the job waits until the oldest send in that hour is an hour old; a full account is also marked (automation_accounts.limited_until) so later claims leave its jobs alone. On success the job becomessending, its attempts count goes up, and anautomation_attemptsrow records the request, with the sha-256 digest of the exact text, before it leaves. - Send (
sendPrivateReply):POST https://graph.instagram.com/v25.0/<ig-id>/messageswith{ recipient: { comment_id }, message: { text } }and the account's token as a Bearer header, 10 second timeout, never repeated inside the call. The text is the reply and link, or for a followers-only rule its request to follow and reply. Only the timeout can cut it off: a run starts a send only with the whole timeout and 2 seconds to spare, so the run's own deadline never turns a send into an unknown outcome. - Finish (
finish_automation_send): records the outcome on the attempt and the comment in one transaction, keeps who Instagram says received an accepted reply (recipient_id, else the commenter's id), starts the followers-only wait (gate_status = 'awaiting_reply'), and sets a cooldown or a hold on the account when the answer calls for one.
A database error on one job is logged and the run moves on; that job's claim or reservation expires and the recovery above picks it up.
Budgets. Each run knows how many subrequests it may still make (the Workers Free plan allows 50 per invocation) and how long it may keep starting sends:
| Run | Subrequests | Time to start sends |
|---|---|---|
| Webhook, after the response | 50, less 10 for the request's own middleware, less the intake's queries | 20 seconds |
| Dispatch, every minute | 39 for private replies, keeping 11 for public replies; follow-ups get what private replies did not use, public replies the rest | 50 seconds, shared in that order |
| Retry from the activity list (private or public) | 40 | 20 seconds |
The claim takes only as many jobs as the budget pays for (one for the claim, one spare, three per reply). When time runs short or the run is cancelled, it hands every job it has not started back in one update (returnUnstarted: processing to queued, due at once), so they go out on the next run instead of waiting for the 20 minute lease.
Clocks. New and retried jobs are due 30 seconds in the past, so a database clock slightly behind the Worker's still finds them due on the immediate run.
What each answer does
| Instagram's answer | Comment | Attempt | Account |
|---|---|---|---|
200 with message_id |
accepted, message_id and recipient kept |
accepted |
|
| Codes 4, 17, 32, 613, 80002, 80006 or HTTP 429 | retry_wait until the cooldown ends |
rate_limited |
cooldown from X-Business-Use-Case-Usage (estimated_time_to_regain_access), else 15 minutes |
| Code 368 (temporarily blocked) | retry_wait |
rejected |
24 hour cooldown |
| Codes 1, 2 or HTTP 5xx | retry_wait after 1, 2, 4, 8 minutes (at most an hour) plus up to 30 seconds; failed after 5 tries |
rejected |
|
| Code 10900 or subcode 2534023 (already replied) | skipped |
rejected |
|
| Codes 3, 190, 200, a bare 10, subcode 2534041 (token or permission) | back to queued, held |
rejected |
paused with the reason: reconnect, then resume |
| Code 551, 10903; subcodes 2534014, 2534022, 2534025, 2018001 (not allowed for this comment) | failed |
rejected |
|
| Any other error | failed, with Instagram's message |
rejected |
|
| Timeout, connection lost, unreadable 200 | needs_review |
ambiguous |
|
| The Worker refused the request (subrequest limit) | retry_wait, 5 minutes |
rejected |
A wait that would end after the 7 day window makes the comment expired instead.
Public Replies (backend/services/automationPublicReplyProcessor.ts)
A public reply is its own job in automation_public_replies, created with its comment at intake. It follows the same claim, check, reserve, send and finish steps as a private reply, and never reads or changes the comment's private reply.
- Claim (
claim_automation_public_replies): the same loose index scan, turns between accounts andFOR UPDATE SKIP LOCKEDas private replies. Accounts that are paused, or whose public replies are cooling down (public_cooldown_until) or at their hourly limit (public_limited_until), are left out; a private reply cooldown does not hold public replies. Asendingreply older than 20 minutes becomesneeds_reviewwith reasoninterrupted. - Check (
publicReadinessPlan): expired after the comment's 7 days, the rule or its public reply turned off (skipped), no token (failed). - Reserve (
reserve_automation_public_reply): one transaction under its own advisory lock, so public and private reservations never wait on each other. A paused account holds it; a public cooldown waits for it; the same person already got a public reply on the same post in the last day (a reply sending, posted or for review) skips it withrecipient_limit, which also ends a loop with another account's automation; then the account's hourly limit, counting public reply attempts only (AUTOMATION_PUBLIC_ACCOUNT_HOURLY_LIMIT, default 60, at most 200). The attempt is recorded with kindpublic_replyand the digest of the text before the request leaves. - Send (
replyToComment):POST https://graph.instagram.com/v25.0/<comment-id>/replieswith{ message }and the token as a Bearer header, 10 second timeout, never repeated inside the call. It counts as posted only when Instagram answers with the new reply'sid. - Finish (
finish_automation_public_reply): the outcome on the attempt and the reply in one transaction, the reply's id, and a cooldown on the account's public replies, or a hold on the whole account when Instagram refused its token.
| Instagram's answer | Public reply | Attempt | Account |
|---|---|---|---|
200 with id |
accepted (Posted), reply_id kept |
accepted |
|
200 without id, timeout, connection lost, unreadable 200 |
needs_review, reason no_answer |
ambiguous |
|
| Code 100 with subcode 33 (the comment is deleted or cannot be seen) | skipped |
rejected |
|
| Rate limit codes or HTTP 429 | retry_wait until the cooldown ends |
rate_limited |
public cooldown from X-Business-Use-Case-Usage, else 15 minutes |
| Code 368 (temporarily blocked) | retry_wait |
rejected |
24 hour public cooldown; private replies go on |
| Codes 1, 2 or HTTP 5xx | retry_wait with the same backoff; failed after 5 tries |
rejected |
|
| Token or permission refused | back to queued, held |
rejected |
paused with the reason |
| Any other error | failed, with Instagram's message |
rejected |
Lost answers. Unlike a private reply, a public reply can be looked for reliably: GET /<comment-id>/replies?fields=id,text,timestamp,from, up to two pages of 50. The reconcile runs check up to five a run, 5 minutes after the attempt and then every 5 minutes, three times at most:
- A reply from the account with the same sha-256 digest, at or after the attempt, marks it
acceptedwith reasonconfirmedand its id. - Missing on two checks, with every reply read each time: it goes back in the queue once (
resend_after_check), and the dispatch posts it again. The reconciler itself never posts. - A second lost answer, a page left unread, or a read Instagram refuses: it stays
needs_reviewwith a note, and a person decides.
Followers-Only Replies (backend/services/automationFollowupProcessor.ts)
Status: in testing. The flow is covered by tests with fakes and a local database, but it has not been tried with a real account. It depends on Meta sending the account's messages events, which may need Advanced Access for instagram_business_manage_messages; this instance runs on Standard Access. The app and the docs label it as testing, and it may or may not work.
Instagram does not let an app check whether a commenter follows the account until that person messages it, so the check cannot happen before the first private reply. A followers-only rule therefore works in two steps, and Twiligent never says a follow was checked when it was not.
- The private reply sends the rule's first message (
follow_prompt_text), with no link: for example "Follow this account, then reply to this message and the link is on its way." Once Instagram accepts it, the comment waits for the person's answer. - Their answer arrives as a
messageswebhook event and becomes a follow-up job (see Intake). Their message gives Instagram's consent for the profile read and opens Instagram's 24 hour window. - The follow-up is claimed like a reply (accounts take turns, paused and cooling accounts left out,
FOR UPDATE SKIP LOCKED), then:- Check (
followupReadiness): the 24 hours ran out:expired; the rule was turned off or is no longer followers-only:skipped; the comment no longer waits (link sent or reminders used):skipped; no token:failed. - Follow check (
readFollowStatus):GET /<igsid>?fields=is_user_follow_businesswith the account's token as a Bearer header and a 5 second timeout. A read, so asking again is always safe. - Decide (
followupMessage):
- Check (
| Instagram says | Sent | Follow-up | Comment |
|---|---|---|---|
| Follows | The reply and link | accepted, kind link |
gate_status completed |
| Does not follow | The reminder (not_following_text) |
accepted, kind reminder |
one reminder counted; the second closes the wait (closed) |
| Cannot say: consent error, no follow field, any other refusal | Nothing | failed, follow_unverifiable, with Instagram's reason |
still waiting; a later message is checked again |
| Token or permission refused | Nothing | failed, not_authorized |
still waiting |
| Rate limit, temporary error, no answer | Nothing | retry_wait 5 minutes, or expired past the window |
still waiting |
- Reserve (
reserve_automation_followup): a paused account holds it and a cooldown waits for it. Follow-ups use the Send API, not the private reply allowance, so the hourly reply limits do not count them (automation_attempts.kind = 'followup'). - Send (
sendMessage):POST /<ig-id>/messageswith{ recipient: { id: <igsid> }, message: { text } }, 10 second timeout, never repeated. A slow follow check that leaves less than the send's whole timeout hands the job back unsent. - Finish (
finish_automation_followup): the same answer table as private replies, plus the comment's wait. A lost answer isneeds_reviewand is never sent again without a person.
Nothing about the follow is stored except the follow-up's outcome; the person's message text is never read or kept.
Duplicates, Ambiguity and Reconciliation
- A notification Meta delivers twice is stored once:
unique (ig_user_id, comment_id)for comments,unique (automation_comment_id)for public replies,unique (ig_user_id, trigger_message_id)for messages. - A private reply and a public reply are separate rows with separate attempts. Retrying one requeues only that row; a failure, cooldown or review of one never sends the other again.
- A comment repeated inside one notification is stored once, and several messages from one person make one open follow-up.
- Two runs never send the same job: the claim locks rows, and the reservation only moves a job this run holds. The every-minute dispatch, the webhook's own runs and a retry can overlap safely.
- A job a run claimed but did not start is handed back at once; one whose run died before the request left is claimed again after its 20 minute lease.
- A private send that may have reached Instagram (timeout, lost connection, a run that stopped while
sending) is never retried on its own. It shows as Needs review. A public reply in the same state is retried only after the comment's replies were read twice and it was in neither (see Public Replies). - Reconciliation. The five minute runs that do not publish look for up to four Needs review replies in the conversation on Instagram (
automationReconciler, Conversations API: the conversation with the commenter, then its latest messages). A message from the account with exactly the text that was sent (the same sha-256 digest), at or after the attempt (2 minutes of slack for the clocks), marks the replyacceptedwith reasonconfirmed, and a followers-only rule then starts waiting for the person. A reply not found stays Needs review with a note. Each is checked at most three times, 30 minutes apart, starting 5 minutes after the attempt. A conversation Instagram will not show counts as a check with its reason. Replies sent before digests were kept are not guessed at. The reconciler only reads from Instagram; it never sends. - A person decides the rest after checking the conversation. If they retry and the first reply did arrive, Instagram refuses a second private reply to the same comment (10900), and the comment is marked skipped.
- Delivery is at least once into the queue and at most once to Instagram without a person's decision. Instagram reports acceptance, not delivery or reading, so the dashboard says "Accepted by Instagram" and never "Delivered".
Comment Status Lifecycle
ignored (no rule matched; final)
queued -> processing -> sending -> accepted ----------------------------------------------.
^ | |-> retry_wait -> processing ... |
| | |-> failed | skipped | expired followers-only:
| | '-> needs_review (no answer, or the run stopped) awaiting_reply
| | '-> accepted (found in the conversation) |-> completed (link sent)
| |-> queued (held: account paused) | retry_wait (limit, cooldown) '-> closed (reminders used)
| '-> skipped (rule off, recipient limit) | expired | failed (no token)
'-- retry by the owner (failed, skipped, needs_review, within 7 days)
queued | retry_wait -> expired (the five minute expiry, without a claim)
| Status | Shown as | Meaning |
|---|---|---|
ignored |
No match | Received; no rule answers it |
queued |
Waiting, or Held | Waiting to send; Held when its account is paused |
processing, sending |
Sending | A run holds it |
retry_wait |
Trying again | Waiting for a retry, a cooldown or an hourly limit |
accepted |
Accepted by Instagram | Instagram took the reply |
accepted, waiting for the person |
Asked to follow | A followers-only reply; the link goes out when they reply and follow |
accepted, follow-up failed or for review |
Follow-up failed, Needs review | The message after their answer did not go out, or may have |
accepted, completed |
Link sent | Instagram confirmed the follow and accepted the link |
accepted, closed |
Not following | Every reminder was used; the link was not sent |
failed |
Failed | Instagram refused it, or it failed 5 times |
needs_review |
Needs review | It may have been sent; check before retrying |
skipped |
Skipped | Rule off, recipient limit, or already answered |
expired |
Expired | The 7 days ran out first |
Follow-ups and public replies use the same statuses, without ignored. Retry on an accepted followers-only reply requeues its latest failed, skipped or review follow-up inside its 24 hours. A comment whose rule sends no private reply is skipped with reason private_reply_off, shown as Off, and its private reply cannot be retried.
| Public reply status | Shown as | Meaning |
|---|---|---|
queued, retry_wait |
Waiting, Held, Trying again | Waiting to post |
processing, sending |
Posting | A run holds it |
accepted |
Posted | Instagram answered with the reply's id |
needs_review |
Checking | It may have been posted; the reconcile runs look for it |
failed, skipped, expired |
Failed, Skipped, Expired | As for private replies; skipped also covers a deleted comment and the one-per-post limit |
POST /api/automations/activity/:id/public-reply/retry requeues a failed, skipped or review public reply inside the comment's 7 days and starts it at once; the private reply is untouched.
Limits and Controls
| Scope | Default | Set with |
|---|---|---|
| Instance, per hour | 1,000 private replies | AUTOMATION_GLOBAL_HOURLY_LIMIT |
| User, per hour | 500 private replies | AUTOMATION_USER_HOURLY_LIMIT |
| Instagram account, per hour | 200 private replies (Instagram allows 750), counted across every member's connection to the same Instagram account | AUTOMATION_ACCOUNT_HOURLY_LIMIT, at most 750 |
| Rule, per hour | none | the rule's hourly limit, 1 to 750 |
| Person, per day per account | 3 replies | AUTOMATION_RECIPIENT_DAILY_LIMIT |
| Instagram account, public replies per hour | 60 | AUTOMATION_PUBLIC_ACCOUNT_HOURLY_LIMIT, at most 200 |
| Person, public replies per post per day | 1 | fixed, in reserve_automation_public_reply |
| Public reply wordings per rule | 5, each at most 300 characters, 4 hashtags and 1 link | lib/automationPublicReply.ts |
| Replies per webhook request or dispatch | 10 | AUTOMATION_BATCH_SIZE, at most 15 |
| Reminders per followers-only reply | 2 | MAX_FOLLOW_REMINDERS in lib/automationDelivery.ts |
Follow-ups count toward none of the hourly reply limits; they respect account pauses and cooldowns. Public replies count only toward their own hourly limit, and private replies never count toward it. The 300 character, 4 hashtag and 1 link bounds are Twiligent's own: Instagram's older API refused comments past them, and short, varied replies are less likely to look like spam.
| Control | Effect |
|---|---|
AUTOMATION_PAUSED=true |
Nothing is sent on the instance; comments and answers are still stored and matched |
| Pause an account (Replies switch) | Its replies and follow-ups wait in place and go out when resumed, within Instagram's windows |
| Turn a rule off | New comments stop matching it; its waiting replies, follow-ups and public replies are skipped |
| Turn a rule's private or public reply off | That reply's waiting jobs are skipped; the other one goes on |
| Retry an item | Puts a failed, skipped or review item, or its failed follow-up, back in the queue and starts it at once |
The batch cap of 15 comes from the Workers Free plan's 50 subrequests per invocation: each reply costs three (reserve, send, finish) and each follow-up four (the follow check too), plus the claim and the intake queries.
Throughput. One dispatch sends up to the batch size, so the queue drains at up to 600 replies an hour with the default batch and 900 at the cap, on top of the replies the webhooks send at once. Before the every-minute dispatch, leftovers drained at 120 an hour.
Observability
| Signal | Where |
|---|---|
| Each reply, follow-up and public reply settled: ids, status, outcome, error codes | automation reply settled, automation follow-up settled, automation public reply settled log lines |
| A dispatch that claimed something: counts by outcome | automation dispatch |
| Each reconcile run: expired counts, review results for both kinds (public: found, not found, failed, sent again), queue health (due, oldest due, waiting, stale, needs review, follow-ups due, public replies due, stale and checking, paused and limited accounts) | automation reconcile |
| The queue falling behind: the oldest due reply or public reply waited over 10 minutes, or jobs are held by stopped runs | one automation queue behind: ... warning per run, so an incident does not flood the logs |
| Every non-dispatch cron run and its duration | cron run finished |
| Accounts at their limit, cooling down, held, or without message events, and public replies cooling down or at their limit | the Instagram accounts card on the Instagram automation page |
Logs carry ids, statuses and error codes, never tokens, secrets, comment text or message text.
Response Time
- Normally a few seconds: Meta delivers the webhook, the Worker stores it and sends the reply right after answering. A follow-up goes out the same way when the person replies.
- Up to a minute for a reply that waits for the dispatch: more than the batch in one notification, a webhook that stopped early, or a reply whose limit or cooldown just ended.
- Longer only while a limit, a cooldown, a pause or Meta's own delivery delay holds it.
Data Kept and Removed
| Data | Kept | Removed |
|---|---|---|
| Matched comments: text, author, status, reply id, recipient id | 90 days | Daily retention, 1,000 a batch, up to 20,000 a day; also when the account or user is removed |
| Unmatched comments | 90 days, without text or author | Same |
| Reply attempts, with the digest of the text sent | With their comment | With their comment |
| Follow-ups: sender id, message id, outcome; never the message text | With their comment | With their comment |
| Public replies: the text posted, status, reply id, attempts | With their comment | With their comment |
| Rules, account controls | Until deleted | With the account |
| Audit events | 1 year | Daily retention; with the user |
Costs
Everything runs on the existing Worker, Supabase project and Workers Free plan; nothing new is billed. Each comment costs one webhook request and, when matched, about four database calls and one Instagram request, plus three database calls and one Instagram request for a public reply. Each follow-up costs one more Instagram call for the follow check. The Workers Free plan allows 100,000 requests a day, and cron runs count as requests: the every-minute dispatch is 1,440 a day, the five minute trigger 288 and the daily one 1, about 1.7% together. With the messages field selected, every direct message to a connected account is also a request. Past the daily allowance the free plan refuses requests rather than billing them, and Meta retries a refused webhook for 36 hours. Cloudflare Queues, KV and D1 are not used. Recheck Cloudflare's and Supabase's pricing pages before relying on these numbers.
Files
| Layer | File |
|---|---|
| Routes | routes/instagramWebhookRoutes.ts (public), routes/automationRoutes.ts |
| Middleware | middleware/metaWebhook.ts |
| Controllers | controllers/instagramWebhookController.ts, controllers/automationController.ts, inBackground() in controllers/http.ts |
| Validators | validators/instagramWebhookValidators.ts, validators/automationValidators.ts |
| Services | services/automationWebhookService.ts, services/automationProcessor.ts, services/automationFollowupProcessor.ts, services/automationPublicReplyProcessor.ts, services/automationReconciler.ts, services/automationService.ts, services/retentionService.ts |
| Cron | jobs/scheduled.ts |
| Platform | services/instagram/instagramMessaging.ts, services/instagram/instagramComments.ts |
| Rules | lib/automationMatching.ts, lib/automationRules.ts, lib/automationDelivery.ts, lib/automationPublicReply.ts, lib/automationReview.ts, lib/automationHealth.ts, lib/metaWebhookSignature.ts |
| Repositories | repositories/automationRuleRepository.ts, automationCommentRepository.ts, automationFollowupRepository.ts, automationPublicReplyRepository.ts, automationAccountRepository.ts, auditRepository.ts |
| Database | supabase/migrations/20261016100000 to 20261016103500, 20261016120000 to 20261016122500 and 20261016130000 to 20261016132100, one entity per file |
| App | frontend/src/features/automations/ |
Rules made from scheduled posts
A scheduled post can carry the reply for its own comments. Once it is published, postAutomation.attachPublished makes an ordinary enabled rule for that post (matchMode: 'any', mediaIds: [publishedMediaId]) through automations.createRule, so everything above applies to it unchanged. The flow is in SCHEDULING.md (Comment automation for a scheduled post) and ADR-054.