Skip to content

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.

Create automation field map
FieldWhere it appearsPurpose
accountIdCreate requestInstagram account identifier returned from integrations
nameCreate request and responseHuman-readable automation name
postScopeCreate request and triggerspecific for one post, any for every post on the account
platformPostIdCreate request and triggerPost identifier for specific scope
keywordsCreate request and triggerKeyword list; empty triggers on every new comment on the post
matchModeCreate request and triggerword, contains, or exact
excludeKeywordsTriggerKeywords that skip a comment
publicRepliesCreate request and actionsOptional public reply alternatives, up to five
dmMessageCreate request and actionsMessage sent as the DM
statsAutomation responsetriggered, succeeded, failed counts

Request and response fields as shown in the preserved contract examples.

matchMode decision table
matchModeRuleWorked example
wordMatches a whole wordcute matches "so cute!" but not "acutely"
containsMatches anywhere in the textKeyword can appear inside a larger string
exactMatches the entire commentComment text must equal the keyword

Examples are the source-stated cute examples.

Logs and stats operations matrix
SignalFields to checkHow to interpret it
Trigger fired and DM sentstatus, privateReplySentstatus succeeded with privateReplySent true indicates the DM went out
Public reply sentpublicReplyStatuspublicReplyStatus sent indicates the public reply was delivered
Delivery problemstatus, stats failedA non-succeeded status or rising failed count needs investigation
Volumestats triggered, succeeded, failed; pagination totalCompare triggered against succeeded and failed to see outcomes

Log and stats fields as shown in the preserved contract examples.

Endpoint contract sheet
Method and pathPurposeKey parameters or fields
GET /v1/connect/instagramGet Instagram authorization URLx-access-key header
GET /v1/connect/integrationsList integrations and find accountIdx-access-key header
GET /v1/comment-automations/posts?accountId=your-ig-idList eligible postsaccountId query parameter
POST /v1/comment-automationsCreate automationaccountId, name, postScope, keywords, matchMode, dmMessage
GET /v1/comment-automations/AUTOMATION_ID/logs?limit=10List logsAUTOMATION_ID path parameter, limit query parameter
PATCH /v1/comment-automations/AUTOMATION_IDPause or update automationAUTOMATION_ID path parameter, status paused example
DELETE /v1/comment-automations/AUTOMATION_IDDelete automationAUTOMATION_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.

Connect Instagram and list integrations
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"
List eligible posts for an automation
curl "{{API_BASE_URL}}/v1/comment-automations/posts?accountId=your-ig-id" \
  -H "x-access-key: YOUR_API_KEY"
List posts response example
{
  "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..."
}
Create a specific-post automation
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"
  }'
Create automation response example
{
  "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 }
  }
}
List automation logs
curl "{{API_BASE_URL}}/v1/comment-automations/AUTOMATION_ID/logs?limit=10" \
  -H "x-access-key: YOUR_API_KEY"
List logs response example
{
  "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 }
}
Pause and delete an automation
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"
Create an account-wide automation
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"
  }'