omnisocials 0.14.0 → 0.16.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 +176 -9
- data/lib/omnisocials/client.rb +17 -6
- data/lib/omnisocials/internal.rb +7 -0
- data/lib/omnisocials/resources/ads.rb +1817 -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/media.rb +3 -1
- data/lib/omnisocials/resources/posts.rb +64 -15
- data/lib/omnisocials/resources/webhooks.rb +46 -8
- data/lib/omnisocials/version.rb +1 -1
- data/lib/omnisocials/webhooks.rb +9 -1
- data/lib/omnisocials.rb +3 -0
- metadata +5 -2
|
@@ -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
|
|
@@ -52,7 +52,9 @@ module OmniSocials
|
|
|
52
52
|
# POST /media/upload-from-url - server-side fetch, up to 1GB.
|
|
53
53
|
#
|
|
54
54
|
# Files over 100MB are streamed in the background: the response has
|
|
55
|
-
# data["status"] == "processing"; poll get() until it is "ready".
|
|
55
|
+
# data["status"] == "processing"; poll get() until it is "ready". When
|
|
56
|
+
# such a file cannot be queued for processing, the answer is 503
|
|
57
|
+
# "processing_unavailable": send the same request again in a minute.
|
|
56
58
|
def upload_from_url(url:, filename: nil, name: nil, folder: nil, folder_id: nil, pdf_mode: nil)
|
|
57
59
|
body = Internal.drop_nil(
|
|
58
60
|
{
|
|
@@ -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
|
|
@@ -181,6 +189,12 @@ module OmniSocials
|
|
|
181
189
|
# most 20; a name that does not exist yet becomes a new tag) to filter
|
|
182
190
|
# and compare posts in Analytics. Tags never go to a platform. Errors:
|
|
183
191
|
# 404 tag_not_found (an unknown id), 400 invalid_tags / too_many_tags.
|
|
192
|
+
#
|
|
193
|
+
# A media id that is still processing (a large video is checked and
|
|
194
|
+
# converted after upload) answers 409 "media_processing" and nothing is
|
|
195
|
+
# created: wait until media.get(id) says "ready", then send the same
|
|
196
|
+
# request again. A file whose processing failed answers 400
|
|
197
|
+
# "invalid_media": upload it again.
|
|
184
198
|
def create(content:, channels: nil, scheduled_at: nil, media_ids: nil,
|
|
185
199
|
media_urls: nil, type: nil, source: nil, link_url: nil,
|
|
186
200
|
link_title: nil, link_description: nil, link_thumbnail_url: nil,
|
|
@@ -218,7 +232,8 @@ module OmniSocials
|
|
|
218
232
|
# See #create for the "warnings" array (X link posts, and the
|
|
219
233
|
# "image_fit" entries steered by media_fit), the 402
|
|
220
234
|
# "x_credits_insufficient" credit gate on X link posts,
|
|
221
|
-
# comment_dm_automation and
|
|
235
|
+
# comment_dm_automation, tags and the 409 "media_processing" / 400
|
|
236
|
+
# "invalid_media" answers.
|
|
222
237
|
def create_and_publish(content:, channels: nil, media_ids: nil,
|
|
223
238
|
media_urls: nil, type: nil, source: nil,
|
|
224
239
|
link_url: nil, link_title: nil, link_description: nil,
|
|
@@ -294,6 +309,15 @@ module OmniSocials
|
|
|
294
309
|
# tags; tags: nil or tags: [] removes them all, and leaving it out
|
|
295
310
|
# keeps them. An update with only tags works on every post, published
|
|
296
311
|
# and failed ones included.
|
|
312
|
+
#
|
|
313
|
+
# 409 answers, where nothing is changed: "post_publishing" while the
|
|
314
|
+
# post is publishing (status "posting") or a retry publishes one of its
|
|
315
|
+
# channels (poll #get until "published", "warning" or "failed"; an
|
|
316
|
+
# update with only tags still works); "review_required" when changes
|
|
317
|
+
# were requested on the post (approval_status "rejected") and the
|
|
318
|
+
# update would schedule it (it needs a new review: create it again
|
|
319
|
+
# with approval_workflow_id; saving it as a draft works);
|
|
320
|
+
# "media_processing" as on #create.
|
|
297
321
|
def update(post_id, content: nil, scheduled_at: nil, channels: nil,
|
|
298
322
|
media_ids: nil, media_urls: nil, type: nil, location_id: nil,
|
|
299
323
|
collaborators: nil, user_tags: nil, pinterest: nil,
|
|
@@ -343,14 +367,21 @@ module OmniSocials
|
|
|
343
367
|
@client.request("PATCH", "/posts/#{post_id}", json: body)
|
|
344
368
|
end
|
|
345
369
|
|
|
346
|
-
# DELETE /posts/{id} - remove a post from OmniSocials (the live post
|
|
370
|
+
# DELETE /posts/{id} - remove a post from OmniSocials (the live post
|
|
371
|
+
# stays on the platform). Returns nil (204). While the post is
|
|
372
|
+
# publishing (status "posting") or a retry publishes one of its
|
|
373
|
+
# channels, the answer is 409 "post_publishing" and nothing is deleted:
|
|
374
|
+
# poll #get until "published", "warning" or "failed", then delete it.
|
|
347
375
|
def delete(post_id)
|
|
348
376
|
@client.request("DELETE", "/posts/#{post_id}")
|
|
349
377
|
end
|
|
350
378
|
|
|
351
379
|
# POST /posts/{id}/publish - publish a draft or scheduled post now.
|
|
352
380
|
# See #create for the 402 "x_credits_insufficient" credit gate that
|
|
353
|
-
# can also refuse publishing a scheduled X link post.
|
|
381
|
+
# can also refuse publishing a scheduled X link post. A post on which
|
|
382
|
+
# changes were requested in its approval workflow (approval_status
|
|
383
|
+
# "rejected") answers 409 "review_required": it publishes only after a
|
|
384
|
+
# new review (create it again with approval_workflow_id).
|
|
354
385
|
def publish(post_id)
|
|
355
386
|
@client.request("POST", "/posts/#{post_id}/publish")
|
|
356
387
|
end
|
|
@@ -361,32 +392,50 @@ module OmniSocials
|
|
|
361
392
|
# Only the platforms that failed are re-published; platforms that
|
|
362
393
|
# already succeeded are never posted again. Asynchronous: a 200 means
|
|
363
394
|
# the retry is queued - poll `get` for the outcome. Max 3 retries per
|
|
364
|
-
# platform.
|
|
395
|
+
# platform. While another retry runs (a second request, the dashboard,
|
|
396
|
+
# the automatic retry) the answer is 409 "retry_in_progress" and
|
|
397
|
+
# nothing is queued: poll `get` and retry once the post is "failed" or
|
|
398
|
+
# "warning" again.
|
|
365
399
|
def retry(post_id)
|
|
366
400
|
@client.request("POST", "/posts/#{post_id}/retry")
|
|
367
401
|
end
|
|
368
402
|
|
|
369
403
|
# POST /posts/{id}/approve - approve the current step of a post's
|
|
370
404
|
# approval workflow, on behalf of the user who owns this API key. That
|
|
371
|
-
# user must be a listed approver for the workflow's CURRENT step
|
|
405
|
+
# user must be a listed approver for the workflow's CURRENT step:
|
|
372
406
|
# steps approve in order, so an approver on a later step gets a 403
|
|
373
407
|
# "forbidden" error until earlier steps clear. Only works on a post
|
|
374
408
|
# with approval_status "pending". If this is the last step, the post
|
|
375
409
|
# finalizes immediately ("scheduled" or "posting"); otherwise it stays
|
|
376
410
|
# "in_approval" and the next step's approvers are notified.
|
|
377
|
-
|
|
378
|
-
|
|
411
|
+
#
|
|
412
|
+
# Pass step_order: the "current_step" of #get_approval, the step you
|
|
413
|
+
# reviewed. When the review is on another step now (somebody decided
|
|
414
|
+
# since you read it, or a retried call already went through), nothing
|
|
415
|
+
# is approved and the call raises a 409 OmniSocials::APIError with
|
|
416
|
+
# code "step_changed"; err.body["error"]["current_step_order"] is the
|
|
417
|
+
# step the review is on now. Read the approval again before you
|
|
418
|
+
# decide. Without step_order the call approves whatever step is
|
|
419
|
+
# current, so a retry after a timeout can approve the next step too.
|
|
420
|
+
def approve(post_id, step_order: nil)
|
|
421
|
+
body = step_order.nil? ? nil : { "step_order" => step_order }
|
|
422
|
+
@client.request("POST", "/posts/#{post_id}/approve", json: body)
|
|
379
423
|
end
|
|
380
424
|
|
|
381
425
|
# POST /posts/{id}/reject - reject a post's approval workflow, on
|
|
382
426
|
# behalf of the user who owns this API key. Same approver requirement
|
|
383
427
|
# as #approve. Unlike approval, a rejection stops the WHOLE workflow
|
|
384
|
-
# immediately (not just the current step)
|
|
385
|
-
# "rejected". `comment` is optional and, when
|
|
386
|
-
# requester and other approvers in the post's
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
428
|
+
# immediately (not just the current step): the post's status becomes
|
|
429
|
+
# "rejected". `comment` is optional (max 2000 characters) and, when
|
|
430
|
+
# given, is shown to the requester and other approvers in the post's
|
|
431
|
+
# review thread. `step_order` works as on #approve: when the review
|
|
432
|
+
# moved on, nothing is rejected and the call raises a 409
|
|
433
|
+
# "step_changed" error with "current_step_order" in its body.
|
|
434
|
+
def reject(post_id, comment: nil, step_order: nil)
|
|
435
|
+
body = {}
|
|
436
|
+
body["comment"] = comment if comment
|
|
437
|
+
body["step_order"] = step_order unless step_order.nil?
|
|
438
|
+
@client.request("POST", "/posts/#{post_id}/reject", json: body.empty? ? nil : body)
|
|
390
439
|
end
|
|
391
440
|
|
|
392
441
|
# GET /posts/{id}/approval - the approval review of a post: every step
|
|
@@ -3,7 +3,11 @@
|
|
|
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 for ads
|
|
7
|
+
# ad.status_changed, ad.created, ad.updated, ad.review,
|
|
8
|
+
# ad.delivery_issue, campaign.created, campaign.updated,
|
|
9
|
+
# campaign.budget, lead.received, ads.sync_failed, ads.sync_recovered,
|
|
10
|
+
# ads.initial_sync_completed and ad_rule.triggered).
|
|
7
11
|
#
|
|
8
12
|
# For verifying incoming deliveries, see OmniSocials::Webhooks.verify.
|
|
9
13
|
class Webhooks
|
|
@@ -11,12 +15,21 @@ module OmniSocials
|
|
|
11
15
|
@client = client
|
|
12
16
|
end
|
|
13
17
|
|
|
14
|
-
# GET /webhooks - list
|
|
18
|
+
# GET /webhooks - list the webhooks of the key's workspace and the
|
|
19
|
+
# organisation-wide webhooks of its organisation.
|
|
20
|
+
#
|
|
21
|
+
# Every webhook carries "workspace_id": nil for an organisation-wide
|
|
22
|
+
# webhook (made in the OmniSocials dashboard), which receives the
|
|
23
|
+
# events of every workspace of the organisation. A webhook whose
|
|
24
|
+
# creator lost access to the organisation or workspace is switched off
|
|
25
|
+
# automatically: "is_active" is false and "last_failure"["error"] says
|
|
26
|
+
# why.
|
|
15
27
|
def list
|
|
16
28
|
@client.request("GET", "/webhooks")
|
|
17
29
|
end
|
|
18
30
|
|
|
19
|
-
# GET /webhooks/{id} - fetch a
|
|
31
|
+
# GET /webhooks/{id} - fetch a webhook of the key's workspace, or an
|
|
32
|
+
# organisation-wide webhook of its organisation ("workspace_id" nil).
|
|
20
33
|
def get(webhook_id)
|
|
21
34
|
@client.request("GET", "/webhooks/#{webhook_id}")
|
|
22
35
|
end
|
|
@@ -25,8 +38,19 @@ module OmniSocials
|
|
|
25
38
|
#
|
|
26
39
|
# `url` must be HTTPS. `events` is a non-empty subset of
|
|
27
40
|
# post.scheduled, post.published, post.failed, post.approved,
|
|
28
|
-
# post.rejected
|
|
29
|
-
#
|
|
41
|
+
# post.rejected and the ads events ad.status_changed, ad.created,
|
|
42
|
+
# ad.updated, ad.review, ad.delivery_issue, campaign.created,
|
|
43
|
+
# campaign.updated, campaign.budget, lead.received, ads.sync_failed,
|
|
44
|
+
# ads.sync_recovered, ads.initial_sync_completed and
|
|
45
|
+
# ad_rule.triggered. The `data` of an ad.status_changed delivery is
|
|
46
|
+
# the campaign, not a post: campaign_id, workspace_id, name, platform,
|
|
47
|
+
# campaign_type, status, previous_status, external_campaign_id and
|
|
48
|
+
# budget; the other ads events carry the campaign (plus "details") or
|
|
49
|
+
# their own data (a lead, a rule run, an ad account). Any Ads event
|
|
50
|
+
# (ad.*, campaign.*, lead.*, ads.*, ad_rule.*) needs the ads:read scope
|
|
51
|
+
# on the key and access_ads for its person (403 insufficient_scope /
|
|
52
|
+
# 403 insufficient_permission). The signing
|
|
53
|
+
# `secret` is only returned once, in this response - store it.
|
|
30
54
|
def create(url:, events:)
|
|
31
55
|
@client.request(
|
|
32
56
|
"POST", "/webhooks",
|
|
@@ -34,7 +58,12 @@ module OmniSocials
|
|
|
34
58
|
)
|
|
35
59
|
end
|
|
36
60
|
|
|
37
|
-
# PATCH /webhooks/{id} - update url, events, or active state.
|
|
61
|
+
# PATCH /webhooks/{id} - update url, events, or active state. Ads
|
|
62
|
+
# events need the same ads:read scope and access_ads as on create.
|
|
63
|
+
# Works on organisation-wide webhooks too. is_active: true switches on
|
|
64
|
+
# a webhook that was switched off (also an automatic switch-off);
|
|
65
|
+
# setting url, events or switching it on makes the key's creator the
|
|
66
|
+
# person behind the webhook.
|
|
38
67
|
def update(webhook_id, url: nil, events: nil, is_active: nil)
|
|
39
68
|
body = Internal.drop_nil(
|
|
40
69
|
{
|
|
@@ -46,14 +75,23 @@ module OmniSocials
|
|
|
46
75
|
@client.request("PATCH", "/webhooks/#{webhook_id}", json: body)
|
|
47
76
|
end
|
|
48
77
|
|
|
49
|
-
# DELETE /webhooks/{id} - delete a webhook
|
|
78
|
+
# DELETE /webhooks/{id} - delete a webhook of the key's workspace or
|
|
79
|
+
# an organisation-wide webhook of its organisation. Returns nil (204).
|
|
50
80
|
def delete(webhook_id)
|
|
51
81
|
@client.request("DELETE", "/webhooks/#{webhook_id}")
|
|
52
82
|
end
|
|
53
83
|
|
|
54
84
|
# POST /webhooks/{id}/rotate-secret - rotate the signing secret.
|
|
55
85
|
#
|
|
56
|
-
# The new secret is only returned once, in this response.
|
|
86
|
+
# The new secret is only returned once, in this response. The old
|
|
87
|
+
# secret keeps signing for 24 hours: every delivery then carries
|
|
88
|
+
# X-OmniSocials-Signature (new secret) and
|
|
89
|
+
# X-OmniSocials-Signature-Previous (old secret, same format, same
|
|
90
|
+
# timestamp and body). Verify the first with the new secret and, when
|
|
91
|
+
# that fails, the second with the old one (see
|
|
92
|
+
# OmniSocials::Webhooks.verify). Rotating again within the 24 hours
|
|
93
|
+
# replaces the previous secret with the one just rotated out. Works on
|
|
94
|
+
# organisation-wide webhooks too.
|
|
57
95
|
def rotate_secret(webhook_id)
|
|
58
96
|
@client.request("POST", "/webhooks/#{webhook_id}/rotate-secret")
|
|
59
97
|
end
|
data/lib/omnisocials/version.rb
CHANGED
data/lib/omnisocials/webhooks.rb
CHANGED
|
@@ -11,6 +11,12 @@ module OmniSocials
|
|
|
11
11
|
# - Header: X-OmniSocials-Signature: t=<unix>,v1=<hex>
|
|
12
12
|
# - Signed value: "{timestamp}.{raw_body}" (UTF-8), keyed with the
|
|
13
13
|
# webhook's secret, hex digest.
|
|
14
|
+
# - For 24 hours after a secret rotation, deliveries also carry
|
|
15
|
+
# X-OmniSocials-Signature-Previous: the same format, timestamp and body,
|
|
16
|
+
# signed with the old secret. To keep accepting deliveries while you
|
|
17
|
+
# switch secrets, verify X-OmniSocials-Signature with the new secret
|
|
18
|
+
# and, when that raises, X-OmniSocials-Signature-Previous with the old
|
|
19
|
+
# secret.
|
|
14
20
|
module Webhooks
|
|
15
21
|
class << self
|
|
16
22
|
# Verify an OmniSocials webhook delivery and return the parsed event.
|
|
@@ -19,7 +25,9 @@ module OmniSocials
|
|
|
19
25
|
# parse and re-serialize it first; the signature is over the
|
|
20
26
|
# raw bytes.
|
|
21
27
|
# signature - the X-OmniSocials-Signature header value, of the form
|
|
22
|
-
# t=<unix>,v1=<hex>.
|
|
28
|
+
# t=<unix>,v1=<hex>. For 24 hours after a secret rotation,
|
|
29
|
+
# pass the X-OmniSocials-Signature-Previous value here
|
|
30
|
+
# with the old secret when the new secret does not match.
|
|
23
31
|
# secret - the webhook's signing secret (returned once when the
|
|
24
32
|
# webhook is created, or via rotate_secret).
|
|
25
33
|
# tolerance - maximum allowed age (and future skew) of the signed
|
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.16.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-07 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
|