# PATCH /v1/projects/:projectId/engagement (/docs/api/reference/engagement/patch-engagement)



<Endpoint method="PATCH" path="/v1/projects/:projectId/engagement" auth="Bearer" scope="engagement:write" phase="1" />

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.

<Parameters
  title="Path"
  rows="[
  { name: 'projectId', type: 'string', required: true, description: 'Project whose engagement layer you want to update.' },
]"
/>

<Parameters
  title="Body"
  rows="[
  { name: 'projectLayerId', type: 'string', description: 'Required only if the project has more than one Social Engagement layer. Otherwise server picks the single layer.' },
  { name: 'enabled', type: 'boolean', description: 'Master switch. Set to false to pause auto-engagement without dropping the config.' },
  { name: 'firstComment', type: 'FirstComment', description: 'First-comment policy. Partial merge - unspecified sub-fields keep their current values.' },
  { name: 'replyToComments', type: 'ReplyToComments', description: 'Reply policy. Partial merge.' },
]"
/>

<Parameters
  title="FirstComment"
  rows="[
  { name: 'targets', type: 'string[]', description: 'Platforms: tiktok, instagram. Omit a platform to turn first-comment off for it.' },
  { name: 'commentTemplate', type: 'string', description: 'Comment body. 1–500 chars. With strategy=&#x22;generated&#x22; (default), used as style examples for the LLM. With strategy=&#x22;literal&#x22;, published verbatim.' },
  { name: 'strategy', type: '&#x22;literal&#x22; | &#x22;generated&#x22;', description: 'How the comment is produced. literal = publish commentTemplate verbatim (no LLM). generated = LLM-written using commentTemplate as examples (default).' },
]"
/>

<Parameters
  title="ReplyToComments"
  rows="[
  { name: 'targets', type: 'string[]', description: 'Platforms where auto-replies run.' },
  { name: 'autoReplyDelay', type: 'string (ISO-8601 duration)', description: 'Delay before replying. ISO-8601 duration between PT30S and PT1H inclusive (for example PT30S, PT5M, PT1H). Default PT3M.' },
  { name: 'tone', type: '&#x22;authentic&#x22; | &#x22;witty&#x22; | &#x22;professional&#x22; | &#x22;warm&#x22; | &#x22;casual&#x22; | &#x22;educational&#x22;', description: 'Brand-voice override applied to replies only. Falls back to the project-level engagement tone when omitted.' },
  { name: 'maxPerPostPerHour', type: 'integer (1–60)', description: 'Rolling-hour cap for owner replies on a single post. Trips before the lifetime per-post cap when exceeded.' },
  { name: 'ignoreCommentsMatching', type: 'string[] (regex sources, max 20)', description: '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.' },
  { name: 'escalateNegativeSentiment', type: 'boolean', description: 'When true, comments classified as negative sentiment route into draft mode for human review instead of auto-publishing.' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    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"
        }
      }'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    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",
      },
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    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",
        },
    )
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="Updated config">
  ```json
  {
    "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"
    }
  }
  ```
</Response>

## Errors [#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.                                                                                                                                                                                                                                                         |

## See also [#see-also]

* [`GET /v1/projects/:id/engagement`](/docs/api/reference/engagement/get-engagement) - read current config
* Configure auto-pilot engagement - end-to-end walk-through