Schedule a post
sprkly_schedule_postQueue a post for publishing, in ONE call. Attach media by passing the user's link straight to media_urls: sprkly downloads it into storage itself for the platforms that need that, so no upload tool has to run first. Runs the same quota, duplicate-content and platform pre-flight checks as the sprkly app. Instagram and TikTok require media at submission time; YouTube and TikTok require a title, and TikTok also requires platform_meta.tiktok.privacyLevel — just send the level the user asked for and this tool names the allowed values if it is not one of them. It reads the real bytes of the media and the response says what will actually publish on each platform (a Reel, a 3-slide carousel, a photo set, a Page feed video) plus anything worth passing on: relay that to the user. Confirm the date, time and target accounts with the user first. If a target platform has more than one connected account and profile_ids is not given, the tool returns needsAccountChoice with the options instead of scheduling — put that choice to the user, then re-call.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "sprkly_schedule_post"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Post title. Required for YouTube (max 100 characters) and TikTok (max 150 characters). | |
| caption | No | Post caption. Each platform's own limit applies: X 280, Bluesky 300, Threads 500, Instagram and TikTok video 2,200, LinkedIn 3,000, TikTok photos 4,000, YouTube 5,000 bytes, Facebook 63,206, Telegram 4,096 as text alone and 1,024 with a photo or video. No < or > on YouTube. Links in a caption or first comment are published as written: sprkly does not check them. Too long for a target is refused with caption_too_long. | |
| alt_text | No | Optional alt text, one entry per media item, in the same order as media_urls then media_ids. Use "" for an item with no alt text. Up to 1,000 characters each. A list longer than the media is refused. Stored with the post. Used on platforms that support it. | |
| category | No | Optional content category, e.g. "fitness". | |
| media_id | No | Id of a single media file already uploaded to sprkly. Shorthand for a one-item media_ids. | |
| media_ids | No | Ids of media files already uploaded to sprkly, in slide order. Array order is the published order. Use these when the user already has media in sprkly, or when one file is going on several posts; for a link the user just gave you, media_urls is fewer steps. Every photo in a set must be the SAME shape or the call is refused: export them all at 1080x1920 (9:16), 1080x1440 (3:4), 1080x1350 (4:5) or 1080x1080 (1:1). Instagram takes at most 20 slides; TikTok photo sets take up to 35. | |
| platforms | No | Platforms to publish to. A platform with exactly one connected account is targeted directly; one with several makes the tool answer needsAccountChoice so the user can pick. | |
| post_type | No | Optional. What the post is for: awareness (show new people who you are and what you sell), educational (teach something useful), proof (show that other people trust you), conversation (get people to reply), conversion (ask people to buy, book or order now), loyalty (for people who already bought). Any other value is refused. Separate from category, which is the topic. | |
| automation | No | Instagram only, optional. An auto reply that switches on once this post is live: when someone comments the keyword, sprkly DMs them. Not on a story. It replies to real people, so show the user the word and the DM first. One per Instagram account in the targets. | |
| media_urls | No | Publicly reachable image or video URLs to attach, in slide order. Pass links through for ANY platform. Instagram and Threads fetch them directly; for TikTok, YouTube and Facebook sprkly downloads the file into its own storage while scheduling, so a link works there too and any problem with it is reported now, in this call. Google Drive and Dropbox share links are converted automatically. JPEG, PNG, WebP, GIF, MP4, MOV and WebM only: AVIF and HEIC (the iPhone camera default) are refused with re-export instructions, because sprkly cannot convert them. Each file must be publicly reachable and under 50 MB. | |
| profile_ids | No | Specific accounts to publish to, from sprkly_list_profiles. When given, this list IS the target set — platforms are not fanned out. | |
| all_accounts | No | Explicitly post to EVERY connected account on every listed platform, skipping the needsAccountChoice question. Only pass true when the user has said they want all accounts. | |
| approval_note | No | Optional note to the owner, shown in the approval email. Only used with requires_approval. | |
| first_comment | No | Instagram only. Optional text sprkly posts as the first comment under the post right after it publishes, e.g. "Comment GUIDE and I will send you the link." Up to 2,200 characters. Ignored for other platforms. Refused on a story (surface story): stories take no comments. Every paid plan: Free gets upgrade_required. | |
| platform_meta | No | Platform-specific publishing options, keyed by platform. | |
| scheduled_time | No | ISO 8601 timestamp to publish at. Must be in the future. If omitted the post goes out on the next publisher run, about a minute from now — there is no smart slot-picking, so pass an explicit time unless the user wants it published immediately. sprkly_get_analytics can suggest one. | |
| x_link_as_text | No | X only. Writes each link in the X caption as plain text, like sprkly dot app, so X counts it as a post without a link. A post with a link uses more of the X posts on lifetime plans. Other platforms keep the caption as sent. | |
| requires_approval | No | Hold the post until the owner approves it. It is saved as pending_approval and never publishes on its own; the owner gets an email with an Approve link and can also approve or reject in the sprkly calendar. Poll sprkly_get_post_approval_status for the answer. Brand, Pro, Agency and lifetime Tier 2 and up only (postApproval in sprkly_get_account_summary): other plans get upgrade_required. |