PATCH /v1/projects/:projectId/engagement

Update the auto-pilot engagement config — first-comment template and reply-to-comments policy.

PATCH/v1/projects/:projectId/engagement

Phase 1stable

Auth: Bearer
Scope: engagement:write

Partial update for the project's engagement config - pass only the fields you want to change. Omitted fields stay as they are.

Auto-replies run through brand-voice and safety filters before posting. You don't configure the filters here - they're fixed - but it's worth knowing that comments flagged as unsafe never go out, regardless of your config.

Path

projectId
stringrequired
Project whose engagement layer you want to update.

Body

projectLayerId
stringoptional
Required only if the project has more than one Social Engagement layer. Otherwise server picks the single layer.
enabled
booleanoptional
Master switch. Set to false to pause auto-engagement without dropping the config.
firstComment
FirstCommentoptional
First-comment policy. Partial merge - unspecified sub-fields keep their current values.
replyToComments
ReplyToCommentsoptional
Reply policy. Partial merge.

FirstComment

targets
string[]optional
Platforms: tiktok, instagram. Omit a platform to turn first-comment off for it.
commentTemplate
stringoptional
Comment body. 1–500 chars. With strategy="generated" (default), used as style examples for the LLM. With strategy="literal", published verbatim.
strategy
"literal" | "generated"optional
How the comment is produced. literal = publish commentTemplate verbatim (no LLM). generated = LLM-written using commentTemplate as examples (default).

ReplyToComments

targets
string[]optional
Platforms where auto-replies run.
autoReplyDelay
string (ISO-8601 duration)optional
Delay before replying. ISO-8601 duration between PT30S and PT1H inclusive (for example PT30S, PT5M, PT1H). Default PT3M.
tone
"authentic" | "witty" | "professional" | "warm" | "casual" | "educational"optional
Brand-voice override applied to replies only. Falls back to the project-level engagement tone when omitted.
maxPerPostPerHour
integer (1–60)optional
Rolling-hour cap for owner replies on a single post. Trips before the lifetime per-post cap when exceeded.
ignoreCommentsMatching
string[] (regex sources, max 20)optional
Regex allowlist of user-comment shapes to skip. Each pattern must compile as a JS RegExp. The first matching pattern aborts the reply for that comment.
escalateNegativeSentiment
booleanoptional
When true, comments classified as negative sentiment route into draft mode for human review instead of auto-publishing.

Example request

curl -X PATCH https://api.layers.com/v1/projects/prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39/engagement \
  -H "Authorization: Bearer lp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "firstComment": {
      "targets": ["tiktok", "instagram"],
      "commentTemplate": "Brewing tip: use filtered water - makes a bigger difference than you'\''d expect."
    },
    "replyToComments": {
      "targets": ["tiktok", "instagram"],
      "autoReplyDelay": "PT3M"
    }
  }'

const updated = await layers.engagement.patch({
  projectId: "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
  enabled: true,
  firstComment: {
    targets: ["tiktok", "instagram"],
    commentTemplate:
      "Brewing tip: use filtered water - makes a bigger difference than you'd expect.",
  },
  replyToComments: {
    targets: ["tiktok", "instagram"],
    autoReplyDelay: "PT3M",
  },
});

updated = layers.engagement.patch(
    project_id="prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
    enabled=True,
    first_comment={
        "targets": ["tiktok", "instagram"],
        "commentTemplate": "Brewing tip: use filtered water - makes a bigger difference than you'd expect.",
    },
    reply_to_comments={
        "targets": ["tiktok", "instagram"],
        "autoReplyDelay": "PT3M",
    },
)

Response

200Updated config

{
  "projectLayerId": "pl_01HXZT9P2K4N5M6Q7RSTUV8WXY",
  "enabled": true,
  "firstComment": {
    "targets": ["tiktok", "instagram"],
    "commentTemplate": "Brewing tip: use filtered water - makes a bigger difference than you'd expect."
  },
  "replyToComments": {
    "targets": ["tiktok", "instagram"],
    "autoReplyDelay": "PT3M"
  }
}

Errors

Status	Code	When
422	`VALIDATION`	`commentTemplate` empty or > 500 chars; `autoReplyDelay` not an ISO-8601 duration or outside PT30S–PT1H; `targets` contains an unknown platform; `strategy` not in `literal\|generated`; `tone` not a brand-voice value; `maxPerPostPerHour` not an integer in 1–60; an `ignoreCommentsMatching` entry doesn't compile as a JS regex.
401	`UNAUTHENTICATED`	Missing or invalid key.
403	`FORBIDDEN_SCOPE`	Key lacks `engagement:write`.
404	`NOT_FOUND`	Project not in your organization, or no Social Engagement layer attached.
409	`CONFLICT`	Project has multiple engagement layers and `projectLayerId` was not supplied.

PATCH /v1/projects/:projectId/engagement

Example request

Response

Errors

See also

On this page