omnisocials 0.13.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 +143 -3
- data/lib/omnisocials/client.rb +18 -6
- data/lib/omnisocials/internal.rb +7 -0
- data/lib/omnisocials/resources/ads.rb +356 -0
- data/lib/omnisocials/resources/analytics.rb +34 -3
- 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 +43 -12
- data/lib/omnisocials/resources/tags.rb +86 -0
- data/lib/omnisocials/resources/webhooks.rb +7 -3
- data/lib/omnisocials/version.rb +1 -1
- data/lib/omnisocials.rb +4 -0
- metadata +6 -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
|
|
|
@@ -425,6 +441,37 @@ client.posts.create(
|
|
|
425
441
|
)
|
|
426
442
|
```
|
|
427
443
|
|
|
444
|
+
## Post tags
|
|
445
|
+
|
|
446
|
+
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.
|
|
447
|
+
|
|
448
|
+
```ruby
|
|
449
|
+
tag = client.tags.create(name: "Question", color: "teal") # color is optional
|
|
450
|
+
client.tags.list
|
|
451
|
+
client.tags.update(tag["data"]["id"], name: "Question hook")
|
|
452
|
+
client.tags.delete(tag["data"]["id"]) # { "data" => { "tag" => ..., "posts_untagged" => 4 } }
|
|
453
|
+
|
|
454
|
+
# Tag a post: ids or names, a new name becomes a tag (at most 20 per post)
|
|
455
|
+
client.posts.create(content: "Would you post this?", channels: ["instagram"], tags: ["Question"])
|
|
456
|
+
client.posts.update("1024", tags: ["Question", "Talking head"]) # replaces; tags: nil or [] removes all
|
|
457
|
+
|
|
458
|
+
# Up to 500 posts at once, published ones included: add, remove or set (replace)
|
|
459
|
+
result = client.tags.apply(post_ids: ["1024", "1025"], add: ["Question"], remove: ["Listicle"])
|
|
460
|
+
puts result["data"]["updated"], result["data"]["not_found"].inspect
|
|
461
|
+
|
|
462
|
+
# Filter by tag (an id or name, or an Array: posts with any of them)
|
|
463
|
+
client.posts.list(tag: "Question")
|
|
464
|
+
client.analytics.overview(period: "30d", tag: ["Question", "Talking head"])
|
|
465
|
+
|
|
466
|
+
# How each tag did against your normal (default: the last 90 days)
|
|
467
|
+
compare = client.analytics.tags(start_date: "2026-08-01", end_date: "2026-10-31")
|
|
468
|
+
compare["data"]["tags"].each do |row|
|
|
469
|
+
puts "#{row["tag"]["name"]} #{row["vs_normal"]} #{row["enough_posts"]}" # vs_normal 0.38 = 38% above
|
|
470
|
+
end
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
`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`.
|
|
474
|
+
|
|
428
475
|
## Accounts
|
|
429
476
|
|
|
430
477
|
```ruby
|
|
@@ -544,6 +591,7 @@ client.inbox.reply(conversation_id, text: "Thanks for reaching out!")
|
|
|
544
591
|
message_id = messages["data"][0]["id"]
|
|
545
592
|
client.inbox.hide(message_id) # hide
|
|
546
593
|
client.inbox.hide(message_id, hide: false) # unhide
|
|
594
|
+
# Delete a comment, or one of your own replies (Facebook, Instagram, TikTok).
|
|
547
595
|
client.inbox.delete_message(message_id)
|
|
548
596
|
|
|
549
597
|
# Like a comment as the Page or account (Facebook, LinkedIn Page, TikTok).
|
|
@@ -600,9 +648,68 @@ end
|
|
|
600
648
|
|
|
601
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.
|
|
602
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
|
+
|
|
603
710
|
## Webhooks
|
|
604
711
|
|
|
605
|
-
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`.
|
|
606
713
|
|
|
607
714
|
```ruby
|
|
608
715
|
webhook = client.webhooks.create(
|
|
@@ -684,6 +791,39 @@ run app
|
|
|
684
791
|
|
|
685
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.
|
|
686
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
|
+
|
|
687
827
|
## Error handling
|
|
688
828
|
|
|
689
829
|
Non-2xx responses raise typed exceptions with `status`, `code`, `message`, and the parsed `body`:
|
|
@@ -714,7 +854,7 @@ The API allows **100 requests per minute** per API key. Every response includes
|
|
|
714
854
|
|
|
715
855
|
## Retries and timeouts
|
|
716
856
|
|
|
717
|
-
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:
|
|
718
858
|
|
|
719
859
|
```ruby
|
|
720
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
|
|
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
|
|
@@ -90,6 +92,7 @@ module OmniSocials
|
|
|
90
92
|
@media = Resources::Media.new(self)
|
|
91
93
|
@folders = Resources::Folders.new(self)
|
|
92
94
|
@hashtag_sets = Resources::HashtagSets.new(self)
|
|
95
|
+
@tags = Resources::Tags.new(self)
|
|
93
96
|
@approval_workflows = Resources::ApprovalWorkflows.new(self)
|
|
94
97
|
@accounts = Resources::Accounts.new(self)
|
|
95
98
|
@analytics = Resources::Analytics.new(self)
|
|
@@ -97,8 +100,11 @@ module OmniSocials
|
|
|
97
100
|
@locations = Resources::Locations.new(self)
|
|
98
101
|
@pinterest = Resources::Pinterest.new(self)
|
|
99
102
|
@automations = Resources::Automations.new(self)
|
|
103
|
+
@ads = Resources::Ads.new(self)
|
|
100
104
|
@inbox = Resources::Inbox.new(self)
|
|
101
105
|
@webhooks = Resources::Webhooks.new(self)
|
|
106
|
+
@limits = Resources::Limits.new(self)
|
|
107
|
+
@feature_requests = Resources::FeatureRequests.new(self)
|
|
102
108
|
end
|
|
103
109
|
|
|
104
110
|
# GET /health - API health check (no scopes required).
|
|
@@ -112,7 +118,11 @@ module OmniSocials
|
|
|
112
118
|
# non-JSON responses, or nil for 204. Raises an OmniSocials::APIError
|
|
113
119
|
# subclass on non-2xx and OmniSocials::APIConnectionError when no
|
|
114
120
|
# response was ever received.
|
|
115
|
-
|
|
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)
|
|
116
126
|
uri = build_uri(path, query)
|
|
117
127
|
last_error = nil
|
|
118
128
|
|
|
@@ -121,13 +131,14 @@ module OmniSocials
|
|
|
121
131
|
response = perform(method, uri, json: json, multipart: multipart)
|
|
122
132
|
rescue *CONNECTION_ERRORS => e
|
|
123
133
|
last_error = e
|
|
124
|
-
|
|
134
|
+
# Not sent again when the call may have started ad spend.
|
|
135
|
+
break if retry_on == :rate_limit || attempt >= max_retries
|
|
125
136
|
|
|
126
137
|
sleep(Internal.backoff_delay(attempt, nil))
|
|
127
138
|
next
|
|
128
139
|
end
|
|
129
140
|
|
|
130
|
-
should_retry, retry_after = retry_info(response)
|
|
141
|
+
should_retry, retry_after = retry_info(response, retry_on)
|
|
131
142
|
if should_retry && attempt < max_retries
|
|
132
143
|
sleep(Internal.backoff_delay(attempt, retry_after))
|
|
133
144
|
next
|
|
@@ -177,9 +188,10 @@ module OmniSocials
|
|
|
177
188
|
http.start { |conn| conn.request(req) }
|
|
178
189
|
end
|
|
179
190
|
|
|
180
|
-
def retry_info(response)
|
|
191
|
+
def retry_info(response, retry_on)
|
|
181
192
|
status = response.code.to_i
|
|
182
|
-
|
|
193
|
+
server_error = RETRY_STATUSES.include?(status) || status >= 500
|
|
194
|
+
if status == 429 || (server_error && retry_on != :rate_limit)
|
|
183
195
|
[true, parse_retry_after(response, Internal.parse_body(response.body))]
|
|
184
196
|
else
|
|
185
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
|
|
@@ -15,7 +15,9 @@ module OmniSocials
|
|
|
15
15
|
|
|
16
16
|
# GET /analytics/posts?ids=a,b,c - bulk metrics for up to 100 posts in
|
|
17
17
|
# one request. `ids` is an Array of post ids (or an already-joined
|
|
18
|
-
# comma-separated String).
|
|
18
|
+
# comma-separated String). Each entry also carries "tags" (the post's
|
|
19
|
+
# tags) and "trial_reel" ({ "strategy" => "MANUAL" | "SS_PERFORMANCE" }
|
|
20
|
+
# for an Instagram Trial Reel, else nil).
|
|
19
21
|
def posts(ids)
|
|
20
22
|
@client.request(
|
|
21
23
|
"GET", "/analytics/posts",
|
|
@@ -24,10 +26,17 @@ module OmniSocials
|
|
|
24
26
|
end
|
|
25
27
|
|
|
26
28
|
# GET /analytics/overview - workspace-wide analytics overview.
|
|
27
|
-
|
|
29
|
+
#
|
|
30
|
+
# tag (a tag id or name, or an Array of them: any of them) keeps the
|
|
31
|
+
# post numbers of the posts with that tag; account numbers stay those
|
|
32
|
+
# of the whole account. An unknown tag is a 404 tag_not_found.
|
|
33
|
+
def overview(period: nil, start_date: nil, end_date: nil, tag: nil)
|
|
28
34
|
@client.request(
|
|
29
35
|
"GET", "/analytics/overview",
|
|
30
|
-
query: {
|
|
36
|
+
query: {
|
|
37
|
+
"period" => period, "start_date" => start_date, "end_date" => end_date,
|
|
38
|
+
"tag" => Tags.tag_query(tag)
|
|
39
|
+
}
|
|
31
40
|
)
|
|
32
41
|
end
|
|
33
42
|
|
|
@@ -49,6 +58,28 @@ module OmniSocials
|
|
|
49
58
|
query: { "platform" => platform, "timezone" => timezone }
|
|
50
59
|
)
|
|
51
60
|
end
|
|
61
|
+
|
|
62
|
+
# GET /analytics/tags - how each tag did against your normal, for the
|
|
63
|
+
# published posts in a period (default the last 90 days).
|
|
64
|
+
#
|
|
65
|
+
# Returns { "data" => { "period", "platform", "min_posts", "tags",
|
|
66
|
+
# "untagged", "normals" } }. Each entry of "tags" is { "tag", "posts",
|
|
67
|
+
# "measured", "median_impressions", "engagement_rate" (percent),
|
|
68
|
+
# "vs_normal" (fraction: 0.38 = 38% above your normal), "best_channel",
|
|
69
|
+
# "enough_posts" }, comparable tags first, best first; "untagged" has
|
|
70
|
+
# the same numbers for the posts without a tag, "normals" the median
|
|
71
|
+
# impressions per channel. platform keeps one channel's numbers;
|
|
72
|
+
# min_posts (1 to 50, default 5) is the measured posts a tag needs
|
|
73
|
+
# before "enough_posts" is true.
|
|
74
|
+
def tags(start_date: nil, end_date: nil, platform: nil, min_posts: nil)
|
|
75
|
+
@client.request(
|
|
76
|
+
"GET", "/analytics/tags",
|
|
77
|
+
query: {
|
|
78
|
+
"start_date" => start_date, "end_date" => end_date,
|
|
79
|
+
"platform" => platform, "min_posts" => min_posts
|
|
80
|
+
}
|
|
81
|
+
)
|
|
82
|
+
end
|
|
52
83
|
end
|
|
53
84
|
end
|
|
54
85
|
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,10 +21,23 @@ 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
|
-
|
|
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).
|
|
28
|
+
# tag (a tag id or name, or an Array of them) keeps the posts with any
|
|
29
|
+
# of those tags; an unknown tag is a 404 tag_not_found. Every post
|
|
30
|
+
# carries "tags" (its tags) and "trial_reel" ({ "strategy" =>
|
|
31
|
+
# "MANUAL" | "SS_PERFORMANCE" } for an Instagram Trial Reel, else nil).
|
|
32
|
+
def list(status: nil, limit: nil, offset: nil, start_date: nil, end_date: nil,
|
|
33
|
+
tag: nil)
|
|
25
34
|
@client.request(
|
|
26
35
|
"GET", "/posts",
|
|
27
|
-
query: {
|
|
36
|
+
query: {
|
|
37
|
+
"status" => status, "limit" => limit, "offset" => offset,
|
|
38
|
+
"start_date" => start_date, "end_date" => end_date,
|
|
39
|
+
"tag" => Tags.tag_query(tag)
|
|
40
|
+
}
|
|
28
41
|
)
|
|
29
42
|
end
|
|
30
43
|
|
|
@@ -159,7 +172,9 @@ module OmniSocials
|
|
|
159
172
|
# "..." }, "public_reply" => { "enabled" => true, "variations" =>
|
|
160
173
|
# [...] } }, "limits" => { "max_sends" => 500 }, "platforms" =>
|
|
161
174
|
# ["instagram", "facebook"] } (see automations.create for the
|
|
162
|
-
# 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
|
|
163
178
|
# must be a channel of the post. Without it: Instagram when the post
|
|
164
179
|
# goes there, else Facebook. Needs the automations:write scope on the
|
|
165
180
|
# key (403 insufficient_scope, checked before anything else); a bad
|
|
@@ -169,6 +184,11 @@ module OmniSocials
|
|
|
169
184
|
# nil, plus "platforms" and "automations", one { "id", "platform",
|
|
170
185
|
# "status" } per channel); each starts listening once the post is
|
|
171
186
|
# live on its channel.
|
|
187
|
+
#
|
|
188
|
+
# tags labels the post with the workspace's own tags (ids or names, at
|
|
189
|
+
# most 20; a name that does not exist yet becomes a new tag) to filter
|
|
190
|
+
# and compare posts in Analytics. Tags never go to a platform. Errors:
|
|
191
|
+
# 404 tag_not_found (an unknown id), 400 invalid_tags / too_many_tags.
|
|
172
192
|
def create(content:, channels: nil, scheduled_at: nil, media_ids: nil,
|
|
173
193
|
media_urls: nil, type: nil, source: nil, link_url: nil,
|
|
174
194
|
link_title: nil, link_description: nil, link_thumbnail_url: nil,
|
|
@@ -180,7 +200,7 @@ module OmniSocials
|
|
|
180
200
|
mastodon: nil, threads: nil, google_business: nil,
|
|
181
201
|
telegram: nil, discord: nil, linkedin_poll: nil,
|
|
182
202
|
approval_workflow_id: nil, draft: nil, media_fit: nil,
|
|
183
|
-
comment_dm_automation: nil)
|
|
203
|
+
comment_dm_automation: nil, tags: nil)
|
|
184
204
|
body = create_body(
|
|
185
205
|
content: content, channels: channels, scheduled_at: scheduled_at,
|
|
186
206
|
media_ids: media_ids, media_urls: media_urls, type: type,
|
|
@@ -196,7 +216,8 @@ module OmniSocials
|
|
|
196
216
|
google_business: google_business, telegram: telegram,
|
|
197
217
|
discord: discord, linkedin_poll: linkedin_poll,
|
|
198
218
|
approval_workflow_id: approval_workflow_id, draft: draft,
|
|
199
|
-
media_fit: media_fit, comment_dm_automation: comment_dm_automation
|
|
219
|
+
media_fit: media_fit, comment_dm_automation: comment_dm_automation,
|
|
220
|
+
tags: tags
|
|
200
221
|
)
|
|
201
222
|
@client.request("POST", "/posts/create", json: body)
|
|
202
223
|
end
|
|
@@ -204,8 +225,8 @@ module OmniSocials
|
|
|
204
225
|
# POST /posts/create-and-publish - create and publish immediately.
|
|
205
226
|
# See #create for the "warnings" array (X link posts, and the
|
|
206
227
|
# "image_fit" entries steered by media_fit), the 402
|
|
207
|
-
# "x_credits_insufficient" credit gate on X link posts
|
|
208
|
-
# comment_dm_automation.
|
|
228
|
+
# "x_credits_insufficient" credit gate on X link posts,
|
|
229
|
+
# comment_dm_automation and tags.
|
|
209
230
|
def create_and_publish(content:, channels: nil, media_ids: nil,
|
|
210
231
|
media_urls: nil, type: nil, source: nil,
|
|
211
232
|
link_url: nil, link_title: nil, link_description: nil,
|
|
@@ -219,7 +240,7 @@ module OmniSocials
|
|
|
219
240
|
threads: nil, google_business: nil,
|
|
220
241
|
telegram: nil, discord: nil, linkedin_poll: nil,
|
|
221
242
|
media_fit: nil,
|
|
222
|
-
comment_dm_automation: nil)
|
|
243
|
+
comment_dm_automation: nil, tags: nil)
|
|
223
244
|
body = create_body(
|
|
224
245
|
content: content, channels: channels, scheduled_at: nil,
|
|
225
246
|
media_ids: media_ids, media_urls: media_urls, type: type,
|
|
@@ -234,7 +255,8 @@ module OmniSocials
|
|
|
234
255
|
x: x, bluesky: bluesky, mastodon: mastodon, threads: threads,
|
|
235
256
|
google_business: google_business, telegram: telegram,
|
|
236
257
|
discord: discord, linkedin_poll: linkedin_poll,
|
|
237
|
-
media_fit: media_fit, comment_dm_automation: comment_dm_automation
|
|
258
|
+
media_fit: media_fit, comment_dm_automation: comment_dm_automation,
|
|
259
|
+
tags: tags
|
|
238
260
|
)
|
|
239
261
|
@client.request("POST", "/posts/create-and-publish", json: body)
|
|
240
262
|
end
|
|
@@ -275,6 +297,11 @@ module OmniSocials
|
|
|
275
297
|
# discord merges into the stored Discord options: a key set to nil
|
|
276
298
|
# removes that option (e.g. discord: { "poll" => nil }), an explicit
|
|
277
299
|
# discord: nil removes every option, and leaving it out keeps them.
|
|
300
|
+
#
|
|
301
|
+
# tags (ids or names, a new name becomes a tag) replaces the post's
|
|
302
|
+
# tags; tags: nil or tags: [] removes them all, and leaving it out
|
|
303
|
+
# keeps them. An update with only tags works on every post, published
|
|
304
|
+
# and failed ones included.
|
|
278
305
|
def update(post_id, content: nil, scheduled_at: nil, channels: nil,
|
|
279
306
|
media_ids: nil, media_urls: nil, type: nil, location_id: nil,
|
|
280
307
|
collaborators: nil, user_tags: nil, pinterest: nil,
|
|
@@ -283,7 +310,8 @@ module OmniSocials
|
|
|
283
310
|
mastodon: nil, threads: nil, google_business: nil,
|
|
284
311
|
telegram: nil, discord: OmniSocials::NOT_GIVEN,
|
|
285
312
|
linkedin_poll: nil, draft: nil, media_fit: nil,
|
|
286
|
-
comment_dm_automation: OmniSocials::NOT_GIVEN
|
|
313
|
+
comment_dm_automation: OmniSocials::NOT_GIVEN,
|
|
314
|
+
tags: OmniSocials::NOT_GIVEN)
|
|
287
315
|
body = Internal.drop_nil(
|
|
288
316
|
{
|
|
289
317
|
"content" => content,
|
|
@@ -318,6 +346,8 @@ module OmniSocials
|
|
|
318
346
|
body["comment_dm_automation"] = comment_dm_automation unless comment_dm_automation.is_a?(NotGiven)
|
|
319
347
|
# Same for discord: an explicit nil removes every Discord option.
|
|
320
348
|
body["discord"] = discord unless discord.is_a?(NotGiven)
|
|
349
|
+
# And for tags: an explicit nil (or []) removes every tag of the post.
|
|
350
|
+
body["tags"] = tags unless tags.is_a?(NotGiven)
|
|
321
351
|
@client.request("PATCH", "/posts/#{post_id}", json: body)
|
|
322
352
|
end
|
|
323
353
|
|
|
@@ -395,7 +425,7 @@ module OmniSocials
|
|
|
395
425
|
threads:, google_business:, linkedin_poll:,
|
|
396
426
|
telegram: nil, discord: nil, approval_workflow_id: nil,
|
|
397
427
|
draft: nil,
|
|
398
|
-
media_fit: nil, comment_dm_automation: nil)
|
|
428
|
+
media_fit: nil, comment_dm_automation: nil, tags: nil)
|
|
399
429
|
Internal.drop_nil(
|
|
400
430
|
{
|
|
401
431
|
"content" => content,
|
|
@@ -434,7 +464,8 @@ module OmniSocials
|
|
|
434
464
|
"approval_workflow_id" => approval_workflow_id,
|
|
435
465
|
"draft" => draft,
|
|
436
466
|
"media_fit" => media_fit,
|
|
437
|
-
"comment_dm_automation" => comment_dm_automation
|
|
467
|
+
"comment_dm_automation" => comment_dm_automation,
|
|
468
|
+
"tags" => tags
|
|
438
469
|
}
|
|
439
470
|
)
|
|
440
471
|
end
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniSocials
|
|
4
|
+
module Resources
|
|
5
|
+
# Tags resource: the workspace's own labels for its posts (a hook style,
|
|
6
|
+
# a format), to filter and compare posts in Analytics. Tags never go to a
|
|
7
|
+
# platform.
|
|
8
|
+
#
|
|
9
|
+
# Set them on a post with tags: on posts.create / create_and_publish /
|
|
10
|
+
# update, in bulk with #apply, filter with tag: on posts.list and
|
|
11
|
+
# analytics.overview, and compare them with analytics.tags. A tag
|
|
12
|
+
# reference is a tag id (Integer or String) or a tag name
|
|
13
|
+
# (case-insensitive); in add / set (and tags: on posts) a name that does
|
|
14
|
+
# not exist yet becomes a new tag.
|
|
15
|
+
class Tags
|
|
16
|
+
# Serialize the tag filter: one id or name, or an Array joined with ",".
|
|
17
|
+
def self.tag_query(tag)
|
|
18
|
+
return nil if tag.nil?
|
|
19
|
+
return tag.map(&:to_s).join(",") if tag.is_a?(Array)
|
|
20
|
+
|
|
21
|
+
tag.to_s
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
def initialize(client)
|
|
25
|
+
@client = client
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
# GET /tags - every tag of the workspace, by name. Each tag is
|
|
29
|
+
# { "id", "name", "color", "created_at" }. Scope posts:read.
|
|
30
|
+
def list
|
|
31
|
+
@client.request("GET", "/tags")
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
# POST /tags - create a tag. `name` is at most 40 characters and unique
|
|
35
|
+
# in the workspace (case-insensitive); `color` is one of blue, green,
|
|
36
|
+
# orange, red, purple, pink, teal, yellow, brown, gray (omit it to get
|
|
37
|
+
# the next colour). At most 200 tags per workspace.
|
|
38
|
+
#
|
|
39
|
+
# Errors: 409 tag_exists (the existing tag is in
|
|
40
|
+
# error.body["error"]["tag"]), 409 tag_limit_reached,
|
|
41
|
+
# 400 invalid_tag_name / invalid_tag_color.
|
|
42
|
+
def create(name:, color: nil)
|
|
43
|
+
@client.request(
|
|
44
|
+
"POST", "/tags",
|
|
45
|
+
json: Internal.drop_nil({ "name" => name, "color" => color })
|
|
46
|
+
)
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# PATCH /tags/{id} - rename or recolour a tag. Only the keys you pass
|
|
50
|
+
# are sent; posts keep the tag. Errors: 404 tag_not_found,
|
|
51
|
+
# 409 tag_exists.
|
|
52
|
+
def update(tag_id, name: nil, color: nil)
|
|
53
|
+
body = Internal.drop_nil({ "name" => name, "color" => color })
|
|
54
|
+
@client.request("PATCH", "/tags/#{tag_id}", json: body)
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
# DELETE /tags/{id} - delete a tag and take it off every post (the
|
|
58
|
+
# posts stay). Returns { "data" => { "tag", "posts_untagged" } }.
|
|
59
|
+
def delete(tag_id)
|
|
60
|
+
@client.request("DELETE", "/tags/#{tag_id}")
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# POST /tags/apply - add, remove or replace the tags of up to 500 posts
|
|
64
|
+
# at once, published ones included.
|
|
65
|
+
#
|
|
66
|
+
# add, remove and set take tag ids or names; a new name in add or set
|
|
67
|
+
# becomes a tag. set replaces a post's tags (set: [] removes them all),
|
|
68
|
+
# add and remove change only the tags you name. Returns
|
|
69
|
+
# { "data" => { "updated", "posts" => [{ "id", "tags" }], "not_found" } };
|
|
70
|
+
# not_found lists the post ids that are not posts of this workspace.
|
|
71
|
+
# Errors: 400 invalid_post_ids / too_many_posts / too_many_tags /
|
|
72
|
+
# invalid_tags, 404 tag_not_found.
|
|
73
|
+
def apply(post_ids:, add: nil, remove: nil, set: nil)
|
|
74
|
+
body = Internal.drop_nil(
|
|
75
|
+
{
|
|
76
|
+
"post_ids" => Array(post_ids).map(&:to_s),
|
|
77
|
+
"add" => add,
|
|
78
|
+
"remove" => remove,
|
|
79
|
+
"set" => set
|
|
80
|
+
}
|
|
81
|
+
)
|
|
82
|
+
@client.request("POST", "/tags/apply", json: body)
|
|
83
|
+
end
|
|
84
|
+
end
|
|
85
|
+
end
|
|
86
|
+
end
|
|
@@ -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
|
@@ -20,6 +20,7 @@ require_relative "omnisocials/resources/posts"
|
|
|
20
20
|
require_relative "omnisocials/resources/media"
|
|
21
21
|
require_relative "omnisocials/resources/folders"
|
|
22
22
|
require_relative "omnisocials/resources/hashtag_sets"
|
|
23
|
+
require_relative "omnisocials/resources/tags"
|
|
23
24
|
require_relative "omnisocials/resources/approval_workflows"
|
|
24
25
|
require_relative "omnisocials/resources/accounts"
|
|
25
26
|
require_relative "omnisocials/resources/analytics"
|
|
@@ -27,8 +28,11 @@ require_relative "omnisocials/resources/audio"
|
|
|
27
28
|
require_relative "omnisocials/resources/locations"
|
|
28
29
|
require_relative "omnisocials/resources/pinterest"
|
|
29
30
|
require_relative "omnisocials/resources/automations"
|
|
31
|
+
require_relative "omnisocials/resources/ads"
|
|
30
32
|
require_relative "omnisocials/resources/inbox"
|
|
31
33
|
require_relative "omnisocials/resources/webhooks"
|
|
34
|
+
require_relative "omnisocials/resources/limits"
|
|
35
|
+
require_relative "omnisocials/resources/feature_requests"
|
|
32
36
|
require_relative "omnisocials/client"
|
|
33
37
|
|
|
34
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
|
+
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,17 +26,21 @@ 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
|
|
39
42
|
- lib/omnisocials/resources/posts.rb
|
|
43
|
+
- lib/omnisocials/resources/tags.rb
|
|
40
44
|
- lib/omnisocials/resources/webhooks.rb
|
|
41
45
|
- lib/omnisocials/version.rb
|
|
42
46
|
- lib/omnisocials/webhooks.rb
|