PATCH /v1/projects/:projectId/engagement

Update the engagement config. V1 template shape only today; v2 fields are planned.

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.

Only the v1 template shape is accepted today. Passing a v2 field (firstComment.strategy, replies.tone, replies.maxPerPostPerHour, replies.ignoreCommentsMatching, replies.escalateNegativeSentiment) returns 403 FORBIDDEN_FENCE — no partial update, no silent drop. The fence lifts once v2 ships.

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.

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.

Example request

curl -X PATCH https://api.layers.com/v1/projects/prj_01HX9Y7K8M2P4RSTUV56789AB/engagement \
  -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..." \
  -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_01HX9Y7K8M2P4RSTUV56789AB",
  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_01HX9Y7K8M2P4RSTUV56789AB",
    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.
401	`UNAUTHENTICATED`	Missing or invalid key.
403	`FORBIDDEN_SCOPE`	Key lacks `engagement:write`.
403	`FORBIDDEN_FENCE`	Body contains a v2 field (`strategy`, `tone`, `maxPerPostPerHour`, `ignoreCommentsMatching`, `escalateNegativeSentiment`). Strip them and retry.
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