omnisocials 0.18.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 396d389f359f705ffd24283768276b53efdc6f1f8f4a9d4448b38788b3f23d1d
4
- data.tar.gz: 45c406d73dd22a7af20c8ec5d02e7f330da72ef9dbe482f9ca5717644439fb02
3
+ metadata.gz: 490b6b315f549b047f79a7bdd796c702b9323536f1628bb08a74588f0179d197
4
+ data.tar.gz: ff14b37094ab09bb02e6e86a7fc6785709bb8c815c17cfcce8b6c1eaf83ba548
5
5
  SHA512:
6
- metadata.gz: 28ede0cfff7007e3ad31e395f3547a2c3f04a31592f4fb4308e7be388bd5466113a9b18260897817c38bfc11f6dc16180cdaeefa57c41c74c0d304f10f1c4897
7
- data.tar.gz: 07be6b2cf99c29d8b2b9f6654615774ba28a31bc3b0e6121b962f6ca93e70aa8133c3d5cc3d6eaf77d28d73190bb422119ff5b679e052cf23fec13d54081dac2
6
+ metadata.gz: e1c426ffcac5d703c4e8d9da2ee717644852fd66704b599e7f200c81f9a300d32e897256d28abdc9138c982db2f7b0be417382186959999b97c21bb857540616
7
+ data.tar.gz: 6af60e23be607ead1188f7f4caa3764cf671ab27f4a59ef5d2bf30500f55ca5179c41a8b114b8c5a3f20ae7cda670178b45e0039483374b214700afda6d1ed55
data/README.md CHANGED
@@ -84,7 +84,7 @@ client.posts.update(proposal["data"]["id"], draft: false)
84
84
 
85
85
  ### Comment-to-DM automations
86
86
 
87
- 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.
87
+ 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 700 DMs an hour per account, and an answer over the cap waits in a queue for up to a day.
88
88
 
89
89
  ```ruby
90
90
  post = client.posts.create(
@@ -129,6 +129,23 @@ client.automations.update(
129
129
  )
130
130
  ```
131
131
 
132
+ A follow-up (`"follow_up"` in the actions, Instagram and Facebook) sends one more DM `delay_hours` (1 to 23, default 23) after the answer went out, with an optional link `button`. Meta allows an automatic message only within 24 hours after the person's last DM, button tap or quick reply; the comment and the private reply do not open that window. So on an Instagram comment with Follow first off the first DM becomes a tap step, a short text with one button (`tap`, default "Tap the button and I'll send you the link 👇" / "Send me the link"), and the tap sends the DM text. Until the tap the event is `waiting` with `event["follow_gate"]["mode"]` `"tap"`; people who never tap get no link and no follow-up. With Follow first on, its own tap is the tap; DM and story reply triggers need none. A Facebook comment answer has no button, so only people who answer the DM in Messenger get the follow-up. At send time it is skipped when the automation is off, the person said stop, your team answered by hand or the window closed: `event["follow_up"]` carries `state`, `due_at`, `sent_at` and `reason` / `reason_label`, and `stats["follow_ups_sent"]` / `stats["follow_ups_skipped"]` count them. `nil`, `false` or `{ "enabled" => false }` turns it off and keeps the texts; on `update` it merges (`"button" => nil` removes the button). `"enabled" => true` on an X automation is a `400 follow_up_not_supported`.
133
+
134
+ ```ruby
135
+ client.automations.update(
136
+ automation_id,
137
+ actions: {
138
+ "dm" => { "text" => "Here is the guide: https://example.com/guide" },
139
+ "follow_up" => {
140
+ "enabled" => true,
141
+ "text" => "Did the guide help? Book a free call if you want a hand.",
142
+ "delay_hours" => 23,
143
+ "button" => { "title" => "Book a call", "url" => "https://example.com/call" }
144
+ }
145
+ }
146
+ )
147
+ ```
148
+
132
149
  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.
133
150
 
134
151
  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.
@@ -69,9 +69,10 @@ module OmniSocials
69
69
  # "2026-12-31T00:00:00Z" } (both optional). `status` is "active"
70
70
  # (default) or "paused". Meta rules, the same on Instagram and
71
71
  # Facebook: one private reply per comment, within 7 days; OmniSocials
72
- # caps sends at 180 DMs an hour per account and platform, and on X at
72
+ # caps sends at 700 DMs an hour per account and platform, and on X at
73
73
  # 15 per 15 minutes and 450 a day; an answer over a cap waits in a
74
- # queue ("queued") for up to an hour.
74
+ # queue ("queued") for up to about a day on Instagram and Facebook
75
+ # (an hour on X).
75
76
  #
76
77
  # Follow first (Instagram only): actions "follow_gate" => { "enabled"
77
78
  # => true, "first_message" => { "text", "button" }, "not_following" =>
@@ -86,8 +87,34 @@ module OmniSocials
86
87
  # the default. nil or false turns it off. The response carries the
87
88
  # gate with its texts (nil on Facebook and X) and stats "followed".
88
89
  #
90
+ # Follow-up (Instagram and Facebook): actions "follow_up" => {
91
+ # "enabled" => true, "text" => "...", "delay_hours" => 23, "button" =>
92
+ # { "title", "url" }, "tap" => { "text", "button" } } sends one more DM
93
+ # delay_hours (1 to 23, default 23) after the answer (the "dm" text)
94
+ # went out. "text" is required when it is on (max 1000 characters,
95
+ # 640 with a "button"); "button" is an optional link button ("title"
96
+ # 1 to 20 characters, "url" an https:// or http:// address of up to
97
+ # 2000). Meta allows an automatic message only within 24 hours after
98
+ # the person's last DM, button tap or quick reply; the comment and the
99
+ # private reply do not open that window. So on an Instagram comment
100
+ # with Follow first off the first DM becomes a tap step, a short text
101
+ # with one button ("tap", Instagram only, "text" max 640 and "button"
102
+ # max 20 characters; default "Tap the button and I'll send you the
103
+ # link 👇" / "Send me the link"): the tap sends the link, and until
104
+ # then the event is "waiting" with follow_gate "mode" "tap". People
105
+ # who never tap get no link and no follow-up. With Follow first on,
106
+ # its own tap is the tap; DM and story reply triggers need none. A
107
+ # Facebook comment answer has no button: only people who answer the
108
+ # DM in Messenger get the follow-up. nil, false or { "enabled" =>
109
+ # false } turns it off and keeps the texts. The response carries
110
+ # actions "follow_up" ({ "enabled", "text", "delay_hours", "button" =>
111
+ # {...} | nil, "tap" => {...} | nil }, "tap" filled in on Instagram
112
+ # and nil on Facebook; the whole follow-up is nil on X) and stats
113
+ # "follow_ups_sent" / "follow_ups_skipped".
114
+ #
89
115
  # Requires the automations:write scope (opt-in on the API key).
90
116
  # Errors: 400 validation_error, 400 follow_gate_instagram_only, 400
117
+ # follow_up_not_supported (a follow-up switched on on X), 400
91
118
  # post_not_instagram, 400 post_not_facebook, 400 post_required, 404 post_not_found, 404
92
119
  # instagram_media_not_found, 404 facebook_post_not_found, 409
93
120
  # instagram_not_connected, 409 instagram_needs_reauth, 409
@@ -114,15 +141,18 @@ module OmniSocials
114
141
  # "public_reply" => { "enabled" => false } or { "variations" => [] }
115
142
  # turns the public reply off; "follow_gate" => { "enabled" => false }
116
143
  # turns Follow first off and keeps its texts, new texts keep the
117
- # switch, and "follow_gate" => nil turns it off; limits: {
118
- # "max_sends" => nil } removes that limit. status: "paused" pauses and "active" resumes; another
144
+ # switch, and "follow_gate" => nil turns it off; "follow_up" merges
145
+ # the same way ("tap" key by key, "button" => nil removes the button,
146
+ # nil, false or { "enabled" => false } turns it off and keeps the
147
+ # texts); limits: { "max_sends" => nil } removes that limit. status: "paused" pauses and "active" resumes; another
119
148
  # post_id / instagram_media_id / facebook_post_id moves the automation
120
149
  # to that post. The platform cannot change: a platform other than the
121
150
  # automation's is a 400 platform_immutable. status: "active" on an X
122
151
  # automation needs X DMs on for the workspace (409 x_dms_off). A
123
152
  # "completed" automation starts again when its limits or trigger
124
153
  # change. Requires the
125
- # automations:write scope. 400 no_fields when nothing is passed.
154
+ # automations:write scope. 400 no_fields when nothing is passed; 400
155
+ # follow_up_not_supported for a follow-up switched on on X.
126
156
  def update(automation_id, name: nil, post_id: nil, instagram_media_id: nil,
127
157
  trigger: nil, actions: nil, limits: nil, status: nil,
128
158
  platform: nil, facebook_post_id: nil)
@@ -143,9 +173,10 @@ module OmniSocials
143
173
  # GET /automations/{id}/events - the automation's activity: one event
144
174
  # per person it answered, skipped or failed on. outcome filters on
145
175
  # "sent", "skipped", "failed", "pending", "queued" (waits for a free
146
- # slot under the send cap, out within the hour), "opted_out" (the
176
+ # slot under the send cap, out as soon as there is room), "opted_out" (the
147
177
  # person replied STOP on X) or "waiting" (Follow first: asked to
148
- # follow, the link goes out after the follow); limit is 1..100
178
+ # follow, the link goes out after the follow; or the tap step of a
179
+ # follow-up: the link goes out after the tap); limit is 1..100
149
180
  # (default 25), offset skips. Requires the automations:read scope.
150
181
  #
151
182
  # The response is not the plain list envelope: { "data" => [...],
@@ -161,7 +192,19 @@ module OmniSocials
161
192
  # @handle), trigger_id, trigger_text, message (the DM sent),
162
193
  # public_reply, platform_message_id, follow_gate (Follow first:
163
194
  # { "state" => "waiting" | "done", "asked_at", "taps", "followed",
164
- # "checked", "after_ask" }, else nil), created_at and sent_at.
195
+ # "checked", "after_ask", "mode" }, else nil; "mode" is "follow", or
196
+ # "tap" for the tap step of a follow-up, which checks no follow:
197
+ # "checked" stays false and "followed" is nil after the tap),
198
+ # follow_up (the follow-up of this answer: { "state" => "scheduled" |
199
+ # "sending" | "sent" | "skipped" | "failed", "due_at", "sent_at",
200
+ # "reason", "reason_label", "platform_message_id" }, else nil;
201
+ # "reason" only on skipped and failed: "automation_off",
202
+ # "follow_up_off", "plan_inactive", "opted_out", "team_answered",
203
+ # "window_closed" (the person's last tap or message is older than 24
204
+ # hours minus 15 minutes) or "cannot_message" for a skip, the
205
+ # platform's error text or "interrupted" (a send that died midway,
206
+ # never sent again) for a failure; "reason_label" = the skip in plain
207
+ # words, or the error text), created_at and sent_at.
165
208
  def list_events(automation_id, outcome: nil, limit: nil, offset: nil)
166
209
  @client.request(
167
210
  "GET", "/automations/#{Internal.path_segment(automation_id)}/events",
@@ -173,7 +173,8 @@ module OmniSocials
173
173
  # [...] } }, "limits" => { "max_sends" => 500 }, "platforms" =>
174
174
  # ["instagram", "facebook"] } (see automations.create for the
175
175
  # fields, also the actions "follow_gate", Follow first, which applies
176
- # to the Instagram automation only). "platforms" makes one automation
176
+ # to the Instagram automation only, and "follow_up", the follow-up,
177
+ # which applies to both). "platforms" makes one automation
177
178
  # per listed channel; each
178
179
  # must be a channel of the post. Without it: Instagram when the post
179
180
  # goes there, else Facebook. Needs the automations:write scope on the
@@ -299,7 +300,8 @@ module OmniSocials
299
300
  # comment_dm_automation (same shape as on #create) as a Hash replaces
300
301
  # the post's comment-to-DM automations (a channel no longer in
301
302
  # "platforms" loses its automation), an explicit nil removes them all,
302
- # and leaving it out keeps them. Needs the automations:write scope.
303
+ # and leaving it out keeps them. An "actions" without "follow_up"
304
+ # keeps the stored follow-up. Needs the automations:write scope.
303
305
  #
304
306
  # discord merges into the stored Discord options: a key set to nil
305
307
  # removes that option (e.g. discord: { "poll" => nil }), an explicit
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module OmniSocials
4
- VERSION = "0.18.0"
4
+ VERSION = "0.19.0"
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: omnisocials
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.18.0
4
+ version: 0.19.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - OmniSocials
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-11-08 00:00:00.000000000 Z
11
+ date: 2026-11-19 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Schedule and publish social media posts, upload media, and read analytics
14
14
  across Instagram, Facebook, LinkedIn, YouTube, TikTok, X, Pinterest, Bluesky, Threads,