Skip to content

Create Comment Automation API

The Create Comment Automation API creates a comment automation for a social account by sending a POST request to {{API_BASE_URL}}/v1/comment-automations/. You supply the accountId, a name, the postScope, trigger keywords, publicReplies and a dmMessage, with optional status, platformPostId, postPermalink, matchMode and excludeKeywords to narrow when the automation applies. A successful request returns a 201 response with the created automation, including its trigger, actions and stats.

Create Comment Automation API - POST {{API_BASE_URL}}/v1/comment-automations/

Use POST {{API_BASE_URL}}/v1/comment-automations/ to create a comment automation. The trailing slash is part of the documented path and should be preserved exactly. Send the request as application/json and include the access key in the x-access-key header, using the header name x-access-key and a token value in place of the placeholder shown in the request example. Before sending, check that every required field is present and that each array and string stays within its documented length and item limits, because the request body table lists those constraints field by field.

Authorization: x-access-key header

Authentication uses the accessKey supplied in the x-access-key header. Place the token in that header on the POST request alongside Content-Type: application/json. If the header is missing or invalid, do not assume the request will succeed; treat any non-201 response as a failure and inspect its status code and message field before retrying.

Request body field map

Build the JSON body around the required fields accountId, name, postScope, keywords, publicReplies and dmMessage. The name must be between 1 and 100 characters, keywords is an array of up to 20 strings each between 1 and 60 characters, publicReplies is an array of up to 5 strings each between 1 and 500 characters, and dmMessage is a string between 1 and 1000 characters. The optional status field accepts active or paused, postScope accepts any or specific, and matchMode accepts exact, contains or word. Use platformPostId with at least 1 character and postPermalink as a URI when you need to target a specific post, and use excludeKeywords as an array of up to 20 strings each between 1 and 60 characters to exclude matching comments. The source contract marks platformPostId and postPermalink as optional in the request, so do not treat them as universally required, and do not assume defaults for the optional fields.

Worked example request

The worked request example in the code examples shows the minimal documented body with accountId, name, postScope set to any, keywords, publicReplies and dmMessage. Replace each string placeholder with a real value that satisfies the length and item constraints, keep the JSON types exact, and send the body with the x-access-key header. After sending, verify the response status before reading the body: only a 201 response contains the automation object.

201 application/json response

A 201 application/json response contains success set to true and an automation object. The automation object contains id, accountId, platform, name, status, trigger, actions, stats, createdAt and updatedAt. The trigger object contains postScope, platformPostId, postPermalink, postId, keywords, matchMode and excludeKeywords, where platformPostId, postPermalink and postId are string or null in the response. The actions object contains publicReplies and dmMessage. The stats object contains triggered, succeeded and failed as numbers, plus lastRunAt and lastError as string or null. Store the returned automation id for later list or update operations, and check stats fields to understand whether the automation has run.

Error status responses 400, 403, 404 and 424

The documented error statuses are 400, 403, 404 and 424, and each returns an application/json body with success and message. The contract specifies the status codes and that shape only, so client code should handle each code distinctly, display or log the message, and avoid inventing a specific cause for any of them. A practical failure check is to branch on the exact status code, confirm that success is present in the body, and only treat a 201 response as a successful creation.

Input contract checklist

Before publishing client code against this endpoint, run a final checklist: confirm the method is POST, the path is /v1/comment-automations/ with its trailing slash, the origin is supplied through {{API_BASE_URL}}, the x-access-key header is set, all required fields are present with correct types, enums use only the documented values, and array and string limits are respected. Then confirm that the client handles the 201 automation response and each documented error status without assuming undocumented meanings or defaults.

Request body fields
FieldRequiredTypeConstraints / enum
accountIdRequiredstring
nameRequiredstring1 <= length <= 100
statusOptionalstring"active" | "paused"
postScopeRequiredstring"any" | "specific"
platformPostIdOptionalstring1 <= length
postPermalinkOptionalstringFormat: uri
keywordsRequiredarray<string>items <= 20; each item 1 <= length <= 60
matchModeOptionalstring"exact" | "contains" | "word"
excludeKeywordsOptionalarray<string>items <= 20; each item 1 <= length <= 60
publicRepliesRequiredarray<string>items <= 5; each item 1 <= length <= 500
dmMessageRequiredstring1 <= length <= 1000

Exact request contract for POST /v1/comment-automations/

201 response fields
FieldTypeNotes
successbooleanRequired
automation.idstringRequired
automation.accountIdstringRequired
automation.platformstringRequired
automation.namestringRequired
automation.statusstring"active" | "paused"
automation.trigger.postScopestring"any" | "specific"
automation.trigger.platformPostIdstring | nullRequired in response
automation.trigger.postPermalinkstring | nullRequired in response
automation.trigger.postIdstring | nullRequired in response
automation.trigger.keywordsarray<string>Required
automation.trigger.matchModestring"exact" | "contains" | "word"
automation.trigger.excludeKeywordsarray<string>Required
automation.actions.publicRepliesarray<string>Required
automation.actions.dmMessagestringRequired
automation.stats.triggerednumberRequired
automation.stats.succeedednumberRequired
automation.stats.failednumberRequired
automation.stats.lastRunAtstring | nulldate-time or null
automation.stats.lastErrorstring | nullRequired
automation.createdAtstringdate-time
automation.updatedAtstringdate-time

Exact 201 response contract

Response status matrix
StatusContent typeBody shapeDocumented meaning
201application/json{success, automation}Automation created
400application/json{success, message}Not specified in source
403application/json{success, message}Not specified in source
404application/json{success, message}Not specified in source
424application/json{success, message}Not specified in source

Statuses and shapes only; meanings not specified in source

Frequently asked questions

What is required to create a comment automation?

Send POST to {{API_BASE_URL}}/v1/comment-automations/ with the x-access-key header and a JSON body containing accountId, name, postScope, keywords, publicReplies and dmMessage. Optional fields are status, platformPostId, postPermalink, matchMode and excludeKeywords.

What does a successful 201 response contain?

A 201 response returns success and an automation object containing id, accountId, platform, name, status, trigger, actions, stats, createdAt and updatedAt. The trigger echoes postScope, platformPostId, postPermalink, postId, keywords, matchMode and excludeKeywords, while actions echoes publicReplies and dmMessage.

Which error statuses are documented for this endpoint?

The documented error statuses are 400, 403, 404 and 424, each with a JSON body containing success and message. The source contract does not specify a distinct meaning for each status, so clients should branch on the status code and surface the message without assuming a cause.

Create Comment Automation request example
curl -X POST "{{API_BASE_URL}}/v1/comment-automations/" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "accountId": "string",
    "name": "string",
    "postScope": "any",
    "keywords": [
      "string"
    ],
    "publicReplies": [
      "string"
    ],
    "dmMessage": "string"
  }'
201 response example
{
  "success": true,
  "automation": {
    "id": "string",
    "accountId": "string",
    "platform": "string",
    "name": "string",
    "status": "active",
    "trigger": {
      "postScope": "any",
      "platformPostId": "string",
      "postPermalink": "string",
      "postId": "string",
      "keywords": [
        "string"
      ],
      "matchMode": "exact",
      "excludeKeywords": [
        "string"
      ]
    },
    "actions": {
      "publicReplies": [
        "string"
      ],
      "dmMessage": "string"
    },
    "stats": {
      "triggered": 0,
      "succeeded": 0,
      "failed": 0,
      "lastRunAt": "2019-08-24T14:15:22Z",
      "lastError": "string"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Error response example for 400, 403, 404 and 424
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.accountIdstring__1Yes
body#1body.namestring__2Yeskind: ; value: 1 <= length <= 100
body#1body.statusstring__3No
body#1body.status[variant1]string__3_extends:__4kind: ; value: "active"
body#1body.status[variant2]string__3_extends:__5kind: ; value: "paused"
body#1body.postScopestring__6Yes
body#1body.postScope[variant1]string__6_extends:__7kind: ; value: "any"
body#1body.postScope[variant2]string__6_extends:__8kind: ; value: "specific"
body#1body.platformPostIdstring__9Nokind: ; value: 1 <= length
body#1body.postPermalinkstring__10Nokind: ; value: uri
body#1body.keywordsarray<string>__11Yeskind: ; value: items <= 20
body#1body.keywords[]string__12kind: ; value: 1 <= length <= 60
body#1body.matchModestring__13No
body#1body.matchMode[variant1]string__13_extends:__14kind: ; value: "exact"
body#1body.matchMode[variant2]string__13_extends:__15kind: ; value: "contains"
body#1body.matchMode[variant3]string__13_extends:__16kind: ; value: "word"
body#1body.excludeKeywordsarray<string>__17Nokind: ; value: items <= 20
body#1body.excludeKeywords[]string__18kind: ; value: 1 <= length <= 60
body#1body.publicRepliesarray<string>__19Yeskind: ; value: items <= 5
body#1body.publicReplies[]string__20kind: ; value: 1 <= length <= 500
body#1body.dmMessagestring__21Yeskind: ; value: 1 <= length <= 1000
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.automationobject__2Yes
response#2response.automation.idstring__3Yes
response#2response.automation.accountIdstring__4Yes
response#2response.automation.platformstring__5Yes
response#2response.automation.namestring__6Yes
response#2response.automation.statusstring__7Yes
response#2response.automation.status[variant1]string__7_extends:__8kind: schemaValueIn; value: "active"
response#2response.automation.status[variant2]string__7_extends:__9kind: schemaValueIn; value: "paused"
response#2response.automation.triggerobject__10Yes
response#2response.automation.trigger.postScopestring__11Yes
response#2response.automation.trigger.postScope[variant1]string__11_extends:__12kind: schemaValueIn; value: "any"
response#2response.automation.trigger.postScope[variant2]string__11_extends:__13kind: ; value: "specific"
response#2response.automation.trigger.platformPostIdstring | null__14Yes
response#2response.automation.trigger.platformPostId[variant1]string__14_extends:__15
response#2response.automation.trigger.platformPostId[variant2]null__14_extends:__16
response#2response.automation.trigger.postPermalinkstring | null__17Yes
response#2response.automation.trigger.postPermalink[variant1]string__17_extends:__18
response#2response.automation.trigger.postPermalink[variant2]null__17_extends:__19
response#2response.automation.trigger.postIdstring | null__20Yes
response#2response.automation.trigger.postId[variant1]string__20_extends:__21
response#2response.automation.trigger.postId[variant2]null__20_extends:__22
response#2response.automation.trigger.keywordsarray<string>__23Yes
response#2response.automation.trigger.keywords[]string__24
response#2response.automation.trigger.matchModestring__25Yes
response#2response.automation.trigger.matchMode[variant1]string__25_extends:__26kind: ; value: "exact"
response#2response.automation.trigger.matchMode[variant2]string__25_extends:__27kind: ; value: "contains"
response#2response.automation.trigger.matchMode[variant3]string__25_extends:__28kind: ; value: "word"
response#2response.automation.trigger.excludeKeywordsarray<string>__29Yes
response#2response.automation.trigger.excludeKeywords[]string__30
response#2response.automation.actionsobject__31Yes
response#2response.automation.actions.publicRepliesarray<string>__32Yes
response#2response.automation.actions.publicReplies[]string__33
response#2response.automation.actions.dmMessagestring__34Yes
response#2response.automation.statsobject__35Yes
response#2response.automation.stats.triggerednumber__36Yes
response#2response.automation.stats.succeedednumber__37Yes
response#2response.automation.stats.failednumber__38Yes
response#2response.automation.stats.lastRunAtstring | null__39Yes
response#2response.automation.stats.lastRunAt[variant1]string__39_extends:__40kind: ; value: date-time
response#2response.automation.stats.lastRunAt[variant2]null__39_extends:__41
response#2response.automation.stats.lastErrorstring | null__42Yes
response#2response.automation.stats.lastError[variant1]string__42_extends:__43
response#2response.automation.stats.lastError[variant2]null__42_extends:__44
response#2response.automation.createdAtstring__45Yeskind: ; value: date-time
response#2response.automation.updatedAtstring__46Yeskind: ; value: date-time
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes