CommentAutomationUpdateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/postzen-dev/json-schema/postzen-dev-comment-automation-update-request-schema.json",
  "title": "CommentAutomationUpdateRequest",
  "description": "Partial update. accountId is immutable. Enabling checks capabilities and duplicate per-post limits. Unsupported fields are rejected as on create.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/postzen-dev-openapi.json#/components/schemas/CommentAutomationUpdateRequest",
  "type": "object",
  "properties": {
    "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": "Plain text: at most 1000 UTF-8 bytes. With buttons: at most 640 characters."
    },
    "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. Pass [] to clear."
    },
    "template": {
      "oneOf": [
        {
          "$ref": "#/$defs/CommentAutomationTemplate"
        },
        {
          "type": "null"
        }
      ],
      "description": "Send null to remove the card and go back to dmMessage."
    },
    "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": {
      "allOf": [
        {
          "$ref": "#/$defs/CommentAutomationAudience"
        }
      ],
      "nullable": true
    },
    "openingDm": {
      "allOf": [
        {
          "$ref": "#/$defs/CommentAutomationOpeningDm"
        }
      ],
      "nullable": true,
      "description": "Send null to turn the Opening DM off. A follower-based `audience` still sends the defaults."
    },
    "followGate": {
      "allOf": [
        {
          "$ref": "#/$defs/CommentAutomationFollowGate"
        }
      ],
      "nullable": true
    }
  },
  "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."
        }
      }
    }
  }
}