Instagram comment to DM automation API: Set Up Keyword-Triggered DMs
This Instagram comment to DM automation API guide shows how to deliver a direct message after a keyword appears in a comment on a post or reel, optionally adding a visible reply beneath that comment. You will connect the account, locate the target post, build the rule, inspect delivery records, and learn how to pause, revise, or remove it.
Prerequisites: Business/Creator account, access key, permissions
Start with an Instagram Business or Creator account, since personal profiles are excluded from comment and DM automation. Obtain an access key and send it on every call through the x-access-key header, using YOUR_API_KEY as the placeholder value. Before building a rule, verify that the linked account carries both the comment-related and message-related scopes described in the next step.
Connect Instagram, grant permissions, retrieve accountId
Begin the Instagram connection through the dashboard or request an authorization URL via GET /v1/connect/instagram. Two scopes matter here: instagram_business_manage_comments covers comment access plus visible replies, while instagram_business_manage_messages covers sending the private message. An account linked before this capability existed may need a fresh connection so both scopes are present. Next, call GET /v1/connect/integrations and copy the returned identifier into accountId for subsequent calls. If later calls target the wrong account, this identifier is the first thing to recheck.
Find post and platformPostId
For a rule tied to a single post or reel, call GET /v1/comment-automations/posts with accountId supplied as a query parameter, then pick the eligible item. Each returned post carries id, caption, mediaType, permalink, previewUrl, and timestamp, and pagination is handled through nextCursor. Pass the chosen id onward as platformPostId. Prefer account-wide scope instead if you do not want a one-post binding.
Create automation: field map, matchMode table, publicReplies, excludeKeywords
Build the rule with POST /v1/comment-automations, supplying accountId, name, postScope, platformPostId when scope is specific, keywords, matchMode, publicReplies, and dmMessage, plus excludeKeywords where needed. Creation leaves the rule active, and the returned automation groups its settings under trigger and actions, alongside stats beginning at triggered 0, succeeded 0, and failed 0. The trigger section mirrors postScope, platformPostId, keywords, matchMode, and excludeKeywords; actions mirrors publicReplies and dmMessage. An empty keywords list means every fresh comment on the chosen post qualifies. Use excludeKeywords to block unwanted phrases. publicReplies may hold as many as five variants, with one chosen in rotation for each qualifying comment, or it may be left out entirely for DM-only delivery. When more than one rule qualifies for a given comment, specificity decides the winner, so a post-bound rule outranks an account-wide rule.
Check logs and stats
Inspect outcomes through GET /v1/comment-automations/AUTOMATION_ID/logs, passing limit as a query parameter. Records expose commentId, commenterName, commentText, status, privateReplySent, publicReplyStatus, and createdAt, with pagination reporting total, limit, skip, and hasMore. Read status together with privateReplySent and publicReplyStatus to tell a complete success from a partial or failed attempt. The counters triggered, succeeded, and failed summarise overall behaviour for display in your own dashboard. A practical debugging order is: confirm the text satisfied matchMode, examine the log status, then compare the DM and public-reply indicators.
Pause, update, delete lifecycle
Use PATCH /v1/comment-automations/AUTOMATION_ID to pause or revise a rule. The linked account stays fixed, while other settings can change, so refreshing dmMessage or setting status to paused does not require rebuilding the rule. Removal uses DELETE /v1/comment-automations/AUTOMATION_ID. After pausing, confirm the new status before expecting triggers to stop; after editing, confirm the changed fields took effect.
Account-wide automation with postScope any
For coverage across the whole account, set postScope to any and leave platformPostId out. Every post on that account then falls under the rule, which suits a permanent keyword that always returns the same link. The remaining fields stay the same: keywords, matchMode, and dmMessage. Keep the specificity precedence in mind when specific and account-wide rules coexist.
Credit cost per DM and public reply
Billing follows triggers rather than rule count. A delivered DM consumes 1 credit. A visible reply adds 1 credit only when delivery actually happens. Combined delivery therefore totals 2 credits for that comment, while DM-only delivery totals 1. Creation, listing, editing, and removal follow standard API usage. Estimate spend from expected matched comments.
Next steps: messaging and comment moderation
You now have a complete workflow: link the account, select a post or choose account-wide scope, define the keyword rule, and observe messages being delivered automatically. For follow-up conversation handling, add Instagram messaging. For thread moderation, use the Instagram comments API. Endpoint details are collected in the linked documentation.
| Field | Where it appears | Purpose |
|---|---|---|
| accountId | Create request | Instagram account identifier returned from integrations |
| name | Create request and response | Human-readable automation name |
| postScope | Create request and trigger | specific for one post, any for every post on the account |
| platformPostId | Create request and trigger | Post identifier for specific scope |
| keywords | Create request and trigger | Keyword list; empty triggers on every new comment on the post |
| matchMode | Create request and trigger | word, contains, or exact |
| excludeKeywords | Trigger | Keywords that skip a comment |
| publicReplies | Create request and actions | Optional public reply alternatives, up to five |
| dmMessage | Create request and actions | Message sent as the DM |
| stats | Automation response | triggered, succeeded, failed counts |
Request and response fields as shown in the preserved contract examples.
| matchMode | Rule | Worked example |
|---|---|---|
| word | Matches a whole word | cute matches "so cute!" but not "acutely" |
| contains | Matches anywhere in the text | Keyword can appear inside a larger string |
| exact | Matches the entire comment | Comment text must equal the keyword |
Examples are the source-stated cute examples.
| Signal | Fields to check | How to interpret it |
|---|---|---|
| Trigger fired and DM sent | status, privateReplySent | status succeeded with privateReplySent true indicates the DM went out |
| Public reply sent | publicReplyStatus | publicReplyStatus sent indicates the public reply was delivered |
| Delivery problem | status, stats failed | A non-succeeded status or rising failed count needs investigation |
| Volume | stats triggered, succeeded, failed; pagination total | Compare triggered against succeeded and failed to see outcomes |
Log and stats fields as shown in the preserved contract examples.
| Method and path | Purpose | Key parameters or fields |
|---|---|---|
| GET /v1/connect/instagram | Get Instagram authorization URL | x-access-key header |
| GET /v1/connect/integrations | List integrations and find accountId | x-access-key header |
| GET /v1/comment-automations/posts?accountId=your-ig-id | List eligible posts | accountId query parameter |
| POST /v1/comment-automations | Create automation | accountId, name, postScope, keywords, matchMode, dmMessage |
| GET /v1/comment-automations/AUTOMATION_ID/logs?limit=10 | List logs | AUTOMATION_ID path parameter, limit query parameter |
| PATCH /v1/comment-automations/AUTOMATION_ID | Pause or update automation | AUTOMATION_ID path parameter, status paused example |
| DELETE /v1/comment-automations/AUTOMATION_ID | Delete automation | AUTOMATION_ID path parameter |
Exact methods and paths preserved; origin shown as {{API_BASE_URL}}.
Frequently asked questions
Which Instagram account types can use Instagram comment to DM automation?
Use an Instagram Business or Creator account. Personal accounts cannot automate comments or DMs under the stated platform limit.
Which permissions does Instagram comment to DM need?
Grant instagram_business_manage_comments for comment access and public replies, plus instagram_business_manage_messages for DM delivery. Accounts linked earlier may need a fresh connection so both scopes are present.
How do word, contains, and exact matchMode values differ?
word requires a whole-word hit, contains allows a hit anywhere inside the text, and exact requires the whole comment to equal the keyword. Under word, cute matches "so cute!" yet not "acutely".
How many credits does a triggered automation spend?
A delivered DM consumes 1 credit. A public reply that actually goes out adds another 1, bringing a combined trigger to 2; without a public reply, the trigger costs 1.
What happens if several automations could match the same comment?
A single winner is chosen by specificity. A rule tied to one post takes precedence over a rule covering the whole account.
curl {{API_BASE_URL}}/v1/connect/instagram \
-H "x-access-key: YOUR_API_KEY"
curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/comment-automations/posts?accountId=your-ig-id" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"posts": [
{
"id": "17901234567890123",
"caption": "An example caption.",
"mediaType": "IMAGE",
"permalink": "https://instagram.com/p/ABC123/",
"previewUrl": "https://scontent.cdninstagram.com/...",
"timestamp": "2026-09-10T15:30:00Z"
}
],
"nextCursor": "QVFIUl9..."
}curl -X POST {{API_BASE_URL}}/v1/comment-automations \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "your-ig-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"
}'{
"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"
},
"stats": { "triggered": 0, "succeeded": 0, "failed": 0 }
}
}curl "{{API_BASE_URL}}/v1/comment-automations/AUTOMATION_ID/logs?limit=10" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"logs": [
{
"commentId": "17987654321098765",
"commenterName": "jane_doe",
"commentText": "Send me the link!",
"status": "succeeded",
"privateReplySent": true,
"publicReplyStatus": "sent",
"createdAt": "2026-09-15T11:45:22Z"
}
],
"pagination": { "total": 128, "limit": 10, "skip": 0, "hasMore": true }
}curl -X PATCH {{API_BASE_URL}}/v1/comment-automations/AUTOMATION_ID \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "paused" }'
curl -X DELETE "{{API_BASE_URL}}/v1/comment-automations/AUTOMATION_ID" \
-H "x-access-key: YOUR_API_KEY"curl -X POST {{API_BASE_URL}}/v1/comment-automations \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "your-ig-id",
"name": "Always send the link",
"postScope": "any",
"keywords": ["link"],
"matchMode": "word",
"dmMessage": "Here you go: https://example.com"
}'