Sprkly

Download an image or video from a public link into sprkly and get a media_id back, for reuse across several posts. You usually do NOT need this: sprkly_schedule_post accepts a link directly in media_urls and pulls it into storage itself whenever the target platform requires that. Reach for this tool only when the user wants one media_id to attach to more than one post. Google Drive and Dropbox share links are converted automatically; the file must be shared publicly. Limit 50 MB.

Set up one ready-made automation on one Instagram account and turn it on. This is the same as Go live in the app. It starts replying to real people right away, so show the user the template, the account, the word and the link first. Pass template_id from sprkly_list_automation_templates and profile_id from sprkly_list_profiles. If asks_for has post, pass post_id: a published Instagram post on that account. If it does not, leave post_id out. If asks_for has link, pass a full https link. keyword is optional and defaults to the template's word. message is optional and replaces the DM, or the public reply on a template that only replies in the comments. On first-comment-on-post, message is required: the comment sprkly adds under each new Instagram post it publishes on that account (up to 2,200 characters). That one is on Creator and Power, and an account can have one live. The coupon template is refused until message holds the real code instead of YOUR-CODE. If asks_for has faq, pass faq: 1 to 10 { keyword, answer } pairs. Each pair becomes its own automation that answers a DM of that word. fallback is optional there and becomes the account's default reply, for a DM with none of the words. It replaces any default reply already on that account, and turns it on if it was off, so tell the user first. A word another live automation already answers is refused. Calling again with the same list skips the words already live. Use sprkly_pause_automation to stop it.

Remove a post from the queue. This is a soft delete. The user can restore it from the Deleted tab for 30 days. Posts that have already published cannot be deleted this way. Always confirm with the user before calling.

Compose a caption from a content hint and save it as a draft in sprkly, shaped to the tightest caption limit among the target platforms. Returns a draft id; the draft appears under /drafts for the user to review.

Download one Instagram auto reply as a shareable template. The file holds the trigger, the keyword and the message, and never a post id, a profile id or any account details, so it is safe to send to someone else. An auto reply that is still a draft has nothing published to export. Needs a connected Instagram account.

Plan tier, trial state, connected account count, scheduled post counts by status, and the next three upcoming posts. Never returns tokens or secrets.

How the user's published posts actually performed: total views and engagement, week-on-week / month-on-month / year-on-year change, their best posting hour, weekday and content category, and the top posts behind those numbers. Every recommendation carries a `samples` count: say how thin the evidence is rather than presenting a one-post pattern as a finding. Every period-on-period percentage carries the post counts and raw totals it came from: quote those, because a big percentage off a tiny base is not a big change. `topPosts` is grouped by platform and ranked only inside each group; `relativeToPlatformBest` compares a post with others on its OWN platform and never across platforms, so use the absolute `value` and its `metric` label to weigh one platform against another. Instagram contributes reach, saves, shares and views only for accounts connected or reconnected with the insights permission, and likes and comments only for the rest. X contributes views, likes, replies, reposts and bookmarks for the newest 10 X posts from the last 2 weeks, updated once a day. Bluesky contributes likes, replies and reposts, never views. Threads and Facebook produce no metrics at all. Read `coverage` before comparing platforms, and never rank platforms on a metric one of them lacks.

For each Instagram account: how many people automations have messaged this month, the plan's monthly limit for that account, and when the count resets. ready is false when Instagram has not given the messaging permission yet.

Subscription status, current plan, period end, purchased handles and the last few billing events. No payment method details; the Stripe customer id is truncated.

For each connected account over the last `days` (default 7): comments received, public replies and automated DMs sent, new contacts and emails captured, each against the window before, plus its top 3 posts. Views and engagement change covers all accounts together. Quote the current and prior numbers beside every percentage, and caveat any marked thin.

One conversation, oldest message first: their DMs and comments, your replies, and what automations sent. Each comment people left carries the comment_id that sprkly_reply_to_comment answers under. dm_window says whether a DM answer is still allowed: Instagram only allows one within 24 hours of their last message. Needs inbox access.

Whether a post is awaiting the owner's approval, approved or rejected, with the reviewer's notes, who asked, and timestamps. A rejected post is a draft again: fix it, then request approval again.

Full detail for one post: status, targets, scheduled and published times, permalink, and the failure reason if it did not publish. Media comes back as mediaIds in slide order, not as links. Ids and profile ids are plumbing: talk to the user about accounts by handle and about posts by their caption, and do not read ids out unless they ask for one.

This creator's allowed TikTok privacy levels and interaction settings, fetched live from TikTok. You usually do NOT need this before scheduling: sprkly_schedule_post checks privacyLevel against this same list itself and, when it is wrong, returns the levels that would work. Call this only when the user asks what their options are, or you want to offer them a choice.

Read an auto reply template, and optionally set it up. With no profile_id NOTHING is written: the template is checked and handed back, which is the safe first call. With a profile_id the automation is created, and it goes live when the trigger can be satisfied. A trigger that watches one post (a keyword on a post, or every comment on a post) needs post_id as well. Without one it saves as a draft that sends nothing until a post is chosen. A keyword on any post and a Profile DM need no post_id. A template that DMs every commenter on the whole account is turned off and is refused. Needs a connected Instagram account.

The ready-made Instagram automations, the same ones as the template gallery in the app. For example: send a link when people comment a word, answer story replies, ask for a follow first, or collect emails. Each one has an id, a name, a goal, what starts it, and the message it sends. asks_for says what sprkly_create_automation_from_template needs besides the template id and the account: a post, a keyword, a link, or faq (a list of words and answers). Every plan has automations.

Every Instagram automation on this account that is not archived. Each row has its name, its state (On, Paused or Draft), the Instagram account it runs on, what starts it, and how many DMs and public replies it has sent. One automation on several accounts shows one row per account, all with the same group_id.

Every ACTIVE social account linked to this sprkly account: platform, handle, follower count, and whether it needs reconnecting. Disconnected/inactive accounts are never listed, so any profileId returned here is a valid posting target. Never returns access tokens.

The most recent conversations in the sprkly inbox, newest first. One row per person per connected account, with their handle, how many of their messages are unread, and the last thing said. Pass unread_only to see only conversations waiting for an answer. Use profile_id and person_id from a row with sprkly_get_inbox_thread to read it. Needs inbox access, which the user allows on its own: a key made with inbox access ticked, or a connection that allowed it.

People an automation answered in the last `days` (default 7), newest first: their handle, the keyword they used, the post they asked under, and the email they gave, if any. Filter by account, keyword or has_email. opted_out is true when the person sent STOP; never contact them. Never message a lead unless the user asks. Needs inbox access.

The profile ids needed to target a post, with each one's platform and handle. Call this before sprkly_schedule_post.

The post queue, newest first, with a caption preview, targets, status and failure reason. Supports a status filter and cursor pagination.

Stop an automation from replying, on every account it runs on. Nothing is deleted. sprkly_resume_automation turns it back on. Any account that could not be changed is named in failed.

Post one public reply under an Instagram comment, from the account that got the comment. Everyone can see it and it cannot be taken back, so show the user the words first. Take comment_id from sprkly_get_inbox_thread. If the answer says Instagram did not confirm, do not send it again: tell the user to check the post. Needs inbox access.

Send one Instagram DM to a person who messaged this account, from the account owner. It cannot be taken back, so show the user the words first. Instagram only allows it within 24 hours of their last message. Replying pauses automations for this person for 5 minutes, like replying in the app. If the answer says Instagram did not confirm, do not send it again: tell the user to check the chat. Needs inbox access.

Hold a draft or scheduled post for the owner's approval. Moves it to pending_approval, where it never publishes on its own, emails the owner an Approve link, and returns an approval id to poll with sprkly_get_post_approval_status. Asking again for a post that is already waiting returns the same request. Approved posts go back to scheduled (a post past its time goes out in about 2 minutes); rejected posts become drafts with the owner's notes. To hold a NEW post, pass requires_approval to sprkly_schedule_post instead. Power plan only: other plans get upgrade_required.

Turn a paused automation back on, on every account it runs on. It starts replying to real people again. A draft has to be finished in sprkly first. An automation that hit its "stop after this many people" limit stays off.

Queue 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.

Change the caption, publish time, target accounts or attached media on a post that has not published yet. Posts with status "scheduled", "pending_approval" or "draft" can be edited, and the status never changes here: editing a post that waits for approval does not approve it, and a rejected post stays a draft until you request approval again. A post waiting for approval can only target one account.

Upload files the user has on their machine (slides, photos, a short video) into sprkly and get a media_id for each. LINK MODE is the way to send a file from disk. Send files, one entry per file with its filename, sha256 and size_bytes. You get back one uploadUrl per file. PUT the bytes to it: curl -sS -X PUT --data-binary @01.jpg "<uploadUrl>". Each PUT answers JSON with mediaId. Links last 15 minutes. Up to 50 MB per file and 35 files per call. The bytes never pass through you, so a whole carousel costs a few hundred tokens. INLINE MODE is for tiny files only (a few KB): data_base64 plus filename, 25 MB at most. base64 costs about one token per character, so never inline a real slide. When files is sent, data_base64 and filename are ignored. For a public link use media_urls on sprkly_schedule_post instead. The same bytes sent twice return the same media_id.

Check a caption against each target platform's posting rules before scheduling: caption length, media requirements, hashtag ceilings, whether links are clickable, required YouTube titles, and PII or prohibited-content warnings. Pure analysis. Writes nothing.