CommentAutomationCreateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postzen-dev/json-schema/postzen-dev-comment-automation-create-request-schema.json",
  "title": "CommentAutomationCreateRequest",
  "description": "Maximum 100 automations per user; at most one active per-post automation for each account and post reference. alsoMatchInDms, clickTag and linkTracking:true return 400 unsupported. Instagram only. A comment permits one private reply ever, within 7 days. Story replies use normal DMs inside the 24-hour messaging window. Buttons and image cards (template) fall back to text with title and URL lines if Meta rejects the template. Reconnect the account on 403 platformCapabilityMissing to grant instagram_business_manage_comments and instagram_business_manage_messages.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postzen-dev-openapi.json#/components/schemas/CommentAutomationCreateRequest",
  "type": "object",
  "required": [
    "accountId",
    "name"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "description": "Connected Instagram account id. Immutable after creation."
    },
    "profileId": {
      "type": "string",
      "description": "If supplied, must equal the account profile."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Trimmed name."
    },
    "trigger": {
      "type": "string",
      "enum": [
        "comment",
        "story_reply"
      ],
      "default": "comment"
    },
    "platformPostId": {
      "type": "string",
      "description": "Instagram media or story id. Mutually exclusive with postId; omit both for account-wide matching."
    },
    "postId": {
      "type": "string",
      "description": "Owned PostZen post with an Instagram target on this account. Resolves providerPostId at match time, including posts not yet published. Mutually exclusive with platformPostId."
    },
    "postTitle": {
      "type": "string",
      "maxLength": 200
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      },
      "maxItems": 50,
      "default": [],
      "description": "Trimmed and deduplicated case-insensitively. Empty matches every comment."
    },
    "matchMode": {
      "type": "string",
      "enum": [
        "exact",
        "contains",
        "word"
      ],
      "default": "contains"
    },
    "excludeKeywords": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      },
      "maxItems": 50,
      "default": [],
      "description": "Vetoes matching using the same matchMode; trimmed and deduplicated case-insensitively."
    },
    "typoTolerance": {
      "type": "boolean",
      "default": false,
      "description": "word mode only: Damerau-Levenshtein per word, 1 edit for 4–7 characters, 2 edits for 8+, none for fewer than 4."
    },
    "dmMessage": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Required unless template is set. Plain text: at most 1000 UTF-8 bytes. With buttons: at most 640 characters. Ignored when a template is sent."
    },
    "dmMessageVariations": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1000
      },
      "maxItems": 5,
      "default": [],
      "description": "Same limits as dmMessage. Uniform random choice from the base message and variations."
    },
    "buttons": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CommentAutomationButton"
      },
      "maxItems": 3,
      "default": [],
      "description": "Mutually exclusive with template."
    },
    "template": {
      "$ref": "#/$defs/CommentAutomationTemplate"
    },
    "commentReply": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Optional public reply, sent only after successful comment DM. Ignored for story_reply."
    },
    "commentReplyVariations": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1000
      },
      "maxItems": 5,
      "default": [],
      "description": "Uniform random choice independent of the DM."
    },
    "dmDelaySeconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 86400,
      "default": 0
    },
    "commentReplyDelaySeconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 86400,
      "default": 0,
      "description": "Effective delay is max(dmDelaySeconds, commentReplyDelaySeconds)."
    },
    "isActive": {
      "type": "boolean",
      "default": true
    },
    "linkTracking": {
      "type": "boolean",
      "enum": [
        false
      ],
      "default": false
    },
    "audience": {
      "$ref": "#/$defs/CommentAutomationAudience"
    },
    "openingDm": {
      "allOf": [
        {
          "$ref": "#/$defs/CommentAutomationOpeningDm"
        }
      ],
      "description": "Send an object (even `{}` for the defaults) to turn the Opening DM on. Omit to leave it off, unless `audience` filters by followers."
    },
    "followGate": {
      "$ref": "#/$defs/CommentAutomationFollowGate"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CommentAutomationAudience": {
      "type": "object",
      "additionalProperties": false,
      "description": "Who a comment automation answers. Instagram only - Meta exposes the follow relationship on no other platform, and only for people who have MESSAGED the account (a comment grants no consent). So any rule here sends the Opening DM first (`openingDm`, defaults when unset) and checks the person when they tap its button. Story replies are already messages and are checked right away.",
      "properties": {
        "followerStatus": {
          "type": "string",
          "enum": [
            "any",
            "follower",
            "non_follower"
          ],
          "default": "any"
        },
        "minFollowerCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Omit for no size rule. Zero is stored as absent."
        },
        "whenUnknown": {
          "type": "string",
          "enum": [
            "send",
            "skip",
            "verify"
          ],
          "default": "send",
          "description": "Applies after the Opening DM tap, when Instagram still will not reveal the follow relationship. `send` (default) - deliver the DM anyway (fails open). `skip` - stay silent. `verify` - treat them as not following, so followerStatus=follower sends the follow request (`followGate.message`); tapping its button re-checks."
        }
      }
    },
    "CommentAutomationButton": {
      "type": "object",
      "required": [
        "type",
        "title",
        "url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "url"
          ]
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20
        },
        "url": {
          "type": "string",
          "format": "uri",
          "pattern": "^https?://",
          "description": "Public HTTP(S) URL; private hosts and embedded credentials are rejected."
        }
      }
    },
    "CommentAutomationFollowGate": {
      "type": "object",
      "additionalProperties": false,
      "description": "Copy for the follow request (audience.followerStatus=follower). Sensible defaults are used for any field left empty.",
      "properties": {
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 640,
          "default": "Follow us to get the link, then tap the button below 👇",
          "description": "The follow request sent after the Opening DM tap to people who do not follow yet."
        },
        "buttonLabel": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "default": "I'm following",
          "description": "Label of the button on the follow request. Tapping it re-checks the follow."
        },
        "notFollowingMessage": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1000,
          "description": "Sent when they tap the follow request button but still do not follow. The button stays, so they can follow and tap again.",
          "default": "Looks like you're not following yet. Follow us, then tap the button again."
        }
      }
    },
    "CommentAutomationOpeningDm": {
      "type": "object",
      "additionalProperties": false,
      "description": "A first DM with a button, sent as the private reply to the comment. Tapping the button counts as the person messaging you, which opens the 24-hour messaging window and lets Instagram reveal whether they follow you. Required for any `audience` rule: when `audience` filters by followers and no `openingDm` is set, the defaults are used. Ignored for story replies, which already count as a message.",
      "properties": {
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 640,
          "default": "Hey! Thanks so much for your interest 😊\n\nTap below and I'll send you the link ✨",
          "description": "Trimmed. Empty or omitted uses the default."
        },
        "buttonLabel": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "default": "Send me the link",
          "description": "Trimmed. Empty or omitted uses the default."
        }
      }
    },
    "CommentAutomationTemplate": {
      "type": "object",
      "required": [
        "type",
        "elements"
      ],
      "description": "Meta generic template: an image card sent instead of dmMessage and buttons. If Meta rejects it for a send, PostZen resends the card's title, subtitle, image URL, and button links as plain text and marks the log buttonsDropped.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "generic"
          ]
        },
        "imageAspectRatio": {
          "type": "string",
          "enum": [
            "horizontal",
            "square"
          ],
          "default": "horizontal"
        },
        "elements": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CommentAutomationTemplateElement"
          },
          "minItems": 1,
          "maxItems": 10,
          "description": "One card per element. Instagram renders several as a swipeable carousel."
        }
      }
    },
    "CommentAutomationTemplateElement": {
      "type": "object",
      "required": [
        "title",
        "imageUrl"
      ],
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 80,
          "description": "Card title. Trimmed."
        },
        "subtitle": {
          "type": "string",
          "maxLength": 80,
          "description": "Optional line under the title."
        },
        "imageUrl": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://",
          "description": "Public HTTPS image URL that Meta fetches. A `publicUrl` from `POST /v1/media/presign` qualifies and is kept for as long as an automation uses it; upload the bytes before saving the automation."
        },
        "buttons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CommentAutomationButton"
          },
          "maxItems": 3,
          "default": [],
          "description": "Up to three link buttons under the card."
        }
      }
    }
  }
}