omnisocials 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dff156c383d34ece380b804eb9dc42fd00bd42782218bd99e7f840dfc4c197e
-  data.tar.gz: 8a7d23f25f08551a42e4b5ad30dc680f2b83045f72bb78c894a9ab13134df8e1
+  metadata.gz: 4b3fed727cadc18b6ea190937598241ea06e5ac3451f5a01e47e993f641f5332
+  data.tar.gz: 6adeeba6ddc69911b79c4b620ddc418e0dd372d6e76e3a417bd285ae54b44e9d
 SHA512:
-  metadata.gz: 3f3ca94edd9dbac14a91c91fc17c39b22efda2385dc36fd6fbc02b881c2f86a661e672a55665e97c47d4a8ee278ed6cb0e9bd961f4dcba495b936e6840316b88
-  data.tar.gz: 9f99feca0fef8165c5d80901cc60f4a3e8f681025e8c786e2e32938582e4194c9a98c8ba60ca54d1166e603bbc3c1f1e751dbdc580e42e9a3032bd650760511a
+  metadata.gz: ad4c11a0f91aa25cd0dfab676f0a28b5973d139a82137c0d753de697a453d710bd9f59f6c212596230fe727e37d20e117635d7b23d06f2f6aeeefce3d66b5ffa
+  data.tar.gz: 1b53388871737de150a7d71387472915b3e1bfcc7c8e245f45e5c3d87ea4ef2ee9d8047855876d33e1028c0b24272accfe663ef482e83bbdc4e60a72fe9268af

data/README.md

@@ -105,7 +105,7 @@ Note that `linkedin` targets a personal LinkedIn profile and `linkedin_page` tar
 
 ### 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). 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):
+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):
 
 ```ruby
 post = client.posts.create(
@@ -392,13 +392,29 @@ end
 client.inbox.mark_read(conversation_id)
 client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
 
-# Threads only: hide or unhide a reply someone left on one of your Threads posts.
+# Hide or unhide a comment someone left on one of your posts (Facebook,
+# Instagram, TikTok, YouTube, Threads). Delete removes it outright (Facebook,
+# Instagram, TikTok; YouTube: hide instead), replies under it included.
 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)
 ```
 
-`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. Only incoming top-level Threads replies can be hidden (nested replies cannot), and a hidden message keeps its place in the conversation with its `hidden` flag set. Threads inbox is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error, and it needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads). 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. 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`. Threads inbox is currently rolling out; until Meta approves the permissions it is disabled on production and calls return a clear error, and it needs a Threads connection with the reply permission (a 401 `reauth_required` means reconnect Threads). 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. 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. 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.
+
+```ruby
+item = client.inbox.next(platform: "instagram")
+while item["data"]
+  message = item["data"]["message"]
+  puts "#{item["remaining"]} left. #{message["sender"]["username"]}: #{message["text"]}"
+
+  reply = client.inbox.reply(message["conversation_id"], text: "Thanks! DM sent.", include_next: true)
+  item = { "data" => reply["next"], "remaining" => reply["remaining"] || 0 }
+end
+```
 
 Replying to an X DM costs 2 prepaid credits, debited from the company balance before the send and automatically refunded if the send fails:
 

data/lib/omnisocials/client.rb

@@ -59,8 +59,8 @@ module OmniSocials
     ].freeze
 
     attr_reader :api_key, :base_url, :timeout, :max_retries,
-                :posts, :media, :folders, :hashtag_sets, :accounts, :analytics,
-                :audio, :locations, :inbox, :webhooks
+                :posts, :media, :folders, :hashtag_sets, :approval_workflows,
+                :accounts, :analytics, :audio, :locations, :inbox, :webhooks
 
     # api_key     - API key (omsk_live_* / omsk_test_*). Falls back to the
     #               OMNISOCIALS_API_KEY environment variable. Raises
@@ -89,6 +89,7 @@ module OmniSocials
       @media = Resources::Media.new(self)
       @folders = Resources::Folders.new(self)
       @hashtag_sets = Resources::HashtagSets.new(self)
+      @approval_workflows = Resources::ApprovalWorkflows.new(self)
       @accounts = Resources::Accounts.new(self)
       @analytics = Resources::Analytics.new(self)
       @audio = Resources::Audio.new(self)

data/lib/omnisocials/resources/approval_workflows.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OmniSocials
+  module Resources
+    # Approval workflows resource: the workflows configured in the dashboard
+    # (Approvals). List them here and route a post through one at create time
+    # via approval_workflow_id on posts.create.
+    class ApprovalWorkflows
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /approval-workflows - the workflows this workspace can use
+      # (company-wide plus workspace-bound), with steps and named approvers.
+      def list
+        @client.request("GET", "/approval-workflows")
+      end
+    end
+  end
+end

data/lib/omnisocials/resources/inbox.rb

@@ -24,24 +24,29 @@ module OmniSocials
       #
       # All filters are optional: platform ("instagram", "facebook",
       # "linkedin", "tiktok", "youtube", "x", "threads"), type ("dm", "comment",
-      # "mention"), unread (only conversations with unread messages), limit
-      # (1-100), and cursor (an opaque cursor from a previous response's
-      # pagination["next_cursor"]).
+      # "mention"), unread (only conversations with unread messages),
+      # unanswered (only conversations that still need an answer: the
+      # customer's latest DM has no reply after it, for Instagram/Facebook DMs
+      # within the 24-hour messaging window only, or a comment/mention that
+      # has not been replied to and is not hidden; replies typed in the native
+      # apps count as answers, and read state is ignored, so use `next` for a
+      # work queue), limit (1-100), and cursor (an opaque cursor from a
+      # previous response's pagination["next_cursor"]).
       #
       # Threads conversations are type "comment" (replies people leave on the
       # user's Threads posts; conversation ids look like
       # "threads_comment_<rootPostId>") and "mention"
       # ("threads_mention_<postId>"); there are no Threads DMs. Threads inbox
-      # is currently rolling out: until Meta approves the permissions it is
-      # disabled on production and calls return a clear error, and it needs a
-      # Threads connection with the reply permission.
-      def list_conversations(platform: nil, type: nil, unread: nil, limit: nil, cursor: nil)
+      # needs a Threads connection with the reply permissions; connections made
+      # before those permissions existed must be reconnected once.
+      def list_conversations(platform: nil, type: nil, unread: nil, unanswered: nil, limit: nil, cursor: nil)
         @client.request(
           "GET", "/inbox/conversations",
           query: {
             "platform" => platform,
             "type" => type,
             "unread" => unread,
+            "unanswered" => unanswered,
             "limit" => limit,
             "cursor" => cursor
           }
@@ -73,10 +78,9 @@ module OmniSocials
       # text-only. Returns the created outgoing message.
       #
       # On a Threads conversation the reply publishes as a native Threads
-      # reply. Threads inbox is currently rolling out (disabled on production
-      # until Meta App Review) and needs a Threads connection with the reply
+      # reply. The Threads inbox needs a Threads connection with the reply
       # permission: a 401 with code "reauth_required" means the connection
-      # lacks that permission (reconnect Threads).
+      # lacks that permission (connected before it existed; reconnect Threads).
       #
       # Replying to an X DM costs 2 prepaid credits, debited from the
       # company balance before the send and automatically refunded if the
@@ -86,12 +90,19 @@ module OmniSocials
       # auto-suspended after the balance hit zero (top up and re-enable it
       # in the dashboard to resume; DMs that arrived while suspended are
       # not recovered).
-      def reply(conversation_id, text: nil, attachment_url: nil, attachment_type: nil)
+      #
+      # Pass include_next: true to also get "next" (the next conversation
+      # that needs an answer, the same object `next` returns under "data",
+      # using its default queue order and filters; nil when nothing is
+      # waiting) and "remaining" in the response. Saves the extra call when
+      # working through the inbox.
+      def reply(conversation_id, text: nil, attachment_url: nil, attachment_type: nil, include_next: nil)
         body = Internal.drop_nil(
           {
             "text" => text,
             "attachment_url" => attachment_url,
-            "attachment_type" => attachment_type
+            "attachment_type" => attachment_type,
+            "include_next" => include_next
           }
         )
         @client.request(
@@ -100,18 +111,31 @@ module OmniSocials
         )
       end
 
-      # POST /inbox/messages/{id}/hide - hide or unhide a reply someone left
-      # on one of the user's Threads posts, as the post owner (Threads only
-      # for now). Pass hide: false to unhide. Only incoming top-level replies
-      # can be hidden (Threads does not allow hiding nested replies); the
-      # message keeps its place in the conversation. Returns the updated
-      # message with its "hidden" flag flipped.
+      # POST /inbox/messages/{id}/hide - hide or unhide a comment someone
+      # left on one of the user's posts, on the platform, as the post owner.
+      # Facebook, Instagram, TikTok, YouTube and Threads comments (Threads:
+      # incoming top-level replies only; Threads does not allow hiding nested
+      # replies). Pass hide: false to unhide. On YouTube, hide sets the
+      # comment's moderation status to rejected, which removes it and its
+      # replies from public view; unhide publishes it again. Returns the
+      # updated message with its "hidden" flag flipped; the message keeps its
+      # place in the conversation, and a hidden comment no longer counts as
+      # unanswered. The account must have been connected with the moderation
+      # permission (Facebook pages_manage_engagement, Instagram
+      # instagram_business_manage_comments).
       #
-      # Errors: 400 "unsupported_platform" (not an incoming Threads reply, or
-      # Threads inbox not available yet), 400 "not_hideable" (nested reply or
-      # Threads refused), 401 "reauth_required" (connection lacks the reply
-      # permission; reconnect Threads), 404 "not_found" (message not in this
-      # workspace) or "account_not_connected" (no Threads account).
+      # Errors: 400 "unsupported_platform" (not an incoming comment on a
+      # supported platform), 400 "not_hideable" (Threads nested reply, or
+      # Threads refused), 401 "reauth_required" (the Threads reply permission
+      # or the TikTok comments authorization is missing or expired), 403
+      # "reconnect_required" (the account was connected without the
+      # comment-moderation permission; reconnect it in the dashboard), 404
+      # "not_found" (message not in this workspace) or
+      # "account_not_connected", 429 "quota_exceeded" (YouTube's daily API
+      # quota is used up; retry after midnight Pacific), 502 "platform_error"
+      # (the platform rejected the call). Threads inbox is currently rolling
+      # out; until Meta approves the permissions it is disabled on production
+      # and Threads calls return a clear error.
       def hide(message_id, hide: true)
         @client.request(
           "POST", "/inbox/messages/#{encode_id(message_id)}/hide",
@@ -119,6 +143,75 @@ module OmniSocials
         )
       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
+      # channel delete other people's comments, hide those instead (`hide`).
+      # Replies under the deleted comment go with it (the platforms cascade
+      # the delete and the inbox mirrors that); their inbox ids come back as
+      # "removed_reply_ids". A comment that is already gone on the platform
+      # is still removed from the inbox. This cannot be undone. Returns
+      # { "data" => { "id", "conversation_id", "removed_reply_ids" } }.
+      #
+      # Errors: 400 "unsupported_platform" (not an incoming Facebook,
+      # Instagram or TikTok comment), 401 "reauth_required" (the TikTok
+      # comments authorization expired), 403 "reconnect_required" (the
+      # account was connected without the comment-moderation permission;
+      # 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 delete_message(message_id)
+        @client.request("DELETE", "/inbox/messages/#{encode_id(message_id)}")
+      end
+
+      # GET /inbox/next - the next conversation that needs an answer: a work
+      # queue for answering the inbox. Returns the oldest (by default) item
+      # that still needs a reply, together with its conversation so far and
+      # the post it belongs to, so a reply can be drafted from one call. An
+      # item needs an answer when it is the customer's latest DM with no
+      # reply after it (Instagram/Facebook DMs within the 24-hour messaging
+      # window only, since Meta refuses replies outside it), or a
+      # comment/mention that has not been replied to and is not hidden.
+      # Replies typed in the native apps count as answers (they are mirrored
+      # into the inbox), so a thread a colleague answered on their phone is
+      # not served again. Instagram mentions are skipped (no reply path).
+      # Looks at the last 30 days of activity. Requires the inbox:read scope.
+      #
+      # Only unread items are served by default: marking a conversation read
+      # (`mark_read`) is how to skip one for good; pass include_read: true to
+      # include read-but-unanswered items. exclude is a session-local skip:
+      # conversation ids (an Array, or a comma-separated String) to leave out
+      # of this call, up to 100. order is "oldest" (default: the item that
+      # has waited longest first) or "newest". platform and type ("dm",
+      # "comment", "mention") narrow the queue.
+      #
+      # Returns { "data" => ..., "remaining" => Integer }. "data" is
+      # { "conversation", "message", "messages" }, 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, its "conversation_id" is what
+      # `reply` takes. "messages" is the conversation so far, oldest first
+      # (the most recent 50 messages for long DM threads). "remaining" is the
+      # number of unanswered items still waiting after this one (capped at
+      # 500), 0 when "data" is nil. To chain the queue, pass
+      # include_next: true to `reply` and it returns the next item in the
+      # same response. Errors: 400 "validation_error" (unknown platform, type
+      # or order).
+      def next(platform: nil, type: nil, order: nil, include_read: nil, exclude: nil)
+        exclude = exclude.join(",") if exclude.is_a?(Array)
+        exclude = nil if exclude == ""
+        @client.request(
+          "GET", "/inbox/next",
+          query: {
+            "platform" => platform,
+            "type" => type,
+            "order" => order,
+            "include_read" => include_read,
+            "exclude" => exclude
+          }
+        )
+      end
+
       private
 
       # URL-encode a conversation or message id for use in a path segment.

data/lib/omnisocials/resources/posts.rb

@@ -46,6 +46,13 @@ module OmniSocials
       # POST /posts/create - create a post (draft, or scheduled when
       # scheduled_at is set).
       #
+      # 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
+      # approvers are notified, and it publishes at scheduled_at once the last
+      # step approves. Requires scheduled_at; not allowed with publish_now.
+      # Errors: 404 workflow_not_found, 400 validation_error.
+      #
       # hashtag_set (set name, case-insensitive) or hashtag_set_id applies a
       # saved hashtag set once at create time; tags already in a caption are
       # skipped; Instagram's 30-hashtag cap returns error code
@@ -88,7 +95,7 @@ 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)
+                 linkedin_poll: nil, approval_workflow_id: nil)
         body = create_body(
           content: content, channels: channels, scheduled_at: scheduled_at,
           media_ids: media_ids, media_urls: media_urls, type: type,
@@ -101,7 +108,8 @@ 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, linkedin_poll: linkedin_poll,
+          approval_workflow_id: approval_workflow_id
         )
         @client.request("POST", "/posts/create", json: body)
       end
@@ -184,7 +192,7 @@ module OmniSocials
         @client.request("PATCH", "/posts/#{post_id}", json: body)
       end
 
-      # DELETE /posts/{id} - delete a post. Returns nil (204).
+      # DELETE /posts/{id} - remove a post from OmniSocials (the live post stays on the platform). Returns nil (204).
       def delete(post_id)
         @client.request("DELETE", "/posts/#{post_id}")
       end
@@ -239,7 +247,8 @@ module OmniSocials
                       hashtag_set_id:, hashtag_placement:, hashtag_platforms:,
                       pinterest:, youtube:, instagram:, facebook:, linkedin:,
                       linkedin_page:, tiktok:, x:, bluesky:, mastodon:,
-                      threads:, google_business:, linkedin_poll:)
+                      threads:, google_business:, linkedin_poll:,
+                      approval_workflow_id: nil)
         Internal.drop_nil(
           {
             "content" => content,
@@ -272,7 +281,8 @@ module OmniSocials
             "mastodon" => mastodon,
             "threads" => threads,
             "google_business" => google_business,
-            "linkedin_poll" => linkedin_poll
+            "linkedin_poll" => linkedin_poll,
+            "approval_workflow_id" => approval_workflow_id
           }
         )
       end

data/lib/omnisocials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OmniSocials
-  VERSION = "0.5.0"
+  VERSION = "0.6.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/approval_workflows"
 require_relative "omnisocials/resources/accounts"
 require_relative "omnisocials/resources/analytics"
 require_relative "omnisocials/resources/audio"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omnisocials
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - OmniSocials
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-17 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,
@@ -27,6 +27,7 @@ files:
 - lib/omnisocials/internal.rb
 - lib/omnisocials/resources/accounts.rb
 - lib/omnisocials/resources/analytics.rb
+- lib/omnisocials/resources/approval_workflows.rb
 - lib/omnisocials/resources/audio.rb
 - lib/omnisocials/resources/folders.rb
 - lib/omnisocials/resources/hashtag_sets.rb