---
title: "Update an automation"
method: PATCH
path: "/automations/{id}"
tags: ["Automations"]
---

# Update an automation

`PATCH /automations/{id}`

## Request

- Base URL: `https://api.omnisocials.com/v1`
- URL: `https://api.omnisocials.com/v1/automations/{id}`
- Auth: HTTP bearer

Partial update. `status` pauses (`paused`) or resumes (`active`) the automation. `trigger`, `actions` and `limits` are merged into the stored sections: keys you omit keep their value (new `keywords` keep the kinds, the scope and the match; a new `dm.text` keeps the public reply). `public_reply.variations: []` or `enabled: false` turns the public reply off; `limits.max_sends: null` removes that limit. Another `post_id`, `instagram_media_id` or `facebook_post_id` moves the automation to that post. The platform never changes: a body that names another platform (or `instagram_media_id` on a Facebook automation, `facebook_post_id` on an Instagram one) answers 400 `platform_immutable`. A `completed` automation starts again when its limits or trigger change.

## Path parameters

- `id` string, required

## Request body

- AutomationInput: The fields of an automation. POST /automations requires `actions`; PATCH /automations/{id} takes any subset.
  - `name` string: A label for the automations list (max 120 characters).
  - `platform` 'instagram' | 'facebook' | 'x': The channel the automation runs on. Default `instagram`. `instagram_media_id` implies `instagram` and `facebook_post_id` implies `facebook`; a body that names another platform answers 400 `validation_error`. On PATCH it cannot change: another platform answers 400 `platform_immutable`. `x` answers DMs to the connected X account: only the `dm` kind (X allows an automated DM only after the person DMed you), the workspace needs X DMs turned on in the dashboard (else 409 `x_dms_off` for an active automation; `status: paused` saves it), every answer ends with the line "Reply STOP to stop automatic messages.", and a person who replies STOP gets no automatic DM from the account again. X does not give apps the messages of an encrypted X Chat conversation, so those get no answer.
  - `trigger` AutomationTrigger
    - `kinds` string[]: What starts the automation. `comment` = a comment on an Instagram post or reel, or on a Facebook Page post (needs `scope`). `dm` = a keyword in a DM to the Instagram account, in a Messenger message to the Facebook Page, or in a DM to the X account. `story_reply` = a keyword in a reply to an Instagram story (Instagram only: Facebook has no story replies, and a Facebook automation with `story_reply` answers 400 `validation_error`). On X only `dm` exists. One automation can listen to several. Default `["comment"]` (pass `["dm"]` on X).
    - `scope` 'post' | 'next_post' | 'any': For the `comment` kind: `post` = one post (pass `post_id`, `instagram_media_id` or `facebook_post_id` on the request), `next_post` = the next post the workspace publishes on the automation's platform, `any` = every post of the account or Page. Default `post`.
    - `keywords` string[]: Up to 20 keywords (60 characters each), matched case-insensitively. Required unless `match` is `any`.
    - `match` 'word' | 'contains' | 'any': `word` (default) = the keyword stands on its own ("guide", "Guide!" match; "linkedin" does not match "link"), `contains` = the keyword appears anywhere, `any` = every comment or message with text.
  - `post_id` string: For `scope` `post`: an OmniSocials post (scheduled or live) that goes to the automation's platform. A post that does not go there answers 400 `post_not_instagram` or `post_not_facebook`. One automation per post and platform: a post that goes to Instagram and Facebook can have one of each.
  - `instagram_media_id` string: For `scope` `post` on Instagram: the numeric id of a post or reel that was published outside OmniSocials (from the Instagram API, `GET /me/media`). The post is read from Instagram to check it belongs to the connected account.
  - `facebook_post_id` string: For `scope` `post` on Facebook: the id of a post that was published on the connected Facebook Page outside OmniSocials. Pass `{page-id}_{post-id}` or the post id alone (the Page id is put in front). The post is read from Facebook with the Page token; a post of another Page answers 404 `facebook_post_not_found`. Implies `platform: facebook`. Pass one of `post_id`, `instagram_media_id` or `facebook_post_id`.
  - `actions` AutomationActions
    - `dm` object, required
      - `text` string, required: The DM sent to the person (max 1000 characters). Sent once per person per automation. On Facebook it lands in Messenger.
    - `public_reply` object: A public reply under the comment, only for the `comment` kind. One of `variations` is picked at random per comment.
      - `enabled` boolean
      - `variations` string[]: Up to 10 replies of 300 characters.
  - `limits` AutomationLimits
    - `max_sends` integer, nullable: Stop after this many DMs (the automation becomes `completed`). Omit for no limit.
    - `stop_at` string, date-time, nullable: Stop at this time. Omit for no end.
  - `status` 'active' | 'paused': `paused` creates the automation without turning it on. Default `active`.

## Response `200`

Automation updated

- object
  - `data` Automation
    - `id` string
    - `type` 'comment_to_dm'
    - `platform` 'instagram' | 'facebook' | 'x': The channel the automation runs on: the connected Instagram account, the connected Facebook Page, or the connected X account. Set at create; it never changes.
    - `status` 'active' | 'paused' | 'completed': `completed` = `max_sends` or `stop_at` was reached. A new limit or trigger starts it again.
    - `name` string, nullable
    - `post_id` string, nullable: The OmniSocials post the automation listens on, for the `post` scope. `null` for a post published outside OmniSocials and for the other scopes.
    - `instagram_media_id` string, nullable: The Instagram media id the automation listens on. Set once the post is live on Instagram. Always `null` for a Facebook automation.
    - `facebook_post_id` string, nullable: The Facebook Page post id (`{page-id}_{post-id}`) the automation listens on. Set once the post is live on the Page. Always `null` for an Instagram automation.
    - `post` object, nullable: A snapshot of the post: `source` (`omnisocials`, `instagram` or `facebook`: a post picked by id is read from that platform), `id`, `caption`, `thumbnail_url`, `permalink`, `media_type` and, for an OmniSocials post, `status` and `live`.
    - `trigger` AutomationTrigger
      - `kinds` string[]: What starts the automation. `comment` = a comment on an Instagram post or reel, or on a Facebook Page post (needs `scope`). `dm` = a keyword in a DM to the Instagram account, in a Messenger message to the Facebook Page, or in a DM to the X account. `story_reply` = a keyword in a reply to an Instagram story (Instagram only: Facebook has no story replies, and a Facebook automation with `story_reply` answers 400 `validation_error`). On X only `dm` exists. One automation can listen to several. Default `["comment"]` (pass `["dm"]` on X).
      - `scope` 'post' | 'next_post' | 'any': For the `comment` kind: `post` = one post (pass `post_id`, `instagram_media_id` or `facebook_post_id` on the request), `next_post` = the next post the workspace publishes on the automation's platform, `any` = every post of the account or Page. Default `post`.
      - `keywords` string[]: Up to 20 keywords (60 characters each), matched case-insensitively. Required unless `match` is `any`.
      - `match` 'word' | 'contains' | 'any': `word` (default) = the keyword stands on its own ("guide", "Guide!" match; "linkedin" does not match "link"), `contains` = the keyword appears anywhere, `any` = every comment or message with text.
    - `actions` AutomationActions
      - `dm` object, required
        - `text` string, required: The DM sent to the person (max 1000 characters). Sent once per person per automation. On Facebook it lands in Messenger.
      - `public_reply` object: A public reply under the comment, only for the `comment` kind. One of `variations` is picked at random per comment.
        - `enabled` boolean
        - `variations` string[]: Up to 10 replies of 300 characters.
    - `limits` AutomationLimits
      - `max_sends` integer, nullable: Stop after this many DMs (the automation becomes `completed`). Omit for no limit.
      - `stop_at` string, date-time, nullable: Stop at this time. Omit for no end.
    - `stats` AutomationStats
      - `matched` integer
      - `sent` integer
      - `skipped` integer
      - `failed` integer
      - `last_event_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400`: Invalid update (`validation_error`, `no_fields`), or `platform_immutable` (the body names another platform)
- `404`: Automation not found, or the new post was not found (`post_not_found`, `instagram_media_not_found`, `facebook_post_not_found`)
- `409`: `automation_exists`: the new post already has an automation on this platform, or `x_dms_off`: an X automation cannot be set `active` while X DMs are off for the workspace

## Changes

- **2026-10-25** `4e6e28d10892`: 1 warning, 1 info
  - added the new `x` enum value to the `data/platform` response property for the response status `200`
  - added the new `x` enum value to the request property `platform`
- **2026-10-22** `1e06adee390e`: 1 warning, 3 info
  - added the new `facebook` enum value to the `data/platform` response property for the response status `200`
  - added the new optional request property `facebook_post_id`
  - added the new optional request property `platform`
  - added the optional property `data/facebook_post_id` to the response with the `200` status
- **2026-10-21** `3aff2f2e3458`: 1 info
  - the request property `actions` became optional
- **2026-10-11** `b64e4a7a8c4b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omnisocials/apis/omnisocials-api/changes/automations/:id/patch.md)

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) - [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisocials/apis/omnisocials-api/revisions/46e479c09474?raw)