omnisocials 0.14.0 → 0.15.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 +4 -4
- data/README.md +112 -3
- data/lib/omnisocials/client.rb +17 -6
- data/lib/omnisocials/internal.rb +7 -0
- data/lib/omnisocials/resources/ads.rb +356 -0
- data/lib/omnisocials/resources/automations.rb +27 -9
- data/lib/omnisocials/resources/feature_requests.rb +61 -0
- data/lib/omnisocials/resources/inbox.rb +3 -2
- data/lib/omnisocials/resources/limits.rb +36 -0
- data/lib/omnisocials/resources/posts.rb +10 -2
- data/lib/omnisocials/resources/webhooks.rb +7 -3
- data/lib/omnisocials/version.rb +1 -1
- data/lib/omnisocials.rb +3 -0
- metadata +5 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 8c00d8899c0d1c024d739775a25508750dfada8a2be74eb4ecdc2b855b39cafe
|
|
4
|
+
data.tar.gz: cad371c9a76055c3331232856d48192f638e1fa382482c018b9b78ff0dc47017
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 93ae9f8f0a567e517c3c45408eaf22f9663d2e9354526d37b05be404ce5805021c70852cedef9a081d4cd27c824ef88e8a9966c8a2c6d9d11b077b29c2e98d2f
|
|
7
|
+
data.tar.gz: 4bfa021ebf8d846b0e705ebd0fdcd95343b0b508c433f9f5e2a86c843f5e8c413044599b176203f0b7c46090204ad537cadf57b758ee23707063bb298c5aba72
|
data/README.md
CHANGED
|
@@ -111,7 +111,23 @@ events["data"].each do |event|
|
|
|
111
111
|
end
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
-
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"], ... }`).
|
|
114
|
+
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`, `waiting`). 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"], ... }`).
|
|
115
|
+
|
|
116
|
+
Follow first (`"follow_gate"` in the actions, Instagram only) sends the link only to people who follow the account. On a comment the private reply is a first message with one button; a tap makes OmniSocials ask Instagram whether the person follows. A follower gets the DM text, anyone else gets the `not_following` message with its button, and every later tap checks again. A DM or a story reply is checked at once. When Instagram gives no answer the link goes out anyway. Texts hold 640 characters and buttons 20; leave them out for the defaults. A person who has not followed yet is an event with outcome `waiting` and `event["follow_gate"]` (`state`, `taps`, `followed`, `checked`, `after_ask`); `stats["followed"]` counts the people who followed after the ask. `"enabled" => true` on a Facebook or X automation is a `400 follow_gate_instagram_only`.
|
|
117
|
+
|
|
118
|
+
```ruby
|
|
119
|
+
client.automations.update(
|
|
120
|
+
automation_id,
|
|
121
|
+
actions: {
|
|
122
|
+
"dm" => { "text" => "Here is the guide: https://example.com/guide" },
|
|
123
|
+
"follow_gate" => {
|
|
124
|
+
"enabled" => true,
|
|
125
|
+
"first_message" => { "text" => "Tap the button and I'll send you the link 👇", "button" => "Send me the link" },
|
|
126
|
+
"not_following" => { "text" => "Almost there! Follow @yourbrand first, then tap the button again.", "button" => "I follow now" }
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
)
|
|
130
|
+
```
|
|
115
131
|
|
|
116
132
|
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.
|
|
117
133
|
|
|
@@ -575,6 +591,7 @@ client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
|
|
|
575
591
|
message_id = messages["data"][0]["id"]
|
|
576
592
|
client.inbox.hide(message_id) # hide
|
|
577
593
|
client.inbox.hide(message_id, hide: false) # unhide
|
|
594
|
+
# Delete a comment, or one of your own replies (Facebook, Instagram, TikTok).
|
|
578
595
|
client.inbox.delete_message(message_id)
|
|
579
596
|
|
|
580
597
|
# Like a comment as the Page or account (Facebook, LinkedIn Page, TikTok).
|
|
@@ -631,9 +648,68 @@ end
|
|
|
631
648
|
|
|
632
649
|
`x_inbox_suspended` fires once a workspace's X inbox has auto-suspended after its credit balance hit zero; topping up and re-enabling it in the dashboard resumes delivery, but DMs that arrived while suspended are not recovered.
|
|
633
650
|
|
|
651
|
+
## Ads
|
|
652
|
+
|
|
653
|
+
Boost a published post or create a new ad on Meta, Pinterest, TikTok, LinkedIn, X and Google. Ads spend real money, so every call that starts or raises spend asks for the amount again: `ads.activate`, `ads.activate_multi`, `ads.drafts.launch` and a budget raise through `ads.update`. Show the person the amount first and pass it only after they agree. These calls (and `ads.resume`) are not retried after a 5xx or a timeout, because the first attempt may have started the ad: read the campaign or the draft to see what happened.
|
|
654
|
+
|
|
655
|
+
The `ads:read` and `ads:write` scopes are opt-in: create the API key with **Ads** switched on (Settings, API). A key without them gets `403 insufficient_scope`. Ad accounts are connected and picked in the OmniSocials dashboard. Budgets are in major units (10 = 10 EUR) in the ad account's currency. Ad account and campaign ids come back as strings (`"51"`); the methods take an id as a string or a number.
|
|
656
|
+
|
|
657
|
+
### Create an ad (draft, then launch)
|
|
658
|
+
|
|
659
|
+
```ruby
|
|
660
|
+
caps = client.ads.capabilities
|
|
661
|
+
p caps["data"]["create_networks"], caps["data"]["network_states"]
|
|
662
|
+
|
|
663
|
+
draft = client.ads.drafts.create(
|
|
664
|
+
name: "Autumn sale",
|
|
665
|
+
objective: "traffic",
|
|
666
|
+
platforms: %w[meta linkedin],
|
|
667
|
+
budget: { "amount" => 10, "currency" => "EUR" },
|
|
668
|
+
schedule: { "duration_days" => 7 },
|
|
669
|
+
targeting: { "countries" => %w[NL BE], "automatic_audience" => true },
|
|
670
|
+
ads: [
|
|
671
|
+
{
|
|
672
|
+
"media" => [{ "url" => "https://example.com/sale.jpg", "type" => "image", "width" => 1080, "height" => 1350 }],
|
|
673
|
+
"primary_text" => "30% off everything this week",
|
|
674
|
+
"headline" => "Autumn sale",
|
|
675
|
+
"cta" => "shop_now",
|
|
676
|
+
"link" => "https://example.com/sale"
|
|
677
|
+
}
|
|
678
|
+
]
|
|
679
|
+
)["data"]
|
|
680
|
+
|
|
681
|
+
# A draft spends nothing. Hand draft["review_url"] to the person, or start it
|
|
682
|
+
# after they confirmed 10 EUR a day per network:
|
|
683
|
+
launch = client.ads.drafts.launch(draft["group_id"], confirm_budget_amount: 10)["data"]
|
|
684
|
+
launch["results"].each do |result|
|
|
685
|
+
puts "#{result["platform"]}: #{result["ok"] ? "started" : result["error"]}"
|
|
686
|
+
end
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
A draft needs no ad account; `client.ads.drafts.attach_account(group_id, platform: "meta", ad_account_id: "51")` sets one, and `campaigns[].readiness` says what still stops a network. `client.ads.drafts.update(group_id, ...)` replaces the whole draft (HTTP PUT), so send every field again. On Meta an ad can carry a second upright 9:16 file for Stories and Reels: `"placement_media" => { "stories_reels" => { "url" => ..., "type" => ... } }`.
|
|
690
|
+
|
|
691
|
+
### Boost a post
|
|
692
|
+
|
|
693
|
+
```ruby
|
|
694
|
+
accounts = client.ads.list_accounts["data"]
|
|
695
|
+
meta = accounts.find { |account| account["platform"] == "meta" && account["is_selected"] }
|
|
696
|
+
|
|
697
|
+
boost = client.ads.boost(
|
|
698
|
+
post_id: 12_345,
|
|
699
|
+
ad_account_id: meta["id"],
|
|
700
|
+
budget: { "type" => "daily", "amount" => 5, "currency" => meta.dig("account_info", "currency") || "EUR" },
|
|
701
|
+
targeting: { "countries" => ["NL"] }
|
|
702
|
+
)["data"]
|
|
703
|
+
|
|
704
|
+
# The boost is a draft. Start it only after the person confirmed 5 a day:
|
|
705
|
+
client.ads.activate(boost["id"], 5)
|
|
706
|
+
```
|
|
707
|
+
|
|
708
|
+
`client.ads.boost_multi` makes one draft boost per ad account (up to 10, the same budget each). `client.ads.suggestions` lists posts that do better than your median, `client.ads.overview` the totals, and `client.ads.list`, `get`, `pause`, `resume` and `delete` manage campaigns. Keyword ideas through the connected Google Ads account: `client.ads.research_keywords(keywords: ["running shoes"], country: "NL")` and `client.ads.keyword_metrics(keywords: [...])`.
|
|
709
|
+
|
|
634
710
|
## Webhooks
|
|
635
711
|
|
|
636
|
-
Subscribe to `post.scheduled`, `post.published`, `post.failed`, `post.approved`, and `post.rejected` events. `post.approved` fires when the last step of a post's approval workflow is approved, `post.rejected` when an approver rejects the post (it will not publish). These two carry `data["approval"]` with `status`, `decided_by` (the approver's user id) and `reason` (`nil` on `post.approved`), and an empty `data["targets"]`.
|
|
712
|
+
Subscribe to `post.scheduled`, `post.published`, `post.failed`, `post.approved`, and `post.rejected` events. `post.approved` fires when the last step of a post's approval workflow is approved, `post.rejected` when an approver rejects the post (it will not publish). These two carry `data["approval"]` with `status`, `decided_by` (the approver's user id) and `reason` (`nil` on `post.approved`), and an empty `data["targets"]`. `ad.status_changed` fires when an ad campaign changes status (for example `pending_review` to `active` or `rejected`); its `data` is the campaign, not a post: `campaign_id`, `workspace_id`, `name`, `platform`, `campaign_type`, `status`, `previous_status`, `external_campaign_id` and `budget`.
|
|
637
713
|
|
|
638
714
|
```ruby
|
|
639
715
|
webhook = client.webhooks.create(
|
|
@@ -715,6 +791,39 @@ run app
|
|
|
715
791
|
|
|
716
792
|
`OmniSocials::Webhooks.verify` uses a constant-time comparison, rejects timestamps older than `tolerance` seconds (default 300) to block replays, and returns the parsed event Hash on success. Respond with any 2xx within 10 seconds to acknowledge; deliveries are retried up to 3 times.
|
|
717
793
|
|
|
794
|
+
## Limits and feature requests
|
|
795
|
+
|
|
796
|
+
`client.limits.list` lists what OmniSocials cannot do, why (`says`) and what to do instead (`instead`): platform rules, features not built yet, features that work in the OmniSocials app only. Read it before you tell a person that something is not possible. When the person still wants a `requestable` entry, send a feature request with its `limit_id`. The request is stored for the person who owns the key; they see it in OmniSocials (Settings, Request a feature) and get an email when its status changes. Works with every key, no scope needed.
|
|
797
|
+
|
|
798
|
+
```ruby
|
|
799
|
+
limits = client.limits.list(platform: "telegram") # area: "posts" | "inbox" | ...
|
|
800
|
+
limits["data"].each do |limit|
|
|
801
|
+
puts [limit["id"], limit["says"], limit["instead"], limit["requestable"]].inspect
|
|
802
|
+
end
|
|
803
|
+
|
|
804
|
+
begin
|
|
805
|
+
result = client.feature_requests.create(
|
|
806
|
+
summary: "Post our daily update to the Announcements topic of our Telegram group, not to the whole group.",
|
|
807
|
+
platform: "telegram",
|
|
808
|
+
limit_id: "telegram.forum_topics"
|
|
809
|
+
)
|
|
810
|
+
# "created" (new), "voted" (added a vote to your organisation's open request)
|
|
811
|
+
# or "already_requested" (you asked before; data is that request)
|
|
812
|
+
puts result["outcome"], result["data"]["id"], result["data"]["status"]
|
|
813
|
+
rescue OmniSocials::APIError => e
|
|
814
|
+
raise unless e.code == "not_requestable"
|
|
815
|
+
|
|
816
|
+
# A platform rule or a choice of OmniSocials: nothing was stored.
|
|
817
|
+
limit = e.body["error"]["limit"]
|
|
818
|
+
puts limit["says"], limit["instead"]
|
|
819
|
+
end
|
|
820
|
+
|
|
821
|
+
mine = client.feature_requests.list # newest first, at most 50
|
|
822
|
+
one = client.feature_requests.get(mine["data"].first["id"]) # status, team_answer, team_replies
|
|
823
|
+
```
|
|
824
|
+
|
|
825
|
+
A limit is `{ "id", "kind", "kind_label", "area", "platforms", "title", "says", "instead", "requestable" }`; `kind` is `platform`, `by_design`, `not_built`, `beta`, `dashboard_only` or `needs_setup`, and `requestable` is false for `platform` and `by_design`. `limits.list` also returns `kinds` (a label per kind). A request carries `status` (`open`, `in_progress`, `completed`, `declined`), `votes_count`, `team_answer` and `team_replies`. `summary:` is 10 to 1000 characters (what the person wants to do and why), `title:` at most 120 (made from the summary when left out); `area:` is one of posts, media, inbox, analytics, automations, accounts, ads, team, other. Errors: `400 invalid_summary` / `invalid_title` / `invalid_platform` / `invalid_area` / `unknown_limit`, `409 not_requestable` (the entry is in `e.body["error"]["limit"]`), `429 too_many_requests` (10 an hour per person), and `400 invalid_id` / `404 not_found` on `get`.
|
|
826
|
+
|
|
718
827
|
## Error handling
|
|
719
828
|
|
|
720
829
|
Non-2xx responses raise typed exceptions with `status`, `code`, `message`, and the parsed `body`:
|
|
@@ -745,7 +854,7 @@ The API allows **100 requests per minute** per API key. Every response includes
|
|
|
745
854
|
|
|
746
855
|
## Retries and timeouts
|
|
747
856
|
|
|
748
|
-
The SDK automatically retries on 429, 5xx, and connection errors with exponential backoff (0.5s, 1s, 2s, with jitter), honoring the `Retry-After` header when present. Other 4xx errors are never retried. Defaults: 2 retries, 30 second timeout. Both are configurable:
|
|
857
|
+
The SDK automatically retries on 429, 5xx, and connection errors with exponential backoff (0.5s, 1s, 2s, with jitter), honoring the `Retry-After` header when present. Other 4xx errors are never retried. The ads calls that start or raise spend retry a 429 only (see [Ads](#ads)). Defaults: 2 retries, 30 second timeout. Both are configurable:
|
|
749
858
|
|
|
750
859
|
```ruby
|
|
751
860
|
client = OmniSocials::Client.new(
|
data/lib/omnisocials/client.rb
CHANGED
|
@@ -38,6 +38,7 @@ module OmniSocials
|
|
|
38
38
|
"GET" => Net::HTTP::Get,
|
|
39
39
|
"POST" => Net::HTTP::Post,
|
|
40
40
|
"PATCH" => Net::HTTP::Patch,
|
|
41
|
+
"PUT" => Net::HTTP::Put,
|
|
41
42
|
"DELETE" => Net::HTTP::Delete
|
|
42
43
|
}.freeze
|
|
43
44
|
|
|
@@ -61,7 +62,8 @@ module OmniSocials
|
|
|
61
62
|
attr_reader :api_key, :base_url, :timeout, :max_retries,
|
|
62
63
|
:posts, :media, :folders, :hashtag_sets, :approval_workflows,
|
|
63
64
|
:accounts, :analytics, :audio, :locations, :pinterest,
|
|
64
|
-
:automations, :inbox, :webhooks, :tags
|
|
65
|
+
:automations, :ads, :inbox, :webhooks, :tags,
|
|
66
|
+
:limits, :feature_requests
|
|
65
67
|
|
|
66
68
|
# api_key - API key (omsk_live_*). Falls back to the
|
|
67
69
|
# OMNISOCIALS_API_KEY environment variable. Raises
|
|
@@ -98,8 +100,11 @@ module OmniSocials
|
|
|
98
100
|
@locations = Resources::Locations.new(self)
|
|
99
101
|
@pinterest = Resources::Pinterest.new(self)
|
|
100
102
|
@automations = Resources::Automations.new(self)
|
|
103
|
+
@ads = Resources::Ads.new(self)
|
|
101
104
|
@inbox = Resources::Inbox.new(self)
|
|
102
105
|
@webhooks = Resources::Webhooks.new(self)
|
|
106
|
+
@limits = Resources::Limits.new(self)
|
|
107
|
+
@feature_requests = Resources::FeatureRequests.new(self)
|
|
103
108
|
end
|
|
104
109
|
|
|
105
110
|
# GET /health - API health check (no scopes required).
|
|
@@ -113,7 +118,11 @@ module OmniSocials
|
|
|
113
118
|
# non-JSON responses, or nil for 204. Raises an OmniSocials::APIError
|
|
114
119
|
# subclass on non-2xx and OmniSocials::APIConnectionError when no
|
|
115
120
|
# response was ever received.
|
|
116
|
-
|
|
121
|
+
#
|
|
122
|
+
# retry_on: :rate_limit retries only a 429. A call that can start ad
|
|
123
|
+
# spend uses it: after a 5xx, a timeout or a lost connection the first
|
|
124
|
+
# attempt may have gone through, so it is never sent again.
|
|
125
|
+
def request(method, path, query: nil, json: nil, multipart: nil, retry_on: nil)
|
|
117
126
|
uri = build_uri(path, query)
|
|
118
127
|
last_error = nil
|
|
119
128
|
|
|
@@ -122,13 +131,14 @@ module OmniSocials
|
|
|
122
131
|
response = perform(method, uri, json: json, multipart: multipart)
|
|
123
132
|
rescue *CONNECTION_ERRORS => e
|
|
124
133
|
last_error = e
|
|
125
|
-
|
|
134
|
+
# Not sent again when the call may have started ad spend.
|
|
135
|
+
break if retry_on == :rate_limit || attempt >= max_retries
|
|
126
136
|
|
|
127
137
|
sleep(Internal.backoff_delay(attempt, nil))
|
|
128
138
|
next
|
|
129
139
|
end
|
|
130
140
|
|
|
131
|
-
should_retry, retry_after = retry_info(response)
|
|
141
|
+
should_retry, retry_after = retry_info(response, retry_on)
|
|
132
142
|
if should_retry && attempt < max_retries
|
|
133
143
|
sleep(Internal.backoff_delay(attempt, retry_after))
|
|
134
144
|
next
|
|
@@ -178,9 +188,10 @@ module OmniSocials
|
|
|
178
188
|
http.start { |conn| conn.request(req) }
|
|
179
189
|
end
|
|
180
190
|
|
|
181
|
-
def retry_info(response)
|
|
191
|
+
def retry_info(response, retry_on)
|
|
182
192
|
status = response.code.to_i
|
|
183
|
-
|
|
193
|
+
server_error = RETRY_STATUSES.include?(status) || status >= 500
|
|
194
|
+
if status == 429 || (server_error && retry_on != :rate_limit)
|
|
184
195
|
[true, parse_retry_after(response, Internal.parse_body(response.body))]
|
|
185
196
|
else
|
|
186
197
|
[false, nil]
|
data/lib/omnisocials/internal.rb
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require "cgi"
|
|
3
4
|
require "json"
|
|
4
5
|
require "pathname"
|
|
5
6
|
|
|
@@ -34,6 +35,12 @@ module OmniSocials
|
|
|
34
35
|
hash.reject { |_key, value| value.nil? || value.is_a?(NotGiven) }
|
|
35
36
|
end
|
|
36
37
|
|
|
38
|
+
# URL-encode an id for use as one path segment. Spaces become %20 (a
|
|
39
|
+
# path segment treats "+" literally, unlike a query string).
|
|
40
|
+
def path_segment(value)
|
|
41
|
+
CGI.escape(value.to_s).gsub("+", "%20")
|
|
42
|
+
end
|
|
43
|
+
|
|
37
44
|
# Join an array into a comma-separated string; pass strings through.
|
|
38
45
|
def join_list(value)
|
|
39
46
|
return nil if value.nil?
|
|
@@ -0,0 +1,356 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniSocials
|
|
4
|
+
module Resources
|
|
5
|
+
# Ads resource: boosts, campaigns and "Create an ad" drafts on Meta,
|
|
6
|
+
# Pinterest, TikTok, LinkedIn, X and Google.
|
|
7
|
+
#
|
|
8
|
+
# Ads spend real money once a campaign starts. Boosts, campaigns and
|
|
9
|
+
# drafts are created as drafts (no spend); activate, activate_multi,
|
|
10
|
+
# drafts.launch, resume and a budget raise through update start or raise
|
|
11
|
+
# spend, and each needs the amount again as a confirmation. These calls
|
|
12
|
+
# are never retried after a 5xx, a timeout or a lost connection (only a
|
|
13
|
+
# 429), because the first attempt may have started the ad. Budgets are in
|
|
14
|
+
# major currency units (10 = 10 EUR) in the ad account's currency. Ad
|
|
15
|
+
# accounts are connected and picked in the OmniSocials dashboard. The
|
|
16
|
+
# scopes ads:read and ads:write are opt-in on the API key (the Ads
|
|
17
|
+
# switch).
|
|
18
|
+
class Ads
|
|
19
|
+
# "Create an ad" drafts (an OmniSocials::Resources::AdDrafts).
|
|
20
|
+
attr_reader :drafts
|
|
21
|
+
|
|
22
|
+
def initialize(client)
|
|
23
|
+
@client = client
|
|
24
|
+
@drafts = AdDrafts.new(client)
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# GET /ads/accounts - the connected ad accounts, as { "data" => [...],
|
|
28
|
+
# "platforms_available" => [...] }. Accounts are connected and picked in
|
|
29
|
+
# the dashboard; only is_selected accounts can run campaigns. Requires
|
|
30
|
+
# ads:read (opt-in on the API key).
|
|
31
|
+
def list_accounts
|
|
32
|
+
@client.request("GET", "/ads/accounts")
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
# GET /ads/capabilities - what each network accepts for a new ad
|
|
36
|
+
# (goals, media, text limits, buttons, minimum daily budget),
|
|
37
|
+
# create_networks and network_states ("live", "preview" or
|
|
38
|
+
# "coming_soon"). Requires ads:read.
|
|
39
|
+
def capabilities
|
|
40
|
+
@client.request("GET", "/ads/capabilities")
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# GET /ads/campaigns - list campaigns and boosts, optionally by status,
|
|
44
|
+
# platform or campaign_type ("campaign" or "boost"); limit is 1..100
|
|
45
|
+
# (default 25). Requires ads:read.
|
|
46
|
+
def list(status: nil, platform: nil, campaign_type: nil, limit: nil, offset: nil)
|
|
47
|
+
@client.request(
|
|
48
|
+
"GET", "/ads/campaigns",
|
|
49
|
+
query: {
|
|
50
|
+
"status" => status, "platform" => platform, "campaign_type" => campaign_type,
|
|
51
|
+
"limit" => limit, "offset" => offset
|
|
52
|
+
}
|
|
53
|
+
)
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
# GET /ads/campaigns/{id} - one campaign with its latest numbers.
|
|
57
|
+
# Requires ads:read.
|
|
58
|
+
def get(campaign_id)
|
|
59
|
+
@client.request("GET", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
# POST /ads/boost - boost a published post. Creates a DRAFT boost: no
|
|
63
|
+
# spend until activate. budget is { "type" => "daily", "amount" => 5,
|
|
64
|
+
# "currency" => "EUR" } in the ad account's currency. TikTok needs
|
|
65
|
+
# creative "spark_auth_code", Google needs "headlines", "descriptions"
|
|
66
|
+
# and "logo_url". Requires ads:write.
|
|
67
|
+
def boost(post_id:, ad_account_id:, budget:, objective: nil, targeting: nil,
|
|
68
|
+
schedule: nil, creative: nil, name: nil)
|
|
69
|
+
body = Internal.drop_nil(
|
|
70
|
+
{
|
|
71
|
+
"post_id" => post_id, "ad_account_id" => ad_account_id, "budget" => budget,
|
|
72
|
+
"objective" => objective, "targeting" => targeting, "schedule" => schedule,
|
|
73
|
+
"creative" => creative, "name" => name
|
|
74
|
+
}
|
|
75
|
+
)
|
|
76
|
+
@client.request("POST", "/ads/boost", json: body)
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
# POST /ads/boost-multi - one DRAFT boost per ad account (up to 10),
|
|
80
|
+
# each with the same budget, so the total is amount x accounts. Answers
|
|
81
|
+
# { "results" => [...] }; one failed account never stops the others.
|
|
82
|
+
# Requires ads:write.
|
|
83
|
+
def boost_multi(post_id:, ad_account_ids:, budget:, objective: nil, targeting: nil,
|
|
84
|
+
schedule: nil, creative: nil, name: nil)
|
|
85
|
+
body = Internal.drop_nil(
|
|
86
|
+
{
|
|
87
|
+
"post_id" => post_id, "ad_account_ids" => ad_account_ids.to_a, "budget" => budget,
|
|
88
|
+
"objective" => objective, "targeting" => targeting, "schedule" => schedule,
|
|
89
|
+
"creative" => creative, "name" => name
|
|
90
|
+
}
|
|
91
|
+
)
|
|
92
|
+
@client.request("POST", "/ads/boost-multi", json: body)
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
# POST /ads/campaigns - a DRAFT campaign without ads. It cannot start
|
|
96
|
+
# (campaign_has_no_ads): use ads.drafts.create for a new ad. Requires
|
|
97
|
+
# ads:write.
|
|
98
|
+
def create(ad_account_id:, name:, budget:, objective: nil, targeting: nil, schedule: nil)
|
|
99
|
+
body = Internal.drop_nil(
|
|
100
|
+
{
|
|
101
|
+
"ad_account_id" => ad_account_id,
|
|
102
|
+
"name" => name,
|
|
103
|
+
"budget" => budget,
|
|
104
|
+
"objective" => objective,
|
|
105
|
+
"targeting" => targeting,
|
|
106
|
+
"schedule" => schedule
|
|
107
|
+
}
|
|
108
|
+
)
|
|
109
|
+
@client.request("POST", "/ads/campaigns", json: body)
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
# PATCH /ads/campaigns/{id} - change the name, budget, targeting or
|
|
113
|
+
# schedule.
|
|
114
|
+
#
|
|
115
|
+
# A higher budget on a running campaign RAISES REAL AD SPEND: show the
|
|
116
|
+
# person the new amount and get their yes first, then pass it again as
|
|
117
|
+
# confirm_budget_amount. Not retried after a 5xx, a timeout or a lost
|
|
118
|
+
# connection: read the campaign with get to see what happened. Requires
|
|
119
|
+
# ads:write.
|
|
120
|
+
def update(campaign_id, name: nil, budget: nil, confirm_budget_amount: nil,
|
|
121
|
+
targeting: nil, schedule: nil)
|
|
122
|
+
body = Internal.drop_nil(
|
|
123
|
+
{
|
|
124
|
+
"name" => name,
|
|
125
|
+
"budget" => budget,
|
|
126
|
+
"confirm_budget_amount" => confirm_budget_amount,
|
|
127
|
+
"targeting" => targeting,
|
|
128
|
+
"schedule" => schedule
|
|
129
|
+
}
|
|
130
|
+
)
|
|
131
|
+
@client.request(
|
|
132
|
+
"PATCH", "/ads/campaigns/#{Internal.path_segment(campaign_id)}",
|
|
133
|
+
json: body, retry_on: :rate_limit
|
|
134
|
+
)
|
|
135
|
+
end
|
|
136
|
+
|
|
137
|
+
# POST /ads/campaigns/{id}/activate - START REAL AD SPEND.
|
|
138
|
+
#
|
|
139
|
+
# Show the person the budget (amount, currency, daily or lifetime) and
|
|
140
|
+
# get their yes first; confirm_budget_amount must equal the campaign's
|
|
141
|
+
# budget amount. A campaign of a draft group answers 409
|
|
142
|
+
# use_draft_launch: use ads.drafts.launch. Not retried after a 5xx, a
|
|
143
|
+
# timeout or a lost connection: read the campaign with get to see what
|
|
144
|
+
# happened. Requires ads:write.
|
|
145
|
+
def activate(campaign_id, confirm_budget_amount)
|
|
146
|
+
@client.request(
|
|
147
|
+
"POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/activate",
|
|
148
|
+
json: { "confirm_budget_amount" => confirm_budget_amount }, retry_on: :rate_limit
|
|
149
|
+
)
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
# POST /ads/campaigns/activate-multi - START REAL AD SPEND on up to 10
|
|
153
|
+
# campaigns.
|
|
154
|
+
#
|
|
155
|
+
# Every campaign's budget must equal confirm_budget_amount; show the
|
|
156
|
+
# person the total (amount x campaigns) and get their yes first.
|
|
157
|
+
# Answers { "results" => [...] }. Not retried after a 5xx, a timeout or
|
|
158
|
+
# a lost connection: read the campaigns with get to see what happened.
|
|
159
|
+
# Requires ads:write.
|
|
160
|
+
def activate_multi(campaign_ids, confirm_budget_amount)
|
|
161
|
+
@client.request(
|
|
162
|
+
"POST", "/ads/campaigns/activate-multi",
|
|
163
|
+
json: {
|
|
164
|
+
"campaign_ids" => campaign_ids.to_a,
|
|
165
|
+
"confirm_budget_amount" => confirm_budget_amount
|
|
166
|
+
},
|
|
167
|
+
retry_on: :rate_limit
|
|
168
|
+
)
|
|
169
|
+
end
|
|
170
|
+
|
|
171
|
+
# POST /ads/campaigns/{id}/pause - pause a campaign (also while in
|
|
172
|
+
# review). Requires ads:write.
|
|
173
|
+
def pause(campaign_id)
|
|
174
|
+
@client.request("POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/pause")
|
|
175
|
+
end
|
|
176
|
+
|
|
177
|
+
# POST /ads/campaigns/{id}/resume - resume a paused campaign: it STARTS
|
|
178
|
+
# REAL AD SPEND again. Show the person the budget and get their yes
|
|
179
|
+
# first. Not retried after a 5xx, a timeout or a lost connection: read
|
|
180
|
+
# the campaign with get to see what happened. Requires ads:write.
|
|
181
|
+
def resume(campaign_id)
|
|
182
|
+
@client.request(
|
|
183
|
+
"POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/resume",
|
|
184
|
+
retry_on: :rate_limit
|
|
185
|
+
)
|
|
186
|
+
end
|
|
187
|
+
|
|
188
|
+
# DELETE /ads/campaigns/{id} - delete a campaign on the network too. A
|
|
189
|
+
# campaign that spent is archived: its spend stays in the totals.
|
|
190
|
+
# Requires ads:write.
|
|
191
|
+
def delete(campaign_id)
|
|
192
|
+
@client.request("DELETE", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
|
|
193
|
+
end
|
|
194
|
+
|
|
195
|
+
# GET /ads/overview - accounts, campaigns per status and total spend.
|
|
196
|
+
# Requires ads:read.
|
|
197
|
+
def overview
|
|
198
|
+
@client.request("GET", "/ads/overview")
|
|
199
|
+
end
|
|
200
|
+
|
|
201
|
+
# GET /ads/suggestions - organic posts that do better than the
|
|
202
|
+
# workspace median: boost candidates. Read-only. Requires ads:read.
|
|
203
|
+
def suggestions
|
|
204
|
+
@client.request("GET", "/ads/suggestions")
|
|
205
|
+
end
|
|
206
|
+
|
|
207
|
+
# POST /ads/research/keywords - keyword ideas from seed keywords (up to
|
|
208
|
+
# 20), a url or both, through the connected Google Ads account. country
|
|
209
|
+
# defaults to "US", language to "en", limit is 1..500 (default 100);
|
|
210
|
+
# ad_account_id only when the workspace has more than one Google Ads
|
|
211
|
+
# account. Read-only and free. Requires ads:read.
|
|
212
|
+
def research_keywords(keywords: nil, url: nil, country: nil, language: nil, limit: nil,
|
|
213
|
+
ad_account_id: nil)
|
|
214
|
+
body = Internal.drop_nil(
|
|
215
|
+
{
|
|
216
|
+
"keywords" => keywords&.to_a,
|
|
217
|
+
"url" => url,
|
|
218
|
+
"country" => country,
|
|
219
|
+
"language" => language,
|
|
220
|
+
"limit" => limit,
|
|
221
|
+
"ad_account_id" => ad_account_id
|
|
222
|
+
}
|
|
223
|
+
)
|
|
224
|
+
@client.request("POST", "/ads/research/keywords", json: body)
|
|
225
|
+
end
|
|
226
|
+
|
|
227
|
+
# POST /ads/research/keywords/metrics - search numbers for an exact
|
|
228
|
+
# keyword list. Read-only. Requires ads:read.
|
|
229
|
+
def keyword_metrics(keywords:, country: nil, language: nil, ad_account_id: nil)
|
|
230
|
+
body = Internal.drop_nil(
|
|
231
|
+
{
|
|
232
|
+
"keywords" => keywords.to_a,
|
|
233
|
+
"country" => country,
|
|
234
|
+
"language" => language,
|
|
235
|
+
"ad_account_id" => ad_account_id
|
|
236
|
+
}
|
|
237
|
+
)
|
|
238
|
+
@client.request("POST", "/ads/research/keywords/metrics", json: body)
|
|
239
|
+
end
|
|
240
|
+
end
|
|
241
|
+
|
|
242
|
+
# "Create an ad" drafts: one campaign per network in platforms, each with
|
|
243
|
+
# the same ads. A draft never spends; launch starts it.
|
|
244
|
+
class AdDrafts
|
|
245
|
+
def initialize(client)
|
|
246
|
+
@client = client
|
|
247
|
+
end
|
|
248
|
+
|
|
249
|
+
# GET /ads/drafts/defaults - suggested countries (where the Instagram
|
|
250
|
+
# followers are), the currency and the workspace's ad account per
|
|
251
|
+
# network. Requires ads:read.
|
|
252
|
+
def defaults
|
|
253
|
+
@client.request("GET", "/ads/drafts/defaults")
|
|
254
|
+
end
|
|
255
|
+
|
|
256
|
+
# POST /ads/drafts - save a new ad as a draft group. It needs no ad
|
|
257
|
+
# account and spends nothing.
|
|
258
|
+
#
|
|
259
|
+
# objective is "traffic", "engagement", "awareness" or "video_views".
|
|
260
|
+
# platforms lists network keys ("meta", "pinterest", "tiktok",
|
|
261
|
+
# "linkedin", "x", "google") or { "platform" => ..., "budget_amount" =>
|
|
262
|
+
# ..., "ad_account_id" => ... } per network. budget is the daily amount
|
|
263
|
+
# per network, { "amount" => 10, "currency" => "EUR" }. schedule is
|
|
264
|
+
# { "duration_days" => 7 } (nil runs until it is stopped). targeting
|
|
265
|
+
# needs "countries"; "automatic_audience" => true lets the network find
|
|
266
|
+
# the audience. Each of ads has "media", "primary_text", "link" and
|
|
267
|
+
# optionally "headline", "description", "cta", "primary_text_b" (an A/B
|
|
268
|
+
# test) and, on Meta, "placement_media" => { "stories_reels" => {...} }
|
|
269
|
+
# (an upright 9:16 file for Stories and Reels).
|
|
270
|
+
#
|
|
271
|
+
# Read ads.capabilities first for what each network accepts. The answer
|
|
272
|
+
# carries review_url (the builder in the dashboard) and per network
|
|
273
|
+
# readiness. Requires ads:write.
|
|
274
|
+
def create(objective:, platforms:, budget:, targeting:, ads:, name: nil, schedule: nil)
|
|
275
|
+
body = draft_body(
|
|
276
|
+
objective: objective, platforms: platforms, budget: budget,
|
|
277
|
+
targeting: targeting, ads: ads, name: name, schedule: schedule
|
|
278
|
+
)
|
|
279
|
+
@client.request("POST", "/ads/drafts", json: body)
|
|
280
|
+
end
|
|
281
|
+
|
|
282
|
+
# GET /ads/drafts/{group_id} - one draft group. Requires ads:read.
|
|
283
|
+
def get(group_id)
|
|
284
|
+
@client.request("GET", "/ads/drafts/#{Internal.path_segment(group_id)}")
|
|
285
|
+
end
|
|
286
|
+
|
|
287
|
+
# PUT /ads/drafts/{group_id} - replace the draft with the full body
|
|
288
|
+
# (the same fields as create). Networks that already started are left
|
|
289
|
+
# alone (campaigns[].editable). Requires ads:write.
|
|
290
|
+
def update(group_id, objective:, platforms:, budget:, targeting:, ads:, name: nil,
|
|
291
|
+
schedule: nil)
|
|
292
|
+
body = draft_body(
|
|
293
|
+
objective: objective, platforms: platforms, budget: budget,
|
|
294
|
+
targeting: targeting, ads: ads, name: name, schedule: schedule
|
|
295
|
+
)
|
|
296
|
+
@client.request("PUT", "/ads/drafts/#{Internal.path_segment(group_id)}", json: body)
|
|
297
|
+
end
|
|
298
|
+
|
|
299
|
+
# DELETE /ads/drafts/{group_id} - delete a draft group that never
|
|
300
|
+
# started. Requires ads:write.
|
|
301
|
+
def delete(group_id)
|
|
302
|
+
@client.request("DELETE", "/ads/drafts/#{Internal.path_segment(group_id)}")
|
|
303
|
+
end
|
|
304
|
+
|
|
305
|
+
# POST /ads/drafts/{group_id}/account - set the ad account of one
|
|
306
|
+
# network in the draft (from ads.list_accounts, same network). Requires
|
|
307
|
+
# ads:write.
|
|
308
|
+
def attach_account(group_id, platform:, ad_account_id:)
|
|
309
|
+
@client.request(
|
|
310
|
+
"POST", "/ads/drafts/#{Internal.path_segment(group_id)}/account",
|
|
311
|
+
json: { "platform" => platform, "ad_account_id" => ad_account_id }
|
|
312
|
+
)
|
|
313
|
+
end
|
|
314
|
+
|
|
315
|
+
# POST /ads/drafts/{group_id}/launch - START REAL AD SPEND for every
|
|
316
|
+
# network of the draft that never started.
|
|
317
|
+
#
|
|
318
|
+
# Show the person the daily amount per network and get their yes first,
|
|
319
|
+
# then pass it as confirm_budget_amount (or per campaign id as
|
|
320
|
+
# confirm_budget_amounts). A wrong or missing amount answers 400
|
|
321
|
+
# budget_confirmation_required and writes nothing. The answer is
|
|
322
|
+
# { "data" => { "group" => ..., "results" => [...] } } with a result per
|
|
323
|
+
# network; one failed network never stops the others. Not retried after
|
|
324
|
+
# a 5xx, a timeout or a lost connection: read the draft with get to see
|
|
325
|
+
# what started. Requires ads:write.
|
|
326
|
+
def launch(group_id, confirm_budget_amount: nil, confirm_budget_amounts: nil)
|
|
327
|
+
body = Internal.drop_nil(
|
|
328
|
+
{
|
|
329
|
+
"confirm_budget_amount" => confirm_budget_amount,
|
|
330
|
+
"confirm_budget_amounts" => confirm_budget_amounts
|
|
331
|
+
}
|
|
332
|
+
)
|
|
333
|
+
@client.request(
|
|
334
|
+
"POST", "/ads/drafts/#{Internal.path_segment(group_id)}/launch",
|
|
335
|
+
json: body, retry_on: :rate_limit
|
|
336
|
+
)
|
|
337
|
+
end
|
|
338
|
+
|
|
339
|
+
private
|
|
340
|
+
|
|
341
|
+
def draft_body(objective:, platforms:, budget:, targeting:, ads:, name:, schedule:)
|
|
342
|
+
Internal.drop_nil(
|
|
343
|
+
{
|
|
344
|
+
"name" => name,
|
|
345
|
+
"objective" => objective,
|
|
346
|
+
"platforms" => platforms.to_a,
|
|
347
|
+
"budget" => budget,
|
|
348
|
+
"schedule" => schedule,
|
|
349
|
+
"targeting" => targeting,
|
|
350
|
+
"ads" => ads.to_a
|
|
351
|
+
}
|
|
352
|
+
)
|
|
353
|
+
end
|
|
354
|
+
end
|
|
355
|
+
end
|
|
356
|
+
end
|
|
@@ -73,9 +73,22 @@ module OmniSocials
|
|
|
73
73
|
# 15 per 15 minutes and 450 a day; an answer over a cap waits in a
|
|
74
74
|
# queue ("queued") for up to an hour.
|
|
75
75
|
#
|
|
76
|
+
# Follow first (Instagram only): actions "follow_gate" => { "enabled"
|
|
77
|
+
# => true, "first_message" => { "text", "button" }, "not_following" =>
|
|
78
|
+
# { "text", "button" } } sends the link (the "dm" text) only to people
|
|
79
|
+
# who follow the account. A comment gets the first message as the
|
|
80
|
+
# private reply, with one button; a tap makes OmniSocials ask
|
|
81
|
+
# Instagram whether the person follows. A follower gets the link,
|
|
82
|
+
# anyone else gets the not_following message with its button, and
|
|
83
|
+
# every later tap checks again. A DM or a story reply is checked at
|
|
84
|
+
# once. When Instagram gives no answer the link goes out anyway.
|
|
85
|
+
# Texts hold 640 characters, buttons 20; a text or button left out is
|
|
86
|
+
# the default. nil or false turns it off. The response carries the
|
|
87
|
+
# gate with its texts (nil on Facebook and X) and stats "followed".
|
|
88
|
+
#
|
|
76
89
|
# Requires the automations:write scope (opt-in on the API key).
|
|
77
|
-
# Errors: 400 validation_error, 400
|
|
78
|
-
# post_not_facebook, 400 post_required, 404 post_not_found, 404
|
|
90
|
+
# Errors: 400 validation_error, 400 follow_gate_instagram_only, 400
|
|
91
|
+
# post_not_instagram, 400 post_not_facebook, 400 post_required, 404 post_not_found, 404
|
|
79
92
|
# instagram_media_not_found, 404 facebook_post_not_found, 409
|
|
80
93
|
# instagram_not_connected, 409 instagram_needs_reauth, 409
|
|
81
94
|
# facebook_not_connected, 409 facebook_needs_reauth, 409
|
|
@@ -99,8 +112,10 @@ module OmniSocials
|
|
|
99
112
|
# kinds, the scope and the match; a new actions "dm" "text" keeps the
|
|
100
113
|
# public reply; limits: { "stop_at" => ... } keeps max_sends.
|
|
101
114
|
# "public_reply" => { "enabled" => false } or { "variations" => [] }
|
|
102
|
-
# turns the public reply off;
|
|
103
|
-
#
|
|
115
|
+
# turns the public reply off; "follow_gate" => { "enabled" => false }
|
|
116
|
+
# 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
|
|
104
119
|
# post_id / instagram_media_id / facebook_post_id moves the automation
|
|
105
120
|
# to that post. The platform cannot change: a platform other than the
|
|
106
121
|
# automation's is a 400 platform_immutable. status: "active" on an X
|
|
@@ -128,9 +143,10 @@ module OmniSocials
|
|
|
128
143
|
# GET /automations/{id}/events - the automation's activity: one event
|
|
129
144
|
# per person it answered, skipped or failed on. outcome filters on
|
|
130
145
|
# "sent", "skipped", "failed", "pending", "queued" (waits for a free
|
|
131
|
-
# slot under the send cap, out within the hour)
|
|
132
|
-
# person replied STOP on X)
|
|
133
|
-
#
|
|
146
|
+
# slot under the send cap, out within the hour), "opted_out" (the
|
|
147
|
+
# person replied STOP on X) or "waiting" (Follow first: asked to
|
|
148
|
+
# follow, the link goes out after the follow); limit is 1..100
|
|
149
|
+
# (default 25), offset skips. Requires the automations:read scope.
|
|
134
150
|
#
|
|
135
151
|
# The response is not the plain list envelope: { "data" => [...],
|
|
136
152
|
# "counts" => { "sent" => 12, "skipped" => 3 }, "pagination" => {...} },
|
|
@@ -138,10 +154,12 @@ module OmniSocials
|
|
|
138
154
|
# events is left out). Each event carries kind ("comment", "dm",
|
|
139
155
|
# "story_reply"), outcome, reason / reason_label (X adds the skip
|
|
140
156
|
# reasons "dms_closed", "no_credits", "opted_out" and
|
|
141
|
-
# "automation_off"), person (id,
|
|
157
|
+
# "automation_off"; Follow first adds "already_waiting"), person (id,
|
|
142
158
|
# username; on Facebook the person's name, since Facebook has no
|
|
143
159
|
# @handle), trigger_id, trigger_text, message (the DM sent),
|
|
144
|
-
# public_reply, platform_message_id,
|
|
160
|
+
# public_reply, platform_message_id, follow_gate (Follow first:
|
|
161
|
+
# { "state" => "waiting" | "done", "asked_at", "taps", "followed",
|
|
162
|
+
# "checked", "after_ask" }, else nil), created_at and sent_at.
|
|
145
163
|
def list_events(automation_id, outcome: nil, limit: nil, offset: nil)
|
|
146
164
|
@client.request(
|
|
147
165
|
"GET", "/automations/#{automation_id}/events",
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniSocials
|
|
4
|
+
module Resources
|
|
5
|
+
# Feature requests resource: requests to the OmniSocials team, for the
|
|
6
|
+
# person who owns the key (their name and email are stored with it so
|
|
7
|
+
# the team can answer). The person sees them in OmniSocials (Settings,
|
|
8
|
+
# Request a feature) and gets an email when the status changes. No scope
|
|
9
|
+
# needed.
|
|
10
|
+
#
|
|
11
|
+
# A request is { "id", "title", "summary", "status" (open, in_progress,
|
|
12
|
+
# completed, declined), "team_answer", "team_replies" => [{ "message",
|
|
13
|
+
# "created_at" }], "votes_count", "limit_id", "platform", "area",
|
|
14
|
+
# "source", "created_at", "updated_at", "completed_at" }.
|
|
15
|
+
class FeatureRequests
|
|
16
|
+
def initialize(client)
|
|
17
|
+
@client = client
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
# POST /feature-requests - send a request. Send it only when the
|
|
21
|
+
# person asked for it.
|
|
22
|
+
#
|
|
23
|
+
# summary: (10 to 1000 characters) says what the person wants to do
|
|
24
|
+
# and why; title: (at most 120) is made from it when left out.
|
|
25
|
+
# limit_id: is the "id" of the limits.list entry the request is about.
|
|
26
|
+
# Returns { "outcome", "data" }: "outcome" is "created" (a new
|
|
27
|
+
# request), "voted" (a vote added to the organisation's open request
|
|
28
|
+
# for the same gap) or "already_requested" (this person already has an
|
|
29
|
+
# open request for it; "data" is that request).
|
|
30
|
+
#
|
|
31
|
+
# Errors: 400 invalid_summary / invalid_title / invalid_platform /
|
|
32
|
+
# invalid_area / unknown_limit; 409 not_requestable (a platform rule or
|
|
33
|
+
# a choice of OmniSocials: the entry is in error.body["error"]["limit"],
|
|
34
|
+
# nothing was stored); 429 too_many_requests (10 an hour per person).
|
|
35
|
+
def create(summary:, title: nil, platform: nil, area: nil, limit_id: nil)
|
|
36
|
+
body = Internal.drop_nil(
|
|
37
|
+
{
|
|
38
|
+
"summary" => summary,
|
|
39
|
+
"title" => title,
|
|
40
|
+
"platform" => platform,
|
|
41
|
+
"area" => area,
|
|
42
|
+
"limit_id" => limit_id
|
|
43
|
+
}
|
|
44
|
+
)
|
|
45
|
+
@client.request("POST", "/feature-requests", json: body)
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
# GET /feature-requests - the person's own requests, newest first, at
|
|
49
|
+
# most 50: { "data" => [FeatureRequest] }.
|
|
50
|
+
def list
|
|
51
|
+
@client.request("GET", "/feature-requests")
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
# GET /feature-requests/{id} - one request with its status and the
|
|
55
|
+
# team's replies. Errors: 400 invalid_id, 404 not_found.
|
|
56
|
+
def get(request_id)
|
|
57
|
+
@client.request("GET", "/feature-requests/#{request_id}")
|
|
58
|
+
end
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
end
|
|
@@ -193,8 +193,9 @@ module OmniSocials
|
|
|
193
193
|
)
|
|
194
194
|
end
|
|
195
195
|
|
|
196
|
-
# DELETE /inbox/messages/{id} - delete a comment
|
|
197
|
-
#
|
|
196
|
+
# DELETE /inbox/messages/{id} - delete a comment on one of the user's
|
|
197
|
+
# posts, on the platform and from the inbox: a comment someone left, or
|
|
198
|
+
# one of the user's own replies (direction "outgoing"). Facebook,
|
|
198
199
|
# Instagram and TikTok comments only: YouTube's API does not let a
|
|
199
200
|
# channel delete other people's comments, hide those instead (`hide`).
|
|
200
201
|
# Replies under the deleted comment go with it (the platforms cascade
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniSocials
|
|
4
|
+
module Resources
|
|
5
|
+
# Limits resource: what OmniSocials cannot do, why, and what to do
|
|
6
|
+
# instead (platform rules, features not built yet, features that work in
|
|
7
|
+
# the OmniSocials app only).
|
|
8
|
+
#
|
|
9
|
+
# Read it before you tell a person that something is not possible, so
|
|
10
|
+
# you can give the reason ("says") and the way around it ("instead").
|
|
11
|
+
# When the person still wants a "requestable" entry, send it with
|
|
12
|
+
# feature_requests.create(summary: ..., limit_id: ...). No scope needed:
|
|
13
|
+
# every key may call it.
|
|
14
|
+
class Limits
|
|
15
|
+
def initialize(client)
|
|
16
|
+
@client = client
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# GET /limits - the things OmniSocials cannot do.
|
|
20
|
+
#
|
|
21
|
+
# platform: keeps the entries for one platform (entries for every
|
|
22
|
+
# channel stay in); area: is one of posts, media, inbox, analytics,
|
|
23
|
+
# automations, accounts, ads, team, other. Returns
|
|
24
|
+
# { "data" => [Limit], "kinds" => { kind => label } }; a limit is
|
|
25
|
+
# { "id", "kind", "kind_label", "area", "platforms", "title", "says",
|
|
26
|
+
# "instead", "requestable" }. "kind" is platform, by_design, not_built,
|
|
27
|
+
# beta, dashboard_only or needs_setup; "requestable" is false for
|
|
28
|
+
# platform and by_design.
|
|
29
|
+
#
|
|
30
|
+
# Errors: 400 invalid_platform / invalid_area.
|
|
31
|
+
def list(platform: nil, area: nil)
|
|
32
|
+
@client.request("GET", "/limits", query: { "platform" => platform, "area" => area })
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
end
|
|
@@ -21,15 +21,21 @@ module OmniSocials
|
|
|
21
21
|
# GET /posts - list posts (status: draft, in_approval, scheduled, posting,
|
|
22
22
|
# posted, failed, warning; in_approval = waiting for a reviewer in an
|
|
23
23
|
# approval workflow).
|
|
24
|
+
# start_date / end_date keep posts whose schedule_at falls in the
|
|
25
|
+
# period, both inclusive: "YYYY-MM-DD" (a UTC day), "YYYY-MM" (a month)
|
|
26
|
+
# or an ISO 8601 datetime. With a range the posts come in calendar order
|
|
27
|
+
# (earliest first).
|
|
24
28
|
# tag (a tag id or name, or an Array of them) keeps the posts with any
|
|
25
29
|
# of those tags; an unknown tag is a 404 tag_not_found. Every post
|
|
26
30
|
# carries "tags" (its tags) and "trial_reel" ({ "strategy" =>
|
|
27
31
|
# "MANUAL" | "SS_PERFORMANCE" } for an Instagram Trial Reel, else nil).
|
|
28
|
-
def list(status: nil, limit: nil, offset: nil,
|
|
32
|
+
def list(status: nil, limit: nil, offset: nil, start_date: nil, end_date: nil,
|
|
33
|
+
tag: nil)
|
|
29
34
|
@client.request(
|
|
30
35
|
"GET", "/posts",
|
|
31
36
|
query: {
|
|
32
37
|
"status" => status, "limit" => limit, "offset" => offset,
|
|
38
|
+
"start_date" => start_date, "end_date" => end_date,
|
|
33
39
|
"tag" => Tags.tag_query(tag)
|
|
34
40
|
}
|
|
35
41
|
)
|
|
@@ -166,7 +172,9 @@ module OmniSocials
|
|
|
166
172
|
# "..." }, "public_reply" => { "enabled" => true, "variations" =>
|
|
167
173
|
# [...] } }, "limits" => { "max_sends" => 500 }, "platforms" =>
|
|
168
174
|
# ["instagram", "facebook"] } (see automations.create for the
|
|
169
|
-
# fields
|
|
175
|
+
# fields, also the actions "follow_gate", Follow first, which applies
|
|
176
|
+
# to the Instagram automation only). "platforms" makes one automation
|
|
177
|
+
# per listed channel; each
|
|
170
178
|
# must be a channel of the post. Without it: Instagram when the post
|
|
171
179
|
# goes there, else Facebook. Needs the automations:write scope on the
|
|
172
180
|
# key (403 insufficient_scope, checked before anything else); a bad
|
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
module OmniSocials
|
|
4
4
|
module Resources
|
|
5
5
|
# Webhooks resource: manage event subscriptions (post.scheduled,
|
|
6
|
-
# post.published, post.failed, post.approved, post.rejected
|
|
6
|
+
# post.published, post.failed, post.approved, post.rejected, and
|
|
7
|
+
# ad.status_changed for ad campaigns).
|
|
7
8
|
#
|
|
8
9
|
# For verifying incoming deliveries, see OmniSocials::Webhooks.verify.
|
|
9
10
|
class Webhooks
|
|
@@ -25,8 +26,11 @@ module OmniSocials
|
|
|
25
26
|
#
|
|
26
27
|
# `url` must be HTTPS. `events` is a non-empty subset of
|
|
27
28
|
# post.scheduled, post.published, post.failed, post.approved,
|
|
28
|
-
# post.rejected. The
|
|
29
|
-
#
|
|
29
|
+
# post.rejected and ad.status_changed. The `data` of an
|
|
30
|
+
# ad.status_changed delivery is the campaign, not a post: campaign_id,
|
|
31
|
+
# workspace_id, name, platform, campaign_type, status, previous_status,
|
|
32
|
+
# external_campaign_id and budget. The signing `secret` is only
|
|
33
|
+
# returned once, in this response - store it.
|
|
30
34
|
def create(url:, events:)
|
|
31
35
|
@client.request(
|
|
32
36
|
"POST", "/webhooks",
|
data/lib/omnisocials/version.rb
CHANGED
data/lib/omnisocials.rb
CHANGED
|
@@ -28,8 +28,11 @@ require_relative "omnisocials/resources/audio"
|
|
|
28
28
|
require_relative "omnisocials/resources/locations"
|
|
29
29
|
require_relative "omnisocials/resources/pinterest"
|
|
30
30
|
require_relative "omnisocials/resources/automations"
|
|
31
|
+
require_relative "omnisocials/resources/ads"
|
|
31
32
|
require_relative "omnisocials/resources/inbox"
|
|
32
33
|
require_relative "omnisocials/resources/webhooks"
|
|
34
|
+
require_relative "omnisocials/resources/limits"
|
|
35
|
+
require_relative "omnisocials/resources/feature_requests"
|
|
33
36
|
require_relative "omnisocials/client"
|
|
34
37
|
|
|
35
38
|
module OmniSocials
|
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.
|
|
4
|
+
version: 0.15.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-
|
|
11
|
+
date: 2026-11-05 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,
|
|
@@ -26,13 +26,16 @@ files:
|
|
|
26
26
|
- lib/omnisocials/errors.rb
|
|
27
27
|
- lib/omnisocials/internal.rb
|
|
28
28
|
- lib/omnisocials/resources/accounts.rb
|
|
29
|
+
- lib/omnisocials/resources/ads.rb
|
|
29
30
|
- lib/omnisocials/resources/analytics.rb
|
|
30
31
|
- lib/omnisocials/resources/approval_workflows.rb
|
|
31
32
|
- lib/omnisocials/resources/audio.rb
|
|
32
33
|
- lib/omnisocials/resources/automations.rb
|
|
34
|
+
- lib/omnisocials/resources/feature_requests.rb
|
|
33
35
|
- lib/omnisocials/resources/folders.rb
|
|
34
36
|
- lib/omnisocials/resources/hashtag_sets.rb
|
|
35
37
|
- lib/omnisocials/resources/inbox.rb
|
|
38
|
+
- lib/omnisocials/resources/limits.rb
|
|
36
39
|
- lib/omnisocials/resources/locations.rb
|
|
37
40
|
- lib/omnisocials/resources/media.rb
|
|
38
41
|
- lib/omnisocials/resources/pinterest.rb
|