n8n-nodes-upload-post 0.1.56 → 0.4.0

package/README.md

@@ -75,6 +75,7 @@ The node provides the following operations grouped for clarity:
   - Supported: Facebook, Instagram, LinkedIn, Pinterest, Reddit, Threads, TikTok, X, YouTube. Analytics are not available for Bluesky, Discord, Google Business or Telegram.
 - **Get Post Analytics**: Per-post metrics for an upload, by `request_id`.
   - Parameters: Request ID, Platform (optional filter).
+  - On TikTok, `post_metrics` also carries `retention`, `impression_sources`, `audience_types`, `new_followers`, `reach` and the watch times.
 - **Get Post Analytics by Platform ID**: Per-post metrics for a post published outside Upload-Post.
   - Parameters: Platform Post ID, Platform, Profile Username.
 - **Get Cached Post Analytics**: Replays per-post metrics already fetched, instead of querying the platforms again, so it is not subject to the live analytics rate limit (100 requests / 5 minutes). Only contains posts previously fetched through a live per-post endpoint; there is no background refresh, so captured_at is the last time that post was read live.
@@ -114,6 +115,31 @@ The node provides the following operations grouped for clarity:
   - Parameters: JWT token (password field).
   - The API response is returned as-is; its `profile` object also carries the `ui_labels` map configured for that profile.
 
+### Comment Actions
+The comment endpoints are shaped like the rest of the API: **one endpoint per question, with a `platform` parameter** that says which connected network is being asked. There is no endpoint per social network.
+- **Get Post Comments**: Comments on a post from the network given by `Platform` (Instagram, Facebook, YouTube, LinkedIn or TikTok).
+  - Parameters: User Identifier, Platform, Post ID or URL, Comment ID (optional).
+  - Instagram and Facebook accept the media ID or the post URL, YouTube the video ID, LinkedIn the post URN, TikTok the video ID. TikTok has no URL lookup, so pasting a URL fails with a descriptive error instead of an upstream one.
+  - Fill **Comment ID** to get the replies to that comment instead of the top-level comments of the post. It is the same question with one parameter more, not a separate operation.
+- **Comment Action**: Moderate one comment — hide, unhide, like, unlike, pin or unpin it.
+  - Parameters: User Identifier, Platform, Comment ID, Action, Post ID (shown only when it is needed).
+  - Each action carries its own inverse, so there is no separate toggle: `hide`/`unhide`, `like`/`unlike`, `pin`/`unpin`.
+  - **Post ID** is required for `hide`, `unhide`, `pin` and `unpin`, and is never sent for `like`/`unlike` — the API rejects a like that carries a post. The node checks it before the request leaves n8n.
+  - TikTok is the network that answers this today, and its profile needs the `comments` capability (see the `capabilities` array returned by **List Users**); an account connected before that capability existed has to reconnect TikTok.
+- **Private Reply to Comment**: DM the author of a comment. Instagram only.
+- **Public Reply to Comment**: Public reply under the comment. Instagram only.
+
+### Insight Actions
+Two more questions with a `platform` parameter, not two TikTok endpoints. A network that cannot answer a question replies with `platform_not_supported` and the list of the ones that can; today that network is TikTok, whose profile needs the `profile_analytics` capability (see the `capabilities` array returned by **List Users**).
+- **Get Audience**: Who follows the profile and when they are around — audience countries, cities, age brackets and genders, followers online per hour, daily followers gained and lost, profile actions and the bio.
+  - Parameters: User Identifier, Platform, Start Date, End Date, Benchmark Category (all optional except the first two).
+  - Dates are `YYYY-MM-DD`. The window is clamped **by the server**: 60 days at most, and End Date always below today. A wider range is trimmed, not rejected, so the node sends it as typed.
+  - Filling **Benchmark Category** adds a `benchmark` object with that niche's averages (comments, engagement rate, follower count and growth, likes, shares, video count and views) next to the account's own numbers. The 25 accepted values come back in `benchmark_categories` on every response, so filling a picker needs no extra call.
+  - Use this to know *who* the audience is and *when* to post; use **Get Post Analytics** for how a given post did.
+- **Get Suggestions**: What to write about — hashtags or the searches people run around a seed word.
+  - Parameters: User Identifier, Platform, Type (`hashtags` / `keywords`), Query, Country Code, Language.
+  - `Type = hashtags` answers with `hashtags: [{ name, view_count }]`; `Type = keywords` answers with `keywords: [...]`. One endpoint, told apart by `type`, not by operation.
+
 Refer to the [Upload Post API Documentation](https://docs.upload-post.com) for detailed information on parameters and platform requirements.
 
 ### Waiting for asynchronous uploads
@@ -168,6 +194,45 @@ If you saw duplicate posts on an older version of this node, upgrade: versions b
 - **Video Options**: Privacy level (Public/Mutual Friends/Followers/Self), disable duet/stitch/comments, cover timestamp (ms), brand content toggles, AI-generated content flag, post mode (Direct Post/Media Upload).
 - **Brand Content**: Separate toggles for paid partnerships and own business promotion.
 
+#### TikTok Advanced Video Options
+
+> **Capability-gated.** `GET /api/uploadposts/users` returns a `capabilities`
+> array on each TikTok account (`music`, `location`, `cover_image`,
+> `cover_timestamp`, `draft`, `photo_privacy`, `video_privacy`,
+> `inbox_fallback`, `profile_analytics`). If the connection does not declare the capability an option
+> needs, the API ignores that field, the post still publishes and the response
+> includes a per-field warning — reconnect the TikTok account to enable it.
+> These options are only sent when actually filled in, so leaving them at their
+> defaults keeps the previous behaviour.
+
+- **Music** (`music`): TikTok Music ID — the `id` of a track returned by `GET /api/uploadposts/tiktok/music/trending` or `GET /api/uploadposts/tiktok/music/search` (not its `commercial_music_id`) — plus music volume (0-100) and music start/end offsets in ms. The Music ID works on **video and photo** posts; the volume and the offsets are video-only, because TikTok's photo contract takes the track id alone.
+
+  To pick a track by name inside a workflow, put an **HTTP Request** node before
+  this one calling
+  `GET https://api.upload-post.com/api/uploadposts/tiktok/music/search?profile=<profile>&q=<song or artist>`
+  with the header `Authorization: Apikey <your key>`, and feed `tracks[0].id`
+  into TikTok Music ID. It also accepts `genre`, `country_code`, `date_range`
+  and `limit`. Note that TikTok has **no music search endpoint**: the search
+  runs over the trending charts Upload-Post caches per genre/country/period, so
+  it finds trending tracks, not TikTok's entire catalogue.
+- **Original Sound Volume**: Volume (0-100) of the video's own audio when music is added. Keep it above 0 so the original audio is not muted. Music volume and original sound volume are only sent when a Music ID is set.
+- **Location** (`location`): TikTok Location ID plus TikTok Location Name — TikTok requires both together. Works on video and photo posts.
+- **Cover Image URL** (`cover_image`): Custom cover image, takes priority over the cover timestamp. Video only.
+- **Is AI Generated**: AI-generated content disclosure. Works on video and photo posts.
+- **Upload to Draft** (`draft`): Sends the video to TikTok drafts instead of publishing; TikTok then ignores the rest of the post settings. Video only.
+
+> **Privacy level on TikTok.** `privacy_level` is accepted on video and photo
+> uploads alike (capabilities `video_privacy` / `photo_privacy`), but **TikTok
+> decides per account which values are available**: a private account is offered
+> Followers / Mutual Friends / Self Only and has no Public. Asking for one the
+> account does not have fails with `tiktok_privacy_unavailable`, and the error
+> lists the ones it does have. The **Account Default** option on the TikTok
+> Privacy Level (Video) field sends nothing and lets TikTok apply the account's
+> own setting — the only choice guaranteed to work on every account, and the
+> default for new nodes. Photo posts default to Public. To pick a value up front,
+> query `GET /api/uploadposts/tiktok/settings?profile=<profile>` from an HTTP
+> Request node and read `privacy_level_options`.
+
 #### YouTube
 - **Video Metadata**: Tags (comma-separated), category ID, privacy status (public/unlisted/private), embeddable, license, public stats viewable.
 - **Compliance**: Made for kids declaration, self-declared made for kids (COPPA), contains synthetic media (AI transparency), has paid product placement (FTC).
@@ -229,6 +294,10 @@ If you saw duplicate posts on an older version of this node, upgrade: versions b
 - **`Description (Optional)`**: Generic description used for LinkedIn, Facebook, YouTube, Pinterest, TikTok when supported.
 - **Platform Description Overrides**: `[platform]_description` (e.g., `youtube_description`, `linkedin_description`).
   - Available for: facebook, tiktok, linkedin, youtube, pinterest
+- **`First Comment`**: Generic first comment posted right after publishing.
+- **Platform First Comment Overrides**: `[platform]_first_comment` (e.g., `instagram_first_comment`, `tiktok_first_comment`).
+  - Available for: instagram, facebook, x, threads, youtube (video only), reddit, bluesky, linkedin, tiktok (media only).
+  - TikTok needs the `comments` capability on the profile's TikTok account.
 
 **⚠️ Runtime Validations**: The node performs automatic validations at runtime including poll constraints, mutually exclusive field checks, and platform-specific requirements. Invalid configurations will throw descriptive error messages.