omnisocials 0.8.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43d0cc71e753d98ddbaa8b1732f140ecfc3d578d02a8e8df81e248c6c9c75131
-  data.tar.gz: a66ae890324f9adc7b37b57add4e76ce1be1b110d4b15f751c611bcbfa6adf61
+  metadata.gz: 473f213709ed52c13f70cd2b84c26b7d92c2355731dfc0fb676d3b0f3949fbac
+  data.tar.gz: 423f50628c3c4dae0b98d3c486337a573cb32972af6cdf74cd41a8646899f162
 SHA512:
-  metadata.gz: 0b30af0ebca987fe7bebb4710d7648d2c0361e8709cdf716897d4f1f82808dc916159742dcae7c9c0512863e01f68435d642a9341e8254d9cc11511459b496ce
-  data.tar.gz: e50bd7f05fe6a2e516ff9ea31bb28307af242c4118ca1a30583008b88591e3b2d9c080fb50447137133f036e21d6fed8721b90bd380cfb670dc3870868ac7710
+  metadata.gz: 5a047afd2262cd53375d22fef8b7c79ed254fddf8e5057cdb4cdd909308821bc19c81b73cddf04ad736cecca998bf0ee0f974f6205d2e0bd4472547ee4464dfa
+  data.tar.gz: 27c340cc9e7954eae71506ed026b10b1421130cb59c283cab8fdbac3016759b5e449c406367579acbc3cf4c4c1b70fb151750350d8e6bbb27fe330eaaf49cba3

data/README.md

@@ -1,6 +1,6 @@
 # OmniSocials Ruby SDK
 
-The official Ruby client for the [OmniSocials](https://omnisocials.com) Public API. Schedule and publish posts, upload media, and read analytics across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads, Mastodon, and Google Business.
+The official Ruby SDK for OmniSocials: post, schedule, reply and report on 12 social platforms (Instagram, Facebook, LinkedIn, X, TikTok, YouTube, Threads, Pinterest, Bluesky, Mastodon, Google Business and Telegram) from one API. Guide: [omnisocials.com/sdk/ruby](https://omnisocials.com/sdk/ruby)
 
 Full API reference: [https://docs.omnisocials.com](https://docs.omnisocials.com)
 
@@ -30,7 +30,7 @@ puts post["data"]["id"]
 
 ## Authentication
 
-Create an API key in the OmniSocials app under **Settings -> API Keys**. Keys look like `omsk_live_...` (or `omsk_test_...` for test keys) and are bound to one workspace.
+Create an API key in the OmniSocials app under **Settings -> API Keys**. Keys start with `omsk_live_` and are bound to one workspace. There are no test keys and no test mode: every key works on your real connected accounts. To try things safely, leave out `scheduled_at` so the post stays a draft (a draft never publishes on its own), or use a separate workspace with test accounts.
 
 Pass the key explicitly or set the `OMNISOCIALS_API_KEY` environment variable:
 
@@ -65,6 +65,54 @@ post = client.posts.create_and_publish(
 )
 ```
 
+### Planned drafts
+
+Pass `draft: true` with `scheduled_at` to store the post as a draft that keeps its time. It shows on the dashboard calendar at that slot with a dashed outline and the scheduler never publishes it: a person schedules it from the composer, or you do with `update` and `draft: false`. Use it when an agent proposes a slot that a human should confirm. `draft: true` is not allowed with `publish_now` or `approval_workflow_id` (`400 validation_error`). On `update`, `draft: false` without `scheduled_at` is a `400 validation_error` when the draft has no time or its time is in the past (pass a new `scheduled_at` then), and `draft: true` on a scheduled post unschedules it while keeping the time.
+
+```ruby
+proposal = client.posts.create(
+  content: "Proposed for Friday morning",
+  channels: ["instagram", "linkedin"],
+  scheduled_at: "2026-08-01T09:00:00Z",
+  draft: true
+)
+puts proposal["data"]["status"], proposal["data"]["schedule_at"] # draft, the time is kept
+
+# The human agrees: schedule it at the time it already carries
+client.posts.update(proposal["data"]["id"], draft: false)
+```
+
+### Comment-to-DM automations
+
+Answer a keyword in an Instagram comment with a DM, once per person, with an optional public reply under the comment. Pass `comment_dm_automation:` on `create` (Instagram must be in `channels`) and the automation is bound to that post; it starts listening once the post is live. Needs the opt-in `automations:write` scope on the key. `client.automations` manages the automations themselves (`list`, `get`, `create`, `update`, `delete`) and reads their activity (`list_events`, `automations:read`). On `update`, `comment_dm_automation:` as a Hash replaces the post's automation and an explicit `nil` removes it. Instagram rules: one private reply per comment, within 7 days; OmniSocials caps sends at 180 DMs an hour per account.
+
+```ruby
+post = client.posts.create(
+  content: "Comment GUIDE and I will send you the link",
+  channels: ["instagram"],
+  scheduled_at: "2026-08-01T09:00:00Z",
+  media_urls: ["https://example.com/guide-cover.jpg"],
+  comment_dm_automation: {
+    "trigger" => { "keywords" => ["guide"], "match" => "word" },
+    "actions" => {
+      "dm" => { "text" => "Here is the guide: https://example.com/guide" },
+      "public_reply" => { "enabled" => true, "variations" => ["Sent you a DM!", "Check your inbox"] }
+    },
+    "limits" => { "max_sends" => 500 }
+  }
+)
+automation_id = post["data"]["comment_dm_automation"]["id"]
+
+# Later: who was answered, and why someone was skipped
+events = client.automations.list_events(automation_id, outcome: "sent")
+puts events["counts"] # { "sent" => 12, "skipped" => 3 }
+events["data"].each do |event|
+  puts [event["person"]["username"], event["outcome"], event["reason_label"]].join(" ")
+end
+```
+
+The events response is `{ "data", "counts", "pagination" }`, not the plain list: `counts` is the number of events per outcome (`sent`, `skipped`, `failed`, `pending`). An automation can also listen on a post published outside OmniSocials (`client.automations.create(instagram_media_id: ..., actions: ...)`), on the next post the workspace publishes (`trigger: { "scope" => "next_post" }`) or on every post (`"scope" => "any"`), and on DMs and story replies (`trigger: { "kinds" => ["dm", "story_reply"], ... }`).
+
 ### Per-media alt text
 
 Every `media_urls` / `media_ids` entry accepts either a plain String or a Hash with an `alt` accessibility description (max 1500 chars). Alt text is delivered to Mastodon (media description), Bluesky (embed alt), X (photos and GIFs), Pinterest (pin alt text), Instagram (images), and LinkedIn (images). Strings and Hashes can be mixed, and the same shape works in per-platform Hashes and `thread_parts` media.
@@ -103,6 +151,32 @@ post = client.posts.create(
 
 Note that `linkedin` targets a personal LinkedIn profile and `linkedin_page` targets a LinkedIn company page. Both can be connected to the same workspace and posted to independently.
 
+### Telegram channels and groups
+
+`telegram` is a channel or group the workspace connected in OmniSocials; the OmniSocials bot posts to it. The `telegram` options: `silent`, `link_preview`, `pin`, `protect_content`, `spoiler` and `caption_above_media` (booleans), up to 3 `buttons` (`{ text, url }`, not on an album or a poll), a native `poll` (2 to 12 options of up to 100 characters, `open_period` 5 to 2628000 seconds, `multiple`; the post text is the question, max 300 characters, no media) and `first_comment` (a reply under the post). Text up to 4,096 characters; with media, text over 1,024 characters is sent as a reply under the media. Albums hold up to 10 photos and videos, files up to 50 MB, no Stories. Once sent, the post's `telegram.result` carries the message ids and the link. Telegram gives bots no view counts: analytics carry the reactions and the poll votes.
+
+```ruby
+client.posts.create(
+  content: "The new collection is live. Tap the button to shop.",
+  channels: ["telegram"],
+  scheduled_at: "2026-11-02T09:00:00Z",
+  media_urls: ["https://example.com/collection.jpg"],
+  telegram: {
+    "silent" => true,
+    "pin" => true,
+    "buttons" => [{ "text" => "Shop now", "url" => "https://example.com/shop" }],
+    "first_comment" => "Questions? Reply to this message."
+  }
+)
+
+# A native poll: the text is the question.
+client.posts.create(
+  content: "Which day suits the live Q&A?",
+  channels: ["telegram"],
+  telegram: { "poll" => { "options" => %w[Tuesday Thursday Saturday], "open_period" => 86_400 } }
+)
+```
+
 ### Chained threads (X, Bluesky, Mastodon, Threads)
 
 Pass 2 to 25 `thread_parts` to publish a chained thread instead of a single tweet (each part is at most 280 characters, 25,000 for X Premium/Premium+ accounts). Bluesky, Mastodon and Threads support the same `thread_parts` shape (Threads: 2 to 25 parts, 500 characters per part, up to 10 media per part; parts after the first publish as replies to the previous part, and the Threads caption is taken from part 1):
@@ -350,9 +424,11 @@ accounts = client.analytics.accounts(platform: "instagram")
 
 ### Best times to post
 
+The response is not wrapped in `data`. `platform`, `timezone`, `basis`, `grid` and `recommendations` sit at the top level.
+
 ```ruby
 best = client.analytics.best_times(platform: "instagram", timezone: "Europe/Amsterdam")
-best["data"]["best_times"].each { |slot| puts slot }
+best["recommendations"].each { |slot| puts "#{slot["day"]} #{slot["time"]} #{slot["score"]}" }
 ```
 
 ## Locations (Instagram and Threads place tagging)
@@ -387,6 +463,32 @@ client.posts.create(
 
 The Threads response is `{ "locations" => [...] }` (each with nullable `name`, `address`, `city`, `country`, `latitude`, `longitude`) or `{ "error" => { "code", "message" } }` with `code` one of `not_available`, `threads_not_connected`, `threads_reauth_required` (reconnect Threads), or `platform_error`. Threads location tagging is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error.
 
+## Pinterest product tags
+
+Tag products on a Pin so people can shop the items in the image. `client.pinterest.list_products` returns the product Pins of the connected Pinterest account; pass their `pin_id` values (max 24) as `"product_tags"` in the `pinterest` options of the post. Only product Pins of your own account can be tagged; products of other merchants cannot. The tags are added right after the Pin is published. A product that Pinterest refuses never fails the post: the outcome is on the post as `pinterest["product_tags_result"]` (`requested`, `tagged`, `skipped`, `error`).
+
+```ruby
+result = client.pinterest.list_products
+
+if result["error"]
+  # HTTP 200 without "products": pinterest_not_connected,
+  # pinterest_catalog_access_required or platform_error
+  warn "#{result["error"]["code"]}: #{result["error"]["message"]}"
+else
+  product_tags = result["products"].first(3).map { |product| product["pin_id"] }
+
+  client.posts.create(
+    content: "Our summer picks",
+    channels: ["pinterest"],
+    media_urls: ["https://example.com/summer-look.jpg"],
+    scheduled_at: "2026-08-01T09:00:00Z",
+    pinterest: { "board_id" => "1234567890", "title" => "Summer picks", "product_tags" => product_tags }
+  )
+end
+```
+
+Without `source:` the list reads the Pinterest catalog (with `price`, `currency`, `availability` and `item_id`) when the connection has catalog access, else the account's own Pins. Catalog access is given one time in the OmniSocials composer: Pinterest options, Add products, Connect catalog. `source: "pins"` scans up to 250 Pins per call, so `"products"` can be empty while `"bookmark"` is set; call again with `bookmark: result["bookmark"]`. To check one Pin id or Pin link before you post, call `client.pinterest.validate_product("813744226420795884")`. On `posts.update` the `pinterest` hash replaces the stored one, so leave `"product_tags"` out to remove the tags.
+
 ## Inbox
 
 Read and reply to social inbox conversations (DMs, comments, mentions) across connected platforms. Requires an API key with the opt-in `inbox:read` / `inbox:write` scopes. The list endpoints are cursor-paginated (unlike the offset pagination used elsewhere): page while `pagination["has_more"]` is true by passing the previous response's `pagination["next_cursor"]` as `cursor`.

data/lib/omnisocials/client.rb

@@ -60,9 +60,10 @@ module OmniSocials
 
     attr_reader :api_key, :base_url, :timeout, :max_retries,
                 :posts, :media, :folders, :hashtag_sets, :approval_workflows,
-                :accounts, :analytics, :audio, :locations, :inbox, :webhooks
+                :accounts, :analytics, :audio, :locations, :pinterest,
+                :automations, :inbox, :webhooks
 
-    # api_key     - API key (omsk_live_* / omsk_test_*). Falls back to the
+    # api_key     - API key (omsk_live_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
     #               OmniSocials::AuthenticationError when neither is set.
     # base_url    - API base URL (default https://api.omnisocials.com/v1).
@@ -94,6 +95,8 @@ module OmniSocials
       @analytics = Resources::Analytics.new(self)
       @audio = Resources::Audio.new(self)
       @locations = Resources::Locations.new(self)
+      @pinterest = Resources::Pinterest.new(self)
+      @automations = Resources::Automations.new(self)
       @inbox = Resources::Inbox.new(self)
       @webhooks = Resources::Webhooks.new(self)
     end

data/lib/omnisocials/resources/analytics.rb

@@ -40,7 +40,9 @@ module OmniSocials
       end
 
       # GET /analytics/best-times - best times to post for a platform,
-      # derived from the workspace's own engagement history.
+      # derived from the workspace's own engagement history. The response has
+      # no "data" wrapper: "platform", "timezone", "basis", "grid" and
+      # "recommendations" sit at the top level.
       def best_times(platform:, timezone: nil)
         @client.request(
           "GET", "/analytics/best-times",

data/lib/omnisocials/resources/automations.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Automations resource: comment-to-DM automations (list, get, create,
+    # update, delete, events). An automation answers a keyword in an
+    # Instagram comment (or a DM, or a story reply) with a DM, once per
+    # person, with an optional public reply under the comment. The scopes
+    # are opt-in on the API key: automations:read for list / get /
+    # list_events, automations:write for create / update / delete (and for
+    # comment_dm_automation on posts).
+    class Automations
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /automations - list the workspace's comment-to-DM automations,
+      # optionally by status ("active", "paused", "completed") or by the
+      # OmniSocials post_id they are bound to. Requires the automations:read
+      # scope (opt-in on the API key).
+      def list(status: nil, post_id: nil)
+        @client.request(
+          "GET", "/automations",
+          query: { "status" => status, "post_id" => post_id }
+        )
+      end
+
+      # GET /automations/{id} - fetch a single automation. Requires the
+      # automations:read scope (opt-in on the API key).
+      def get(automation_id)
+        @client.request("GET", "/automations/#{automation_id}")
+      end
+
+      # POST /automations - create a comment-to-DM automation.
+      #
+      # A keyword in an Instagram comment (or a DM, or a story reply) is
+      # answered with a DM, once per person, with an optional public reply
+      # under the comment. Bind it to one post with post_id (an OmniSocials
+      # post that goes to Instagram, scheduled or live; one automation per
+      # post) or instagram_media_id (a post published outside OmniSocials),
+      # not both; a trigger scope of "next_post" or "any" needs neither.
+      #
+      # `actions` is required: { "dm" => { "text" => "..." } } (max 1000
+      # characters) plus an optional "public_reply" => { "enabled" => true,
+      # "variations" => [...] } (comment kind only, up to 10 of 300
+      # characters). `trigger` is { "kinds" => ["comment"], "scope" =>
+      # "post", "keywords" => [...], "match" => "word" }: kinds one or more
+      # of "comment", "dm", "story_reply"; keywords up to 20 of 60
+      # characters, required unless match is "any"; match is "word",
+      # "contains" or "any". `limits` is { "max_sends" => 500, "stop_at" =>
+      # "2026-12-31T00:00:00Z" } (both optional). `status` is "active"
+      # (default) or "paused". Instagram rules: one private reply per
+      # comment, within 7 days; OmniSocials caps sends at 180 DMs an hour per
+      # account.
+      #
+      # Requires the automations:write scope (opt-in on the API key).
+      # Errors: 400 validation_error, 400 post_not_instagram, 400
+      # post_required, 404 post_not_found, 404 instagram_media_not_found,
+      # 409 instagram_not_connected, 409 instagram_needs_reauth, 409
+      # automation_exists (the error body also carries automation_id).
+      def create(actions:, trigger: nil, limits: nil, name: nil, post_id: nil,
+                 instagram_media_id: nil, status: nil)
+        body = automation_body(
+          name: name, post_id: post_id, instagram_media_id: instagram_media_id,
+          trigger: trigger, actions: actions, limits: limits, status: status
+        )
+        @client.request("POST", "/automations", json: body)
+      end
+
+      # PATCH /automations/{id} - partial update.
+      #
+      # Each section (trigger, actions, limits) is merged into the stored
+      # one; keys you omit keep their value: new trigger "keywords" keep the
+      # kinds, the scope and the match; a new actions "dm" "text" keeps the
+      # public reply; limits: { "stop_at" => ... } keeps max_sends.
+      # "public_reply" => { "enabled" => false } or { "variations" => [] }
+      # turns the public reply off; limits: { "max_sends" => nil } removes
+      # that limit. status: "paused" pauses and "active" resumes; another
+      # post_id / instagram_media_id moves the automation to that post. A
+      # "completed" automation starts again when its limits or trigger
+      # change. Requires the automations:write scope. 400 no_fields when
+      # nothing is passed.
+      def update(automation_id, name: nil, post_id: nil, instagram_media_id: nil,
+                 trigger: nil, actions: nil, limits: nil, status: nil)
+        body = automation_body(
+          name: name, post_id: post_id, instagram_media_id: instagram_media_id,
+          trigger: trigger, actions: actions, limits: limits, status: status
+        )
+        @client.request("PATCH", "/automations/#{automation_id}", json: body)
+      end
+
+      # DELETE /automations/{id} - delete an automation. Returns nil (204).
+      # Requires the automations:write scope.
+      def delete(automation_id)
+        @client.request("DELETE", "/automations/#{automation_id}")
+      end
+
+      # GET /automations/{id}/events - the automation's activity: one event
+      # per person it answered, skipped or failed on. outcome filters on
+      # "sent", "skipped", "failed" or "pending"; limit is 1..100 (default
+      # 25), offset skips. Requires the automations:read scope.
+      #
+      # The response is not the plain list envelope: { "data" => [...],
+      # "counts" => { "sent" => 12, "skipped" => 3 }, "pagination" => {...} },
+      # where counts is the number of events per outcome (an outcome with no
+      # events is left out). Each event carries kind ("comment", "dm",
+      # "story_reply"), outcome, reason / reason_label, person (id,
+      # username), trigger_id, trigger_text, message (the DM sent),
+      # public_reply, platform_message_id, created_at and sent_at.
+      def list_events(automation_id, outcome: nil, limit: nil, offset: nil)
+        @client.request(
+          "GET", "/automations/#{automation_id}/events",
+          query: { "outcome" => outcome, "limit" => limit, "offset" => offset }
+        )
+      end
+
+      private
+
+      def automation_body(name:, post_id:, instagram_media_id:, trigger:,
+                          actions:, limits:, status:)
+        Internal.drop_nil(
+          {
+            "name" => name,
+            "post_id" => post_id,
+            "instagram_media_id" => instagram_media_id,
+            "trigger" => trigger,
+            "actions" => actions,
+            "limits" => limits,
+            "status" => status
+          }
+        )
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/media.rb

@@ -8,7 +8,8 @@ module OmniSocials
         @client = client
       end
 
-      # GET /media - list library files.
+      # GET /media - list library files. Each item carries "width" and
+      # "height" (pixels; nil for videos and older files).
       def list(limit: nil, offset: nil, search: nil, folder_id: nil)
         @client.request(
           "GET", "/media",
@@ -98,6 +99,16 @@ module OmniSocials
       #
       # Provide one of: a public `url`, an existing `media_id`, or
       # `size_bytes` + `mime`.
+      #
+      # The result carries "file" (size_bytes, mime, size_known, width,
+      # height; the pixel size is known for library images, nil otherwise),
+      # "connected_platforms", "compatible", "warnings", "summary" and "fit":
+      # one entry per connected channel with a fit rule for an IMAGE as a
+      # feed post (platform, display_name, fits, ratio, shown = "whole" |
+      # "cut", target, default_action = "crop" | "keep" | nil, message).
+      # fits false = the ratio is outside the window the channel shows
+      # uncropped; default_action is what a post create does unless the
+      # post's media_fit says otherwise. Empty for videos and unknown sizes.
       def check(url: nil, media_id: nil, size_bytes: nil, mime: nil)
         body = Internal.drop_nil(
           {

data/lib/omnisocials/resources/pinterest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Pinterest resource: product Pins for product tagging (list + validate).
+    class Pinterest
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /pinterest/products - list the product Pins of the connected
+      # Pinterest account. Pass a result's pin_id in
+      # pinterest: { "product_tags" => [...] } on post create/update to tag
+      # the product on the Pin (max 24 per Pin). Pinterest only accepts a
+      # product Pin that is public, belongs to the same account and links to
+      # a website that account claimed; products of other merchants cannot
+      # be tagged.
+      #
+      # source is "catalog" or "pins". "catalog" reads the Pinterest catalog
+      # (with price, currency, availability, item_id) and needs catalog
+      # access, which is given one time in the OmniSocials composer
+      # (Pinterest options, Add products, Connect catalog); product_group_id
+      # and page_size (1..100, default 25) apply to this source only. "pins"
+      # reads the account's own Pins and works on every connection; one call
+      # scans up to 250 Pins, so "products" can be empty while "bookmark" is
+      # set (call again with bookmark:). When source is left out the API
+      # uses "catalog" when the connection has catalog access, else "pins".
+      #
+      # Response (not the usual "data" envelope):
+      # { "products" => [{ pin_id, title, description, link, image_url,
+      # price, currency, availability, item_id }], "bookmark", "source",
+      # "catalog_access" } plus "product_groups" and "product_group_id" for
+      # the catalog source, or { "error" => { "code", "message" } } without
+      # "products" when the list could not be read, both with HTTP 200. code
+      # is one of "pinterest_not_connected",
+      # "pinterest_catalog_access_required" or "platform_error". A bad source
+      # or product_group_id raises a 400 with the standard error envelope.
+      def list_products(source: nil, product_group_id: nil, bookmark: nil,
+                        page_size: nil)
+        @client.request(
+          "GET", "/pinterest/products",
+          query: {
+            "source" => source,
+            "product_group_id" => product_group_id,
+            "bookmark" => bookmark,
+            "page_size" => page_size
+          }
+        )
+      end
+
+      # GET /pinterest/products/validate?id= - check whether a Pin can be
+      # used in pinterest product_tags before creating the post. id is a Pin
+      # id or a Pin link (https://www.pinterest.com/pin/<id>/). Response:
+      # { "valid", "pin_id", ... }; "unverified" => true means the check
+      # could not run and the publish step is the final check.
+      def validate_product(id)
+        @client.request("GET", "/pinterest/products/validate", query: { "id" => id })
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/posts.rb

@@ -46,6 +46,25 @@ module OmniSocials
       # POST /posts/create - create a post (draft, or scheduled when
       # scheduled_at is set).
       #
+      # draft: true with scheduled_at stores a planned draft: the post is
+      # "draft" and keeps that time, shows on the dashboard calendar at that
+      # slot with a dashed outline, and the scheduler never publishes it. A
+      # person schedules it from the composer, or you do with #update and
+      # draft: false. Use it when an agent proposes a slot that a human
+      # should confirm. Not allowed with publish_now or approval_workflow_id
+      # (400 validation_error). Without scheduled_at it changes nothing.
+      #
+      # media_fit is the image fit per channel for feed images whose ratio is
+      # outside what a channel shows uncropped: a Hash of platform id
+      # ("instagram", "pinterest", ...) to "auto", "crop" or "keep". auto
+      # (default): Instagram crops a tall or wide image to 4:5 / 1.91:1 around
+      # the subject (Instagram cuts it to that window anyway and Meta cannot
+      # boost a feed post outside it); Pinterest keeps a Pin taller than 2:3
+      # and reports it. crop / keep force it per channel. Every decision comes
+      # back in the same "warnings" array with code "image_fit" (action is
+      # "cropped", "kept" or "crop_failed", with platform, media_url, ratio,
+      # target and crop_url).
+      #
       # approval_workflow_id (a workflow id from client.approval_workflows.list)
       # routes the post through a saved approval workflow: it is created as
       # in_approval (approval_status "pending") instead of scheduled, the
@@ -86,6 +105,43 @@ module OmniSocials
       # disabled on production and create/update/publish return a 400 (also a
       # 400 validation_error asking you to reconnect Threads when the
       # connection lacks the threads_location_tagging permission).
+      #
+      # Pinterest posts can tag products: pass
+      # pinterest: { "board_id" => "...", "product_tags" => [...] } with up
+      # to 24 product Pins of the connected Pinterest account, each as a Pin
+      # id String (see pinterest.list_products) or a Pin link. Products of
+      # other merchants cannot be tagged. The tags are added right after the
+      # Pin is published; a product Pinterest refuses never fails the post,
+      # and the Post's "pinterest" block then carries "product_tags_result"
+      # (requested, tagged, skipped, error). More than 24 entries or an
+      # invalid entry raises a 400 validation_error.
+      #
+      # telegram holds the Telegram options (the connected channel or group,
+      # posted by the OmniSocials bot): "silent", "link_preview", "pin",
+      # "protect_content", "spoiler", "caption_above_media" (booleans), up to
+      # 3 "buttons" ({ "text" => ..., "url" => ... }, not on an album or a
+      # poll), a native "poll" ({ "options" => 2 to 12 of up to 100
+      # characters, "open_period" => 5 to 2628000 seconds, "multiple" => true
+      # }; the post text is the question, max 300 characters, no media) and
+      # "first_comment" (a reply under the post). Text up to 4,096
+      # characters; with media, text over 1,024 characters is sent as a reply
+      # under the media. No Stories. On #update every key merges into the
+      # stored options. Once sent, the Post's "telegram" block carries
+      # "result" (message ids and links).
+      #
+      # comment_dm_automation binds a comment-to-DM automation to the post
+      # (Instagram must be in channels): a keyword in a comment is answered
+      # with a DM, once per person, with an optional public reply under the
+      # comment. Shape: { "trigger" => { "keywords" => ["guide"], "match" =>
+      # "word" }, "actions" => { "dm" => { "text" => "..." }, "public_reply"
+      # => { "enabled" => true, "variations" => [...] } }, "limits" =>
+      # { "max_sends" => 500 } } (see automations.create for the fields).
+      # Needs the automations:write scope on the key (403
+      # insufficient_scope, checked before anything else); a bad Hash is a
+      # 400 validation_error whose message starts with
+      # "comment_dm_automation: ". The response then carries
+      # data["comment_dm_automation"] (the automation, with "post" nil); it
+      # starts listening once the post is live on Instagram.
       def create(content:, channels: nil, scheduled_at: nil, media_ids: nil,
                  media_urls: nil, type: nil, source: nil, link_url: nil,
                  link_title: nil, link_description: nil, link_thumbnail_url: nil,
@@ -95,7 +151,9 @@ module OmniSocials
                  instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
                  mastodon: nil, threads: nil, google_business: nil,
-                 linkedin_poll: nil, approval_workflow_id: nil)
+                 telegram: nil, linkedin_poll: nil,
+                 approval_workflow_id: nil, draft: nil, media_fit: nil,
+                 comment_dm_automation: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -108,15 +166,19 @@ module OmniSocials
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
-          google_business: google_business, linkedin_poll: linkedin_poll,
-          approval_workflow_id: approval_workflow_id
+          google_business: google_business, telegram: telegram,
+          linkedin_poll: linkedin_poll,
+          approval_workflow_id: approval_workflow_id, draft: draft,
+          media_fit: media_fit, comment_dm_automation: comment_dm_automation
         )
         @client.request("POST", "/posts/create", json: body)
       end
 
       # POST /posts/create-and-publish - create and publish immediately.
-      # See #create for the "warnings" array and the 402
-      # "x_credits_insufficient" credit gate on X link posts.
+      # See #create for the "warnings" array (X link posts, and the
+      # "image_fit" entries steered by media_fit), the 402
+      # "x_credits_insufficient" credit gate on X link posts and
+      # comment_dm_automation.
       def create_and_publish(content:, channels: nil, media_ids: nil,
                              media_urls: nil, type: nil, source: nil,
                              link_url: nil, link_title: nil, link_description: nil,
@@ -128,7 +190,8 @@ module OmniSocials
                              facebook: nil, linkedin: nil, linkedin_page: nil,
                              tiktok: nil, x: nil, bluesky: nil, mastodon: nil,
                              threads: nil, google_business: nil,
-                             linkedin_poll: nil)
+                             telegram: nil, linkedin_poll: nil, media_fit: nil,
+                             comment_dm_automation: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: nil,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -141,28 +204,53 @@ module OmniSocials
           youtube: youtube, instagram: instagram, facebook: facebook,
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
-          google_business: google_business, linkedin_poll: linkedin_poll
+          google_business: google_business, telegram: telegram,
+          linkedin_poll: linkedin_poll,
+          media_fit: media_fit, comment_dm_automation: comment_dm_automation
         )
         @client.request("POST", "/posts/create-and-publish", json: body)
       end
 
       # PATCH /posts/{id} - update a draft or scheduled post.
       #
+      # draft: false without scheduled_at schedules a planned draft at the
+      # scheduled_at it already carries (400 validation_error when it has
+      # none or it is in the past). draft: true without scheduled_at
+      # unschedules a scheduled post: it keeps its time and stays on the
+      # calendar as a dashed draft, nothing publishes; a post waiting for
+      # approval leaves its workflow. draft: true with scheduled_at moves the
+      # time and keeps (or makes) the post a draft.
+      #
+      # media_fit (same shape as on #create) alone re-decides the stored
+      # images: "keep" gives the original back, "crop" crops an image that
+      # was kept. Like #create, the response can carry a top-level "warnings"
+      # array with "image_fit" entries when the update changes the images or
+      # media_fit.
+      #
       # Only top-level nils are dropped from the body, so passing e.g.
       # x: { "thread_parts" => nil } still clears an X thread (reverts the
       # post to single-tweet mode). The same applies to bluesky, mastodon
       # and threads thread parts, and to a Threads location tag:
       # threads: { "location_id" => nil } (or "location" => nil) clears it.
       #
+      # pinterest replaces the stored Pinterest options wholesale, so leave
+      # "product_tags" out (or send []) to remove the product tags.
+      #
       # See #create for the 402 "x_credits_insufficient" credit gate that
       # can also refuse an update to a scheduled X link post.
+      #
+      # comment_dm_automation (same shape as on #create) as a Hash replaces
+      # the post's comment-to-DM automation, an explicit nil removes it, and
+      # leaving it out keeps it. Needs the automations:write scope.
       def update(post_id, content: nil, scheduled_at: nil, channels: nil,
                  media_ids: nil, media_urls: nil, type: nil, location_id: nil,
                  collaborators: nil, user_tags: nil, pinterest: nil,
                  youtube: nil, instagram: nil, facebook: nil, linkedin: nil,
                  linkedin_page: nil, tiktok: nil, x: nil, bluesky: nil,
                  mastodon: nil, threads: nil, google_business: nil,
-                 linkedin_poll: nil)
+                 telegram: nil, linkedin_poll: nil, draft: nil,
+                 media_fit: nil,
+                 comment_dm_automation: OmniSocials::NOT_GIVEN)
         body = Internal.drop_nil(
           {
             "content" => content,
@@ -186,9 +274,15 @@ module OmniSocials
             "mastodon" => mastodon,
             "threads" => threads,
             "google_business" => google_business,
-            "linkedin_poll" => linkedin_poll
+            "telegram" => telegram,
+            "linkedin_poll" => linkedin_poll,
+            "draft" => draft,
+            "media_fit" => media_fit
           }
         )
+        # An explicit nil removes the post's automation, so it must survive
+        # drop_nil; NOT_GIVEN (the default) leaves it untouched.
+        body["comment_dm_automation"] = comment_dm_automation unless comment_dm_automation.is_a?(NotGiven)
         @client.request("PATCH", "/posts/#{post_id}", json: body)
       end
 
@@ -264,7 +358,8 @@ module OmniSocials
                       pinterest:, youtube:, instagram:, facebook:, linkedin:,
                       linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
                       threads:, google_business:, linkedin_poll:,
-                      approval_workflow_id: nil)
+                      telegram: nil, approval_workflow_id: nil, draft: nil,
+                      media_fit: nil, comment_dm_automation: nil)
         Internal.drop_nil(
           {
             "content" => content,
@@ -297,8 +392,12 @@ module OmniSocials
             "mastodon" => mastodon,
             "threads" => threads,
             "google_business" => google_business,
+            "telegram" => telegram,
             "linkedin_poll" => linkedin_poll,
-            "approval_workflow_id" => approval_workflow_id
+            "approval_workflow_id" => approval_workflow_id,
+            "draft" => draft,
+            "media_fit" => media_fit,
+            "comment_dm_automation" => comment_dm_automation
           }
         )
       end

data/lib/omnisocials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.8.0"
+  VERSION = "0.11.0"
 end

data/lib/omnisocials.rb

@@ -25,6 +25,8 @@ require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"
 require_relative "omnisocials/resources/audio"
 require_relative "omnisocials/resources/locations"
+require_relative "omnisocials/resources/pinterest"
+require_relative "omnisocials/resources/automations"
 require_relative "omnisocials/resources/inbox"
 require_relative "omnisocials/resources/webhooks"
 require_relative "omnisocials/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.11.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies: []
 description: Schedule and publish social media posts, upload media, and read analytics
   across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads,
@@ -29,20 +29,22 @@ files:
 - lib/omnisocials/resources/analytics.rb
 - lib/omnisocials/resources/approval_workflows.rb
 - lib/omnisocials/resources/audio.rb
+- lib/omnisocials/resources/automations.rb
 - lib/omnisocials/resources/folders.rb
 - lib/omnisocials/resources/hashtag_sets.rb
 - lib/omnisocials/resources/inbox.rb
 - lib/omnisocials/resources/locations.rb
 - lib/omnisocials/resources/media.rb
+- lib/omnisocials/resources/pinterest.rb
 - lib/omnisocials/resources/posts.rb
 - lib/omnisocials/resources/webhooks.rb
 - lib/omnisocials/version.rb
 - lib/omnisocials/webhooks.rb
-homepage: https://omnisocials.com
+homepage: https://omnisocials.com/sdk/ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://omnisocials.com
+  homepage_uri: https://omnisocials.com/sdk/ruby
   documentation_uri: https://docs.omnisocials.com
   source_code_uri: https://github.com/OmniSocials/omnisocials-ruby
   bug_tracker_uri: https://github.com/OmniSocials/omnisocials-ruby/issues