Comment-to-DM
Turn Instagram comments, Facebook Page comments and X replies into direct messages with webhooks and the Conversations API.
Someone comments "LINK" on your post. Your application matches the comment, sends a DM and continues the conversation if they reply. Outstand provides the comment webhook and messaging API; your application owns the campaign rules, queue and duplicate prevention.
For a deployable architecture, use the production guide. For follower gating, see Instagram follow-to-unlock. If a flow is failing, start with troubleshooting.
Availability and limits
Comment-to-DM through Outstand supports Instagram, Facebook Pages and X. A comment event on another network does not imply messaging support. For example, Threads comments cannot be answered through the Conversations API.
Instagram and Facebook Pages
Meta allows one private reply to a comment within seven days. Further automated messages require the recipient to respond, opening the standard 24-hour messaging window. The initial private reply alone does not open that window. For Instagram Live, Meta permits private replies only while the broadcast is live, not for seven days afterwards. Do not assume an accepted comment event means the broadcast is still live.
Keep platform rules separate from Outstand's current API surface:
| Constraint | Source |
|---|---|
| One private reply per comment, within seven days; follow-ups require a response | Meta platform rules |
| Facebook private replies cannot target another Facebook Page; Standard Access is limited to people with an app role | Meta platform rules |
First message uses content, without media | Outstand start-conversation API |
| Instagram supports quick replies or buttons; Facebook starts with plain text only through Outstand | Outstand API support, not a claim that Messenger supports only text |
| Instagram needs both the comment ID and author ID; Facebook needs the comment ID only | Outstand request contract |
Meta's broader Messenger surface also covers other entry points and message types. This guide covers comments on connected Facebook Page posts, not Group automation or arbitrary user messaging. Filtering to top-level comments is a useful campaign rule (parentCommentId === null), not a universal Meta restriction on all private replies.
Sources: Meta's Instagram private replies and Messenger private replies.
X
X sends an ordinary DM to the reply's author, not a Meta-style private reply. There is no Meta messaging window or one-send-per-comment protection. The recipient's DM settings still apply. Outstand's X comment events cover direct replies to the account's posts, not nested replies or protected accounts. Resolving x.comment_id reads the reply and is billed to your X app. X requires BYOK.
1. Prepare the account
- Connect an Instagram Business or Creator account with Allow access to messages enabled, or a Facebook Page. See Instagram requirements.
- Connect or reconnect with messaging and comment webhook permissions.
scopesreplaces defaults, so preserve the other scopes your integration needs. Reconnecting updates the account in place. - For Meta BYOK, configure the app's comment and message webhook subscriptions. Managed Keys handle app-level setup. See Instagram BYOK messaging setup, Facebook availability and X setup.
- Subscribe your Outstand webhook endpoint to
comment.receivedandmessage.received. Addconversation.started,message.sentandmessage.failedfor monitoring.
| Network | Required scopes for this flow |
|---|---|
instagram_business_manage_comments, instagram_business_manage_messages | |
pages_manage_metadata, pages_messaging | |
| X | tweet.read, dm.write, dm.read |
Instagram comment access is a default scope; Instagram messaging is not. Facebook Managed Keys include the two listed scopes by default; BYOK must request them. X includes tweet.read and dm.write by default, but not dm.read. See the full connection examples before constructing a replacement scope list.
2. Receive and persist the comment
An abridged event for a post created outside Outstand:
{
"event": "comment.received",
"timestamp": "2026-11-01T10:30:00.000Z",
"data": {
"orgId": "YOUR_ORG_ID",
"network": "instagram",
"accountId": "x8Kp2",
"postId": null,
"platformPostId": "17912345678901234",
"commentId": "17865799348089039",
"parentCommentId": null,
"authorId": "17841400000000000",
"authorUsername": "jane.doe",
"authorName": null,
"text": "LINK please",
"author": null
}
}postId is Outstand's post ID and can be null when no matching Outstand post exists. platformPostId is the native post ID: use it with accountId and network to scope campaigns on posts published outside Outstand. A null postId does not prevent the private DM. Do not substitute platformPostId into an API path that expects an Outstand post ID.
Verify the signature over the raw body, validate the event and durably enqueue or commit it before returning 2xx. If persistence fails, return a non-2xx. Send from a worker, not an unawaited task after the response. Webhook redelivery can occur on every network; deduplicate before sending.
orgId is the Outstand organization, not necessarily a customer tenant in your application. Resolve an authorized tenant and connected-account mapping before using credentials or campaign rules.
3. Send the private reply
For Instagram, use accountId, commentId and authorId from the event:
curl -X POST https://api.outstand.so/v1/conversations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"social_account_id": "x8Kp2",
"content": "Here is the guide you requested: https://example.com/guide",
"instagram": {
"comment_id": "17865799348089039",
"author_id": "17841400000000000"
}
}'For Facebook, replace instagram with:
{ "facebook": { "comment_id": "122100000000000000_1122334455667788" } }For X, replace it with:
{ "x": { "comment_id": "1849000000000000001" } }Use the appropriate connected account's social_account_id for each request. Facebook resolves the recipient's Messenger ID from its response; the comment's authorId is not that Messenger ID.
Success returns 201 with success, conversation and message. Store conversation.id, message.id and the source comment key. A sent message or message.sent event means the platform accepted the send, not that the person saw it. A non-follower's Instagram private reply can land in Requests. A private reply can join an existing conversation rather than create a new one.
4. Continue only after a response
The person's reply arrives as message.received with conversationId. On Meta, it updates lastInboundAt and opens the 24-hour window for Send a message:
curl -X POST https://api.outstand.so/v1/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "Happy to help. What would you like to know?"}'Instagram quick replies and postback buttons can elicit that response. A url button only opens a URL: it does not send a reply or open the window. See message lifecycle and the follow-to-unlock example.
Errors and recovery
| Status | Action |
|---|---|
400 | Fix the body or unsupported network. Instagram needs both IDs; Facebook needs comment_id; X takes exactly one target field. |
401 / 403 | Check API-key access and organization/account authorization. Do not retry unchanged credentials. |
404 | Check the authorized account, comment visibility and target IDs. A deleted or inaccessible comment cannot be retried into existence. |
409 | Stop resending the Meta private reply. Mark it already contacted, not proof that this job delivered your desired content. |
422 | Inspect the error: an expired private-reply window, unopened follow-up window or X recipient restriction needs a different action, not a blind retry. |
429 | Respect retry guidance and use bounded backoff, without exceeding the platform window. |
502, timeout or lost response | Inspect the cause and reconcile the outcome before resending. The platform might have accepted the message even if the request failed locally. |
Do not use a blanket 502 retry or assume an error means nothing was stored or sent. See the durable job state and retry design and symptom-based troubleshooting.