Comment to DM API
The Comment to DM API automates a keyword-triggered DM: when a new comment matches your configured keywords, the commenter receives a direct message, with an optional public reply posted under the comment.
curl -X POST "{{API_BASE_URL}}/v1/comment-automations/" \
-H "x-access-key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "INTEGRATION_ID",
"name": "Link in DM",
"postScope": "specific",
"platformPostId": "17901234567890123",
"keywords": ["link", "guide"],
"matchMode": "word",
"publicReplies": ["Sent you a DM!"],
"dmMessage": "Here is the link you asked for: https://example.com"
}'curl -X POST "{{API_BASE_URL}}/v1/comment-automations/" \
-H "x-access-key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
You configure the trigger, scope, matching rules, and message once through one API, and managed webhooks deliver the result in real time without running your own webhook server.
What the Comment to DM API does and when to use it
A Comment to DM API is useful when a comment is a request for information, such as a link, guide, or price, and the response should arrive privately rather than in a long public thread. Instead of polling comments or building keyword matching and DM delivery yourself, you create a comment automation that watches for new comments, checks them against your rules, and sends the configured dmMessage to the commenter. An optional public reply can confirm that a DM was sent, which helps other readers understand why the conversation moved to private messages.
Use this workflow when the trigger is a word or phrase in a comment, when you want the same response across many comments, or when you need a record of what was triggered and whether delivery succeeded. It is less suitable when every comment needs a human judgment call, when the response depends on information outside the comment, or when you need to negotiate a conversation rather than send a fixed message. In those cases, use the automation for the first response and handle follow-up through the Messaging API.
Integration follows three steps. First, obtain an API key through signup, without a sales setup. Second, integrate by connecting an account once and then using the same API to publish, schedule, analyze, manage comments, and handle messages. Third, support the platforms your users need through that single connection instead of building and maintaining each platform integration separately. For this contract, the REST path is the primary route: send the request shown in the Create a comment automation request example and read the structured response shown in the Structured response for a created comment automation example.
Exact endpoint and worked request and response example
The worked example creates an automation named Link in DM for a specific post. The request sets postScope to specific and supplies platformPostId, so only comments on that post or reel are in scope. The keywords list contains link and guide, matchMode is word, publicReplies contains one confirmation message, and dmMessage contains the private message to send. The response confirms success, returns the automation id, identifies the platform as instagram, sets status to active, and echoes the trigger and actions in nested objects. Treat the identifiers in the example, such as INTEGRATION_ID, AUTOMATION_ID, and the platform post id, as placeholders to replace with your own values.
Before you rely on the automation, check the response rather than assuming creation succeeded. Confirm that success is true, that automation.status is active, and that the echoed trigger and actions match what you sent. If any echoed field differs, correct the request and create or update the automation again instead of debugging delivery against a misconfigured trigger. Keep the returned automation id with your own records so you can later list, update, delete, and inspect logs for that automation.
Field map and decision criteria
Use the field map and decision criteria in the tables below to choose each setting deliberately. postScope decides whether the automation covers every post on the account or one specific post or reel identified by platformPostId. When you choose specific, fetch eligible posts from the API first and use the exact platform post id, because a wrong id silently scopes the automation to the wrong content. When you choose account-wide scope, expect every new comment on the account to be evaluated, so keep keywords and exclusions tight.
matchMode decides how a keyword must appear. Choose word when you want the keyword as a whole word, contains when a match anywhere in the text is acceptable, and exact when only the full comment should trigger. excludeKeywords is your safety valve: add words that should never trigger a DM, for example when a keyword appears in a complaint, a joke, or an unrelated phrase. publicReplies is optional; when you use it, provide up to five alternatives and one is rotated per comment so replies do not read as identical bot text. dmMessage is the private payload, so write it as a complete message that makes sense without the public reply, including the link or next step the commenter asked for.
Keyword matching, exclusions, and public-reply rotation
Keyword matching is the core of a keyword-triggered DM. Set trigger words such as link or guide, and a new comment that matches sends the commenter your DM automatically. Leave keywords empty when you want to reply to every new comment, but do that only when every comment genuinely deserves a DM, because empty keywords remove your main filter. Pair keywords with excludeKeywords whenever a common word could appear in comments you do not want to answer, and test your list against realistic comments before activating the automation.
The public reply is a separate action from the DM. It posts under the comment, for example Sent you a DM!, and it can use up to five rotating alternatives. Rotation matters for tone: varied confirmations look more natural than the same sentence repeated under every comment. Keep the public reply short and factual, and put the useful content in the dmMessage. If you do not want a public confirmation, omit publicReplies and rely on the DM alone, remembering that other readers will not see why the conversation moved private.
Delivery, logs, stats, and failure handling
Delivery runs through managed webhooks: the account is subscribed to comment webhooks and events are delivered in real time with automatic retries. You do not run a webhook server and you do not file your own Meta App Review for this flow. That removes a common failure point, but it does not remove the need to verify outcomes. After activation, review the per-automation records: each entry identifies the triggering comment and its author, records whether the private message and visible confirmation went out, and contributes to triggered, succeeded, and failed totals.
Use the failure matrix in the tables below as your checklist. A triggered count that rises without matching successes means delivery is failing after the match, so inspect the logged comment and commenter and check the connected account and its permissions. A succeeded DM with a failed public reply means the private message landed but the confirmation did not, so check the public-reply action separately. A failed DM means the commenter received nothing, so do not assume the public reply alone is enough. Billing follows successful delivery: one credit for a delivered private message and one additional credit for a delivered visible confirmation. Investigate failures promptly rather than letting retries mask a broken configuration.
Platform scope and integration prerequisites
Comment to DM automations currently support Instagram Business and Creator accounts, and the Instagram Comment to DM API covers Instagram posts and reels with an optional public reply triggered in real time through managed webhooks. The architecture is pluggable, so additional Meta-family platforms can be added through the same integration, but you should only promise a platform once it is listed as supported for your account. Do not assume that a platform supported for posting or comments automatically supports comment automations.
Prerequisites are account connection and permissions. Users connect their account and grant the comment and messaging permissions needed for the automation to read comments and send DMs. If a user has not granted those permissions, or the connected account is not an eligible Instagram Business or Creator account, expect triggers to fail and check the logs for the affected comment and commenter. Related workflows can be built through the same integration: the Posting API for publishing, the Comments API for reading and replying to comments, the Messaging API for conversations and DM replies, and the Analytics API for normalized performance metrics. Access paths include REST, typed SDKs, no-code automation, and AI agents and MCP, all powered by the same API contract.
| Field | Location | Type in example | Requiredness | Purpose |
|---|---|---|---|---|
| accountId | Request body | string ("INTEGRATION_ID") | Not stated in source | Identifies the connected account/integration the automation belongs to. |
| name | Request body | string ("Link in DM") | Not stated in source | Human-readable automation name, echoed in the response. |
| postScope | Request body and trigger | string enum in example: "specific" | Not stated in source | Decides account-wide versus specific-post scope. |
| platformPostId | Request body and trigger | string ("17901234567890123") | Not stated in source | Platform post or reel id used when postScope is specific. |
| keywords | Request body and trigger | array of strings ["link", "guide"] | Not stated in source | Trigger words; empty means trigger on every new comment. |
| matchMode | Request body and trigger | string enum in example: "word" | Not stated in source | Matching rule: word, contains, or exact. |
| excludeKeywords | Response trigger | array of strings [] | Not stated in source | Words that skip a comment even if a keyword matches. |
| publicReplies | Request body and actions | array of strings ["Sent you a DM!"] | Not stated in source | Optional public reply alternatives, up to five, rotated per comment. |
| dmMessage | Request body and actions | string | Not stated in source | Private direct message sent to the commenter. |
Requiredness is not stated in the captured source for individual fields; the worked example shows all of these fields present. Do not treat presence in the example as a verified requiredness rule.
| Response field | Type in example | Meaning |
|---|---|---|
| success | boolean true | Whether creation succeeded. |
| automation.id | string ("AUTOMATION_ID") | Identifier for later management and log lookup. |
| automation.platform | string "instagram" | Platform the automation runs on. |
| automation.name | string "Link in DM" | Echo of the request name. |
| automation.status | string "active" | Current automation status. |
| automation.trigger | object | Echo of postScope, platformPostId, keywords, matchMode, and excludeKeywords. |
| automation.actions | object | Echo of publicReplies and dmMessage. |
Field map derived from the captured structured response example.
| Decision | Choose this when | Watch out for |
|---|---|---|
| postScope: specific | You want comments on one post or reel only. | A wrong platformPostId scopes the automation to the wrong content. |
| Account-wide scope (descriptive) | You want every post on the account evaluated. | Every new comment is evaluated, so keywords and exclusions must be tight. |
| matchMode: word | The keyword must appear as a whole word. | Phrases containing the keyword as part of another word will not match. |
| matchMode: contains | A match anywhere in the text is acceptable. | Higher false-positive risk; pair with excludeKeywords. |
| matchMode: exact | Only the full comment should trigger. | Comments with extra words or punctuation will not match. |
| keywords empty | Every new comment should receive a DM. | Removes filtering; volume and credit use rise with comment volume. |
| excludeKeywords set | Some comments containing a keyword must never trigger. | Over-broad exclusions can block legitimate requests. |
| publicReplies provided | Readers should see a confirmation under the comment. | Up to five alternatives; one is rotated per comment. |
| dmMessage | Always needed as the private payload. | Write it as a complete standalone message. |
Decision guidance based on the captured matching and scope behavior. Account-wide is descriptive prose for covering every post on the account, not a captured enum value.
| Logged outcome | What it means | First checks |
|---|---|---|
| Triggered, DM succeeded, public reply succeeded | Full workflow delivered. | No action; use counts to confirm volume. |
| Triggered, DM succeeded, public reply failed | Commenter got the DM but no public confirmation. | Check the public-reply action and the connected account permissions. |
| Triggered, DM failed | Commenter received no private message. | Check the logged comment and commenter, account connection, and granted permissions. |
| Triggered count rises, succeeded count does not | Matching works but delivery is failing. | Inspect recent logs before changing keywords; the problem is after the match. |
| No triggers for expected comments | Comments are not matching or not in scope. | Check postScope, platformPostId, keywords, matchMode, and excludeKeywords. |
Diagnostic guidance derived from the logged outcomes and triggered/succeeded/failed counts; the source provides no error or status codes for these rows.
Frequently asked questions
What is a comment to DM automation API?
It connects comment activity to private messaging. You configure trigger words, matching rules, and the message to deliver; when a qualifying comment appears, the system sends that message to its author, optionally adding a visible confirmation beneath the comment.
Which platforms does the Comment to DM API support?
The captured scope covers Instagram Business and Creator accounts. For that platform, the Instagram Comment to DM API handles posts and reels, using managed webhooks to react as comments arrive.
Can I send a public reply as well as a DM?
Yes, both actions can run together. The private message is the main delivery, while a public reply is an optional extra. Supplying several reply variants lets the system vary the visible confirmation from one comment to the next, up to the five-variant limit.
How does keyword matching work?
Three matching styles are available through matchMode. The word setting requires a standalone word, contains allows the term anywhere inside the text, and exact requires the entire comment to match. Terms placed in excludeKeywords block otherwise qualifying comments. An empty keyword list removes the word filter, so each new comment can qualify.
How much does the Comment to DM API cost?
Credit use depends on successful delivery. A delivered private message uses one credit. If a visible confirmation is also delivered, that action uses one additional credit. Setup and management calls for comment automations use the standard API usage rules.
Do I need my own Meta developer app or App Review?
No separate Meta developer application or review process is required from the customer for this flow. Account connection and the needed comment and messaging permissions are handled through the managed setup, while webhook subscription and delivery are handled behind the API.
{
"success": true,
"automation": {
"id": "AUTOMATION_ID",
"platform": "instagram",
"name": "Link in DM",
"status": "active",
"trigger": {
"postScope": "specific",
"platformPostId": "17901234567890123",
"keywords": ["link", "guide"],
"matchMode": "word",
"excludeKeywords": []
},
"actions": {
"publicReplies": ["Sent you a DM!"],
"dmMessage": "Here is the link you asked for: https://example.com"
}
}
}