omnisocials 0.11.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 473f213709ed52c13f70cd2b84c26b7d92c2355731dfc0fb676d3b0f3949fbac
-  data.tar.gz: 423f50628c3c4dae0b98d3c486337a573cb32972af6cdf74cd41a8646899f162
+  metadata.gz: 27468385685af2b1f49e6665393bb687f2dd9fc18cf7d06b98190c78c9b3c3fe
+  data.tar.gz: 24dafc551dc62fd9922aa9ce330ae138288a3ecd86dc768abcf35e2f5f466cae
 SHA512:
-  metadata.gz: 5a047afd2262cd53375d22fef8b7c79ed254fddf8e5057cdb4cdd909308821bc19c81b73cddf04ad736cecca998bf0ee0f974f6205d2e0bd4472547ee4464dfa
-  data.tar.gz: 27c340cc9e7954eae71506ed026b10b1421130cb59c283cab8fdbac3016759b5e449c406367579acbc3cf4c4c1b70fb151750350d8e6bbb27fe330eaaf49cba3
+  metadata.gz: 43d61512382a55a5ef87c2e906f28f55153a15d3deed758262e6f919eeb934e5de86be8e700570ffc2bb9862a33e111e285085248ed0bbd7f3645046a3dcf6ce
+  data.tar.gz: 93c23762f52f0550bf38fcae55d850aafa24365966adad31d71b603c8c9fbee3c297be8cb31219d947fc2dd38d1d7b7b2252642460ae98d65a024060cb3d16ba

data/README.md

@@ -1,6 +1,6 @@
 # OmniSocials Ruby SDK
 
-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)
+The official Ruby SDK for OmniSocials: post, schedule, reply and report on 13 social platforms (Instagram, Facebook, LinkedIn, X, TikTok, YouTube, Threads, Pinterest, Bluesky, Mastodon, Google Business, Telegram and Discord) from one API. Guide: [omnisocials.com/sdk/ruby](https://omnisocials.com/sdk/ruby)
 
 Full API reference: [https://docs.omnisocials.com](https://docs.omnisocials.com)
 
@@ -111,7 +111,11 @@ events["data"].each do |event|
 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"], ... }`).
+The events response is `{ "data", "counts", "pagination" }`, not the plain list: `counts` is the number of events per outcome (`sent`, `skipped`, `failed`, `pending`, `queued`, `opted_out`). 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"], ... }`).
+
+A Facebook Page works the same way, and the DM lands in Messenger: pass `platform: "facebook"` to `client.automations.create`, or `facebook_post_id: ...` for a Page post published outside OmniSocials. On a post, `comment_dm_automation: { "platforms" => ["instagram", "facebook"], ... }` makes one automation per channel with the same keywords and DM. Facebook has no story replies.
+
+On X, pass `platform: "x"` with `trigger: { "kinds" => ["dm"], "keywords" => ["guide"] }`: the X account answers a keyword in a DM, once per person, and every answer ends with "Reply STOP to stop automatic messages." An active X automation needs X DMs on for the workspace (`409 x_dms_off`; `status: "paused"` always saves). An answer over the send cap waits in a queue (`queued`) for up to an hour.
 
 ### Per-media alt text
 
@@ -177,6 +181,30 @@ client.posts.create(
 )
 ```
 
+### Discord channels
+
+`discord` is one Discord channel the workspace connected in OmniSocials; the post goes out through the channel's incoming webhook and shows the webhook's name and picture. The `discord` options: `silent`, `link_preview` (default on), `allow_mentions` (default off, so @everyone, @here, role and user mentions show as text and ping nobody) and `spoiler` (booleans), `thread_name` (the post title in a forum or media channel, 1 to 100 characters), up to 5 `buttons` (`{ text, url }`, one row, not with a poll) and a native `poll` (2 to 10 options of up to 55 characters, `duration_hours` 1 to 768, default 24, `multiple`; the post text is the question, max 300 characters, no media). Text up to 2,000 characters. Up to 10 images, GIFs and videos per message; a video or GIF over Discord's 20 MB attachment limit is sent as a link in the text. No Stories. Once sent, the post's `discord.result` carries the message id and the link. Discord gives webhooks no view counts: analytics carry the reactions and the poll votes.
+
+```ruby
+client.posts.create(
+  content: "Patch 2.4 is out. Read the notes below.",
+  channels: ["discord"],
+  scheduled_at: "2026-11-02T09:00:00Z",
+  media_urls: ["https://example.com/patch-notes.png"],
+  discord: {
+    "silent" => true,
+    "buttons" => [{ "text" => "Patch notes", "url" => "https://example.com/patch-2-4" }]
+  }
+)
+
+# A native poll: the text is the question.
+client.posts.create(
+  content: "Which mode do we test next?",
+  channels: ["discord"],
+  discord: { "poll" => { "options" => %w[Ranked Co-op Arena], "duration_hours" => 48 } }
+)
+```
+
 ### 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):
@@ -216,6 +244,8 @@ On update, passing `x: { "thread_parts" => nil }` clears the thread and reverts
 
 Threads posts can also carry a location tag: pass `threads: { "location_id" => "..." }` with an id from `client.locations.search(platform: "threads")` (see Locations below). On a multi-post thread the tag is applied to part 1, and on update `threads: { "location_id" => nil }` clears it. Threads location tagging is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error.
 
+Threads posts can carry a topic too: pass `threads: { "topic_tag" => "Build in public" }`. Unlike a #tag in the text, a topic can hold spaces. 1 to 50 characters, no period and no ampersand; a leading `#` is dropped. On a multi-post thread the topic is applied to part 1, and on update `threads: { "topic_tag" => nil }` removes it.
+
 ### X link posts use credits
 
 X bills API posts whose text contains a URL at a premium, and OmniSocials passes that fee through as prepaid credits (20 credits per URL-containing tweet; threads billed per part with a link). When a create targets X and the text contains a URL, the response Hash includes a top-level `"warnings"` array (a sibling of `"data"`):
@@ -395,6 +425,37 @@ client.posts.create(
 )
 ```
 
+## Post tags
+
+Tags are your workspace's own labels for posts (a hook style, a format, a campaign), to filter posts and compare how each kind does. They never go to a platform. Uses the `posts:read` / `posts:write` scopes; the comparison uses `analytics:read`. A tag is `{ "id", "name", "color", "created_at" }`; names are unique in the workspace (case-insensitive, max 40 characters), at most 200 tags per workspace.
+
+```ruby
+tag = client.tags.create(name: "Question", color: "teal")  # color is optional
+client.tags.list
+client.tags.update(tag["data"]["id"], name: "Question hook")
+client.tags.delete(tag["data"]["id"])  # { "data" => { "tag" => ..., "posts_untagged" => 4 } }
+
+# Tag a post: ids or names, a new name becomes a tag (at most 20 per post)
+client.posts.create(content: "Would you post this?", channels: ["instagram"], tags: ["Question"])
+client.posts.update("1024", tags: ["Question", "Talking head"])  # replaces; tags: nil or [] removes all
+
+# Up to 500 posts at once, published ones included: add, remove or set (replace)
+result = client.tags.apply(post_ids: ["1024", "1025"], add: ["Question"], remove: ["Listicle"])
+puts result["data"]["updated"], result["data"]["not_found"].inspect
+
+# Filter by tag (an id or name, or an Array: posts with any of them)
+client.posts.list(tag: "Question")
+client.analytics.overview(period: "30d", tag: ["Question", "Talking head"])
+
+# How each tag did against your normal (default: the last 90 days)
+compare = client.analytics.tags(start_date: "2026-08-01", end_date: "2026-10-31")
+compare["data"]["tags"].each do |row|
+  puts "#{row["tag"]["name"]} #{row["vs_normal"]} #{row["enough_posts"]}"  # vs_normal 0.38 = 38% above
+end
+```
+
+`analytics.tags` returns `period`, `platform`, `min_posts`, `tags` (comparable tags first, best first; each with `posts`, `measured`, `median_impressions`, `engagement_rate` in percent, `vs_normal` as a fraction, `best_channel` and `enough_posts`), `untagged` (the same numbers for posts without a tag) and `normals` (median impressions per channel). `platform:` keeps one channel's numbers and `min_posts:` (default 5) sets how many measured posts a tag needs before `enough_posts` is true. Every post carries `tags` and `trial_reel` (`{ "strategy" => "MANUAL" | "SS_PERFORMANCE" }` for an Instagram Trial Reel, else `nil`), and so does every entry of `analytics.posts`. Errors: `404 tag_not_found`, `409 tag_exists` (the existing tag is in `e.body["error"]["tag"]`), `409 tag_limit_reached`, `400 invalid_tag_name`, `invalid_tag_color`, `invalid_tags`, `invalid_post_ids`, `too_many_posts`, `too_many_tags`.
+
 ## Accounts
 
 ```ruby
@@ -515,9 +576,15 @@ message_id = messages["data"][0]["id"]
 client.inbox.hide(message_id)               # hide
 client.inbox.hide(message_id, hide: false)  # unhide
 client.inbox.delete_message(message_id)
+
+# Like a comment as the Page or account (Facebook, LinkedIn Page, TikTok).
+# The returned message carries its "liked" flag.
+liked = client.inbox.like(message_id)       # like
+client.inbox.like(message_id, like: false)  # unlike
+puts liked["data"]["liked"]                 # true
 ```
 
-`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, `"youtube"`, `"x"`, or `"threads"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. Threads conversations are comments (replies people leave on your Threads posts) and mentions; there are no Threads DMs. Comments can be hidden on Facebook, Instagram, TikTok, YouTube, and Threads (Threads: incoming top-level replies only), and a hidden message keeps its place in the conversation with its `hidden` flag set; `hidden` is `true`/`false` on comments and `nil` on DMs. A comment/mention's `post` carries `url` (public link when the platform provides one) and `media_type` (the platform's own label) next to `id`, `caption`, and `thumbnail`. The Threads inbox needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads; an account connected before 2026-09-14 needs this once). TikTok and YouTube replies are comments only; TikTok replies are capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
+`platform` accepts `"instagram"`, `"facebook"`, `"linkedin"`, `"tiktok"`, `"youtube"`, `"x"`, or `"threads"`; `type` accepts `"dm"`, `"comment"`, or `"mention"`. Threads conversations are comments (replies people leave on your Threads posts) and mentions; there are no Threads DMs. Comments can be hidden on Facebook, Instagram, TikTok, YouTube, and Threads (Threads: incoming top-level replies only), and a hidden message keeps its place in the conversation with its `hidden` flag set; `hidden` is `true`/`false` on comments and `nil` on DMs. `liked` is `true`/`false` on Facebook, LinkedIn Page, and TikTok comments (whether the connected account liked it; on Facebook and LinkedIn it reflects likes made through OmniSocials, TikTok also syncs likes made in the TikTok app) and `nil` where the platform has no like through OmniSocials (DMs, Instagram, YouTube, X, Threads). A comment/mention's `post` carries `url` (public link when the platform provides one) and `media_type` (the platform's own label) next to `id`, `caption`, and `thumbnail`. The Threads inbox needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads; an account connected before 2026-09-14 needs this once). TikTok and YouTube replies are comments only; TikTok replies are capped at 150 characters. Conversation ids are URL-encoded for you, so pass them exactly as returned - LinkedIn ids contain `":"` and `"()"` (e.g. `"linkedin_comment_urn:li:activity:123"`).
 
 `next` hands out the next conversation that still needs a reply (the customer's latest DM with no reply after it, or an unreplied comment/mention that is not hidden), with the whole thread and the post it belongs to, so a reply can be drafted from one call. DMs that can still be answered come first, then Instagram/Facebook DMs whose 24-hour window has closed (`reply_window["open"]` is `false`: answer those from the native app or mark them read), then comments and mentions, oldest first. Replies typed in the native apps count as answers. Only unread items are served by default, so `mark_read` is the durable way to skip one; `exclude` skips conversation ids for the current session only. Always pass `message_id: message["id"]` to `reply` on comment threads: every comment on a post shares one conversation, and without it the reply goes under the newest comment on the post. Pass `include_next: true` to `reply` to get the following item in the same response. `list_conversations(unanswered: true)` gives the same set as a plain list.
 
@@ -555,7 +622,7 @@ rescue OmniSocials::APIError => e
   when "insufficient_credits"
     puts "Not enough credits to send this reply (need 2)."
   when "x_inbox_suspended"
-    puts "X inbox is suspended - top up and re-enable it in the dashboard."
+    puts "X inbox is suspended until a top-up."
   else
     raise
   end

data/lib/omnisocials/client.rb

@@ -61,7 +61,7 @@ module OmniSocials
     attr_reader :api_key, :base_url, :timeout, :max_retries,
                 :posts, :media, :folders, :hashtag_sets, :approval_workflows,
                 :accounts, :analytics, :audio, :locations, :pinterest,
-                :automations, :inbox, :webhooks
+                :automations, :inbox, :webhooks, :tags
 
     # api_key     - API key (omsk_live_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
@@ -90,6 +90,7 @@ module OmniSocials
       @media = Resources::Media.new(self)
       @folders = Resources::Folders.new(self)
       @hashtag_sets = Resources::HashtagSets.new(self)
+      @tags = Resources::Tags.new(self)
       @approval_workflows = Resources::ApprovalWorkflows.new(self)
       @accounts = Resources::Accounts.new(self)
       @analytics = Resources::Analytics.new(self)

data/lib/omnisocials/resources/analytics.rb

@@ -15,7 +15,9 @@ module OmniSocials
 
       # GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
       # one request. `ids` is an Array of post ids (or an already-joined
-      # comma-separated String).
+      # comma-separated String). Each entry also carries "tags" (the post's
+      # tags) and "trial_reel" ({ "strategy" => "MANUAL" | "SS_PERFORMANCE" }
+      # for an Instagram Trial Reel, else nil).
       def posts(ids)
         @client.request(
           "GET", "/analytics/posts",
@@ -24,10 +26,17 @@ module OmniSocials
       end
 
       # GET /analytics/overview - workspace-wide analytics overview.
-      def overview(period: nil, start_date: nil, end_date: nil)
+      #
+      # tag (a tag id or name, or an Array of them: any of them) keeps the
+      # post numbers of the posts with that tag; account numbers stay those
+      # of the whole account. An unknown tag is a 404 tag_not_found.
+      def overview(period: nil, start_date: nil, end_date: nil, tag: nil)
         @client.request(
           "GET", "/analytics/overview",
-          query: { "period" => period, "start_date" => start_date, "end_date" => end_date }
+          query: {
+            "period" => period, "start_date" => start_date, "end_date" => end_date,
+            "tag" => Tags.tag_query(tag)
+          }
         )
       end
 
@@ -49,6 +58,28 @@ module OmniSocials
           query: { "platform" => platform, "timezone" => timezone }
         )
       end
+
+      # GET /analytics/tags - how each tag did against your normal, for the
+      # published posts in a period (default the last 90 days).
+      #
+      # Returns { "data" => { "period", "platform", "min_posts", "tags",
+      # "untagged", "normals" } }. Each entry of "tags" is { "tag", "posts",
+      # "measured", "median_impressions", "engagement_rate" (percent),
+      # "vs_normal" (fraction: 0.38 = 38% above your normal), "best_channel",
+      # "enough_posts" }, comparable tags first, best first; "untagged" has
+      # the same numbers for the posts without a tag, "normals" the median
+      # impressions per channel. platform keeps one channel's numbers;
+      # min_posts (1 to 50, default 5) is the measured posts a tag needs
+      # before "enough_posts" is true.
+      def tags(start_date: nil, end_date: nil, platform: nil, min_posts: nil)
+        @client.request(
+          "GET", "/analytics/tags",
+          query: {
+            "start_date" => start_date, "end_date" => end_date,
+            "platform" => platform, "min_posts" => min_posts
+          }
+        )
+      end
     end
   end
 end

data/lib/omnisocials/resources/automations.rb

@@ -5,9 +5,15 @@ module OmniSocials
     # 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
+    # person, with an optional public reply under the comment. With
+    # platform: "facebook" it runs on a Facebook Page instead, and the DM
+    # lands in Messenger (a Page has no story replies). With platform: "x"
+    # it answers a keyword in a DM to the X account ("dm" kind only, no
+    # post, no public reply) while X DMs are on for the workspace; every X
+    # answer ends with "Reply STOP to stop automatic messages." and a
+    # person who replies STOP gets no automatic DM again. 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)
@@ -15,13 +21,14 @@ module OmniSocials
       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)
+      # optionally by status ("active", "paused", "completed"), by platform
+      # ("instagram", "facebook", "x") 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, platform: nil)
         @client.request(
           "GET", "/automations",
-          query: { "status" => status, "post_id" => post_id }
+          query: { "status" => status, "platform" => platform, "post_id" => post_id }
         )
       end
 
@@ -35,10 +42,21 @@ module OmniSocials
       #
       # 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.
+      # under the comment. platform is "instagram" (default) or "facebook":
+      # on a Facebook Page a keyword in a comment (or a Messenger message to
+      # the Page) is answered in Messenger, and a Page has no story replies.
+      # platform: "x" answers a keyword in a DM to the X account: trigger
+      # kinds must be ["dm"] (X allows an automated DM only after the person
+      # wrote first), with no post and no public reply; an active X
+      # automation needs X DMs on for the workspace (409 x_dms_off; status
+      # "paused" always saves), and every X answer ends with "Reply STOP to
+      # stop automatic messages.". Bind it to one post with post_id (an OmniSocials post that goes to
+      # the channel, scheduled or live; one automation per post and
+      # platform), instagram_media_id (an Instagram post published outside
+      # OmniSocials) or facebook_post_id (a Page post published outside
+      # OmniSocials, as "{page-id}_{post-id}" or the post id alone; implies
+      # "facebook"), at most one; a trigger scope of "next_post" or "any"
+      # needs none.
       #
       # `actions` is required: { "dm" => { "text" => "..." } } (max 1000
       # characters) plus an optional "public_reply" => { "enabled" => true,
@@ -49,20 +67,27 @@ module OmniSocials
       # 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.
+      # (default) or "paused". Meta rules, the same on Instagram and
+      # Facebook: one private reply per comment, within 7 days; OmniSocials
+      # caps sends at 180 DMs an hour per account and platform, and on X at
+      # 15 per 15 minutes and 450 a day; an answer over a cap waits in a
+      # queue ("queued") for up to an hour.
       #
       # 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).
+      # post_not_facebook, 400 post_required, 404 post_not_found, 404
+      # instagram_media_not_found, 404 facebook_post_not_found, 409
+      # instagram_not_connected, 409 instagram_needs_reauth, 409
+      # facebook_not_connected, 409 facebook_needs_reauth, 409
+      # x_not_connected, 409 x_dms_off, 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)
+                 instagram_media_id: nil, status: nil, platform: nil,
+                 facebook_post_id: nil)
         body = automation_body(
           name: name, post_id: post_id, instagram_media_id: instagram_media_id,
-          trigger: trigger, actions: actions, limits: limits, status: status
+          trigger: trigger, actions: actions, limits: limits, status: status,
+          platform: platform, facebook_post_id: facebook_post_id
         )
         @client.request("POST", "/automations", json: body)
       end
@@ -76,15 +101,20 @@ module OmniSocials
       # "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
+      # post_id / instagram_media_id / facebook_post_id moves the automation
+      # to that post. The platform cannot change: a platform other than the
+      # automation's is a 400 platform_immutable. status: "active" on an X
+      # automation needs X DMs on for the workspace (409 x_dms_off). A
       # "completed" automation starts again when its limits or trigger
-      # change. Requires the automations:write scope. 400 no_fields when
-      # nothing is passed.
+      # 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)
+                 trigger: nil, actions: nil, limits: nil, status: nil,
+                 platform: nil, facebook_post_id: nil)
         body = automation_body(
           name: name, post_id: post_id, instagram_media_id: instagram_media_id,
-          trigger: trigger, actions: actions, limits: limits, status: status
+          trigger: trigger, actions: actions, limits: limits, status: status,
+          platform: platform, facebook_post_id: facebook_post_id
         )
         @client.request("PATCH", "/automations/#{automation_id}", json: body)
       end
@@ -97,15 +127,20 @@ module OmniSocials
 
       # 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.
+      # "sent", "skipped", "failed", "pending", "queued" (waits for a free
+      # slot under the send cap, out within the hour) or "opted_out" (the
+      # person replied STOP on X); 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),
+      # "story_reply"), outcome, reason / reason_label (X adds the skip
+      # reasons "dms_closed", "no_credits", "opted_out" and
+      # "automation_off"), person (id,
+      # username; on Facebook the person's name, since Facebook has no
+      # @handle), 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(
@@ -117,12 +152,15 @@ module OmniSocials
       private
 
       def automation_body(name:, post_id:, instagram_media_id:, trigger:,
-                          actions:, limits:, status:)
+                          actions:, limits:, status:, platform: nil,
+                          facebook_post_id: nil)
         Internal.drop_nil(
           {
+            "platform" => platform,
             "name" => name,
             "post_id" => post_id,
             "instagram_media_id" => instagram_media_id,
+            "facebook_post_id" => facebook_post_id,
             "trigger" => trigger,
             "actions" => actions,
             "limits" => limits,

data/lib/omnisocials/resources/inbox.rb

@@ -167,6 +167,32 @@ module OmniSocials
         )
       end
 
+      # POST /inbox/messages/{id}/like - like or unlike a comment someone left
+      # on one of the user's posts, as the connected Page or account.
+      # Facebook Page, LinkedIn Page and TikTok comments (incoming comments
+      # only). Pass like: false to remove the like. Facebook allows only Like
+      # (no Love or other reactions). Liking a comment that is already liked,
+      # or unliking one that is not, succeeds. Returns the comment after the
+      # change with its "liked" flag set: true when the account liked it,
+      # false when not, nil where the platform has no like through
+      # OmniSocials (DMs, Instagram, YouTube, X, Threads). On Facebook and
+      # LinkedIn "liked" reflects likes made through OmniSocials; TikTok also
+      # syncs likes made in the TikTok app. Requires the inbox:write scope.
+      #
+      # Errors: 400 "unsupported_platform" (not an incoming Facebook, LinkedIn
+      # or TikTok comment), 401 "reauth_required" (the TikTok comments
+      # authorization is missing or expired, or the LinkedIn Page connection expired), 403 "reconnect_required" (the
+      # account was connected without the permission to like comments;
+      # reconnect it in the dashboard), 404 "not_found" (message not in this
+      # workspace) or "account_not_connected", 502 "platform_error" (the
+      # platform rejected the call).
+      def like(message_id, like: true)
+        @client.request(
+          "POST", "/inbox/messages/#{encode_id(message_id)}/like",
+          json: { "like" => like }
+        )
+      end
+
       # DELETE /inbox/messages/{id} - delete a comment someone left on one of
       # the user's posts, on the platform and from the inbox. Facebook,
       # Instagram and TikTok comments only: YouTube's API does not let a
@@ -218,9 +244,9 @@ module OmniSocials
       # { "conversation", "message", "messages", "reply_window" }, or nil
       # when nothing is waiting. "message" is the unanswered incoming item
       # itself (the customer's latest DM, or the specific comment): its "id"
-      # is what `hide` and `delete_message` take and the message_id: to pass
-      # to `reply` on comment threads, its "conversation_id" is what `reply`
-      # takes. "messages" is the conversation so far, oldest first (the most
+      # is what `hide`, `like` and `delete_message` take and the message_id:
+      # to pass to `reply` on comment threads, its "conversation_id" is what
+      # `reply` takes. "messages" is the conversation so far, oldest first (the most
       # recent 50 messages for long DM threads). "reply_window" is
       # { "open" => Boolean, "closes_at" => String|nil }: "open" is false
       # only for an Instagram/Facebook DM past its 24-hour window, which

data/lib/omnisocials/resources/posts.rb

@@ -21,10 +21,17 @@ module OmniSocials
       # GET /posts - list posts (status: draft, in_approval, scheduled, posting,
       # posted, failed, warning; in_approval = waiting for a reviewer in an
       # approval workflow).
-      def list(status: nil, limit: nil, offset: nil)
+      # tag (a tag id or name, or an Array of them) keeps the posts with any
+      # of those tags; an unknown tag is a 404 tag_not_found. Every post
+      # carries "tags" (its tags) and "trial_reel" ({ "strategy" =>
+      # "MANUAL" | "SS_PERFORMANCE" } for an Instagram Trial Reel, else nil).
+      def list(status: nil, limit: nil, offset: nil, tag: nil)
         @client.request(
           "GET", "/posts",
-          query: { "status" => status, "limit" => limit, "offset" => offset }
+          query: {
+            "status" => status, "limit" => limit, "offset" => offset,
+            "tag" => Tags.tag_query(tag)
+          }
         )
       end
 
@@ -106,6 +113,11 @@ module OmniSocials
       # 400 validation_error asking you to reconnect Threads when the
       # connection lacks the threads_location_tagging permission).
       #
+      # Threads posts can carry a topic: threads: { "topic_tag" => "Build in
+      # public" } (1 to 50 characters, no period and no ampersand; a topic can
+      # hold spaces). On a multi-post thread it goes on part 1; on update
+      # "topic_tag" => nil removes it.
+      #
       # 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
@@ -129,19 +141,46 @@ module OmniSocials
       # stored options. Once sent, the Post's "telegram" block carries
       # "result" (message ids and links).
       #
+      # discord holds the Discord options (one Discord channel, posted
+      # through its incoming webhook with the webhook's name and picture):
+      # "silent", "link_preview" (default on), "allow_mentions" (default off:
+      # @everyone, @here, role and user mentions show as text and ping
+      # nobody), "spoiler" (booleans), "thread_name" (the post title in a
+      # forum or media channel, 1 to 100 characters; on a text channel the
+      # post goes out without it), up to 5 "buttons" ({ "text" => 1 to 80 characters, "url" =>
+      # https:// or http:// }, one row, not with a poll) and a native "poll"
+      # ({ "options" => 2 to 10 of up to 55 characters, "duration_hours" =>
+      # 1 to 768 (default 24), "multiple" => true }; the post text is the
+      # question, max 300 characters, no media and no buttons). Text up to
+      # 2,000 characters; up to 10 images, GIFs and videos per message, a
+      # video or GIF over 20 MB is sent as a link in the text. No Stories.
+      # On #update every key merges into the stored options, a key set to
+      # nil removes it and discord: nil removes every option. Once sent, the
+      # Post's "discord" block carries "result" (message id and link).
+      #
       # 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
+      # (Instagram or Facebook 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 }, "platforms" =>
+      # ["instagram", "facebook"] } (see automations.create for the
+      # fields). "platforms" makes one automation per listed channel; each
+      # must be a channel of the post. Without it: Instagram when the post
+      # goes there, else Facebook. 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.
+      # data["comment_dm_automation"] (the first automation, with "post"
+      # nil, plus "platforms" and "automations", one { "id", "platform",
+      # "status" } per channel); each starts listening once the post is
+      # live on its channel.
+      #
+      # tags labels the post with the workspace's own tags (ids or names, at
+      # most 20; a name that does not exist yet becomes a new tag) to filter
+      # and compare posts in Analytics. Tags never go to a platform. Errors:
+      # 404 tag_not_found (an unknown id), 400 invalid_tags / too_many_tags.
       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,
@@ -151,9 +190,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,
-                 telegram: nil, linkedin_poll: nil,
+                 telegram: nil, discord: nil, linkedin_poll: nil,
                  approval_workflow_id: nil, draft: nil, media_fit: nil,
-                 comment_dm_automation: nil)
+                 comment_dm_automation: nil, tags: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -167,9 +206,10 @@ module OmniSocials
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
           google_business: google_business, telegram: telegram,
-          linkedin_poll: linkedin_poll,
+          discord: discord, linkedin_poll: linkedin_poll,
           approval_workflow_id: approval_workflow_id, draft: draft,
-          media_fit: media_fit, comment_dm_automation: comment_dm_automation
+          media_fit: media_fit, comment_dm_automation: comment_dm_automation,
+          tags: tags
         )
         @client.request("POST", "/posts/create", json: body)
       end
@@ -177,8 +217,8 @@ module OmniSocials
       # POST /posts/create-and-publish - create and publish immediately.
       # 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.
+      # "x_credits_insufficient" credit gate on X link posts,
+      # comment_dm_automation and tags.
       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,
@@ -190,8 +230,9 @@ module OmniSocials
                              facebook: nil, linkedin: nil, linkedin_page: nil,
                              tiktok: nil, x: nil, bluesky: nil, mastodon: nil,
                              threads: nil, google_business: nil,
-                             telegram: nil, linkedin_poll: nil, media_fit: nil,
-                             comment_dm_automation: nil)
+                             telegram: nil, discord: nil, linkedin_poll: nil,
+                             media_fit: nil,
+                             comment_dm_automation: nil, tags: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: nil,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -205,8 +246,9 @@ module OmniSocials
           linkedin: linkedin, linkedin_page: linkedin_page, tiktok: tiktok,
           x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
           google_business: google_business, telegram: telegram,
-          linkedin_poll: linkedin_poll,
-          media_fit: media_fit, comment_dm_automation: comment_dm_automation
+          discord: discord, linkedin_poll: linkedin_poll,
+          media_fit: media_fit, comment_dm_automation: comment_dm_automation,
+          tags: tags
         )
         @client.request("POST", "/posts/create-and-publish", json: body)
       end
@@ -240,17 +282,28 @@ module OmniSocials
       # 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.
+      # the post's comment-to-DM automations (a channel no longer in
+      # "platforms" loses its automation), an explicit nil removes them all,
+      # and leaving it out keeps them. Needs the automations:write scope.
+      #
+      # discord merges into the stored Discord options: a key set to nil
+      # removes that option (e.g. discord: { "poll" => nil }), an explicit
+      # discord: nil removes every option, and leaving it out keeps them.
+      #
+      # tags (ids or names, a new name becomes a tag) replaces the post's
+      # tags; tags: nil or tags: [] removes them all, and leaving it out
+      # keeps them. An update with only tags works on every post, published
+      # and failed ones included.
       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,
-                 telegram: nil, linkedin_poll: nil, draft: nil,
-                 media_fit: nil,
-                 comment_dm_automation: OmniSocials::NOT_GIVEN)
+                 telegram: nil, discord: OmniSocials::NOT_GIVEN,
+                 linkedin_poll: nil, draft: nil, media_fit: nil,
+                 comment_dm_automation: OmniSocials::NOT_GIVEN,
+                 tags: OmniSocials::NOT_GIVEN)
         body = Internal.drop_nil(
           {
             "content" => content,
@@ -283,6 +336,10 @@ module OmniSocials
         # 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)
+        # Same for discord: an explicit nil removes every Discord option.
+        body["discord"] = discord unless discord.is_a?(NotGiven)
+        # And for tags: an explicit nil (or []) removes every tag of the post.
+        body["tags"] = tags unless tags.is_a?(NotGiven)
         @client.request("PATCH", "/posts/#{post_id}", json: body)
       end
 
@@ -358,8 +415,9 @@ module OmniSocials
                       pinterest:, youtube:, instagram:, facebook:, linkedin:,
                       linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
                       threads:, google_business:, linkedin_poll:,
-                      telegram: nil, approval_workflow_id: nil, draft: nil,
-                      media_fit: nil, comment_dm_automation: nil)
+                      telegram: nil, discord: nil, approval_workflow_id: nil,
+                      draft: nil,
+                      media_fit: nil, comment_dm_automation: nil, tags: nil)
         Internal.drop_nil(
           {
             "content" => content,
@@ -393,11 +451,13 @@ module OmniSocials
             "threads" => threads,
             "google_business" => google_business,
             "telegram" => telegram,
+            "discord" => discord,
             "linkedin_poll" => linkedin_poll,
             "approval_workflow_id" => approval_workflow_id,
             "draft" => draft,
             "media_fit" => media_fit,
-            "comment_dm_automation" => comment_dm_automation
+            "comment_dm_automation" => comment_dm_automation,
+            "tags" => tags
           }
         )
       end

data/lib/omnisocials/resources/tags.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Tags resource: the workspace's own labels for its posts (a hook style,
+    # a format), to filter and compare posts in Analytics. Tags never go to a
+    # platform.
+    #
+    # Set them on a post with tags: on posts.create / create_and_publish /
+    # update, in bulk with #apply, filter with tag: on posts.list and
+    # analytics.overview, and compare them with analytics.tags. A tag
+    # reference is a tag id (Integer or String) or a tag name
+    # (case-insensitive); in add / set (and tags: on posts) a name that does
+    # not exist yet becomes a new tag.
+    class Tags
+      # Serialize the tag filter: one id or name, or an Array joined with ",".
+      def self.tag_query(tag)
+        return nil if tag.nil?
+        return tag.map(&:to_s).join(",") if tag.is_a?(Array)
+
+        tag.to_s
+      end
+
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /tags - every tag of the workspace, by name. Each tag is
+      # { "id", "name", "color", "created_at" }. Scope posts:read.
+      def list
+        @client.request("GET", "/tags")
+      end
+
+      # POST /tags - create a tag. `name` is at most 40 characters and unique
+      # in the workspace (case-insensitive); `color` is one of blue, green,
+      # orange, red, purple, pink, teal, yellow, brown, gray (omit it to get
+      # the next colour). At most 200 tags per workspace.
+      #
+      # Errors: 409 tag_exists (the existing tag is in
+      # error.body["error"]["tag"]), 409 tag_limit_reached,
+      # 400 invalid_tag_name / invalid_tag_color.
+      def create(name:, color: nil)
+        @client.request(
+          "POST", "/tags",
+          json: Internal.drop_nil({ "name" => name, "color" => color })
+        )
+      end
+
+      # PATCH /tags/{id} - rename or recolour a tag. Only the keys you pass
+      # are sent; posts keep the tag. Errors: 404 tag_not_found,
+      # 409 tag_exists.
+      def update(tag_id, name: nil, color: nil)
+        body = Internal.drop_nil({ "name" => name, "color" => color })
+        @client.request("PATCH", "/tags/#{tag_id}", json: body)
+      end
+
+      # DELETE /tags/{id} - delete a tag and take it off every post (the
+      # posts stay). Returns { "data" => { "tag", "posts_untagged" } }.
+      def delete(tag_id)
+        @client.request("DELETE", "/tags/#{tag_id}")
+      end
+
+      # POST /tags/apply - add, remove or replace the tags of up to 500 posts
+      # at once, published ones included.
+      #
+      # add, remove and set take tag ids or names; a new name in add or set
+      # becomes a tag. set replaces a post's tags (set: [] removes them all),
+      # add and remove change only the tags you name. Returns
+      # { "data" => { "updated", "posts" => [{ "id", "tags" }], "not_found" } };
+      # not_found lists the post ids that are not posts of this workspace.
+      # Errors: 400 invalid_post_ids / too_many_posts / too_many_tags /
+      # invalid_tags, 404 tag_not_found.
+      def apply(post_ids:, add: nil, remove: nil, set: nil)
+        body = Internal.drop_nil(
+          {
+            "post_ids" => Array(post_ids).map(&:to_s),
+            "add" => add,
+            "remove" => remove,
+            "set" => set
+          }
+        )
+        @client.request("POST", "/tags/apply", json: body)
+      end
+    end
+  end
+end

data/lib/omnisocials/version.rb

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

data/lib/omnisocials.rb

@@ -20,6 +20,7 @@ require_relative "omnisocials/resources/posts"
 require_relative "omnisocials/resources/media"
 require_relative "omnisocials/resources/folders"
 require_relative "omnisocials/resources/hashtag_sets"
+require_relative "omnisocials/resources/tags"
 require_relative "omnisocials/resources/approval_workflows"
 require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.14.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-11-02 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,
@@ -37,6 +37,7 @@ files:
 - lib/omnisocials/resources/media.rb
 - lib/omnisocials/resources/pinterest.rb
 - lib/omnisocials/resources/posts.rb
+- lib/omnisocials/resources/tags.rb
 - lib/omnisocials/resources/webhooks.rb
 - lib/omnisocials/version.rb
 - lib/omnisocials/webhooks.rb