Blotato

Get analytics for a single DM automation. `triggered` is the total number of runs that have started; `completed` is the number that finished successfully; `failed` is the number that failed; and `issues` is the number that failed in the last 7 days. `completed` plus `failed` can be less than `triggered`, because runs that are still in flight, or that expired while waiting on the contact, do not count towards either outcome. `issues` is a recent subset of `failed` rather than a fourth outcome, so do not add it to the others. Use it for a quick health check on an automation before digging into individual runs with blotato_list_automation_runs.

blotato_get_automation_analytics

Check the rendering status of a Blotato design. Use this after blotato_create_design to track progress and retrieve the URLs of the final rendered designs. While rendering, a design's status changes several times. Once rendering finishes or stops, the status is one of: done | creation-from-template-failed | insufficient-credits | draft. Optionally will return an error message if the design failed due to insufficient credits or other reasons. Whenever error is set, processing has stopped and the status will never change again, even when it is not one of the final statuses above. For example, a design that could not be rendered stays at script-ready with an error. Stop polling at that point and report the error message to the user. When status is "done", the response includes URLs to the rendered designs that can be passed directly to blotato_create_post's mediaUrls field. Rendering typically takes 30s–5min depending on template complexity. Wait at least 15 seconds between polls — do NOT poll more frequently than that.

blotato_get_design_status

Get a single direct message by its Blotato ID. The message may be an inbound message received from a contact, or an outbound message the user sent through Blotato. The message includes a direction ("incoming" = received from the other party, "outgoing" = sent by the account) and a status (queued, processing, sent, delivered, or failed) with an errorMessage when failed. Facebook/Instagram: Its payload carries rich content: attachment and quickReplies on a message the account sent, and selection on an incoming message where the recipient tapped a postback button or a quick reply.

blotato_get_message

Get analytics for a single published post, including the latest metrics and the full snapshot history. This does not trigger a re-fetch; it returns the most recent analytics collected in the background. Use blotato_list_posts or blotato_list_top_posts to find the published post id first. Metrics are returned as strings. When a post has not been synced yet, metrics is null and lastError may explain why.

blotato_get_post_analytics

Check the publishing status of a previously created post. Use this if blotato_create_post timed out and returned an in-progress status. Statuses: in-progress → published | scheduled | failed. When status is "published", the response includes the live publicUrl of the post. When "scheduled", includes the scheduledTime as a UTC ISO8601 string. When "failed", includes an errorMessage. Most failures are permanent — retrying the same submission is not recommended. Wait at least 10 seconds between polls.

blotato_get_post_status

Get a single scheduled post by its ID. Returns the full schedule details including the draft content, scheduled time, and account information. Use this to inspect a specific schedule before updating or deleting it.

blotato_get_schedule

Check the status of a source extraction. Use this if blotato_create_source timed out and returned an in-progress status. Statuses: queued → processing → completed | failed. When status is "completed", the response includes the extracted title, content text, and referenceUrl. When "failed", includes an error message. Wait at least 10 seconds between polls.

blotato_get_source_status

Get the current authenticated Blotato user. Returns the user's id, subscription status, and subscription plan. Use this to verify the API key is valid and the subscription is active before performing other operations. For connected social accounts, use blotato_list_accounts.

blotato_get_user

List comments that were left on the user's published posts, ordered by creation time (most recent first). Comments may have been left by the user's audience or by the user themselves. If a comment's isAuthor flag is true, the comment was authored by the user; if false, the comment was received from a contact. Supports cursor-based pagination and optional filters by platform, account, and published post. Pass the returned cursor back as the cursor argument to fetch the next page. When the response omits a cursor, you have reached the end of the list. Comments support one level of threading: a comment whose parentCommentId is set is a reply to that comment. Pass parentCommentId to list the direct replies to a single comment. Each comment has a status: posted, queued, processing, failed, or deleted.

blotato_list_comments

List all social media accounts connected to the user's Blotato workspace. Returns each account's id, platform, display name, username, subaccounts (Facebook Pages, LinkedIn Company Pages, YouTube Playlists), and the platform-specific required fields needed when creating a post. You MUST call this before blotato_create_post to get the correct accountId and understand what each platform requires. For example, Facebook requires a pageId (returned as a subaccount), TikTok requires privacyLevel and several boolean flags, Pinterest requires a boardId, and YouTube requires a title and privacyStatus. Supports: Twitter, Facebook, Instagram, LinkedIn, TikTok, Pinterest, Threads, Bluesky, and YouTube. Optionally filter by platform to narrow results.

blotato_list_accounts

List the user's direct-message conversations across connected social accounts, ordered by most recent activity. Supports cursor-based pagination and optional filters by platform and account. Pass the returned cursor back as the cursor argument to fetch the next page. When the response omits a cursor, you have reached the end of the list. Each conversation includes its participants. To reply, get the other party's id from a message in the thread (blotato_list_messages) — an incoming message's senderId or an outgoing message's recipientId — and pass it as recipientId to blotato_send_message.

blotato_list_conversations

List the execution logs written as a DM automation's runs advance, ordered by creation time (most recent first). Supports cursor-based pagination. Each log line has a level (info, warning, error), a message describing the step, the id of the run it belongs to, and a context object with step-specific details.

blotato_list_automation_logs

List the execution runs of one DM automation, ordered by start time (most recent first). Supports cursor-based pagination. A run is one execution of the automation. It records the associated contact, its status, and if it failed, the error. A run expires when the contact never replies within the waiting window, and is superseded when a newer run starts waiting on the same contact's input. Use it to check whether an automation is firing and why a reply did not go out.

blotato_list_automation_runs

List the current user's DM automations, ordered by creation time (most recent first). Each automation includes `stats`: run counts (triggered, completed, failed) over the last 24 hours and `lastRunAt`. Supports cursor-based pagination.

blotato_list_automations

List available Blotato design templates. Templates are organized into categories: for example, slideshows (quote cards, tweet cards, tutorial carousels) and infographics (news, education, urban themes). Each template returns its id, title, description, and available inputs (e.g., topic, style, colors, number of slides). Use the template id with blotato_create_design to render it.

blotato_list_design_templates

List the user's direct messages, ordered by creation time (most recent first). Pass conversationId to list all messages in a given conversation. Supports cursor-based pagination and optional filters by platform and account. Pass the returned cursor back as the cursor argument to fetch the next page. When the response omits a cursor, you have reached the end of the list. Each message includes a direction ("incoming" = received from the other party, "outgoing" = sent by the account) and a status (queued, processing, sent, delivered, or failed) with an errorMessage when failed. To reply with blotato_send_message, use the other party's id as recipientId: an incoming message's senderId, or an outgoing message's recipientId. Facebook/Instagram: A message's payload carries its rich content: attachment and quickReplies on messages the account sent, and selection on an incoming message where the recipient tapped a postback button or a quick reply. Read selection.payload to see which option they chose.

blotato_list_messages

List the boards owned by a connected Pinterest account. Each entry has an id and name. Use the id as the boardId required by blotato_create_post when publishing to Pinterest. Call blotato_list_accounts first to get the Pinterest accountId, then pass it here.

blotato_list_pinterest_boards

List the user's posts (scheduled, published, and failed) within a time window, ordered by post time (most recent first). Supports cursor-based pagination and optional filters by status and platform. Pass the returned cursor back as the cursor argument to fetch the next page. When the response omits a cursor, you have reached the end of the list. Each item has a state field with a type of "scheduled", "published" (includes postUrl and analytics, the latest metrics snapshot or null if none have been fetched yet), or "failed" (includes errorMessage), and an account field with the connected account's id and name (plus subaccount for Facebook and LinkedIn pages). The account field is null if the account is no longer connected.

blotato_list_posts

List all scheduled posts for the current user. Returns posts scheduled in the future, ordered by scheduled time (ascending). Supports cursor-based pagination. Each schedule includes the draft content, scheduled time (ISO 8601 UTC), and the target account information (platform, name, username). Use the returned cursor (if present) to fetch the next page of results.

blotato_list_schedules

List the user's top performing published posts, ranked by a chosen engagement metric over a time range. Use this to answer questions like "what were my best posts last month" or "which posts got the most views". Each item includes the post content, public URL, platform, publish time, media URLs, the latest analytics snapshot, and the full snapshot history. Analytics are refreshed periodically in the background, so recent posts may have no metrics yet. Analytics are currently collected for Twitter/X, Instagram, Facebook, Threads, and Bluesky. Other platforms return no metrics yet. - Metrics are returned as strings (counts can exceed normal number precision). - lastError on a post, when present, explains why analytics could not be fetched for it.

blotato_list_top_posts

Post a comment on one of the user's published posts (Instagram and Facebook), or a threaded reply to an existing comment on that post when parentCommentId is provided. IMPORTANT: postId is the Blotato id of a published post. Get it from blotato_list_posts (items whose state.type is "published") or from the postId field of a blotato_list_comments result. The comment is queued and posted asynchronously; it is returned immediately with status "queued". Use blotato_get_comment to check whether it became "posted" or "failed".

blotato_post_comment

Send a direct message to a recipient on Facebook or Instagram. IMPORTANT: Call blotato_list_accounts first to get the accountId (and, for Facebook, the pageId from the account's subaccounts). The platform must match the account's platform. MESSAGING WINDOWS (enforced on all Facebook and Instagram messages — a violation is rejected and the message ends up "failed"): - Standard DM (default): May only be sent within 24 hours of the recipient's most recent message to this account. If the recipient has not messaged within the last 24 hours, the send fails. Check the latest inbound message time with blotato_list_messages before sending. - Private reply to a comment: If the recipient commented on one of the account's own posts, you may send a SINGLE private reply to that comment within 7 days of the comment — even with no prior direct message. To send it, pass the comment's Blotato ID as commentId (from blotato_list_comments). DETERMINING recipientId: - Replying in a DM thread (blotato_list_messages): read the message's direction. When direction is "incoming", use the message's senderId. When direction is "outgoing", use the message's recipientId. - Replying to a comment (blotato_list_comments): if isAuthor is false, use the comment's authorId. RICH MESSAGE OPTIONS (Facebook/Instagram ONLY; mutually exclusive — pass buttons, or quickReplies, or neither; sending both is rejected): - buttons: up to 3 call-to-action buttons pinned under the message. Use type "web_url" with an https url to open a link, or type "postback" with a payload to capture the tap. Requires text of 1 to 640 characters. - quickReplies: up to 13 tappable chips offered as canned replies. Each carries a payload. Requires non-empty text. Chips disappear once the recipient taps one or types their own message. Returns the queued message immediately with status "queued"; it is delivered asynchronously. Use blotato_get_message to check delivery status.

blotato_send_message

Update a DM automation. Any of name, triggers, dmMessage, buttons, followGate, emailGate, webhook, or commentReply you pass replaces that field; omitted fields are left unchanged. Pass null to followGate, emailGate, webhook, and/or commentReply to remove those fields. To remove all buttons, pass buttons: []. To remove all triggers, pass triggers: [] subject to the active-flow requirements below. name and dmMessage must be strings; triggers and buttons must be arrays, not null. Omitting isActive keeps the automation in its current state. Content changes to an ACTIVE automation are published immediately — they go live as soon as the update succeeds. Changes to an inactive one are saved as a draft until you pass isActive true. An active automation can send DMs to contacts on Instagram/Facebook, reply publicly to the comments that trigger it, and call its configured webhook on matching events without another tool call. Every webhook method except GET shares the contact's email address and follower status with the configured endpoint in a JSON body (each null when unknown); GET carries no body. To go live a flow needs: at least one active trigger; a non-empty dmMessage (1-640 characters); at most 3 buttons, each with a title of at most 20 characters and, for url buttons, a valid http(s) url; and, if commentReply is on, reply texts that are not blank, fit the platform's comment length, and use no variable other than {{mention}}. To remove every trigger from an active automation, pass an empty triggers array and set isActive to false on the flow in the same call: an active automation must have at least one trigger, so clearing them on its own is rejected. To remove a single trigger, send a new triggers array with the specific trigger removed. To pause or resume a trigger without any other changes to the flow, use blotato_update_automation_trigger.

blotato_update_automation

Turn one trigger of a DM automation on or off. It takes effect immediately on an active automation. At least one trigger for a flow must stay active if the flow is active. Enabling a trigger on an inactive automation does not activate the automation. On an active automation, matching events can send the configured DMs to contacts on Instagram/Facebook, reply publicly to the comments that trigger it, and call its configured webhook without another tool call. Every webhook method except GET shares the contact's email address and follower status with the configured endpoint in a JSON body (each null when unknown); GET carries no body. Trigger IDs are subject to change whenever a flow is updated. Always use the trigger IDs as provided by blotato_update_automation, or re-list using blotato_list_automations to get the latest IDs.

blotato_update_automation_trigger

Update a scheduled post. You can change the post content, the scheduled time, or both. At least one field must be provided. The scheduled time must be a valid ISO 8601 date string and must be in the future. When the scheduled time is changed, the post is re-queued for publishing at the new time. To update the post content, provide post as a complete replacement draft. accountId, platform, and text are required. Call blotato_get_schedule first to retrieve the existing draft, then map its content and target settings into the same fields used by blotato_create_post. Include every media URL, thread item, and platform-specific setting you want to retain: omitted fields within post are not preserved, and omitted mediaUrls defaults to []. Omit post entirely to change only the scheduled time. IMPORTANT: Call blotato_list_schedules first to get the schedule ID. Call blotato_list_accounts to get the accountId and platform-specific required fields. The platform field must match the account's platform (e.g. "twitter" for a Twitter account). mediaUrls accepts an array of publicly accessible URLs (images, videos). Use [] for text-only posts. For Instagram and LinkedIn carousels, pass multiple image URLs. additionalPosts is an optional array for creating threads on Twitter, Bluesky, and Threads. Each item has { text, mediaUrls }. The main text/mediaUrls become the first post, and additionalPosts become subsequent posts in the thread. Platform-specific fields (pass alongside accountId, platform, text): Twitter: no extra fields needed. Supports threads via additionalPosts. Bluesky: no extra fields needed. Supports threads via additionalPosts. Threads: optional replyControl (everyone|accounts_you_follow|mentioned_only). Supports threads via additionalPosts. Facebook: requires pageId (from blotato_list_accounts subaccounts). Optional: mediaType (reel|story), link for link previews, firstComment (posted as the first comment after publishing; not for stories; useful for links). LinkedIn: optional pageId for company pages (from blotato_list_accounts subaccounts). Omit pageId to post to personal profile. Instagram: optional mediaType (reel|story), collaborators (array of usernames without @), altText, coverImageUrl, shareToFeed, audioName, firstComment (posted as the first comment after publishing; not for stories; useful for links). TikTok: requires privacyLevel (SELF_ONLY|PUBLIC_TO_EVERYONE|MUTUAL_FOLLOW_FRIENDS|FOLLOWER_OF_CREATOR), disabledComments (bool), disabledDuet (bool), disabledStitch (bool), isBrandedContent (bool), isYourBrand (bool), isAiGenerated (bool). Optional: title, autoAddMusic, isDraft, imageCoverIndex, videoCoverTimestamp. Pinterest: requires boardId. How to get it: https://help.blotato.com/api/accounts#pinterest. Optional: title, altText, link. YouTube: requires title, privacyStatus (public|private|unlisted), shouldNotifySubscribers (bool). Optional: isMadeForKids, containsSyntheticMedia.

blotato_update_schedule