OMomnisocials
Automations

Create an automation

Changed on

Creates a comment-to-DM automation on the connected Instagram account (default) or on the connected Facebook Page (platform: facebook). When somebody comments a keyword on the post (or sends it in a DM, or in an Instagram story reply, see trigger.kinds), the account sends them actions.dm.text as a private message, once per person, and optionally posts one of actions.public_reply.variations under the comment. On Facebook the DM lands in Messenger. Meta's rules are the same on both: one private reply per comment, within 7 days of the comment; a follow-up is only possible after the person answers (24-hour window). OmniSocials caps sends at 180 DMs an hour per account and platform; an answer over the cap waits in a queue for up to an hour. On X (platform: x) only trigger.kinds: ["dm"] exists: the account answers a DM with the keyword (or any first message with match: any), once per person, after X DMs are turned on for the workspace in the dashboard; X allows 15 answers per 15 minutes per account, and each answer ends with "Reply STOP to stop automatic messages.". For scope post, pass one of post_id (an OmniSocials post that goes to the platform; a scheduled post starts listening once it is live), instagram_media_id (an Instagram post published outside OmniSocials) or facebook_post_id (a Page post published outside OmniSocials). Needs the opt-in automations:write scope and a connected Instagram account, Facebook Page or X account; an active X automation also needs X DMs on (else 409 x_dms_off; status: paused always saves).

post/automations

Request

  • Base URL
    https://api.omnisocials.com/v1
  • URL
    https://api.omnisocials.com/v1/automations
  • Auth
    HTTP bearer

Request body

namestring

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.

post_idstring

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_idstring

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_idstring

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.

status'active' | 'paused'

paused creates the automation without turning it on. Default active.

Example request

{
  "name": "Guide DM",
  "platform": "instagram",
  "trigger": {
    "keywords": [
      "guide"
    ]
  },
  "post_id": "1024",
  "instagram_media_id": "17912345678901234",
  "facebook_post_id": "104857600123456_987654321098765",
  "actions": {
    "dm": {
      "text": "Here is the guide: https://example.com/guide"
    },
    "public_reply": {
      "enabled": true,
      "variations": [
        "Sent you a DM!"
      ]
    }
  },
  "limits": {
    "max_sends": 500,
    "stop_at": "2026-11-30T23:00:00.000Z"
  }
}

Response

Automation created

Example response

{
  "data": {
    "id": "318",
    "name": "Guide DM",
    "post_id": "1024",
    "instagram_media_id": "17912345678901234",
    "facebook_post_id": "104857600123456_987654321098765",
    "trigger": {
      "keywords": [
        "guide"
      ]
    },
    "actions": {
      "dm": {
        "text": "Here is the guide: https://example.com/guide"
      },
      "public_reply": {
        "enabled": true,
        "variations": [
          "Sent you a DM!"
        ]
      }
    },
    "limits": {
      "max_sends": 500,
      "stop_at": "2026-11-30T23:00:00.000Z"
    },
    "stats": {
      "matched": 120,
      "sent": 112,
      "skipped": 6,
      "failed": 2,
      "last_event_at": "2026-10-21T15:00:12.000Z"
    },
    "created_at": "2026-10-20T14:32:10.000Z",
    "updated_at": "2026-10-20T14:35:42.000Z"
  }
}

Changes

  • 4e6e28d10892Revision changes
    • warning

      added the new x enum value to the / response property for the response status

    • info

      added the new x enum value to the request property ////

  • 1e06adee390eRevision changes
    • warning

      added the new facebook enum value to the / response property for the response status

    • info

      added the new optional request property ////

    • info

      added the new optional request property ////

    • info

      added the optional property / to the response with the status