Engineering

Instagram comment-to-DM automation: how it works on the API

Turn Instagram comments into private replies with Outstand. Learn Meta's limits, messaging permissions, BYOK setup and the production-safe webhook flow.

Someone comments “GUIDE” on a Reel. Your application sends them a direct message with the guide. That is Instagram comment-to-DM automation: a comment triggers a private response, without asking the account owner to copy links into their inbox all day.

Underneath that familiar experience is Meta's Private Replies feature. It is not permission to message every commenter indefinitely. You get one private reply per comment, within seven days of the comment. Further automated messages require an inbound response from the person.

This guide explains the complete flow through Outstand: account setup, comment targeting, the first DM, reliable webhook handling, and what happens after someone answers. It covers the current Instagram Login integration, not a different Meta login flow's permission names.

What Instagram actually allows

Meta's private replies documentation sets the boundaries:

  • One private reply per comment. A later comment is a separate opportunity, not permission to resend against the original comment.
  • Seven days from comment creation. Your webhook arrival time and queue processing time do not restart the clock.
  • Follow-up only after a response. Sending the private reply does not itself open the standard 24-hour messaging window.
  • Instagram Live is different. Meta permits private replies to Live comments only during the broadcast. Receiving a Live comment through Outstand is not a guarantee of additional Live reply capabilities. Keep Live out of a regular-post campaign unless you have separately verified the intended behavior.

The first message can contain a useful link. Outstand also supports quick replies and buttons in Instagram private replies, so “text only” should not be read as “no interactive controls.” Media attachments are not supported in the conversation-start request.

Private replies can appear in the recipient's inbox or message requests, depending on whether they follow the account. A successful API send does not mean the person saw it, opened it, or downloaded your resource.

1. Connect an account with messaging access

Use an Instagram Business or Creator account and enable Allow access to messages in its connected-tools settings. Personal Instagram accounts are not supported by the professional messaging API.

For Outstand's current Instagram Login connection, plan around these scopes:

Scope

Role in the flow

instagram_business_basic

Basic account access

instagram_business_manage_comments

Comment access and notifications

instagram_business_manage_messages

Messaging access for the complete private-reply and inbound-response flow

Outstand requests the first two by default, alongside publishing and insights permissions. Messaging is opt-in, not a default dashboard permission. Connect or reconnect with an explicit scope list that includes it. Outstand's scopes value replaces the defaults rather than appending to them, so retain the existing scopes:

bash
1curl -X POST https://api.outstand.so/v1/social-networks/instagram/auth-url \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "redirect_uri": "https://your-app.example.com/social/callback",
6    "scopes": "instagram_business_basic,instagram_business_content_publish,instagram_business_manage_comments,instagram_business_manage_insights,instagram_business_manage_messages"
7  }'

Send the owner to the returned auth_url and have them approve messaging access. Reconnection updates the existing social account rather than requiring a new account ID. Reconnecting later without the messaging scope can remove that access again.

Both Managed Keys and BYOK support inbound DMs. The difference is who configures the Meta app. Managed Keys use Outstand's app. With BYOK, configure your own app's webhook subscriptions, including comments and messages, on its verified per-app callback at https://webhooks.outstand.so/instagram/{YOUR_APP_ID}. Outstand handles the account-level subscriptions when the account connects with the appropriate permissions.

For a BYOK app serving accounts you do not own or manage, arrange the required Advanced Access, App Review and Business Verification, and use Live mode for production. Follow the Instagram configuration guide, including support-assisted callback setup if yours is not already verified. Do not assume subscribing your application's Outstand webhook also configures the upstream Meta app.

2. Receive the comment and target the right campaign

Subscribe your Outstand webhook endpoint to comment.received and message.received. Add message.sent, message.failed and conversation.started for lifecycle tracking.

An Instagram comment event includes these routing fields, shown here as an abridged example:

json
1{
2  "event": "comment.received",
3  "data": {
4    "orgId": "YOUR_OUTSTAND_ORG_ID",
5    "network": "instagram",
6    "accountId": "x8Kp2",
7    "postId": null,
8    "platformPostId": "17912345678901234",
9    "commentId": "17865799348089039",
10    "parentCommentId": null,
11    "authorId": "17841400000000000",
12    "authorUsername": "jane.doe",
13    "text": "GUIDE please!",
14    "isLive": false
15  }
16}

A null postId does not disqualify the comment. Instagram posts published natively, including Reels uploaded from a phone, can trigger comment events. Their Outstand post ID can be null, while platformPostId still identifies the Instagram media. The private reply needs the account, comment and author IDs, not an Outstand post record.

Target a campaign using the connected accountId plus platformPostId, then match the keyword. Otherwise, a generic “GUIDE” trigger could answer an unrelated post on the same account. Use parentCommentId to decide whether replies to other comments should qualify, and filter out isLive: true for a normal feed or Reel campaign.

orgId identifies an Outstand organization, not automatically one of your SaaS customers. If several customers share an Outstand organization, resolve the connected account through your own authorized tenant mapping. Check both organization and account ownership before selecting credentials, campaign data or customer-specific content.

Comments from the connected account itself are skipped, which helps prevent reply loops. Persist the incoming event data you need: Outstand does not provide a stored comment history to reconstruct a lost trigger later.

3. Send the private reply

Map three event fields into Start a conversation:

Event field

Request field

accountId

social_account_id

commentId

instagram.comment_id

authorId

instagram.author_id

bash
1curl -X POST https://api.outstand.so/v1/conversations \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "social_account_id": "x8Kp2",
6    "content": "Here is the guide you requested: https://example.com/guide. Reply if you have a question.",
7    "instagram": {
8      "comment_id": "17865799348089039",
9      "author_id": "17841400000000000"
10    }
11  }'

The current Instagram implementation sends to the platform before returning 201 Created, with the conversation and a message marked sent. Store the conversation ID and message ID against your campaign job. This is send confirmation, not proof of recipient delivery or reading.

For a first-time contact, lastInboundAt remains null because an outbound private reply is not an inbound message. If the person already has a conversation with the account, Outstand reuses it; preserve its actual inbound history rather than assuming every private reply starts a new thread.

Interactive replies are supported

Instead of sending the resource immediately, you can ask “Would you like the guide?” with instagram.quick_replies, or use instagram.buttons.

A quick-reply tap or a postback button produces an inbound message.received event and opens the reply window. A url button only opens a link: clicking it does not open the messaging window.

Outstand supports up to 13 quick replies or three buttons, not both on the same message. Buttons limit content to 640 characters. Quick replies are not shown on Instagram desktop, so make the text understandable without them. See the interactive message reference for payloads and limits.

4. Make the automation durable, not just fast

The safe production order is:

  1. Verify the webhook signature against the raw request body, using your configured signing secret and a constant-time comparison.
  2. Validate the event and durably enqueue it, or commit it to a database-backed inbox.
  3. Await that durable write before returning 2xx. If persistence fails, return a failure so webhook delivery can retry.
  4. Let a worker resolve ownership, campaign eligibility and job state, then send the DM.
  5. Record confirmed send results before attempting an optional public confirmation.

Outstand gives each webhook delivery a 30-second timeout and retries failed delivery. Starting an unawaited promise, returning success, and hoping background work survives is not durable receipt.

Use a job key containing organization, account and comment IDs. Keep retryable states such as pending, processing with an expiring lease, retry_scheduled, sent, terminal_failure, and needs_review.

A permanent claimOnce(commentId) flag is insufficient: if the worker crashes after claiming but before sending, the next delivery skips the only remaining opportunity. Persist attempt counts, the last error, the next attempt time, and the confirmed Outstand IDs. Recover expired worker leases.

There is still a boundary between the remote send and your local commit. A timeout can leave an unknown outcome. Reconcile available conversation messages, commentId and lifecycle events before retrying or announcing success. Local deduplication is not an exactly-once guarantee across two systems.

Classify failures before retrying

Result

Handling

400

Fix the request; do not repeat the same invalid body.

404

Check account/comment pairing, visibility and deletion.

409

Stop resending this comment. Reconcile the existing reply before claiming your campaign succeeded.

422

Inspect the reason. An expired private-reply window is terminal.

502

Inspect the upstream error. Permissions need repair; transient failures may justify bounded backoff.

Timeout or interrupted response

Mark the outcome uncertain and reconcile before another attempt.

Never treat every 502 as “safe to retry.” A permissions failure does not improve with repetition, and an ambiguous network failure does not prove that nothing was sent.

5. Confirm publicly only after the DM succeeds

“Sent, check your DMs” should follow confirmed send state, not precede it. Otherwise, the public promise survives even when the private reply fails.

For an eligible Outstand-published post, send the optional confirmation through POST /v1/posts/{id}/replies. Use the event's postId in the path, commentId as parent_comment_id, and platformPostId as platform_post_id to select the platform target, particularly on multi-account posts. See Publish a comment.

When postId is null, skip this public-reply endpoint, not the private reply. It does not accept a native Instagram media ID in place of an Outstand post ID.

Track public confirmation separately. Its failure must not cause the worker to resend a successful DM.

What happens after the commenter answers?

Handle the verified, durably stored message.received event using its conversationId. An inbound reply opens the standard 24-hour window, measured from the contact's last inbound message. Your outbound messages do not extend it.

Continue through Send a message, checking the window again when a queued job actually runs. Ordinary follow-up sends return 202 Accepted; track their eventual message.sent or message.failed outcome rather than counting acceptance as success.

No answer means no automated day-two reminder. The separately approved HUMAN_AGENT extension is for human support, not a way to stretch a marketing sequence.

Start with one post, one keyword and one useful private reply. Test duplicate webhooks, revoked permissions, native posts and worker crashes before expanding. The comment-to-DM API guide provides the endpoint reference; the reliable product experience comes from respecting the boundaries around that first message.