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

<Callout type="warn">
  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.
</Callout>

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.' },
]"
/>

<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.' },
]"
/>

## Example request [#example-request]

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

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

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

## See also [#see-also]

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