Publicações

Crie, publique e analise publicações sociais, incluindo publicações impulsionadas.

• Writecreate_postCreate a post for a location (or client) and submit it to the selected platforms — name them in `platforms`, or name exact accounts in `connectionIds` (from list_publish_targets) and omit `platforms`. One of the two is required. When it has destinations, the response also carries `targets`: each connection's platform and status. Publishes immediately unless scheduledFor is set or draft is true. A requested platform with no active connection never fails this call — the post is still created (as a draft if nothing resolved), and the response is `{ status: "no_connection", missingPlatforms, scope, post: { id, status } }` instead of the usual `{ id, status }` for whichever platforms couldn't resolve a connection. Compose what to tell the user from that data; do not assume the call failed just because `status` is "no_connection" — the content was saved. Likewise a post that cannot go live yet because a REQUIRED FIELD is absent (an event with no start/end date, a caption-less announcement, Instagram with no image) is saved as a draft and answers `{ status: "incomplete", missingFields, scope, post }`. Both gaps can appear together, in which case `status` is "no_connection" and `missingFields` rides alongside it — tell the user about BOTH at once rather than letting them discover the second after fixing the first. In every one of these cases the content EXISTS as a draft: say what was saved, name what it needs, point at where to fix it, and never report it as a failure. PLATFORM RULES (enforced — violations rejected): Post types: `announcement` works on every platform; `event` and `offer` are Google-only (any social platform ⇒ must be announcement). Caption char limits: google 1500, facebook 30000, instagram 2200, x 280 WEIGHTED characters rather than typed ones — Japanese/Chinese/Korean characters and emoji cost 2 each and any link costs a flat 23, so a non-Latin caption fits roughly 140 typed characters; setting linkUrl appends that link to the caption for a further 25 weighted (X thread mode is exempt from the limit entirely), linkedin 2000, pinterest 500, mastodon 500, bluesky 300, youtube 5000. Media (per platform, using each item's `platform`): facebook ≤10 images OR ≤1 video, no mix (carousel = 2–10 images only, per-card headline ≤80 / description ≤200); instagram requires ≥1 media, ≤10 images OR ≤1 video, no image/video mix; x ≤4 images OR ≤1 video, no mix; linkedin ≤5 images OR ≤1 video, no mix; pinterest image-only, exactly 1, required; mastodon ≤4 images OR ≤1 video, no mix; youtube video-only, exactly 1, required. Google event ⇒ eventTitle (≤58 chars) + eventStartAt + eventEndAt (end after start) required. Google offer ⇒ ctaType + ctaUrl required. scheduledFor must be in the future. Drafts (draft=true) skip required-field checks but still enforce all structural checks above.
• Writeupdate_postUpdate an editable post (draft/scheduled/error/active). Only the content and schedule fields you supply are changed — omitted fields keep their stored values (name, postType, platforms, captions, media, scheduledFor, etc.). Editing a post that is a draft keeps it a draft — a caption fix never publishes it. To take a draft live pass draft=false, a scheduledFor, or call publish_post_now. Pass draft=true to save any post as a draft (skips required-field checks); on a post that is already scheduled/active, omitting draft reconciles and publishes. Reconciles platform submissions. UI Series drafts use suggestedFor rather than an applied schedule; read get_distribution_campaign and preview_distribution_time_change first. Generic update_post does not authorize Series scheduling. A requested platform with no active connection never fails this call either (same as create_post) and the response is `{ status: "no_connection", missingPlatforms, scope, post: { id, status } }` instead of the usual `{ id, status }`. PLATFORM RULES (enforced — violations rejected): Post types: `announcement` works on every platform; `event` and `offer` are Google-only (any social platform ⇒ must be announcement). Caption char limits: google 1500, facebook 30000, instagram 2200, x 280 WEIGHTED characters rather than typed ones — Japanese/Chinese/Korean characters and emoji cost 2 each and any link costs a flat 23, so a non-Latin caption fits roughly 140 typed characters; setting linkUrl appends that link to the caption for a further 25 weighted (X thread mode is exempt from the limit entirely), linkedin 2000, pinterest 500, mastodon 500, bluesky 300, youtube 5000. Media (per platform, using each item's `platform`): facebook ≤10 images OR ≤1 video, no mix (carousel = 2–10 images only, per-card headline ≤80 / description ≤200); instagram requires ≥1 media, ≤10 images OR ≤1 video, no image/video mix; x ≤4 images OR ≤1 video, no mix; linkedin ≤5 images OR ≤1 video, no mix; pinterest image-only, exactly 1, required; mastodon ≤4 images OR ≤1 video, no mix; youtube video-only, exactly 1, required. Google event ⇒ eventTitle (≤58 chars) + eventStartAt + eventEndAt (end after start) required. Google offer ⇒ ctaType + ctaUrl required. scheduledFor must be in the future. Drafts (draft=true) skip required-field checks but still enforce all structural checks above.
• Readget_postGet a post with per-platform submission performance (agency-scoped).
• Readlist_publish_targetsList where a post for this location can go: its own connected profiles and its client's brand-level pages. Each target's connectionId is what create_post / update_post take in `connectionIds` to publish to exactly those. canPublish is false when the connection needs reconnecting. Same list as GET /api/v1/locations/{id}/publish-targets.
• Readlist_postsScope location means one location, brand means locationless client posts, all means every client post; default location when locationId is given, otherwise all. Read stored Synup Posts only, including unpublished Series drafts and imported posts; this does not fetch Google or any other provider. Zero matching stored posts is not proof of zero public posts. Includes client-level posts without a location. Provide clientId or locationId; both must agree. Follow nextPage until hasMore is false and reconcile changed totals/IDs; pages reflect current database reads, not a snapshot; live-pagination means database consistency, never a live provider check. createdFrom/createdTo (legacy from/to) filter creation dates; scheduledFrom/scheduledTo filter actual schedules, never suggestions. UI Series titles belong to list_distribution_campaigns, not ContentSeries ideas.
• Writedelete_postDelete a post and unpublish it from its platforms. Unpublishes every platform first, then archives the post ONLY IF every platform unpublish succeeded — this never permanently deletes the row; it just stops appearing anywhere in the API. If even one platform fails to unpublish, nothing is archived — the call still succeeds (no throw) but returns `ok: false` with a `failed` list; check `ok` rather than assuming the post is gone.
• Writepublish_post_nowPublish an EXISTING POST now: force-submit a draft/errored post (retries pending/errored platform submissions). To publish an idea use publish_post_idea instead. Throws if the post is scheduled for a future time — cancel or wait for the schedule instead. A no-op (no error, nothing retried) if there's nothing pending or errored to retry.
• Readget_post_analyticsPost analytics rollup for a client: engagement summary, per-platform breakdown, trends, top posts. Use for social media performance, content effectiveness. channel `brand` (default) is the client's brand-level pages; `local` is its locations' own profiles, optionally narrowed to the locations carrying one tag (a name from list_location_tags). The result says which slice it covers (`scope`). Brand and local are separate numbers — add them yourself if you want a combined figure, and note a page can appear in only one. Pass postId (a published YouTube video) to get that video's YouTube Analytics report instead — the post page's analytics panel — filtered by `report` (daily, totals, retention, traffic, searches, geography, demographics, devices, subscribers, content, revenue; default daily) and from/to (YYYY-MM-DD, required with postId).
• Readget_posts_client_rollupPosts summary across all locations: total posts, per-location post health, which locations fall behind on posting cadence. Use for social media overview, content output review.
• Writecreate_post_boostBoost a post with paid ad spend through a connected ad account — this spends real money. dailyBudget (minor currency units, e.g. cents) and durationDays are ALWAYS required, regardless of whether you also pass boostConfigId; if boostConfigId is given, only its adAccountId/targeting/publisherPlatforms/delayHours are used as defaults for whatever you don't specify — its own saved budget is never used silently. Pass postSubmissionId to boost an ALREADY-PUBLISHED post's live submission (spends immediately). Pass postId (+ platform or connectionId) instead to pre-configure a boost on a post that hasn't published yet — it stays queued (no spend) and only starts once that post's submission goes live. adAccountId must belong to a connected account (see list_ad_accounts); use select_ad_account first if none is selected.
• Readlist_post_boostsList boosts (paid promotions of posts), newest first, so one can be found again without the create_post_boost response: status, whether it is deferred (waiting for its post to publish), the budget, spend so far, the post it promotes, and `control` — the tool that applies now (`stop_post_boost` with adRunId for a live one, `cancel_deferred_boost` with adCampaignId for a deferred one, null when it is over). Filter by postId, status, or activeOnly. Up to 50 per page; follow hasMore. A client (portal) session sees only its own client's boosts, without the agency's ad spend and without controls; a member limited to some clients sees only those clients'.
• Readget_post_boostGet one boost by its adRunId (from list_post_boosts or create_post_boost): status, budget, spend, the post, and the control that applies. A client (portal) session can read only its own client's boosts, without spend or controls.
• Writestop_post_boostStop a LIVE boost that's already spending on the platform — halts real in-flight ad spend. This cannot be resumed; a new boost would need to be created. To cancel a boost that hasn't gone live yet (still queued, awaiting the post to publish, no spend yet), use cancel_deferred_boost instead. Identify the boost by its adRunId — find it with list_post_boosts (each boost lists the control that applies).
• Writecancel_deferred_boostCancel a deferred boost that hasn't gone live yet (its post hasn't published, so no money has been spent). To stop a boost that's already live and spending, use stop_post_boost instead. Identify it by its adCampaignId — find it with list_post_boosts (a deferred boost shows its adCampaignId). Answers `{ cancelled: true, runsCancelled }` when it cancelled something, `{ cancelled: false, reason }` when the boost exists but nothing was waiting, and an error when the id is not a boost of this agency.
• Writecreate_youtube_playlistCreate a playlist on a connected YouTube channel (the composer's "New playlist"). Returns its id and title, to put a video in when publishing. Title up to 150 characters; privacy private | public | unlisted.
• Readget_post_boost_analyticsRead paid-promotion totals, trends and per-post performance for one client, with brand/local channel and optional local tag filters. Requires an active agency user with Social and owning-client access. Reads stored results only and never publishes or creates ad spend. Date filters, where supported, default to the last 30 days.
• Readget_post_follower_analyticsRead follower snapshots, measured coverage and prior-window comparisons for client brand accounts. Missing observations remain unavailable. Requires an active agency user with Social and owning-client access. Reads stored results only and never publishes or creates ad spend. Date filters, where supported, default to the last 30 days.
• Readget_location_post_analyticsRead Google and Facebook local post views, clicks, daily trends and top posts for a location. Requires an active agency user with Social and owning-client access. Reads stored results only and never publishes or creates ad spend. Date filters, where supported, default to the last 30 days.
• Readget_post_boost_campaignsRead all campaigns behind one post, including budget, targeting, status and latest recorded performance. Returns a distinct campaign count. Requires an active agency user with Social and owning-client access. Reads stored results only and never publishes or creates ad spend. Date filters, where supported, default to the last 30 days.
• Readget_post_series_analyticsRead publishing-series choices and lifetime post outcomes, or pass seriesId and optional compareId for attributed provider-day KPIs, charts and paid analytics. Filter by client, location, brand/local channel, local tag, network platform and dates. Account-level follower counts cannot be attributed to a series. Reads stored results only, with reporting-limit and measurement coverage flags.
• Readget_workspace_postsRead a paginated workspace-wide publishing calendar, content series, or local/brand organic analytics. Pass scope=workspace and view=calendar|series|analytics. Includes only accessible active clients in the acting workspace. Stored reads only; never publishes or changes schedules.
• Writepause_scheduled_postPause a scheduled post while retaining its date and destinations. A post already claimed for publishing is refused. Requires the Social revamp feature and an active agency user with Social and owning-client access.
• Writeresume_paused_postResume a paused post at its existing future date. Past dates are refused. Series publishing permissions, approvals and paused/archived series checks still apply. Requires Social revamp and an active agency user with Social and owning-client access.
• Writeunschedule_postMove a scheduled post back to draft, clear its date and disarm failed-submission retries. Preserves its destinations. Refuses cancellation once publishing has claimed the post. Requires an active agency user with Social and owning-client access.
• Writeduplicate_postCopy a post through the ordinary creation and content-check pipeline. Optional scheduledFor is an ISO timestamp; omitted date or draft:true saves a draft. Series variants cannot be duplicated this way. Requires Social revamp and an active agency user with Social and owning-client access. Never authorizes bypassing content checks.
• Writerecover_failed_post_destinationsCreate a recovery draft for a partly-published post's failed destinations. Copies the original content and targets only the failed connections. The user then edits content if needed, picks a time, and schedules through the normal flow. Idempotent: returns the existing recovery draft if one already exists. Claims the source's failed submissions so they cannot be retried. Requires Social revamp and an active agency user with Social and owning-client access.
• Writerecord_assisted_post_outcomeRecord an assisted publication the user already completed outside Synup. action:published requires its live URL matching the destination; Reddit also requires rulesReviewed:true only when the person explicitly confirmed reviewing the destination rules, or alreadyPosted:true only when the person says the post was made before the hand-off (it is recorded as is). action:emailed records a Substack email already sent after web publication. Never publishes or sends email itself. Refuses canceled submissions and archived series. Requires an active agency user with Social and owning-client access.