# Welcome to Blotato! ## What is Blotato? Your all-in-one AI content workspace to create and distribute viral posts and faceless videos, and turn one piece of content into many. I built Blotato to help me teach 10 million people AI and distribute 150+ pieces of content per week. New to Blotato? Watch the [Blotato Beginner Tutorial](https://youtu.be/o5GsAxEX-Bk) for a step-by-step walkthrough. ## The Problem Blotato Solves Producing high-quality content, consistently, while growing on multiple platforms. Without paying for multiple tools that don't talk to each other. ## Key Features and Benefits * Easily turn content into posts across multiple platforms. For example, turn a Youtube/TikTok video into an Instagram post or Twitter thread; or, turn multiple articles into a YouTube script. * Generate high-quality faceless AI images, videos, and voices. * Schedule and publish posts in advance to all platforms. * Track trending viral posts and never run out of ideas. ## Results? I grew my personal brand from 0 to 1,300,000+ followers in 15 months WITHOUT: a team, budget, VA, paid ads, masterminds, courses, coaches, consultants, agencies, prior existing audience, and prior social media experience. ## Who is Blotato For? * Solopreneurs * Content creators * Small business owners * Social media marketers * Digital marketing agencies *** ## :point\_down::point\_down: Get Started Now! Make Your First 5 Posts :point\_down::point\_down: # Make Your First 5 Posts {% embed url="" %} If you are new to Blotato and want a complete walkthrough, watch the [Blotato Beginner Tutorial](https://youtu.be/o5GsAxEX-Bk). ## Login Log into Blotato: [https://my.blotato.com](https://my.blotato.com/) Once you're in, you'll be taken to the dashboard where you can start creating content. *** ## Add Context To generate content, provide Blotato with any topic or piece of context. Add it under **Context** in the left sidebar of the [AI Agent](https://my.blotato.com/agent): ✅ Website or article ✅ YouTube video ✅ TikTok video ✅ Podcast ✅ Audio file ✅ PDF ✅ Perplexity AI prompt ✅ Paste in any text Let's say you want to create social media posts based on a YouTube video: 1\. Copy the YouTube video link 3\. In blotato, click "+ Add Context" > "Youtube" > paste the link 4\. Click "Add"
*** ## Select Platforms and Create Posts Blotato publishes to: ✅ Instagram ✅ LinkedIn ✅ Facebook ✅ Threads ✅ TikTok ✅ Twitter ✅ Bluesky ✅ Youtube ✅ Pinterest 1. Open the [AI Agent](https://my.blotato.com/agent). 2. Confirm your source material is selected under **Context** in the left sidebar of the AI Agent. 3. Type: "Using my context, create five posts for Instagram, LinkedIn, Facebook, Threads, and TikTok. Adapt each post to the platform." 4. Press **Enter**. 5. Wait for the five draft cards to appear. Once generated, edit the draft posts to match your voice and brand. Use Chat on the right side for quick edits and brainstorming, such as: * Remove unnecessary formatting (like asterisks or extra spaces). * Insert a direct quote from the context (especially useful for YouTube videos). * Research 30 viral hooks related to my post. * Regenerate drafts to get many variations.
*** ## Add Images or Videos Visuals often boost engagement, and Blotato makes it easy to add them. Platforms like Tiktok, Instagram, and Youtube REQUIRE your post to have images/videos. You can: ✅ Upload your own images or videos. ✅ Generate AI-powered images or videos. Click **Photo / Video** to add images or videos:
If you want an eye-catching image for your LinkedIn post, click "Generate Realistic Image", and Blotato will make one in a few moments. If you don’t like the first result, click "Regenerate" to get a new variation or click "Edit Prompt" to edit the AI image prompt. *** ## Publish or Schedule Your Posts Once you're satisfied with your drafts: 1. Click a draft card. 2. Select at least one social account in the **Schedule** panel. 3. Choose **Now**, **Pick a time**, or **Next free slot time** under **Scheduling for**. 4. Select a date and time when you choose **Pick a time**. 5. Click **Publish Now** or **Schedule**. Once published, your posts move to the "Published Posts" screen. Track them there. *** ## Reuse a Post Across More Platforms To publish the same content to more social accounts without rewriting it: 1. Open the original draft in the [AI Agent](https://my.blotato.com/agent). 2. Select each connected social account in the **Schedule** panel. 3. Choose **Now**, **Pick a time**, or **Next free slot time**. 4. Select a date and time when you choose **Pick a time**. 5. Click **Publish Now** or **Schedule**. The Schedule panel lists accounts already connected to Blotato. If an account or platform is missing: 1. Open [Settings > Social Accounts](https://my.blotato.com/settings). 2. Connect the missing account. 3. Return to the draft in the AI Agent. 4. Select the account in the **Schedule** panel. If the original draft is no longer available, click **New post** and paste the original text into the blank draft. ## Different Platform Character Limits Selecting several accounts does not rewrite one caption for each platform. Blotato checks the caption against each platform's character limit. A caption accepted by LinkedIn or Facebook might be too long for Threads or a standard X account. To create a shorter version: 1. Open the draft in the AI Agent. 2. In the Chat panel on the right, ask Blotato to shorten the post for the target platform. 3. Review the shorter version. 4. Schedule it to the account with the lower character limit. For example, finalize a longer LinkedIn version for LinkedIn and Facebook. Then ask Chat to shorten it for Threads or X. See [Social Platform Requirements](/tips-and-tricks/social-platform-requirements) for each platform's limits. *** ## Saved Draft Posts All draft posts are automatically saved by Blotato. Draft posts are tied to the browser where you created them, so drafts made on your laptop will not appear on your phone or another computer. Scheduled and published posts are visible from any device. See: [Why don't my drafts show up on my phone?](/support/faqs#why-dont-my-drafts-show-up-on-my-phone-i-made-drafts-on-my-laptop-and-they-are-not-on-my-other-device) To start a blank draft, click **New post**. To generate a draft from your context, type a prompt in the chat box at the bottom of the [AI Agent](https://my.blotato.com/agent).
*** ## Bonus Tips for Better Content Quality * **Personalize Your Posts:** AI-generated content is a great starting point, but adding your own insights, experiences, and opinions makes your content way more authentic and stand out. * **Use Platform-Specific Formatting:** LinkeiIn posts may benefit from bullet points, while Instagram captions should include engaging hooks and hashtags. Experiment a lot and observe what the top creators in your industry are having success with. * **Experiment With Different Styles:** If a draft post doesn’t feel right, regenerate it using different prompts to see what works best. I personally generate at least 5 drafts, then choose the best one and start tweaking it. # Understanding Context {% embed url="" %} Context is the raw material you use to generate social media post drafts. Add a YouTube video, article, or PDF as context, then Blotato uses AI to turn that content into post drafts for each platform. Context and drafts are different: * **Context** = raw materials (videos, articles, PDFs, text) stored locally in your browser * **Drafts** = social media posts generated from your context. Drafts are tied to the browser where you created them and do not carry across devices — see [Why don't my drafts show up on my phone?](/support/faqs#why-dont-my-drafts-show-up-on-my-phone-i-made-drafts-on-my-laptop-and-they-are-not-on-my-other-device) Here's a step-by-step guide to using context effectively in Blotato: ## Context Supported Click "+ Add Context" at the top of the left sidebar in the [AI Agent](https://my.blotato.com/agent). To generate rich well-researched posts, focus on the QUALITY of each context item! Here is all the context currently supported by Blotato: * **Text:** Copy and paste any relevant text from articles, notes, or documents. * **Articles & Websites:** Input the website URL and Blotato will extract the text content. * **YouTube & TikTok:** Add a link, and Blotato will extract the transcript. The video must have **English captions (subtitles)** for transcript extraction to work. Transcript extraction only reads English, so a non-English video, or a video with no captions, fails with an "error fetching" message. For those videos, copy-paste the content as Text instead. Note: Facebook Reel and Instagram URLs are not supported as video context — use Text or Articles instead. * **Audio, Podcasts, & Meeting Recordings:** Upload audio files to extract useful content. * **PDFs:** Upload PDF documents, ebooks, research papers, case studies, etc. * **Perplexity AI:** Research any topic by using Perplexity's AI-powered real-time web search. > :bulb: The quality of your context directly affects your final output — use reliable, well-structured context for the best results. Garbage In, Garbage Out. > :warning: Context is stored locally in your browser and is NOT saved across devices. If you switch from laptop to phone, your context will not transfer over. *** ## Toggling Context On/Off Once you've added context, toggle each item on or off based on relevance. Only the toggled-on items will be used when you generate a new post or re-generate an existing post. 🚀 Pro Tip: If you're overwhelmed adding context, start by adding ONE high-quality item. I personally don't often use more than 2-3 context items. A SINGLE high-quality piece of context can be used to generate many diverse posts. *** ## Saving Sources to Your Sources Library The Sources library is not a media library. It stores saved context for AI Agent content generation, not reusable images or videos for posting. To attach your own media to a post, follow [How do I upload my own video or image to schedule a post?](/support/faqs#how-do-i-upload-my-own-video-or-image-to-schedule-a-post) By default, context is stored locally in your browser and does not carry across devices. To keep a source across sessions, save it to your Sources library: 1. Open the [AI Agent](https://my.blotato.com/agent). 2. In the left sidebar, click the source you want to keep. 3. Check the "Save Source?" box. 4. The source now appears in your [Sources library](https://my.blotato.com/sources). To save more sources, repeat these steps for each one. The Sources page has no separate "add" button — you save sources from the AI Agent sidebar. *** ## Workaround for Paywalled or Inaccessible Websites Blotato can only extract the visible text from websites that are publicly accessible. Paid articles are not supported. Here's a workaround if adding the website URL does NOT work: * Manually copy and paste the website's text. * Add it as "Text" context. *** ## Research Any Topic with Perplexity AI If you're not sure what context to use, let Perplexity do the research for you! :point\_right: Add "Perplexity" as context. 🔍 Type any prompt (e.g., “latest AI trends”) 📜 Blotato uses Perplexity AI to research the web. *** ## Custom Instructions to Pre-process Each Context Item "Custom Instructions" allow you to apply a prompt to each context item before generating your final content. When using multiple context items, custom instructions helps AI prioritize key information – ensuring only the most impactful data, statistics, or insights are used to write your posts. Example: if you're using a long Youtube video as context, a custom instruction like *“Extract the top three takeaways”* ensures the post remains concise and valuable. If you have multiple context items, I highly recommend using custom instructions. They lead to **higher-quality content by instructing AI to focus on what's important.** *** ## Examples of Custom Instructions Here are some examples of custom instructions. | Purpose | Custom Instruction | | ------------------------------ | ---------------------------------------------------------------------------------------------- | | Extract Main Content Only | Ignore sidebars, ads, and navigation menus; extract only the core article or video transcript. | | Summarize Key Points | Generate a concise bullet-point summary of the most important insights from the context. | | Highlight Actionable Tips | Identify and list any actionable tips or strategies mentioned in the content. | | Emphasize Quotes | Extract and highlight impactful quotes, ensuring they’re clearly formatted and attributed | | Conversational Rewrite | Rephrase the source material in a friendly, conversational tone suitable for social media. | | Create a Step-by-Step Guide | Break down the content into a simple, numbered process or checklist. | | Focus on Data-Driven Insights | Prioritize statistical data and research findings. | | Format for Readability | Reformat the content into short, digestible paragraphs with subheadings where applicable. | | Identify Trends and Patterns | Highlight any emerging trends or recurring themes mentioned in the context. | | Generate FAQs | Based on the content, produce a list of potential FAQs with brief answers. | | Extract Problem/Solution Pairs | Identify any problem statements and their corresponding solutions, listing them side-by-side. | | Focus on Expert Opinions | Extract and emphasize expert opinions, including any credentials or references. | | Emphasize Urgency | Highlight any points that suggest urgency or immediate action, framing them as timely advice. | | Data Exctraction | Extract only the most shocking facts and numerical data. | # Content Calendar Setup {% embed url="" %} Managing social media content efficiently can be exhausting. But with Blotato, you can plan your content in advance, schedule posts, and maintain a consistent online presence without having to manually post each day. In this step-by-step guide, we’ll walk you through setting up your Blotato content calendar, scheduling posts across various platforms, and troubleshooting common issues. ## Navigate to Calendar Your content calendar is the foundation of your scheduling process. It allows you to plan posts across different platforms at optimal times for engagement. * On the left-hand menu in Blotato, navigate to "Calendar". * If you’re using Blotato for the first time, you’ll see "No upcoming posts scheduled." * You’ll need to configure your slot schedule for posting.
*** ## Setup Slot Schedule ### Create Slot Schedule A schedule ensures that you have designated time slots for different platform posts. * Go to [Schedule Slots](https://my.blotato.com/queue/slots) * You will see available time slots for each social media platform. Example: *You have a LinkedIn post slot at 8:23 AM on Monday.*
### **Add New Slots** If you want to add a new posting slot: * Click "+ Add Slot" * Select the time of day and days of the week for your slot * Choose the social media platforms for this slot *** ## Enabling Slots for Different Platforms Within the slot schedule, you can click on the icons for each platform to enable slots for that platform. Enabling a slot for a platform means that at the specified time, you have an available slot for posting content to that particular platform. For instance, you can enable slots for Twitter, Threads, TikTok, and Blue Sky at a specific time on a particular day. This allows you to customize your posting schedule according to your content strategy and target audience for each platform
*** ## Schedule Post Now that your calendar is ready, schedule a post: 1. Open the [AI Agent](https://my.blotato.com/agent). 2. Click the draft card you want to schedule. 3. Select at least one social account in the **Schedule** panel. 4. Select **Next free slot time** under **Scheduling for**. 5. Click **Schedule**. Review scheduled posts in [Upcoming Posts](https://my.blotato.com/queue/schedules). *** ## Managing Scheduled Posts You can easily view, edit, and delete scheduled posts. "Upcoming Posts" shows all your scheduled content. ### Edit Scheduled Post To make quick text-only edits while keeping the post scheduled, click the post in Upcoming Posts and edit the text. To edit the media (images, videos) or make larger changes, move the post back to Drafts first. See [Move Scheduled Post Back to Drafts](#move-scheduled-post-back-to-drafts) below.
### Reschedule Scheduled Post Reschedule updates the date and time only -- the post stays scheduled. From Upcoming Posts: 1. Click the three-dot menu on the post 2. Click "Reschedule" 3. Pick a new date and time in the modal 4. Click "Save" From Calendar (BETA): 1. Click on the scheduled post 2. Click "Reschedule" 3. Pick a new date and time in the modal 4. Click "Save" ### Move Scheduled Post Back to Drafts Move to Drafts brings the post back to your Drafts so you can edit anything -- text, media, platforms, or the schedule. 1. Select the upcoming post in Upcoming Posts 2. Click the three-dot menu on the right 3. Click "Move to Drafts" The post returns to the AI Agent where you can change media or keep working on it before publishing again. ### Delete Scheduled Post Click "Delete" to delete a scheduled post. To delete multiple posts at once, select the posts you want to remove in the "Upcoming Posts" list, then click the red bulk delete button at the bottom of the screen. ### Delete an Already-Published Post Once a post is on the social platform, Blotato can no longer remove it. Open the social platform directly and delete the post there. **TikTok exception**: do NOT delete posts on TikTok. Instead, change the post's privacy to "Private" to hide it. Deleting hurts your TikTok account's algorithm; hiding preserves account health. See [TikTok Best Practices](/platforms/tiktok/best-practices-playbook#your-main-account). ### Posted to the Wrong Account? If Blotato published to a different connected account than you intended: 1. Delete (or hide, on TikTok) the post on the social platform itself — Blotato cannot remove already-published posts. 2. Go to **Settings → Social Accounts** to verify which account is currently connected to each platform. 3. To prevent recurrence, see [Connecting to the wrong account?](/support/faqs#how-do-i-connect-multiple-social-accounts-connecting-to-the-wrong-account). *** ## Viewing Published Posts To view all of the posts you've published, go to the "Published Posts" screen in the left sidebar menu. You can filter by platform, or search by keywords:
*** ## Troubleshooting Posts that Failed to Publish If a post fails to publish, go to the "Failed Posts" screen. Each failed post will display error details explaining why it didn’t get published.
The most common reasons for posts failing to publish are:: 1. **Expired Social Media Account Connection** * Social platforms require you to reintegrate 3rd-party apps periodically for security * Go to "Settings" → click "Login with \" to reconnect the platform 2. **Unsupported Media Size** * Ensure that your images and videos meet a platform's specifications. * Example: If you try to post a non-standard video size to Tiktok, it will likely fail, whereas the 9:16 vertical format is a standard accepted aspect ratio. * To fix this, ensure your images or videos match the platform’s preferred aspect ratios. Upload a correctly formatted media file and reschedule the post. After fixing the issue, click "Move to Drafts" to bring the post back to the AI Agent, so you can try to publish it again.
*** By following these steps, you can efficiently organize and schedule content using Blotato. With a well-planned content calendar, scheduled posts, and the ability to troubleshoot failed posts, maintaining an active social media presence becomes much easier. > :bulb:Pro tip! Spend a few hours each week to batch-create posts and schedule them in advance. This will keep your content strategy consistent and free up your time for other important tasks. *** ## Manage Your Calendar via API You can manage your entire content calendar programmatically -- list, update, reschedule, and delete scheduled posts, and configure recurring time slots. * [Scheduled Posts API](/api/schedules) -- list, update, and delete scheduled posts * [Schedule Slots API](/api/schedule-slots) -- create and manage recurring time slots * [Calendar Management Recipes](/api/workflows) -- pseudocode and examples # Error Reference This page contains all Blotato error messages and their explanations. Use your browser's search function (Ctrl+F or Cmd+F) to find your specific error. ## API Errors | Error | Explanation | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization failed - please check your credentials | Double check your Blotato API key. Use the n8n/Make official Blotato nodes for easier setup. You don't have to worry about copy/pasting IDs or raw JSON code. See tutorial: | | Wrong Blotato API Key | Check you've copied the API key correctly without whitespaces. Use the official Blotato n8n/Make nodes for easier setup - you won't need to hardcode API keys manually. See tutorial: | | URL is empty | The URL being passed is empty. Check that previous step finished creating your video/carousel. Increase WAIT time if needed and verify you have enough credits (check with `GET /v2/credits`). | | Wrong Account ID | Use the official Blotato n8n/Make nodes - you can select accounts from a dropdown instead of copying IDs manually. See tutorial: . If not using official nodes: Check you've copied the social account ID correctly from Settings > Social Accounts. | | Account \[ID] not found | The accountId in your request does not exist for the user/workspace behind your API key. Use the official Blotato n8n/Make nodes to avoid ID errors -- select accounts from a dropdown instead of copying IDs manually. Install guide: . If you are using MCP or an AI coding tool, your AI tool handles account lookup automatically. Point it to: | | Wrong Page ID | Facebook requires both Account ID and Page ID. Check you've copied Page ID correctly using the "Copy Page ID" button. | | The setting for future activity history off Meta technologies is not in Account Center anymore | Meta is replacing **Your activity off Meta technologies** with **Activity from Other Businesses**. Update the setting, then reset and relink Facebook or Instagram in Blotato. Follow the [Meta connection steps](/settings/social-accounts#error-your-activity-off-meta-technologies-is-missing). | | Invalid File Format | Check your file format is valid per social platform requirements. | | Invalid Video Dimensions | Video dimensions not supported by platform. Test with this sample video: | | reached\_active\_user\_cap | Account not properly warmed up. Follow warm-up guide before connecting to Blotato. | | You Ran Out Of AI Credits | Go to Settings > Billing to check and add credits. Via API or MCP, check your balance with `GET /v2/credits` and buy more with `POST /v2/credits` (`blotato_buy_credits`) -- see [Credits API](/api/credits). | | Image or video stuck on "generating" indefinitely | This is not a credits issue. The generation silently failed. Refresh the page and try again. If it persists: create a new video instead of regenerating the stuck one. Check your [API Dashboard](https://my.blotato.com/api-dashboard) for error details. If you have credits but the generation hangs, do not assume credits are the problem. | | 500 Internal Server Error on visual creation | A server-side error occurred. This is not a credits issue. Check your [API Dashboard](https://my.blotato.com/api-dashboard) for the error details. Retry after a few minutes. If using Claude Code or MCP, verify your template ID and inputs are valid. | | Media conversion failed | The media file could not be converted to the format required by the target platform. Common causes: 1) Wrong aspect ratio for Instagram (must be 1:1, 4:5, 1.91:1, or 9:16). 2) Resized templates producing non-standard dimensions. 3) Too many hashtags (Instagram rejects posts exceeding its hashtag limit during media processing). 4) Unsupported codec -- use H.264 MP4 format. Check [Social Platform Requirements](/tips-and-tricks/social-platform-requirements) for each platform's specs. | | ClientError: Command failed: ffprobe ... Invalid data found when processing input | The media file itself could not be read -- it is corrupt, incomplete, or not a real video/image file. This often happens when the media URL returned an error page or a truncated download instead of the actual file. This is not a TikTok/Instagram outage and not a credits issue. Re-export or re-download the media, upload a fresh copy (or pass a direct public media URL), then retry from Failed Posts. See: [Troubleshooting Posts that Failed to Publish](/features/content-calendar/tutorial#troubleshooting-posts-that-failed-to-publish) | | Could not publish on Instagram: An unexpected error has occurred | This error comes from Instagram/Meta, not Blotato. Troubleshooting steps: 1) Check the [API Dashboard](https://my.blotato.com/api-dashboard) for the full error. 2) Reconnect your Instagram account in [Settings > Social Accounts](https://my.blotato.com/settings). 3) Verify the media URL is publicly accessible (open in incognito). 4) Reduce hashtags and caption length. 5) Increase time between posts. If the error persists after reconnecting, submit a support ticket with the reqId from the error message. | | Unsupported media format (.mov) | Blotato requires H.264 MP4 format for video publishing via API. The .mov format is not supported even if the file is under size limits. Convert your video to H.264 MP4 before uploading or passing via mediaUrls. | | Account \[ID] not found (LinkedIn) | For LinkedIn company pages, you need both an accountId and a pageId. A common mistake is passing the pageId where accountId is expected. Use `GET /v2/users/me/accounts` to get the accountId, then `GET /v2/users/me/accounts/{accountId}/subaccounts` to get the pageId. Pass accountId in `post.accountId` and pageId in `post.target.pageId`. See: [Accounts API](/api/accounts) | | 503 Service Unavailable | The social platform or a connected service is temporarily down. This is usually a platform-side outage, not a Blotato issue. Wait a few minutes and retry. If the error persists, check the platform's status page. | | 504 Gateway Timeout | The request took too long and timed out. This happens when the social platform does not respond within the allowed time. Retry after a few minutes. If it keeps happening, reconnect the account in [Settings > Social Accounts](https://my.blotato.com/settings). | | Wrong Template Parameters | Each video template has different parameters. Check API docs for correct template parameters. | | Missing AI Voice | POV template doesn't include AI voice. Use empty template ID for AI voiceover. | | Missing Music | Add autoAddMusic: true parameter in PUBLISH TO TIKTOK step for music. | | Wrong Heygen API Key and IDs | Check you've copied HEYGEN AVATAR ID correctly, not the Avatar GROUP ID. | | You're On Heygen Free Plan | HeyGen API requires $99/mo API plan. Free API plan won't work. | | Your Avatar Has a Background | Set matting to false and remove background section for default avatar background. | | Invalid JSON Error | Validate JSON at jsonlint.com and compare with Blotato API docs. | | The service is receiving too many requests from you | Rate limit exceeded. Upload Media: 30 requests/minute. Publish Post: 30 requests/minute. | | Exceeded rate limits (repeated YouTube or LinkedIn publish failures) | The platform is rate-limiting publishing for your connected account. Wait an hour and retry from [Failed Posts](https://my.blotato.com/failed). If posts keep failing with this error after waiting, reconnect the social account in [Settings > Social Accounts](https://my.blotato.com/settings), then retry the post -- a stale connection token keeps triggering the platform's rate limiter. | | Unsupported media format: mov,mp4,m4a,3gp,3g2,mj2 (X/Twitter or LinkedIn post failed) | Misleading error text -- your file format is usually fine. The real failure is most often video duration: X (Twitter) requires between 0.5 and 140 seconds, and if Blotato has to convert the video it must be under 120 seconds. Check the video length first and trim if needed. If length is fine, pre-encode to the platform's exact spec (H.264/AAC MP4) so no conversion runs. See [Social Platform Requirements](/tips-and-tricks/social-platform-requirements) and [X FAQs](/platforms/faqs). | | The aspect ratio is not supported | Video aspect ratio not supported by platform. Check platform requirements. | | body/template/id must be equal to constant | Pass template object with id. See API examples for correct format. | | scenes.0: missing object | Incorrect JSON format for scenes array in CREATE VISUAL node. Each template has a specific scenes format -- find your template's exact format with examples at [Visual Templates](https://help.blotato.com/api/visuals). To debug: (1) Select template in n8n/Make, (2) Remove ALL parameters including Prompt, (3) Run the step, (4) Check [API Dashboard](https://my.blotato.com/api-dashboard) to see the exact JSON structure your template expects. | | slides.image: must be at most 400 characters | The image field expects a short public URL (e.g. ), not a base64 string or data blob. Keep image URLs under 400 characters. | | mediaURL is null or empty | Video not done. Increase wait time or check if you have AI credits (`GET /v2/credits`). | | Cannot read properties of undefined (reading 'mediaUrl') | You're trying to publish before the visual/video is finished rendering. After your Create Visual step, add a Get Visual step and wait until the status is "done", then map the mediaUrl into the Publish step's Media URLs field. If the visual creation failed or you ran out of AI credits, the mediaUrl will never be produced. | | Cannot read properties of undefined (reading 'status') | The social platform (Instagram, TikTok, etc.) did not return a response. This is usually a temporary issue. Wait a few minutes and retry. If the error persists, check that your media file is in a supported format: [Social Platform Requirements](/tips-and-tricks/social-platform-requirements). In the web app, retry from the [Failed Posts](https://my.blotato.com/failed) screen. | | Failed to upload stream to Supabase | The media file could not be saved to storage. Common causes: the source URL is not publicly accessible, the URL points to a preview page instead of the direct file, the file is too large, or the media file is corrupted. Open the media URL in an incognito browser window to verify it downloads directly. If using Google Drive, use a direct download link, not a /view link. | | Could not upload media to storage | Same underlying cause as "Failed to upload stream to Supabase" above. Blotato fetched the URL in your `mediaUrls` but could not read it as a media file, almost always because the file is not reachable rather than broken. Check: 1) The URL is publicly accessible -- open it in an incognito window and confirm it downloads the raw file instead of a login or preview page. 2) It is not a Google Drive or Dropbox share link -- those open a preview page, so use a direct download link (`https://drive.usercontent.google.com/download?id=FILE_ID&export=download&confirm=t`). 3) The file is within your plan's upload size cap ([Plan Limits](/settings/billing-and-credits#plan-limits)). For local files, use the [Presigned Upload](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) flow and publish with the returned `publicUrl`. | | Failed to fetch media URL: char '...' is not expected.:1:1 (often shown in n8n alongside "Deserialization error: to see the raw response, inspect the hidden field {error}.$response on this object.") | Blotato downloaded the URL in your `mediaUrls`, but the response was not binary media -- it was plain text (the first character of that text shows up in the error, e.g. `e` for "expired" or "error..."). Open `{error}.$response` in n8n to read the actual body the URL returned. Common causes: 1) Signed URL expired before Blotato fetched it (Canva exports, S3 presigned URLs, Google Drive). 2) URL points to a preview page or folder, not a direct file (e.g. Google Drive `/view`). 3) Auth or CDN bot protection on the host. Fixes: For Google Drive use `https://drive.usercontent.google.com/download?id=FILE_ID&export=download&confirm=t`. For Canva, pass the export URL directly into `mediaUrls`. For local files, upload via Blotato's presigned upload flow and publish using the returned `publicUrl`. If you uploaded the video directly from your computer (no external URL) and the post keeps failing with this error, the stored file reference is bad -- retrying alone does not fix it. Re-upload instead: 1) move the failed post back to Drafts, 2) remove the current video and upload the MP4 again so it gets a clean file reference, 3) reschedule the post. Also confirm the file is a standard MP4, not corrupted, and within your plan's upload size limit ([Plan Limits](/settings/billing-and-credits#plan-limits)). Different case -- the media was generated BY Blotato: if the failing URL points to Blotato's own hosting (for example a `...r2.dev/pipeline/...` or `database.blotato.io` link from a video Blotato created) and a plain retry sometimes publishes the same post with no changes, the cause is on Blotato's side -- the media fetch timed out (most common with larger files), not your URL or your workflow. Retry the post from [Failed Posts](https://my.blotato.com/failed). If the same post keeps failing after several retries, contact support in the in-app chat with the post link so the team investigates. See: [Posts failing with "Could not fetch media"](/api/mcp/examples#posts-failing-with-could-not-fetch-media). | | Please review our URL ownership verification rules | TikTok rejects certain URLs. Try using a different hosting service for your media, or use the optional Blotato Upload endpoint first: | | Tiktok's servers may be experiencing issues. This is a retryable error | TikTok server issue or posting too frequently. Wait and retry. | | Could not refresh TikTok access\_token: Service Unavailable | TikTok's servers temporarily rejected the token refresh. Wait 15-30 minutes and retry. If the error persists, reconnect your TikTok account in [Settings > Social Accounts](https://my.blotato.com/settings). | | JSON value expected but got '<' at position 0 (TikTok) | TikTok's API returned an HTML error page instead of a JSON response. This is a temporary TikTok server issue (outage, rate limiting, or maintenance). Your post payload is valid. Retry after a few minutes. If it keeps failing, reconnect your TikTok account in [Settings > Social Accounts](https://my.blotato.com/settings). | | Threads API Feature Not Available: This user does not have access to this Threads API feature | Link Instagram account to Threads. Warm up Threads account for a few days with posts before connecting to Blotato. | | Failed to read media metadata. Is the file accessible and a valid media file? | Three causes, in order of likelihood: 1) **File not publicly accessible.** Open the URL in an incognito browser and confirm it downloads the raw file. For Google Drive, set the file to "Anyone with the link" as Viewer and use a direct download URL: `https://drive.usercontent.google.com/download?id=FILE_ID&export=download&confirm=t` 2) **The file host throttles or interferes with server-side fetches.** Hosting behind GoDaddy, Cloudflare, or similar CDN/bot protection can slow or garble Blotato's server-to-server download enough that metadata reading fails, especially on larger files (tens of MB) -- even when `curl` from your machine returns HTTP 200 with `content-type: video/mp4`. Fix: move the file to a host without bot protection (a public S3/GCS bucket or similar), or switch to the [Presigned Upload](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) flow, which handles large binaries via direct PUT and skips the URL fetch entirely. Also confirm the file is within your plan's upload size cap: 400MB on Starter, 1GB on Creator and Agency ([Plan Limits](/settings/billing-and-credits#plan-limits)). 3) **Intermittent metadata-reader flake.** If the exact same call on the same small file passes sometimes and fails other times, the URL is not the problem. Wrap `/v2/media` in a 2-attempt retry with a 3-second delay, or switch to presigned upload, which runs through a different code path and avoids the issue entirely. | | Google Drive virus scan warning popup blocking media access | Google Drive sometimes returns a warning page instead of the file for large videos. Blotato does not impose a 100 MB Google Drive cutoff. First, share the file as "Anyone with the link" and use `https://drive.usercontent.google.com/download?id=FILE_ID&export=download&confirm=t`. If Google Drive still returns the warning page, use the [Presigned Upload](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) flow, frame.io, AWS S3, or Google Cloud Storage. Check your [Blotato plan limit](/settings/billing-and-credits#plan-limits) and the destination platform's [media limit](/api/publish-post/media) separately. | | Base64 data is too large, maximum size is 20MB | This error happens when uploading media larger than 15MB via the n8n Upload "Binary Data" option. Switch to URL-based upload: use the [Presigned Upload](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) endpoint to upload directly to Blotato, or host on AWS S3/GCP and pass the URL. See: [Plan Limits](/settings/billing-and-credits#plan-limits) for more details on max upload sizes. | | Visual creation fails or images are blank when using self-hosted image URLs | Your server's firewall or CDN (e.g., Cloudflare) is blocking Blotato from fetching your images. Blotato's servers make server-to-server requests to download media, which bot-protection rules block. Add a firewall rule to allow these requests, or host your images on a service without bot protection (e.g., a public S3 bucket, Imgur, or the Blotato [Upload endpoint](https://help.blotato.com/api/api-reference/upload-media-v2-media)). Test accessibility with `curl ` from another server. | | Error posting to Instagram: No error |

I've noticed a recent glitch with Instagram API that sometimes returns "No Error" and video rejected, but this looks like an issue on IG side, as I haven't changed anything on the Blotato side. I'll keep monitoring it, but I generally recommend the following:

  • reduce the number of hashtags
  • reducing the length of caption
  • increasing time between posts
| | Error posting to Instagram: An internal server error occurred | A brief temporary outage of Instagram's API, not a Blotato issue. Blotato auto-retries the post 2 times. If it still failed, the outage lasted longer than a few minutes -- wait a few hours and retry from [Failed Posts](https://my.blotato.com/failed). See [Instagram FAQs](/platforms/instagram/faqs#why-did-my-post-fail-with-error-posting-to-instagram-an-internal-server-error-occurred). | | Instagram rejected your post | The account is hitting Instagram's spam and bot-risk checks. Log into the Instagram account daily for the next week and scroll the feed for about 10 minutes like a normal user, and space out posts instead of retrying in a rapid loop. See [Instagram FAQs](/platforms/instagram/faqs#why-does-instagram-keep-rejecting-my-posts-instagram-rejected-your-post). | | The user has not authorized application (Instagram/Facebook) | The Meta access token for the account is no longer valid -- tokens go stale when they expire, get revoked (password change or security refresh), or the Blotato app was removed from Business Integrations. Newly released features like comments and messaging also require updated permissions. Fix: go to [Settings > Social Accounts](https://my.blotato.com/settings), click Reconnect on the account, and approve the Meta popup with the Instagram account and its linked Facebook Page both checked. | | Could not publish on Instagram: Error validating access token: Sessions for the user are not allowed because the user is not a confirmed user | This error comes from Instagram/Meta. The Instagram account session is not confirmed. To fix: 1) Log into the Instagram account in a browser and complete any pending prompts (email/phone confirmation, security checkpoints, updated terms). 2) Reconnect the account in Blotato: go to Settings > Social Accounts, disconnect and reconnect using an incognito browser logged into only that Instagram account. 3) Verify the account is a Professional or Business account (personal accounts have issues with third-party publishing). See: | | Instagram allows a maximum of 5 hashtags per post | This is a Blotato guardrail, not an Instagram rule. Instagram itself allows more hashtags, but Blotato caps posts at 5 on purpose because more than 5 hashtags reduces your reach on Instagram, TikTok, and Facebook. Fix: trim your caption to 5 hashtags or fewer and republish. See [hashtag rules by platform](/tips-and-tricks/social-platform-requirements#hashtags) and [how many hashtags to use](/support/faqs#how-many-hashtags-should-i-use). | ## Source / Ingestion Errors | Error | Explanation | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TikTok video has no captions / transcript extraction failed | Blotato extracts the transcript from TikTok videos to use as a source. If the TikTok video has no captions (subtitles), Blotato cannot pull the transcript. Try a different TikTok video that has captions, or copy-paste the video's content as a Text source instead. | ## Connection Errors | Error | Explanation | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 Session Error Connecting Instagram Account | Sometimes connection succeeds despite error. Test with a post first. If not, use incognito browser, log out of other accounts, log into only the target account, then reconnect. | | "No LinkedIn pages found for this account" | Not an error. This message appears in the **Select LinkedIn pages** window after your LinkedIn sign-in succeeds. It means the signed-in profile has no company Pages where it holds the **Super Admin** or **Content Admin** role. Analyst, Curator, Paid Media Admin, Recruiting Poster, and collaborator roles do not expose Pages to Blotato. Your personal LinkedIn profile remains connected. See: [LinkedIn FAQs](/platforms/linkedin/faqs) | | Unable to connect LinkedIn company page (a Page you administer is missing from the list) | Open the Page on LinkedIn and go to **Admin tools > Manage admins**. Confirm your profile has the **Super Admin** or **Content Admin** role. Ask a Super Admin to update your role if needed. After the role changes, use an incognito browser, log into LinkedIn, then Blotato, and connect the Page. If your role stays unchanged, ask a Super Admin or Content Admin to connect the Page to Blotato. | | YouTube Unauthorized error | Use incognito browser. Log into YouTube, then Blotato. Reconnect account. Update YouTube account ID in automation workflows. | | Unable to connect social account (general) | Use incognito Chrome browser. Log into social account first, then Blotato. Connect account. | | invalid\_grant (Instagram/Meta) | The Instagram/Meta authorization token expired. Go to [Settings > Social Accounts](https://my.blotato.com/settings), find the Instagram account, and click Reconnect. This error often causes follow-on "mediaUrl" TypeErrors -- fix the token first. | | Account requires reconnect | The account's authorization token expired, or the account requires some other manual reconnect/confirmation. Go to [Settings > Social Accounts](https://my.blotato.com/settings), click Reconnect on the Instagram account, then retry your request. | | invalid\_grant (Claude Cowork / MCP) | Your Blotato MCP OAuth connection expired. In Claude, open **Customize > Connectors**, remove and re-add the Blotato custom connector, and re-approve access via OAuth. This is separate from reconnecting a social account. See: [MCP Setup](/api/mcp/setup) | | Blotato shows "Connected" in Claude Settings, but Claude.ai returns an OAuth error when asked to list accounts | Blotato API and MCP require a paid subscription. Go to [Settings > API](https://my.blotato.com/settings/api) and click "Generate API Key" to activate your paid subscription. | ## Comments Errors | Error | Explanation | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Comments not available for this post's platform (error code 20200) | The post you tried to comment on is on a platform Blotato does not support comments for. Comments work on Instagram and Facebook Page posts only. Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, and YouTube are not supported. See [Comments API](/api/comments). | | Comment failed to post (error code 20201) | The social platform rejected the comment. Check the comment's `errorMessage` for the reason. Common causes: the parent post was removed, the comment triggered the platform's spam rules, or the account lost comment permissions. Reduce how often you comment and retry. See [Comments API](/api/comments). | | Active contacts limit reached (error code 20101) | You reached the maximum active contacts for your plan this month by replying to audience comments (Starter 1,000, Creator 6,000, Agency 15,000). Your count resets at the start of next month. Upgrade your plan to raise the limit. See [Comments API](/api/comments). | ## Messaging Errors | Error | Explanation | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Active contacts limit reached (error code 20101) | You reached the maximum active contacts for your plan this month by messaging new people. Your count resets at the start of next month. Upgrade your plan to raise the limit. See [Active Contacts](/settings/billing-and-credits#active-contacts). | | Message failed to send (error code 20102) | The social platform rejected the message. Check the message's `errorMessage` for the reason. Common causes: the 24-hour messaging window closed, the comment you replied to is invalid or already received a private reply, or the account lost messaging permissions. See [Messages API](/api/messages). | | Your Instagram account has expired / Your Facebook account has expired (error code 5002) | The connected account's authorization expired, so the message never reached the platform. Reconnect the account. See [Connection Errors](#connection-errors). | ## DM Automation Errors | Error | Explanation | | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No connected Instagram account / No connected Facebook account (error code 5000) | The account the automation runs on is disconnected or expired. Reconnect it in [Settings > Social Accounts](https://my.blotato.com/settings), then publish the automation again. | | Automation is invalid (error code 20303) | The automation is missing something it needs to go live: a trigger, message text of 1 to 640 characters, a valid `http(s)` URL on every button, a message on every gate you turned on, or a valid `http(s)` URL on the webhook. Fix the flagged field and publish again. See [DM Automations API](/api/dm-automations). | | Follow gate requires an Instagram automation (error code 20303) | A follow gate runs on Instagram only. Remove it from the Facebook automation, or rebuild the automation on an Instagram account. See [Follow Gate Object](/api/dm-automations#follow-gate-object). | | Request URL must be http(s) / Request URL resolves to a private address / Could not resolve request URL (error code 20304) | The automation webhook failed. Blotato calls public `http(s)` endpoints only and rejects private, loopback, link-local, and cloud metadata addresses. Point the webhook at a public URL, confirm the domain resolves, and confirm the endpoint answers inside 10 seconds. Blotato does not follow redirects, so use the final URL. See [Webhook Object](/api/dm-automations#webhook-object). | | Your subscription is not active. DM automations are paused until you reactivate. (error code 20300) | The run stopped because your Blotato subscription is not active. Reactivate your plan in [Settings > Billing](https://my.blotato.com/settings/billing). | | You have reached the maximum active contacts for your plan this month (error code 20101) | The DM the automation tried to send hit your plan's monthly active-contacts limit, so the run failed. Wait for the monthly reset or upgrade your plan. See [Active Contacts](/settings/billing-and-credits#active-contacts). | A DM automation that fails after the message is queued reports the platform error on the run, not on the request. Open the automation in [Automations](https://my.blotato.com/dm-automations), or call [List Runs](/api/dm-automations#list-runs), and read the run's `error`. The codes match the messaging errors above. A run stuck on a follow gate until it expires usually means button taps are not reaching Blotato. Blotato subscribes your account to button-tap events at connect time, so an account connected before DM automations and follow gating landed does not reliably receive them. Reconnect the account in [Settings > Social Accounts](https://my.blotato.com/settings). Instagram also renders the confirm button in the mobile app only, so ask for a typed reply in the gate message for desktop readers. Blotato runs the follower check on any reply. A run showing `expired` is not an error. It means the person never answered a follow gate or an email gate inside the 1-hour window, so nothing further sent. A run showing `superseded` means a newer run started waiting on the same person. A webhook endpoint answering with a non-2xx status does not fail the run. Blotato records the status in the run logs and the run still completes. ## Platform-Specific Errors | Error | Explanation | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Post failed to publish. Could not upload video | Each platform has different requirements for video uploads. Check that your video follows the requirements here: | | Could not upload media to \[platform] (e.g. "Could not upload media to Twitter"), same message on every platform | The platform rejected the media Blotato tried to upload. This is not a rate-limit or credits problem, and retrying the same media without changes will not help. Open the specific failed post in [Failed Posts](https://my.blotato.com/failed) (web app) or the [API Dashboard](https://my.blotato.com/api-dashboard) (API) to read the exact per-post error, then follow the matching steps in this reference. Common causes: the media does not meet the platform's format or size specs ([Social Platform Requirements](/tips-and-tricks/social-platform-requirements)), or a stale connection -- reconnect the account in [Settings > Social Accounts](https://my.blotato.com/settings) and retry. When the same message appears on every platform at once, check each post's error separately, because the cause can differ per platform. | | Video duration exceeds the maximum convertible duration of N seconds | Your video required conversion (resizing, re-encoding, bitrate adjustment, etc.) to meet the platform's format requirements, but the video is too long to convert. Blotato caps video conversion at 2 minutes, even when the target platform allows longer videos. To fix: 1) Trim your video to under 2 minutes; or 2) Pre-encode your video to match the platform's specs exactly (correct codec, aspect ratio, resolution, bitrate) so no conversion is needed. Check [Social Platform Requirements](/tips-and-tricks/social-platform-requirements) for each platform's specs. | | The user has exceeded the number of videos they may upload (YouTube) | YouTube upload limit reached. Wait 24 hours. Check API quota in Google Cloud Console. Verify account. | | You have reached the maximum number of 10 posts for the last 24 hours for this account (YouTube) | YouTube enforces a limit of 10 uploads per channel per 24 hours via API. Wait 24 hours and try again, or upload directly via the YouTube website. This is a YouTube limit, not a Blotato limit. | | You have reached the maximum number of 25 posts for the last 24 hours for this account (Facebook) | Facebook publishing is limited to 25 posts per 24 hours per Page. Each Page has its own independent limit. Wait 24 hours and try again, or publish to a different Page. | | You have reached the maximum number of 50 posts for the last 24 hours for this account (LinkedIn) | LinkedIn publishing is limited to 50 posts per 24 hours per profile and per company Page. Each profile and company Page has its own independent limit. Wait 24 hours and try again, or publish to a different profile or company Page. | | Unsupported picture size (TikTok) | TikTok rejects images that do not meet its format requirements. TikTok accepts WebP and JPEG only (no PNG). Max resolution: 1080 pixels. Max file size: 20 MB per image. Convert PNG images to JPEG before posting. Full specs: [Social Platform Requirements](https://help.blotato.com/tips-and-tricks/social-platform-requirements#tiktok) | | TikTok views consistently < 50 | Account likely shadowbanned. Start fresh with new account. | | TikTok views consistently \~200 | TikTok doesn't know your video topic. Use niche keywords in title, description, and audio. | | Single TikTok video stuck at low views | Change video privacy to PRIVATE, close app, reopen, switch back to EVERYONE. | | TikTok account banned | Account not warmed up properly. Follow warm-up guide. Don't post more than 3x/day via API. Stay active on account. | | body.post.target must have required property 'isYourBrand' or 'isBrandedContent' | Both fields are required on every TikTok post sent through the REST API, including the n8n and Make.com nodes. Put them inside the `target` object, not `content`. There is no default -- send both explicitly, even when both are false. Set `isYourBrand: true` when the post promotes your own brand, and `isBrandedContent: true` for a paid partnership. See [Publish Post](/api/publish-post). | | Escape Multi-Line Paragraphs error | Long text with linebreaks needs escaping. In n8n use toJsonString() function. | | Brand New Account error | Account not warmed up. Don't connect 3rd party apps until account is established with manual posts. | | Sorry! This site doesn't allow you to save Pins. | This error is from Pinterest. Two common causes: 1) The website indicated they do not want to be pinned. 2) Pinterest's blocklist flagged your URL (often a false positive). Workaround: append parameters to your link (e.g., `?ref=pin&v=111`) so Pinterest sees it as a new URL that bypasses the filter. | | Pinterest API access is temporarily restricted to verified accounts only | Your Pinterest still looks pretty new. You MUST warm it up for 2 weeks before connecting to 3rd party posting tools like Blotato. Failing to do this often results in being shadowbanned or flagged by Pinterest. Start posting 1 pin per day manually, then gradually ramp up to 2, then 3, etc. pins per day. Once you get 100+ views per month, reconnect your Pinterest account with Blotato and it will be automatically verified. If your Pinterest account already has 100+ monthly views, do not keep warming it up. Go to [Settings > Social Accounts](https://my.blotato.com/settings), click **Reconnect** on the Pinterest account, then retry the publish. | | Could not create Pinterest pin (no specific reason shown) | This is the generic wrapper Blotato shows when Pinterest rejects the pin without a readable reason. Open your [API Dashboard](https://my.blotato.com/api-dashboard) and click the failed request to read the exact Pinterest error response for that pin, then match it to the specific Pinterest rows above (permission, blocked URL, or verification). If the failure starts across all your Pinterest accounts at once while manual pinning still works in the Pinterest app, it points to a temporary Pinterest API issue on Pinterest's side rather than your account or link -- check the API Dashboard for the exact response and retry later. | | Error posting to Facebook: (#200) requires pages\_read\_engagement and pages\_manage\_posts permission (the full message may also mention "If posting to a group..." and "requires both pages\_read\_engagement and pages\_manage\_posts as an admin with sufficient administrative permission") | Facebook Page permissions are incomplete or partially authorized, or you do not have a full Admin role on the Page. Blotato publishes to Facebook **Pages** only -- it cannot post to Facebook **Groups** or personal profiles. Go to [Settings > Social Accounts](https://my.blotato.com/settings), click Reconnect for your Facebook account. In the Meta permissions popup, select "Opt in to current Pages only" and check each Page individually. Confirm you have a full **Admin** role on the Page (an Editor, Advertiser, or Analyst role is not enough) -- [check your Page role](https://www.facebook.com/help/510247025775149). If the Page still fails, remove the Blotato app from Meta Business Suite (Settings > Accounts > Apps) and reconnect fresh. See: [Facebook Connection Guide](/settings/social-accounts/facebook) | | Please reduce the amount of data you're asking for, then retry your request (may also appear as "Could not upload video to Facebook: ...") | Facebook/Meta API server-side error -- not a Blotato bug. It is more common on larger Pages or groups, often around 5,000+ followers, because Facebook may run out of memory while processing the publish request, and it can affect any post type (text, image, link, or video). Retry publishing the post -- it often succeeds on a later attempt. First check the Facebook Page, because the post can sometimes publish successfully even though the API reports a failure. If it did not publish, wait a few minutes and retry from [Failed Posts](https://my.blotato.com/failed). If the post uses Page mentions, try removing the mention and adding it manually later on Facebook. If the error persists across multiple retries over an hour, submit a support ticket via in-app chat with the post ID, timestamp, and Facebook Page follower count. See: [Facebook Errors](/platforms/facebook/errors) | | Error posting to Instagram: We restrict certain activity to protect our community. | Instagram made a final decision based on risk/spam scores. To fix: 1) Reduce the number of hashtags. 2) Reduce your caption length. 3) Increase time between posts. 4) If none of the above works, try posting manually to warm up your account and prove to Instagram you're not a bot. | | Cannot read properties of undefined (reading 'mediaUrl') | This Instagram-specific error has multiple causes: 1) Expired Instagram token -- check for `invalid_grant` errors in your [API Dashboard](https://my.blotato.com/api-dashboard) and reconnect the account in [Settings](https://my.blotato.com/settings). 2) The `content.mediaUrls` array is empty or contains URLs that are not publicly accessible. 3) In n8n/Make workflows, the node upstream of the Publish node is not outputting a media URL -- verify the Create Visual step completed with status "done". Fix the token first, as expired tokens cause this error most frequently. | | Instagram encountered a temporary error while publishing your post. Please try again in a few minutes. (error code 20003) | Instagram returned a temporary error while Blotato published the post. Blotato retries on its own before reporting this. Wait a few minutes and retry from [Failed Posts](https://my.blotato.com/failed). The message ends with a reference ID. Include it when you contact support if the post keeps failing. | | Instagram server media processing timed out. Please try submitting the post again in a few minutes. (error code 20003) | Instagram accepted the media but did not finish processing it within 20 minutes, so Blotato stopped waiting and the post did not publish. Submit the post again in a few minutes. The message ends with a reference ID. Include it when you contact support if the post keeps failing. | | Could not publish on Instagram: Unsupported post type. The post has too little or too many attachments to qualify as a carousel | Via API, Instagram supports a maximum of 10 images or videos per carousel. See: | | This user is not allowed to post a video longer than 2 minutes (X/Twitter 403 Forbidden) | Two causes: 1) Free X accounts are limited by X to 2-minute videos -- posting longer videos requires X Premium. 2) X Premium accounts also hit this error when Blotato has to convert the video, because Blotato caps video conversion at 2 minutes regardless of your X plan. Fix for X Premium accounts: pre-encode your video to match X's specs exactly (H.264 video codec, AAC audio codec, MP4 container) so Blotato skips the conversion step and uploads the file as-is -- then X Premium's longer video limit applies. Full specs: [Social Platform Requirements](/tips-and-tricks/social-platform-requirements#twitter) | | You are not permitted to perform this action (X/Twitter 403 Forbidden) | Twitter/X authorization expired or permissions changed. Go to [Settings > Social Accounts](https://my.blotato.com/settings), find your Twitter account, and click Reconnect. Re-authorize the app when prompted. Retry your post after reconnecting. | | You are not allowed to create a Tweet with duplicate content (X/Twitter 403 Forbidden) | X/Twitter rejects posts with identical text to a previous tweet on your account. Change the caption text (even slightly) before reposting. If you scheduled the same post twice by accident, delete the duplicate from [Upcoming Posts](https://my.blotato.com/queue/calendar). | | Post published twice / duplicate post | A timeout during publishing caused Blotato to retry, resulting in two posts on the social platform. Delete the duplicate from the social platform. If this happens repeatedly, submit a support ticket with the post URLs and timestamps. | | Bluesky posts publish without images (API) | Known bug affecting image attachments to Bluesky posts via API. The post publishes but images are missing. Contact support via in-app chat for status updates. | | Unsupported picture size (TikTok) | TikTok rejected the image. Ensure the image is in JPEG or WebP format (not PNG), under 20 MB, and max 1080 pixels resolution. See: [Social Platform Requirements](/tips-and-tricks/social-platform-requirements#tiktok) | | The parent job ... cannot be replaced. addJob | This error comes from the internal media conversion queue when multiple publish attempts try to use the same job ID instead of creating a new one. Common causes: 1) Your automation runs parallel publish attempts for the same post, 2) WAIT time too short - previous conversion still in progress, 3) Publishing before mediaURL/asset is ready. Fix: In n8n/Make automations, ensure only one publish attempt runs at a time and wait for mediaURL to be ready before publishing. Check API Dashboard for the exact failed request details. | | Failed to publish TikTok post after 3 retries (Unknown error reason) | Temporary TikTok-side outage, not a Blotato issue and not a credits issue. Retrying immediately or reconnecting the account usually will not help, and a public status page will not always show it (some outages affect only certain regions or posts from external URLs). Wait a few hours and retry from [Failed Posts](https://my.blotato.com/failed). If several recent TikTok posts fail at once, message in-app chat support to confirm a known TikTok outage and receive +3000 credits for the inconvenience. | | TikTok post disappears and never appears (stuck "buffering," not in Failed Posts) | The post leaves Upcoming Posts, then never shows on TikTok, in Published Posts, or in Failed Posts, with no request in the [API Dashboard](https://my.blotato.com/api-dashboard). This is a TikTok-side issue processing videos from external URLs -- the post stays stuck in "publishing" so TikTok never returns success or failure, which is why it does not land in Failed Posts. Not a credits or Blotato queue issue, and can affect only certain regions (for example, European accounts). Wait a few hours, then repost with a longer lead time. Message in-app chat support with the account name and scheduled time to confirm a known TikTok outage and receive credits. See: [TikTok FAQs](/platforms/tiktok/faqs). | | Error uploading images to Tiktok: Please notice the user to update their TikTok to the latest version to enable this functionality | This error comes from TikTok on image and carousel (photo) posts, and it appears even when the TikTok app is already up to date. On the phone connected to that TikTok account: update the TikTok app, open it once and log in, force close, reopen, then go to Profile > Settings and privacy > Free up space and clear the cache. Retry from [Failed Posts](https://my.blotato.com/failed). If it persists, click the blue Reconnect button next to TikTok in [Settings > Social Accounts](https://my.blotato.com/settings). If it still keeps returning, ask in the in-app chat for the team to remove the TikTok account from the database, then connect it fresh with Login with TikTok. If one TikTok account works while another keeps failing, the block sits on that specific TikTok account. See: [TikTok FAQs](/platforms/tiktok/faqs#my-tiktok-post-fails-with-a-message-saying-i-need-to-update-tiktok). | | Scheduled posts disappear at publish time (no error, not in Failed Posts) -- YouTube, Facebook, Instagram | The scheduled post vanishes at its publish time: it does not publish, does not fail, and leaves no record in Failed Posts. In the server logs this shows up as the post's media failing to download at publish time, for example "ClientError: Failed to fetch media URL: 400 Bad Request" -- the publish job dies before TikTok/YouTube/Facebook ever receives the post, so no Failed Posts record is created. It is not a rate-limit or credits issue. Fix: re-upload the media fresh instead of rescheduling the same post (the stored file reference is bad), and confirm the file is a standard MP4, not corrupted. Steps: [re-upload a failing video](/support/faqs#my-scheduled-post-keeps-failing-with-a-media-fetch-error-but-i-uploaded-the-video-from-my-computer). If posts keep vanishing, message in-app chat support with the account name and scheduled times so the team checks the publish logs for the exact error. | | Post shows "published" but does not appear on the platform | The social platform accepted the post but later delayed or suppressed it. Wait 10-15 minutes, then check the post URL from [Published Posts](https://my.blotato.com/queue/calendar). If the URL returns 404, the platform removed it (spam filter, account health). Reduce posting frequency and engage organically. | | Could not schedule post: No available slot time found in the next 9 months (also shown as "in the next year") | No schedule slots exist for the platform/account you are scheduling to. This appears in the web app when you pick **Next free slot time**, and via API when you set `useNextFreeSlot: true`. Slots live on the [Schedule Slots](https://my.blotato.com/queue/slots) page, not the Calendar page. In the web app: open [Schedule Slots](https://my.blotato.com/queue/slots), click "+ Add Slot", pick a day and time, and assign the slot to the exact platform/account you are posting to. Each slot is platform-specific -- a slot for "Instagram" does not match a LinkedIn post, so create slots for every platform you schedule to. See: [Schedule Slots API](/api/schedule-slots) | | Post shows CANCELED | CANCELED is a post status, not a publishing error. A post is marked canceled when its schedule was removed before it published: the scheduled post was deleted, moved back to drafts in the calendar, or removed via `DELETE /v2/schedules/:id` through the API. Nothing failed on the social platform, and it is different from FAILED (a permanent publishing error). If you meant the post to go out, open it and schedule it again. | ## Plan Limit Errors These errors are returned when you exceed one of your Blotato plan limits. For the full table of limits per plan, see [Plan Limits](/settings/billing-and-credits#plan-limits). | Error | Explanation | | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You have reached the maximum number of connected accounts (N) for your plan. Please disconnect some accounts or upgrade your plan. | You hit the connected-accounts cap for your plan. Disconnect an account in [Settings > Social Accounts](https://my.blotato.com/settings) or upgrade. Each connected Facebook Page counts toward the limit (the Facebook login does not), and for LinkedIn your profile plus each connected company Page count. See: [Plan Limits](/settings/billing-and-credits#plan-limits) | | You have reached the maximum number of scheduled posts (N) for your plan. Please remove some scheduled posts or upgrade your plan. | You hit the queued-scheduled-posts cap. Delete upcoming posts from [Upcoming Posts](https://my.blotato.com/queue/calendar) or upgrade your plan. See: [Plan Limits](/settings/billing-and-credits#plan-limits) | | Scheduled time is too far in the future. | Your scheduled time is past your plan's horizon. Pick a time within your plan's window or upgrade. See: [Plan Limits](/settings/billing-and-credits#plan-limits) | | File exceeds the maximum upload size (N MB) for your plan. Upload a smaller file, or upgrade your plan to increase your max upload size. | Your media file is larger than your plan's upload cap. Compress or trim the file, or upgrade. See: [Plan Limits](/settings/billing-and-credits#plan-limits) | ## Account Limits | Platform | Limit | Explanation | | --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | TikTok (Starter Plan) | 3 unique accounts per 24h, 10 posts per account | Limit applies to Starter plan only. Creator and Agency plans unrestricted. | | Instagram | 50 posts per day per account | Hard limit per 24-hour window. | | LinkedIn | 50 posts per 24h per profile and per Page | Your profile and each connected company Page each have their own independent 50-post limit. | | Pinterest | 10 pins per day per account | Auto-verified by Blotato when you reconnect, provided your Pinterest has 100+ monthly views from a 2-week manual warm-up (1 pin/day ramping to 3/day). | | Facebook | 25 posts per 24h per Page; 5 per day per Page recommended | Each Page has its own independent 25-post limit, so posts to one Page do not count against another. Posting above 5 per day per Page also negatively impacts post reach. | | YouTube | 10 uploads per channel per 24h via API | YouTube-enforced limit. New channels may have lower quotas. Upload via YouTube website to bypass. | For full details on platform posting limits, see: ## App Errors | Error | Explanation | | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application error: a client-side exception has occurred while loading my.blotato.com | This is almost always a browser issue, not your account. Start with a hard refresh. If it persists, follow the full checklist in [App Won't Load (client-side exception)](#app-wont-load-client-side-exception) below. | ## Troubleshooting Steps ### App Won't Load (client-side exception) If you see "Application error: a client-side exception has occurred while loading my.blotato.com" (often after a few loading screens, and you cannot log in), it comes from your browser, not your Blotato account. Work through these steps in order: 1. Refresh the page first. This clears it more often than you would expect. 2. Open [my.blotato.com/login](https://my.blotato.com/login) in an incognito window, logged out of other accounts. 3. Still stuck? Try a different browser or your phone to see if the issue is only on one device. 4. Turn off ad blockers and privacy extensions (uBlock, Ghostery, and similar), then reload. 5. Clear site data for blotato.com only: click the padlock by the URL, open Site settings, click Clear data, then log in fresh. 6. If none of that helps, open the browser console when the error shows (right-click the page, Inspect, Console tab), screenshot it, and send it to support through the in-app messenger. ### General Connection Issues 1. Open incognito Chrome browser 2. Log out of all other accounts 3. Log into target social account only 4. Log into Blotato 5. Connect account ### API Issues 1. Check your [API Dashboard](https://my.blotato.com/api-dashboard) - click on any request to see the full payload, error response, and which account it was sent to 2. Verify API keys copied correctly without spaces 3. Check you have sufficient AI credits (`GET /v2/credits`) 4. Validate JSON at jsonlint.com 5. Compare your request with API documentation ### Account Health Issues 1. Warm up new accounts manually for several days 2. Post organically before connecting to Blotato 3. Stay active on account (reply to comments, engage) 4. Don't exceed platform posting limits 5. Use platform-appropriate content formats # Community Forum Blotato weekly office hours have ended. For help, use these support channels: * In-app support: click the orange circle button inside [Blotato](https://my.blotato.com) to send a message * Help docs: browse [help.blotato.com](https://help.blotato.com) for guides and FAQs Past office hours recordings are available [here](https://drive.google.com/drive/folders/16PhBNOtAuSplp50Hv1VknO8Pgcu-3TKw?usp=sharing). # Get Support ## Support channels for all plans: * **Messaging:** inside Blotato, click the orange circle button to send a support message * **Email:** *** ## Community Forum Blotato weekly office hours have ended. See [Past Office Hours & Recordings](/support/weekly-office-hours) for recordings and current support channels. *** ## Do you do 1:1 calls? I no longer offer 1:1 onboarding calls or monthly strategy calls. To get started, follow this guide to make your first 5 posts: [Make Your First 5 Posts](/start/posts) # FAQs ## How do I get back to the main page? Click the Blotato logo in the top left corner from any screen. This takes you back to the home page. You can also use the left sidebar to navigate between sections (New post, Published, Calendar, Videos, Settings). The sidebar is collapsed by default and expands when you hover over it. *** ## Don't know where to start? The best place to start is the [Blotato Beginner Tutorial](https://youtu.be/o5GsAxEX-Bk). It shows how to use the Blotato AI Agent. The AI Agent is located at [my.blotato.com/agent](https://my.blotato.com/agent). It learns your brand, remixes YouTube and TikTok videos, and helps you post to many platforms in a few clicks. To start in the web app: 1. Watch the [Blotato Beginner Tutorial](https://youtu.be/o5GsAxEX-Bk). 2. Open the [Blotato AI Agent](https://my.blotato.com/agent). 3. Add your brand details in [Brand Kit](/settings/brand-kit). 4. Add a YouTube video, TikTok video, or other source under **Context**. 5. Ask the AI Agent to create posts from your source. 6. Select your social accounts and publish or schedule your posts. Many Blotato users also combine Blotato with Claude or ChatGPT. This setup is more powerful, but takes about 30 minutes to set up. If you want that workflow, watch the [Blotato + Claude setup tutorial](https://youtu.be/mh4Z9U-oaps). The video shows Claude Cowork, but the steps are the same for the [Claude.ai](https://Claude.ai) website. *** ## Where is the AI Agent screen? The AI Agent is in the left sidebar. The sidebar is collapsed by default -- hover over it to expand, then click "New post." You can also go directly to: [my.blotato.com/agent](https://my.blotato.com/agent) *** ## My screen is blank and only shows "What would you like to do?" / I can't see my calendar or settings Type anything into the prompt box and press Enter. This takes you into the full AI Agent. This screen is not broken or blank. The "What would you like to do?" screen is the AI Agent prompt screen, not an error. 1. Type anything into the prompt box, then press Enter. 2. You go straight into the full AI Agent at [my.blotato.com/agent](https://my.blotato.com/agent). 3. To reach Calendar, Videos, or Settings, hover over the left sidebar to expand it, or click the Blotato logo in the top left. *** ## The options from the tutorials don't exist / "New post" only opens a basic chat / I can't add media or generate an AI image The chat IS the starting point -- the AI Agent creates your posts from what you type. The other options appear once a draft exists, or live on other screens: 1. To write a post: type what you want to make into the chat and press Enter. The agent creates a draft post, which appears as a tab you edit directly. 2. To add media to a post: open the draft and click **Photo / Video**. 3. To generate AI images, carousels, or videos: go to [Videos](https://my.blotato.com/videos), click "Create New Video," and pick a template. Image templates (Quote Card, Infographic) make images instead of videos. 4. Wrong brand selected? Set up or edit your brands in [Brand Kit](https://my.blotato.com/settings/brand), then pick the brand you want on the draft. *** ## I click "New post" but the draft is blank and nothing generates from my context The pencil **New post** button creates a blank draft canvas for manual writing. Older tutorials call this button **+ Add Post**. It does not generate content from your selected context. To generate real drafts from your context, use the chat box instead: 1. Go to the [AI Agent](https://my.blotato.com/agent) 2. Confirm the context you want is toggled on in the left sidebar 3. Find the chat box at the bottom of the screen (placeholder text like "Write posts about...") 4. Type a prompt, for example: "Using my context, create one LinkedIn post and one Facebook post. Adapt each to the platform's style and length." 5. Press the send arrow Blotato generates one draft per platform from your selected context. Use **New post** when you want a blank draft. *** ## How do I go back to the old Blotato (the previous version where I paste source text and it makes up to 5 posts)? The older "remix" screen is still available. Two ways to reach it: 1. Click **View old remix screen** in the left sidebar of the [AI Agent](https://my.blotato.com/agent). This opens the previous version at [my.blotato.com/remix](https://my.blotato.com/remix), where you paste your source text and generate up to 5 posts. 2. To stay in the current version, click **CHAT** in the top-right corner and describe your posts to the Blotato AI Agent. The remix screen does not apply your [Brand Kit](/settings/brand-kit), so use the AI Agent for on-brand content. If you are learning how to use the AI Agent, watch the [Blotato Beginner Tutorial](https://youtu.be/o5GsAxEX-Bk). *** ## Blotato posts the same text to every platform — how do I get a different post for each social site? When you publish one draft to several platforms, Blotato sends that draft's text to each one. To get a separate post per social site, use one of these: 1. In the [AI Agent](https://my.blotato.com/agent), name the platforms in your prompt so Blotato generates one draft per platform. Example: "Using my context, create one LinkedIn post and one Facebook post. Adapt each to the platform's style and length." 2. Open a draft and use the **Chat** panel on the right to adapt or shorten the text for a specific platform. 3. To paste your idea and generate up to 5 posts at once, like the previous version, open the old remix screen at [my.blotato.com/remix](https://my.blotato.com/remix). Click **View old remix screen** in the left sidebar of the AI Agent to reach it. See [How do I go back to the old Blotato](#how-do-i-go-back-to-the-old-blotato-the-previous-version-where-i-paste-source-text-and-it-makes-up-to-5-posts). The remix screen does not apply your [Brand Kit](/settings/brand-kit). *** ## Where are my generated images and videos? All visuals you generate — images, carousels, videos, infographics, slideshows — are saved at [Videos](https://my.blotato.com/videos), regardless of how you created them (web app, API, or MCP). If you can't find a visual, go directly to [my.blotato.com/videos](https://my.blotato.com/videos) and look for your recent creations there. To download or publish a visual, click on it in the Videos library to open the editor. *** ## What are the AI Agents in Blotato? Blotato has two ways to create with AI: 1. **AI Agent** — the main agent at [my.blotato.com/agent](https://my.blotato.com/agent). Chat to write posts and captions and to create visuals, using your [Brand Kit](/settings/brand-kit). 2. **Video AI Agent** — generates AI videos and image carousels from templates. Go to [Videos > New](https://my.blotato.com/videos/new) and choose "Create Everything with AI Agent." *** ## My post shows "published" but does not appear on the platform Platforms sometimes delay surfacing new posts, or suppress them after accepting the upload. This is common when uploading video content. 1. Wait 10-15 minutes -- some platforms delay new posts before they appear in feeds 2. Check your [API Dashboard](https://my.blotato.com/api-dashboard) or [Published Posts](https://my.blotato.com/queue/calendar) for the post URL 3. Open the post URL directly -- if it returns a 404, the platform removed it after accepting the upload 4. If posts are consistently suppressed, reduce posting frequency and engage with your account organically for a few days If Blotato shows "published" with a valid post URL, the post was delivered to the platform. Removal or suppression after delivery is a platform-side action. *** ## My posts show CANCELED — are they failing? No. CANCELED is a post status, not a publishing failure. A post is marked canceled when its schedule was removed before it published: * The scheduled post was deleted from the calendar * The post was moved back to drafts * The schedule was removed via the API (`DELETE /v2/schedules/:id`) Nothing went wrong on the social platform. CANCELED is different from FAILED, which is a permanent publishing error. If you meant the post to go out, open it and schedule it again. *** ## Which social platforms does Blotato support? Blotato publishes and crossposts to: Instagram, TikTok, LinkedIn, Facebook, X (Twitter), Threads, Bluesky, Pinterest, and YouTube. This list is exhaustive for the Blotato web app, API, MCP, and Cowork. Blotato does not publish to platforms outside this list. ## Is Substack supported? Substack is not a supported platform. You cannot crosspost to Substack from Blotato -- not in the web app, the API, or via MCP/Cowork. ### Unofficial workaround for Substack Notes Blotato does not officially support this method, and Substack does not officially allow automated posting, so you use it at your own risk. You build and run it yourself, outside Blotato. 1. Open Substack in your browser with Claude for Chrome 2. Post a Note on Substack manually 3. Ask Claude to reverse engineer the network request Substack sends when you post the Note 4. Replicate that request in your own automation tool, such as n8n 5. Send your Note content through that request to post programmatically For the account types supported per platform, see [Social Accounts](/settings/social-accounts). *** ## Can I add a blog or publish to WordPress? You cannot connect a blog or WordPress site as a social account in Blotato. The account connection flow is for social platforms only (Instagram, TikTok, LinkedIn, Facebook, X, Threads, Bluesky, Pinterest, and YouTube). To publish to a blog, WordPress, or any other custom destination, use the **webhook** publish target. Blotato sends your post data to a webhook URL you control, and your own automation receives it and posts to your blog. ### Using Blotato API (n8n / Make.com) 1. In the Publish Post node, set the target type to `webhook` 2. Set `url` to your webhook endpoint 3. Blotato sends the post content (text and media URLs) to that URL 4. Your workflow (n8n, Make, Zapier, or a custom endpoint) receives the data and publishes it to WordPress or your blogging platform See: [Publish Post -- Webhook target](/api/publish-post#webhook) *** ## How do I connect my social accounts? 1. Go to [Settings](https://my.blotato.com/settings) 2. Log into the social account you want to connect (in a separate tab) 3. Click the "Login with \[Platform]" button for your platform 4. Approve the permissions For platform-specific instructions and troubleshooting, see: [Connect Social Accounts](https://help.blotato.com/settings/social-accounts) *** ## When do posts publish immediately vs get scheduled? Posts publish **immediately** when: * No scheduling fields are provided (`scheduledTime` and `useNextFreeSlot` are both omitted) * `useNextFreeSlot: true` but no available slots exist in your calendar for that platform Posts get **scheduled** when: * `scheduledTime` is provided (exact time scheduling) * `useNextFreeSlot: true` and available slots exist **Priority order** (if both scheduling options are provided): 1. `scheduledTime` takes priority over `useNextFreeSlot` **Common mistake**: Setting `useNextFreeSlot: true` without setting up any schedule slots at [Schedule Slots](https://my.blotato.com/queue/slots). This causes immediate publishing because no slots are available. To schedule posts: 1. First create schedule slots at [Schedule Slots](https://my.blotato.com/queue/slots) 2. Then use `useNextFreeSlot: true` or provide a specific `scheduledTime` *** ## How do I create an Instagram Reel or TikTok video? There are two ways, depending on whether you already have a video or need Blotato to generate one. ### Option A: Post your own video Use this if you already filmed a video on your phone or have a video file ready. The easiest way is the [Blotato AI Agent](https://my.blotato.com/agent). Upload your video, describe what you want, and crosspost to multiple platforms in a few clicks. The AI Agent writes captions using your [Brand Kit](/settings/brand-kit) and lets you publish to all your platforms at once. You can also use the [AI Agent](https://my.blotato.com/agent) directly: 1. Add Context (your website, a text description, etc.) so Blotato generates relevant captions 2. Type a prompt naming the platforms you want 3. Press **Enter** 4. Edit the generated captions to match your voice 5. Click **Photo / Video** on the post 6. Upload your video file in MP4 format 7. Schedule or publish Note: You do not need to select "media type" or "Reel" anywhere. When you attach a video, Blotato automatically publishes it as a Reel. ### Option B: Generate a video with Blotato Use this if you want Blotato to create an AI video from a script or idea. 1. Open the [Blotato AI Agent](https://my.blotato.com/agent) and describe the video you want 2. The AI Agent generates your video using your [Brand Kit](/settings/brand-kit) for on-brand visuals and copywriting 3. Chat with the AI to make changes -- update text, swap images, change styles 4. For AI video with AI voice, ask the AI Agent for a video with voiceover 5. Click "Export Video" when done 6. Click "Create Post" to publish it as an Instagram Reel or TikTok video You can also create visuals directly in Claude Code and Antigravity: [Watch tutorial](https://youtu.be/3HVH2Iuplqo) *** ## How do I edit my video with prompts? Open the [Blotato AI Agent](https://my.blotato.com/agent) and chat with the AI to create or edit your visuals. The AI Agent uses your [Brand Kit](/settings/brand-kit) and lets you describe changes in plain language -- swap images, update text, change colors, or adjust the style. For manual editing in the video editor: 1. Open the video in the editor 2. Click any GREEN image or video clip 3. Update the prompt in the left panel to describe the new scene 4. Click "Generate" or "Regenerate" to remake that clip 5. Be specific in your prompts -- vague prompts give the AI too much freedom *** ## How do I add audio or music to my content? It depends on the content type: * In the Blotato video editor, click "Audio" in the left sidebar to upload your own music or sounds before exporting your video. See: [Custom Assets](/features/videos/custom-assets) * For AI-generated voiceover, select the 2nd template when creating a new video. This generates AI voice synced to each scene. See: [AI Voiceover & Captions](/features/videos/ai-voiceover-captions) * For TikTok slideshows via API, set `autoAddMusic: true` in the Publish node to add TikTok's recommended music (photo/slideshow posts only). * For Instagram Reels, if your video already has audio it will play when posted. To add a music track before posting, use the Blotato video editor. For single image posts and carousels, music cannot be added through Blotato — publish first, then add music in the Instagram app. * To add trending music to an existing video before posting, use the "Combine Clips and Apply Basic Edits" template. Pass your video and a music URL. See: [How do I add music to my video/reel before posting?](/features/videos/faqs#how-do-i-add-music-to-my-videoreel-before-posting) *** ## How do I add music to Instagram posts, reels, and carousels? **Reels:** If your video already has audio, it will play when posted. To add a music track before posting, use the Blotato video editor — click "Audio" in the left sidebar to upload a music file, then export the video with the audio included. **Single image posts and carousels:** Music cannot be added through Blotato. Publish your post first, then open it in the Instagram app and add music there. Note: TikTok supports auto-adding music via API with `autoAddMusic: true`. Instagram does not have an equivalent. *** ## If I post to Instagram through Blotato, will it also cross-post to Facebook automatically? Yes — if you have Instagram's native "Share to Facebook" setting enabled, posts made through Blotato will still be automatically cross-posted to Facebook by Instagram. This works because the cross-post happens at the Instagram platform level, not at the Blotato level. Blotato posts to Instagram via the API, and Instagram then applies your account's cross-posting settings just like it would for any other post. To enable or disable this: open the Instagram app → Profile → Settings → Account → Sharing to other apps → Facebook. If you want to post to both Instagram and Facebook independently (with different captions or formats), connect both accounts in Blotato and select each one when publishing. *** ## What uses credits and what doesn't? Credits are only used for AI-generated images and videos: Uses credits: * Generating AI images (text-to-image) * Generating AI video clips (image-to-video) Does NOT use credits: * AI voiceover generation * Publishing or scheduling posts * Adding context (YouTube, articles, text) * Generating text captions with AI * Uploading your own images or videos * Using the AI Agent On the free trial, you receive a limited number of AI credits. Each time you click "Generate" on an image or video, credits are spent -- even if you're testing. To check your balance, go to [Settings > Billing](https://my.blotato.com/settings/billing). For a full credit cost breakdown per model, see: [AI Video Credits](/features/videos/ai-video-credits) *** ## How do I buy more credits? AI credits pay for AI image and video generation. If you run low, buy more in two ways. **In the web app:** Go to **Settings > AI Credits and Usage > Buy More Credits**. Credit packs are $6.00 for 1000 credits. **Via the API or MCP:** Check your balance with `GET /v2/credits` (or the `blotato_get_credits` MCP tool), then buy with `POST /v2/credits` (or the `blotato_buy_credits` MCP tool). The API/MCP tool returns a Stripe Checkout link to open in a browser and complete payment. See the [Credits API](/api/credits). Purchased credits are non-transferable between accounts. For how credits work and per-plan monthly amounts, see [Billing & Credits](/settings/billing-and-credits). *** ## How do I upload my own video or image to schedule a post? The easiest way is the [Blotato AI Agent](https://my.blotato.com/agent). Upload your media, describe your post, and crosspost to multiple platforms in a few clicks. You can also upload directly in the [AI Agent](https://my.blotato.com/agent): 1. Open a draft or click **New post** to create a blank draft 2. Click **Photo / Video** on the draft 3. Upload your video or image file 4. Click the draft card 5. Select at least one social account in the **Schedule** panel 6. Choose **Now**, **Pick a time**, or **Next free slot time** 7. Click **Publish Now** or **Schedule** **Photo / Video** attaches your own media to a post. **Context** holds source material Blotato uses to generate draft content. Images and photos are not supported as Context. Supported context types: YouTube video, TikTok video, article/website URL, PDF, audio file, tweet/X post, raw text, and AI web research (Perplexity). *** ## Does Blotato have a media library where I can upload and reuse images or videos? No. Blotato does not have an official media library yet. Images and videos are attached to individual post drafts instead of stored in a reusable media library. To upload your own media: 1. Open the [AI Agent](https://my.blotato.com/agent). 2. Open a draft or click **New post**. 3. Click **Photo / Video** on the draft. 4. Upload your image or video file. The [Sources library](https://my.blotato.com/sources) stores saved context for AI Agent content generation. It is not a media library and does not store reusable post images or videos. *** ## How do I schedule many existing videos across my social accounts? ### Using Blotato Web App 1. Set your posting times in [Schedule Slots](https://my.blotato.com/queue/slots). 2. Open the [AI Agent](https://my.blotato.com/agent). 3. Click **New post**. 4. Click **Photo / Video**. 5. Upload one video. 6. Add the caption for the video. 7. Click the draft card. 8. Select the social accounts in the **Schedule** panel. 9. Select **Next free slot time** under **Scheduling for**. 10. Click **Schedule**. 11. Repeat the steps for each video. ### Using Blotato API (n8n / Make.com) 1. Give each video a public URL. 2. Use the [Media Upload flow](/api/publish-post/upload-media-v2-media) when a video needs a public URL. 3. Fetch your account IDs with [List Accounts](/api/accounts). 4. Submit one Publish Post request for each video and social account. 5. Put the video URL in `post.content.mediaUrls`. 6. Set `useNextFreeSlot` to `true` as a top-level field. 7. Poll each `postSubmissionId` with [Get Post Status](/api/publish-post/get-post). See: [Publish Post](/api/publish-post) *** ## No platforms show up when I try to schedule my post If you loaded a video and caption but no social platforms populate when you try to schedule, you are likely on a screen without the account selector. Reconnecting your social accounts will not fix this -- the accounts are connected, you are on the wrong screen. 1. Open the [Remix screen](https://my.blotato.com/remix) 2. You will see the option to select your social media accounts 3. Select the accounts you want, then schedule your post You can also publish from the [AI Agent](https://my.blotato.com/agent): open your draft post and select the social accounts on the post before scheduling. If no accounts appear on either screen, check [Settings > Social Accounts](https://my.blotato.com/settings) to confirm your accounts show as connected. If your accounts show as connected but no platforms appear on either screen, your browser is blocking the account selector. This happens when cookies or pop-ups are blocked, or a privacy extension is active -- especially if scheduling works on another device (like a phone or tablet) but not on your computer. 1. Allow cookies for blotato.com in your browser settings 2. Disable pop-up and ad blockers for the site 3. Try a different browser or an incognito window *** ## The Schedule button is grey and does not work If the Schedule button looks grey, disabled, or unclickable, the draft post is not open yet. The Schedule panel only appears after you open a draft post. 1. Click on the draft post you want to publish 2. The Schedule panel appears on the right side of the screen 3. Select your social accounts, then click Schedule to pick a time If the panel opens but no social platforms appear, see the FAQ above -- the accounts are connected, you are on a screen without the account selector. *** ## There is no option to select platforms when I generate posts / Clicking Post sends me back to the chat instead of the scheduler Platform selection in the [AI Agent](https://my.blotato.com/agent) happens in two places, neither of which is a separate "select platforms" step before generating: 1. When generating: name the platforms in your chat prompt. Example: "Using my context, create one LinkedIn post and one Facebook post." Blotato generates one draft per platform you ask for. 2. When scheduling: open the draft post. The Schedule panel appears on the right side of the screen -- select your social accounts there, then click Schedule. If clicking Post or Create Post returns you to the chat, the draft is not open yet. Click the draft post tab first, then use the Schedule panel on the right. *** ## How do I get AI to write a caption for my photo? You cannot upload a photo as Context. Context is for text-based content (YouTube links, articles, text, etc.). To get an AI-generated caption for your photo: 1. Go to the [AI Agent](https://my.blotato.com/agent) 2. Add text Context describing what the photo is about 3. Type your request in the chat box at the bottom of the screen to generate a draft post from your text 4. Click **Photo / Video** on the post to attach your photo 5. Edit the caption with Chat as needed *** ## Can I create content in both English and Spanish? Do I need to switch a language setting each time? Yes, you can create content in both languages. There is no language setting or toggle to switch. The output language follows your input: * AI videos: write your script in Spanish and Blotato generates the Spanish voiceover automatically. Spanish is fully supported. * Text posts: the AI Agent writes in whatever language you prompt it in. To publish to both audiences, create two separate posts (one per language) and cross-post each to the matching accounts. For example, publish the Spanish post to your Spanish YouTube channel and the English post to your English channel. You can connect more than one YouTube channel to Blotato. For the full list of supported languages, see [Translate languages](/tips-and-tricks/translate-languages). *** ## Stuck in onboarding? 1. Click "Reveal Full Week" 2. Wait for all 7 days of posts to be created 3. Click "Schedule Week" to enter the app *** ## What are the current plans and pricing? For the most up-to-date pricing and plan details, visit: [blotato.com/pricing](https://www.blotato.com/pricing) Blotato includes AI video generation, AI carousels, AI copywriting, scheduling, and publishing to all platforms. For comparison, [Buffer charges $83/month](https://buffer.com/pricing) for posting to 20 channels, and that covers scheduling and posting only -- no AI content creation, no video generation, no carousels. ![Buffer pricing for 20 channels](/files/J6xMVZ1mq36bkItsoCHm) *** ## How do I get the $50 Trustpilot review reward? Blotato sends a $50 gift card to customers who leave a review on Trustpilot. 1. Write a review for Blotato on Trustpilot 2. Reply in the in-app support chat to let the team know you left a review 3. Sabrina verifies your review and emails your $50 gift card Sabrina handles each reward personally, so allow a few business days for your gift card to arrive. If you already left a review and have not received your gift card, reply in the support chat with the name on your Trustpilot review and the email where you want the gift card sent. *** ## Can I schedule a call, Zoom meeting, or screen-share with the Blotato team? Blotato does not offer Zoom calls, phone calls, or live meetings with customers. All support happens in the in-app chat. The support team guides you step by step in chat instead. Describe what you are trying to do, and share screenshots or screen recordings of where you are stuck. You get the same walkthrough you would get on a call, in writing you keep. *** ## Do you offer done-for-you (DFY) setup? Can someone set up my account for me? Blotato does not offer done-for-you (DFY) setup or a managed onboarding service at this time. You set up and run your account yourself. To get started, follow these resources: 1. Watch the [Blotato Beginner Tutorial](https://youtu.be/o5GsAxEX-Bk) to learn the AI Agent workflow. 2. Open the [Blotato AI Agent](https://my.blotato.com/agent) to create and schedule your first posts. 3. If you want to combine Blotato with Claude or ChatGPT, watch the [Blotato + Claude setup tutorial](https://youtu.be/mh4Z9U-oaps). 4. Message the support team in the in-app chat when you get stuck. The team guides you step by step in writing. See: [Can I schedule a call, Zoom meeting, or screen-share with the Blotato team?](#can-i-schedule-a-call-zoom-meeting-or-screen-share-with-the-blotato-team) *** ## How does the referral program work? / My referral wasn't credited Blotato's referral and affiliate program runs through Tolt. Referrals are tracked and approved automatically, not by hand in Blotato. 1. Share your referral link from your Tolt affiliate dashboard. 2. When someone signs up through your link and completes a paid subscription through Stripe, Tolt tracks the referral and credits you per the program's rules. 3. Commission approval and payout timing are managed in Tolt, so check your Tolt affiliate dashboard for status. A referral does not get credited if the referral link was not used, cookies were blocked, or the purchase did not go through the tracked checkout. If you believe a referral was missed, reply in the support chat with the referred customer's email so the team can check. *** ## How do I start my paid subscription? / How do I pay? You have 2 options to start your paid subscription: 1. Go to [Settings > API](https://my.blotato.com/settings/api) and generate an API key. This will activate your paid subscription. 2. Go to [Settings > Billing](https://my.blotato.com/settings/billing) and click "View Billing Portal" to manage your subscription. *** ## How do I change my plan? 1. Go to [Settings > Billing](https://my.blotato.com/settings/billing) 2. Click "View Billing Portal" 3. Click the purple "Update subscription" button 4. Select your new plan and confirm The same steps switch you between monthly and yearly billing. You do not need to cancel first. For more details, see [Billing & Credits](https://help.blotato.com/settings/billing-and-credits#how-do-i-change-my-plan) and [Is there a yearly plan?](https://help.blotato.com/settings/billing-and-credits#is-there-a-yearly-plan-how-do-i-switch-from-monthly-to-yearly) *** ## What are the posting limits per platform? For platform posting limits, see: These limits reduce spam. You will rarely exceed these limits. For example, I grew from 0 to 1M+ followers in 1 year without hitting any of these limits. Additional resources: * Growth Best Practices: * My personal Social Playbook (focused on thought leadership brand + tech startup): *** ## How many social accounts can I connect? The total number of connected social accounts depends on your plan: | Plan | Connected social accounts | | ------- | ------------------------- | | Starter | 20 | | Creator | 40 | | Agency | 100 | Facebook Pages and LinkedIn Pages count toward your total: * Facebook: Each Page counts towards your total. Your login itself does not count. * LinkedIn: Your profile and each connected company Page count toward your total You can connect multiple social accounts for the same platform, such as 3 Instagram accounts or 3 TikTok accounts. For the full list of plan limits, see [Plan Limits](/settings/billing-and-credits#plan-limits). For per-platform posting limits, see [Platform Posting Limits](https://help.blotato.com/settings/social-accounts#platform-posting-limits). *** ## How many scheduled posts can I have in my queue? The number of future-dated posts you can have scheduled at any one time depends on your plan: | Plan | Queued scheduled posts | | ------- | ---------------------- | | Starter | 200 | | Creator | 1,000 | | Agency | 3,000 | If you hit the limit, delete some upcoming posts from [Upcoming Posts](https://my.blotato.com/queue/calendar) or upgrade your plan. See: [Plan Limits](/settings/billing-and-credits#plan-limits) *** ## Can I bulk upload a CSV with my whole content calendar? Blotato has no native CSV import for the content calendar. You cannot upload a spreadsheet of captions, links, and dates directly in the web app. To bulk-schedule a month of posts from a spreadsheet, use the Blotato API with an automation tool: 1. Put your captions, media URLs, and dates in a Google Sheet or Airtable 2. In n8n or Make, add a Google Sheets (or Airtable) trigger to read each row 3. Map each row into the Blotato Publish Post node 4. Set `scheduledTime` per row for exact dates, or `useNextFreeSlot: true` to fill your calendar slots automatically See: [Cross-post to all platforms from one workflow](/blog/cross-post-all-platforms-one-workflow) and [Publish Post](/api/publish-post) *** ## How far in advance can I schedule posts? The scheduling horizon depends on your plan: * Starter: 9 months ahead * Creator: 1 year ahead * Agency: 2 years ahead If you try to schedule a post past your plan's horizon, Blotato returns an error. Pick a time within your plan's window or break longer campaigns into shorter batches. See: [Plan Limits](/settings/billing-and-credits#plan-limits) *** ## Can I send a post for approval before publishing? Blotato does not have a built-in approval-link feature in the web app. You have two options: ### Using Blotato Web App 1. Create your post and schedule it for a future time. 2. Review all scheduled posts in the **Upcoming Posts** screen ([my.blotato.com/queue/schedules](https://my.blotato.com/queue/schedules)). 3. To pause a post for edits, open the three-dot menu and choose **Move to Drafts**. 4. Publish or reschedule once you are satisfied. ### Using Blotato API (n8n / Make.com) Build an approval gate in your workflow: 1. Generate the post content. 2. Add a Slack or email notification step that sends the draft to your reviewer. 3. Wait for an approval signal, for example a webhook triggered by the reviewer. 4. Run the Publish step only after approval, using `scheduledTime` to publish at a set time. See: [Write and publish social posts with AI](/blog/use-ai-write-publish-social-media-posts) *** ## What is the maximum file size I can upload? Upload size depends on your plan: | Plan | Max media upload size | | ------- | --------------------- | | Starter | 400 MB | | Creator | 1 GB | | Agency | 1 GB | If your file is too large, compress or trim it, or upgrade your plan. See: [Plan Limits](/settings/billing-and-credits#plan-limits) *** ## Can I manage multiple client accounts as an agency? There are two ways to run multiple clients or brands in Blotato. Both are supported -- pick the one matching how separate you want each client to be. **Option 1 -- one Blotato account for all clients.** Connect every client's social accounts under your own Blotato login, up to your plan's connected-account limit: 20 social accounts on Starter, 40 on Creator, 100 on Agency. Every connected Facebook Page and every connected LinkedIn company Page counts toward this limit, so an agency running many client Pages reaches the cap faster than the client count suggests. See [Account Limits](/settings/social-accounts#account-limits). Each client authorizes their social account once in [Settings > Social Accounts](https://my.blotato.com/settings) -- use an incognito window logged into the client's social account so you connect the right profile. This is the setup the automation guide [Manage Multiple Accounts from One Automation](/blog/manage-multiple-accounts-brands-one-automation) builds on: one workflow posts to any number of client accounts. Keep in mind everything lives in one workspace -- there are no separate client logins, roles, or per-client permissions. **Option 2 -- one Blotato account per client.** Each client signs up for their own Blotato account with a shared email address so you log in and manage it. The client signs up, connects their social accounts, and you log in to manage their account. Use this when each client should have their own workspace, billing, and content history. A master agency account for managing all client subaccounts from one dashboard is not available yet, and there is no firm release date. *** ## How do I connect ChatGPT? You do not need to connect your ChatGPT Plus subscription to Blotato. Blotato does not use your personal ChatGPT Plus subscription for features inside the Blotato web app. If you want to control Blotato from ChatGPT Work or the ChatGPT desktop app, connect Blotato through MCP: 1. Go to [Settings > API](https://my.blotato.com/settings/api). 2. Click **Codex** to see the step-by-step setup instructions. 3. Follow the ChatGPT setup steps in [MCP Setup](/api/mcp/setup#chatgpt). This connection uses your Blotato API key, not your ChatGPT Plus subscription. You need a paid Blotato subscription for API and MCP access. You can also connect Blotato to Claude, Cursor, Antigravity, Replit Agent, and other MCP-compatible AI tools. See [MCP Server Setup](/api/mcp/setup). *** ## How do I connect multiple social accounts? / Connecting to the wrong account? You don't need to create multiple Blotato accounts -- connect all your social accounts under one Blotato login. You can connect up to **20** social accounts on the **Starter** plan, **40** on **Creator**, and **100** on **Agency**. Facebook Pages and LinkedIn company Pages also count towards this limit: * Facebook: Each Page counts as an independent social acccount (your Facebook login does not). * LinkedIn: Your profile plus each connected company Page count as independent social accounts. To connect an account, go to [Settings](https://my.blotato.com/settings) and click the **"Login with \[Platform]"** button. If you're connecting a second account for the same platform, look for a button with 3 dots to switch between accounts and select the correct one. If that doesn't work, or if it keeps auto-logging into the wrong account, use an incognito browser as a last resort: 1. Open an incognito Chrome browser 2. Log into the social account you want to connect 3. Go to [my.blotato.com/settings](https://my.blotato.com/settings) 4. Connect your social account See [Social accounts](/settings/social-accounts#account-limits) for full account limits. *** ## How do I reconnect a social account? / My social account expired Social platforms require you to reauthorize 3rd-party apps periodically for security. To reconnect your account: 1. Go to [Settings](https://my.blotato.com/settings) 2. Find the account you want to reconnect 3. Click the blue "Reconnect" button Only use "Login with \[Platform]" if you want to connect a new social account. If you have issues reconnecting, use an incognito Chrome browser, log into the social account first, then log into Blotato and reconnect. *** ## Unable to login? / I can't access my account Log in here: [my.blotato.com/login](https://my.blotato.com/login) Blotato uses magic link authentication, so there is no password. Simply enter your email, then grab the verification code sent to your email. Check the spelling of your email first: it must match your account email exactly, in all lowercase. A typo or capital letters is the most common reason login fails or your account looks empty. There is no way to change or manage your password because Blotato does not use passwords. ### I never receive the verification code email 1. Check your spam and junk folders. 2. Using a work or company email address? Corporate mail filters are the most common cause -- they silently block the verification email. Check your company's spam quarantine. 3. Make sure you are logging in at [my.blotato.com/login](https://my.blotato.com/login) with the exact email address on your Blotato account, spelled in all lowercase. 4. If the code still does not arrive, ask in the support chat to temporarily switch your account email to a personal address (for example Gmail). Support updates the email on your account so the code reaches you. Blotato works on any laptop or desktop computer, Mac or PC -- login problems come from the email delivery above, not from your device. :bulb: Magic link authentication is more secure than passwords because it eliminates the risk of choosing weak or reused passwords that can be phished or brute-forced. It relies on one-time, time-limited links sent to a verified email, reducing the overall attack surface and risk of compromised passwords. *** ## How do you update your email? 1. Log into Blotato with your current email 2. Go to [Profile](https://my.blotato.com/settings/profile) 3. Change your email to the new one and click "Update Email" 4. Blotato sends a verification code to your new email 5. Enter the verification code in the prompt that appears in Blotato The verification code is sent to the new email address, not the old one. Check your spam folder if you do not see it. The code expires after a few minutes -- if it expires, click "Update Email" again to get a new code. You must be logged in to make the change. If you are locked out of your account, submit a help request via the in-app support messenger (orange circle in the bottom right corner). *** ## I want to use Blotato with a different email. Do I lose my credits or content? Change the email on your existing account instead of creating a new one. This keeps your credits, videos, posts, and settings. 1. Log into Blotato with your current email 2. Go to [Profile](https://my.blotato.com/settings/profile) 3. Change your email to the new one and click "Update Email" 4. Enter the verification code sent to your new email Credits and content are tied to your account and do not transfer between separate accounts. If you cancel a subscription, your remaining credits are deleted, so creating a second account means starting fresh. Changing your email on your existing account avoids this. *** ## How do I log out of Blotato? To log out of Blotato, go to [Settings](https://my.blotato.com/settings), click Profile tab, and click Log Out button. *** ## Where do I find key Blotato pages? * [Settings](https://my.blotato.com/settings) * [AI Agent](https://my.blotato.com/agent) * [Videos Dashboard](https://my.blotato.com/videos) * [Create New Video](https://my.blotato.com/videos/new) * [Upcoming Posts Calendar](https://my.blotato.com/queue/schedules) * [API Dashboard](https://my.blotato.com/api-dashboard) * [Billing](https://my.blotato.com/settings/billing) * [API Keys](https://my.blotato.com/settings/api) * [Brand Kit](https://my.blotato.com/settings/brand) * [Profile](https://my.blotato.com/settings/profile) *** ## How do I add a first comment to a post? Blotato has a **First Comment** field for Instagram and Facebook. It auto-posts your comment right after the post publishes, whether you publish now or schedule for later. A common use is putting a link in the first comment instead of the caption. **Using the Blotato web app:** Open the Instagram or Facebook post options and fill in the **First Comment** field. **Using the Blotato API or MCP:** Set `target.firstComment` in [Publish Post](/api/publish-post), or pass `firstComment` to the `blotato_create_post` MCP tool. Facebook allows up to 8000 characters, Instagram up to 2200. First comments are not supported on Stories. For other platforms, add the comment after the post publishes: call [Post Comment](/api/comments#post-comment) (or the `blotato_post_comment` MCP tool) with the published post's ID, or open the post on the platform and comment manually. In n8n or Make, add a Post Comment step after your publish step. *** ## How do I delete my account? / How do I cancel my account? Go to [Settings > Billing](https://my.blotato.com/settings/billing) and click "Open Billing Portal" to cancel your subscription. There are no long-term commitments. You can cancel anytime. For more details, see: [Billing & Credits](https://help.blotato.com/settings/billing-and-credits#cancel-account) *** ## Can I pause or freeze my subscription instead of cancelling? Blotato does not have a pause or freeze feature. You have two choices: 1. Keep your subscription active to retain your credits, scheduled posts, and access. 2. Cancel from [Settings > Billing](https://my.blotato.com/settings/billing) > Open Billing Portal. Cancelling takes effect immediately and you lose: * All remaining AI credits. If you resubscribe, you start fresh with your plan's default credits. * All scheduled posts. They will not be published. If you only want a short break, keep your subscription rather than cancelling, because cancelling removes your remaining credits and scheduled posts. *** ## I cancelled my subscription but want to access my old videos After cancelling your subscription, Blotato shows a reactivation modal when you log in. You cannot access the app (including previously created videos, posts, and settings) without an active subscription. To regain access: 1. Go to [my.blotato.com/login](https://my.blotato.com/login) and log in 2. Click "Reactivate" on the subscription modal 3. Your old videos, posts, and settings will still be there Your content is not deleted when you cancel. It remains saved and will be available when you reactivate. *** ## Markdown (e.g. asterisks) appearing in your post? Most social platforms do NOT support markdown. You have 2 options to remove markdown from your post: 1. Instruct Chat to "remove markdown" 2. Permanently disable markdown by going to Settings > Disable Markdown (toggle). *** ## How do I add or tag collaborators to my Instagram post? > **Note:** Collaborators are supported on **single image posts and reels**. They are **not supported on carousels** (multi-image/video posts) - a carousel with collaborators will fail to publish. For a carousel, publish it first, then add the collaborator in the Instagram app. ### Using Blotato Web App 1. Create your Instagram post 2. Click SCHEDULE 3. Enter the collaborator handle in the Collaborators field (without the @ sign, e.g., "sabrina\_ramonov")
### Using n8n, Make, or API 1. Open the Instagram publish node 2. Click "Add Option" (n8n) or "Advanced Settings" (Make) 3. Select "Collaborators" 4. Enter the collaborator handle without the @ sign
*** ## Ideas for automating content? There are lots of content automation templates in the help section, combining Blotato with tools like n8n and Make.com: RSS.app is also useful for pulling content ideas from social platforms such as X, Reddit, Instagram, and TikTok. *** ## How do you find what you've created? You can find all your generated visuals (videos, images, carousels, infographics, and slideshows) here: . Click on any visual to open it in the editor. Click the red trash icon to delete one. You can find your published posts here: You can find your draft posts in the [AI Agent](https://my.blotato.com/agent) Some drafts open in the older [Remix screen](https://my.blotato.com/remix) instead. See [Why is my draft in the Remix screen and not the AI Agent?](#why-is-my-draft-in-the-remix-screen-and-not-the-ai-agent) You can find your scheduled and published posts in the Calendar: *** ## Why is my draft in the Remix screen and not the AI Agent? Some drafts open in the older Remix screen () instead of the new [AI Agent](https://my.blotato.com/agent). This happens when you: * Retry a failed post * Reschedule a post * Move a scheduled post back to drafts * Click "Create Post" in the video editor To find these drafts: 1. Open the [Remix screen](https://my.blotato.com/remix) 2. Look for your draft there Note: Blotato is phasing out the Remix screen. Routing every draft into the AI Agent screen is in progress. Until then, check the Remix screen when a draft is missing from the AI Agent. **TikTok drafts are the exception.** A TikTok post published as a draft does not appear in Blotato at all -- not in the AI Agent and not in the Remix screen. It lands in the **TikTok app's notifications** (often labeled "System Notifications"), shown as "Draft Video from Blotato." See [How Do I Access TikTok Drafts Published via Blotato?](/platforms/tiktok/faqs#how-do-i-access-tiktok-drafts-published-via-blotato). *** ## Why don't my drafts show up on my phone? / I made drafts on my laptop and they are not on my other device Drafts in the [AI Agent](https://my.blotato.com/agent) are tied to the browser where you created them. The AI Agent workspace (your session, drafts list, and context) is stored in that browser, so drafts made on your laptop will not appear when you log in on your phone or another computer. Refreshing or logging in again on the other device does not bring them over. What to do: 1. Finish and schedule a draft on the same device and browser where you created it 2. Once a post is scheduled or published, it is visible from any device in [Upcoming Posts](https://my.blotato.com/queue/schedules) and [Published Posts](https://my.blotato.com/published) The new AI Agent works best on desktop. Use your phone to review scheduled and published posts rather than to edit drafts. ## How do I clear or delete all my scheduled posts? 1. Go to [Upcoming Posts](https://my.blotato.com/queue/schedules) 2. Select the scheduled posts you want to remove 3. Click the red bulk delete button at the bottom of the screen 4. Confirm to delete them To delete a single post, click the three-dot menu on that post and click "Delete." See: [Content Calendar Tutorial](/features/content-calendar/tutorial#delete-scheduled-post) *** ## How do I reschedule a scheduled post? You can reschedule a post directly from your Calendar. From Upcoming Posts: 1. Go to [Upcoming Posts](https://my.blotato.com/queue/schedules) 2. Click the three-dot menu on the post 3. Click "Reschedule" 4. Pick a new date and time in the modal 5. Click "Save" From Calendar (BETA): 1. Go to [Calendar](https://my.blotato.com/queue/calendar) 2. Click on the scheduled post 3. Click "Reschedule" 4. Pick a new date and time in the modal 5. Click "Save" For more details on managing scheduled posts, see: [Content Calendar Setup](/start/calendar#managing-scheduled-posts) *** ## How do I move a scheduled post back to drafts? 1. Go to [Upcoming Posts](https://my.blotato.com/queue/calendar) 2. Select the scheduled post 3. Click the three-dot menu on the right 4. Click "Move to Drafts" 5. The post moves back to drafts, usually in the [AI Agent](https://my.blotato.com/agent) — some drafts open in the older [Remix screen](https://my.blotato.com/remix) instead, see [Why is my draft in the Remix screen and not the AI Agent?](#why-is-my-draft-in-the-remix-screen-and-not-the-ai-agent) 6. Edit the post or change its media from there Use this when you want to change a post's media or keep working on it before publishing. To reschedule without editing, use the Reschedule option instead. For more details on managing scheduled posts, see: [Content Calendar Setup](/start/calendar#managing-scheduled-posts) *** ## Where can I view my scheduled or upcoming posts? Check your content calendar here: *** ## I get "All selected platforms are already queued for publishing" This message means a post is already queued or publishing for those accounts, so Blotato blocks a second one to prevent a duplicate. What to do: 1. Wait for the current post to finish publishing. 2. Check [Upcoming Posts](https://my.blotato.com/queue/schedules), Published Posts, and [Failed Posts](https://my.blotato.com/failed) to confirm its status. 3. To post right now, select different accounts or platforms that are not already queued. If you already cleared Upcoming Posts and the message stays, check these causes in order: 1. [Failed Posts](https://my.blotato.com/failed): a post stuck in Failed Posts still counts as queued for the account. Delete anything there for the platforms you want to schedule to. 2. Stuck video processing: a post whose video is still rendering blocks the account until it finishes or fails. Open [Videos](https://my.blotato.com/videos) and look for anything in "processing" or "queueing" status. 3. Hard refresh the browser: press Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows). Closing and reopening the tab does not clear the state. 4. Reconnect the social account: if the error persists after the steps above, go to [Settings > Social Accounts](https://my.blotato.com/settings) and click the blue **Reconnect** button on the affected account. A stale account connection keeps the account stuck in a queued state even after everything else is cleared. *** ## My scheduled post keeps failing with a media fetch error, but I uploaded the video from my computer If you uploaded an MP4 directly (no external link) and the post fails repeatedly with an error like "Failed to fetch media URL" or a media parsing failure, the stored file reference is bad. Retrying the same post does not fix it. The reliable fix is to re-upload the video rather than retry: 1. Move the failed post back to Drafts. 2. Remove the current video and upload the MP4 again so it gets a clean file reference. 3. Reschedule the post. While you are at it, confirm the file is a standard MP4, is not corrupted, and is within your plan's upload size limit -- YouTube is stricter about video files. Media details: [Media](https://help.blotato.com/api/media) *** ## AI Agent FAQ ### How do I make a post if I only put text context? Follow [Make Your First 5 Posts](/start/posts). ### Where is the Save button? I only see "Publish" / I don't want to publish yet, I just want to save my work There is no separate Save button, and this is by design. All posts and videos are automatically saved as you edit. * Posts are saved as drafts in the [AI Agent](https://my.blotato.com/agent) * Videos are saved in [Videos](https://my.blotato.com/videos) To keep a finished post without publishing it right now, click Schedule and pick a future date instead of Publish. ### How do I create a new post when I still have a different one in drafts? / I have content open but want to post something else quickly All drafts are auto-saved. To create a new post while keeping your existing drafts: 1. Click **New post** in the [AI Agent](https://my.blotato.com/agent) to start a blank draft 2. To fill it with content, type a prompt in the chat box at the bottom of the screen -- Blotato generates from your toggled-on context 3. Your existing drafts remain saved and accessible as tabs *** ## How do you sync content across devices (e.g. mobile, desktop)? Content in the [AI Agent](https://my.blotato.com/agent) does NOT sync across devices: * **Context** (videos, articles, PDFs, text) is stored locally in your browser. If you switch from laptop to phone, re-add your context on the new device. * **Drafts** are tied to the browser where you created them. Drafts made on your laptop will not appear when you log in on your phone or another computer. See: [Why don't my drafts show up on my phone?](#why-dont-my-drafts-show-up-on-my-phone-i-made-drafts-on-my-laptop-and-they-are-not-on-my-other-device) Scheduled and published posts DO sync. Once you schedule or publish a post, it is visible from any device in [Upcoming Posts](https://my.blotato.com/queue/schedules) and [Published Posts](https://my.blotato.com/published). *** ## Is there a Blotato mobile app? How do I use Blotato on mobile? The new Blotato agent (the main screen where you create and publish posts) is meant for desktop and laptop, not mobile. The video editor is also not mobile-friendly. You can open in a mobile browser (Chrome, Safari, or Brave) to review [Upcoming Posts](https://my.blotato.com/queue/schedules) and [Published Posts](https://my.blotato.com/published). Create and edit your posts and videos on a desktop or laptop for the full workflow. AI Agent drafts are tied to the browser where you created them, so drafts made on your laptop will not appear on your phone. I don't have plans to release a separate mobile app. *** ## How do I type emojis? In the AI Agent where you have draft posts, type a colon ":" and you should see the emoji picker. *** ## Can I connect Dropbox, Google Drive, or other cloud storage? Blotato has no direct integration with Dropbox, Google Drive, or other cloud storage. You cannot connect them as an account or browse their files inside Blotato. You can still publish files you keep there: 1. Get a public direct file URL for the image or video (a link to the file itself, not a shared preview page). 2. Publish with that URL as your media. Pass it in the `mediaUrls` parameter when you use the API, or upload the file in the web app when you create a post. *** ## Where do I add my sources or context when creating a video or post? In the AI Agent, click the + button next to CONTEXT in the left sidebar to add a source. Supported context types are YouTube links, TikTok links, article and website URLs, PDFs, audio files, tweets and X posts, and text. The AI Agent uses them to generate your posts and videos. Your saved sources also have a dedicated page: the [Sources library](https://my.blotato.com/sources). Use this page to view and manage saved sources. To add a new source, open the [AI Agent](https://my.blotato.com/agent), click the + button next to CONTEXT, add the source, and select **Save Source?**. Older tutorial videos call this the Source screen. It lives in two places today: the Context section in the AI Agent at [my.blotato.com/agent](https://my.blotato.com/agent), and the [Sources library](https://my.blotato.com/sources). If the new post screen looks different from the tutorial, use either of these. *** ## How do I remix a YouTube video? (I saw a Remix button for a YouTube URL) Paste the YouTube URL as Context in the AI Agent, and Blotato remixes it into new posts and videos: 1. Open the [AI Agent](https://my.blotato.com/agent) 2. Click **+ Add Context** in the left sidebar 3. Choose **YouTube** and paste the video URL 4. Blotato extracts the content and generates on-brand drafts you edit and publish Older tutorial videos call this "remix a YouTube video." The button is now **+ Add Context** in the AI Agent. The **Remix** button on the Inspiration page is a separate feature for adapting existing posts in Blotato's Inspiration Database, not YouTube URLs. *** ## How do I add my own video (for example from CapCut) as a source or context? Context does not accept a direct video-file upload. To use your own edited video as a source the AI Agent generates from: 1. Upload your video to YouTube and set it to Unlisted. 2. Copy the YouTube link. 3. In the AI Agent, click the + button next to CONTEXT and paste the YouTube link. To publish your own finished video instead of using it as a source, you do not need YouTube. Open or create a post, click **Photo / Video**, and upload your video file. See: [Understanding Context](/start/sources) If you want to add your own video file, a suggested way is to add your video to YouTube as unlisted, then paste the YouTube URL as a source. *** ## Why does my Instagram Story post as a feed post instead of a Story? An Instagram Story accepts only one image or one video per post. If you attach multiple images to a Story, Blotato publishes them as a regular feed post instead. To post several Stories, create a separate post for each image or video and schedule them one at a time. *** ## Do you support Facebook personal profiles or Facebook groups? Unfortunately, Facebook does NOT allow publishing to personal profiles or groups. If this ever changes, I'd happily integrate it! ## Do you support Facebook Stories? Yes. When scheduling a Facebook post, select "Story" from the media type dropdown. Facebook stories require one video or image attachment. If more than one is provided, only the first is used and published. For API and MCP users, pass `"story"` as the `mediaType` in the target object. See the [Publish Post API reference](/api/publish-post) for details. ## Unable to Post on Facebook? When you click "Schedule", make sure you select which Facebook page you want to post to. Fill out the dropdown "Facebook Page ID".
## How do you remove "Posted by Blotato" from Facebook post? The "Published by \[App Name]" label appears on Facebook posts when they are published via any third-party app, rather than directly through Facebook. Unfortunately, Facebook does not allow you to remove this label because it is part of their transparency policy. *** ## How do I delete multiple scheduled posts at once? 1. Go to [Upcoming Posts](https://my.blotato.com/queue/calendar) 2. Select the posts you want to remove 3. Click the red bulk delete button at the bottom of the screen *** ## Do you support Google Business Profile? Blotato does not support Google Business Profile. Blotato publishes to Instagram, Facebook, TikTok, YouTube, LinkedIn, X (Twitter), Threads, Pinterest, and Bluesky. To send post content to another destination like Google Business Profile, use the [webhook publish target](/api/publish-post) with an automation tool (n8n, Make.com, or Zapier): Blotato sends the post data to your webhook, and your automation posts it to the destination. *** ## Does Blotato have dark mode? Not yet. Blotato does not have a dark mode option. The app uses a light theme only. *** ## Do you support Claude.ai, Claude Desktop, and Claude Cowork? Yes. Open **Customize > Connectors**, click the **+** button, then **Add custom connector**, enter the Blotato MCP URL, and approve access via OAuth. See the setup guide: [MCP Setup](/api/mcp/setup) *** ## Is there a Claude course with certification? Anthropic offers free official Claude courses with certificates at [Anthropic Academy](https://anthropic.skilljar.com/). Start there for a structured learning path with certification. For Blotato-specific workflows, follow Sabrina's tutorials: [Claude + Blotato setup](https://www.youtube.com/watch?v=1dSNfnFL40c), [Build an AI Social Media Manager with Claude Code](https://youtu.be/3HVH2Iuplqo), and the [Claude Cowork & Desktop setup tutorial](https://youtu.be/mh4Z9U-oaps). *** ## Where are the free Claude skills? / Where are the marketing skills? The 7 free Claude content skills are here: [Free Claude Skills](https://help.blotato.com/claude-skills/claude-skills) The 7 skills compose into one workflow: * **content-coach** — start here. Takes you from "I don't know what to post" to a scheduled post, and runs the others for you. * **brand-brief** — one-time setup that captures your business, customer, CTA, story, and voice. * **post-writer** — writes a graded, polished post about any topic. * **post-grader** — scores a draft and lists the top 3 fixes. * **post-scheduler** — ships the final post via Blotato. * **repurpose** — turns one blog post, newsletter, or transcript into a week of platform-native content. * **viral-hooks** — a library of 100 proven viral hook frameworks that opens every post with a tested hook. You install each skill once, then use it forever in Claude Code, Claude Desktop, and Claude Cowork. On day one you only need content-coach. It calls the others behind the scenes. *** ## Where are the 100 skills or 100 viral hooks I was promised when I subscribed? The promotion in the app refers to the free Claude skills bundle, which includes the **viral-hooks** skill: a library of **100 proven viral hook frameworks** grouped into 13 categories. Everything is here: * Download and install the skills: [Free Claude Skills](https://help.blotato.com/claude-skills/claude-skills) * Browse the hooks guide in the docs: [Hooks](https://help.blotato.com/tips-and-tricks/hooks) The skills do not appear inside your Blotato subscription dashboard. You install them once in Claude (Code, Desktop, claude.ai, or Cowork) and use them forever. Start with **content-coach**, and use **viral-hooks** to open any post with one of the 100 hook frameworks. *** ## Can I import my existing Instagram Reels or social posts as a content source? No. You cannot import your existing Instagram posts or Reels as a source for Blotato to learn from. Instagram is not a supported source type. Supported source types: YouTube video, TikTok video, X (tweet), article/website URL, PDF, audio file, raw text, and Perplexity AI research. A TikTok or X post URL works as a source, but an Instagram post or Reel URL does not. To shape on-brand output, set up your [Brand Kit](/settings/brand-kit) with your business description, audience, topics, and uploaded brand visuals and documents. *** ## How do I use Google Drive files as context? Google Drive is not a supported Context type in Blotato. You cannot paste a Google Drive link into "+ Add Context" in the AI Agent. Workaround based on file type: 1. For documents or articles: Open the file in Google Drive, copy the text, and add it as "Text" context 2. For PDFs: Download the PDF from Google Drive, then upload it as "PDF" context 3. For audio files: Download the audio from Google Drive, then upload it as "Audio" context 4. For videos: If it is a YouTube video, paste the YouTube link directly (YouTube is supported context) Supported context types: Text, Articles/Websites, YouTube, TikTok, Audio/Podcasts, PDFs, and Perplexity AI. See: [Understanding Context](/start/sources) *** ## How do I save a source or add to my Sources library? Save a source from the AI Agent, not from the Sources page directly: 1. Open the [AI Agent](https://my.blotato.com/agent). 2. In the left sidebar, click the source you want to keep. 3. Check the "Save Source?" box to save it to your [Sources library](https://my.blotato.com/sources). Repeat for each source you want to save. See: [Understanding Context](/start/sources#saving-sources-to-your-sources-library) *** ## Trying to add a website but it's not working? Sometimes when you try to add a blog, article, or website as new context, you'll see a message related to "enabling Javascript and cookies". This means Blotato's website scraper is unable to access the website due to its anti-scraping policies. I recommend this workaround: Copy and paste the article, website, or blog, then add it as Text context. ## Why did I get charged during my free trial? During your free trial, you can add unlimited context, create unlimited posts, publish and schedule to 9 social platforms, and view the inspiration database of viral posts.\ ​\ However, your free trial has a limited amount of AI credits for AI image, video, and voice generation since it costs me money. If you click "Upgrade" during your free trial, your paid subscription will begin, and you will unlock all the credits for your plan. Also, the API is limited to paying users to prevent spam/abuse of people posting low-quality content. If you generated an API key, it will activate your paid subscription. *** ## I signed up for the free trial but I was still billed? Blotato free trial includes everything except API access. The API is limited to paying users to help reduce spammy content. Before you generate an API key, there is huge sign explaining this, PLUS a confirmation popup requiring you to confirm, which you clicked. It's also on the website at the top of the Pricing page: ​ ​ Alternatively, if you clicked the UPGRADE popup after running out of free trial credits, this will also convert your free trial to a paid subscription. ## My account shows "incomplete payment" but I already paid This happens when Stripe generates a second subscription or invoice that did not complete payment, even though your previous invoice is paid. 1. Go to [Settings > Billing](https://my.blotato.com/settings/billing) and click "View Billing Portal" 2. Check your INVOICE HISTORY for duplicate invoices in the same billing period 3. If you see a paid invoice and a separate open/unpaid invoice for the same amount, contact support through the in-app chat (orange circle in the bottom right corner) Do not retry payment on the open invoice until support confirms whether it is a duplicate. Blotato support can void the duplicate invoice and restore your access. If you cannot sign in or the chat widget does not load, email with your account email and the charge date. ### It says "Your subscription setup is incomplete. Please complete the payment process to activate your subscription." This message means Stripe started your subscription but the payment itself never went through, so the subscription is stuck in an incomplete state. Having a payment method saved is not enough -- the charge must succeed. 1. Go to [Settings > Billing](https://my.blotato.com/settings/billing) and click "Open Billing Portal" 2. Complete the pending payment there, or update your card and retry once 3. If the charge keeps failing with a valid card, contact your bank -- banks decline subscription charges, and only your bank sees the decline reason 4. Still stuck? Contact support in the in-app chat with your account email -- support clears the incomplete subscription so you subscribe cleanly. You can also create a fresh account with a different email and subscribe there **Already paid?** If your charge succeeded (your bank shows the money left, or the invoice shows Paid) and this message still appears, do not pay again and do not retry checkout -- another attempt bills you again for the same period. Stripe is trying to bill a stale Incomplete or Expired subscription on your account. Contact support in the in-app chat with your account email: support cancels the stale subscription and restarts your plan cleanly. Wait a minute after support confirms, then refresh the page. The sections below cover the matching symptoms. ### It says "Your subscription setup has expired" (status INCOMPLETE\_EXPIRED) but my invoice shows Paid You paid, the invoice shows Paid in the billing portal, but every login shows a "Your subscription setup has expired" modal and your subscription status reads INCOMPLETE\_EXPIRED. Your API key is also rejected while the account is in this state. This happens when the payment confirmation settles after Stripe's confirmation window (about 23 hours) closes — the subscription record expires even though the charge succeeded. Reactivating from the billing portal does not clear this state. Do not pay again. Contact support in the in-app chat with your account email: support cancels the expired Stripe subscription and restarts your plan cleanly. Wait a minute after support confirms, then refresh the page. ### My payment was deducted but Blotato says the transaction failed / I keep getting charged after canceling A related pattern: Stripe keeps trying to bill a previously Incomplete or Expired subscription on your account. This causes payments that show as failed even though money left your bank, repeated charge attempts after you canceled, or an account that stays locked after paying. Do not pay again -- another attempt lands on the same stale subscription. Contact support in the in-app chat and say your payment shows failed or you are still being charged. Support cancels the Incomplete or Expired Stripe subscription, then restarts your plan cleanly. If a duplicate payment went through, support refunds it. A stale Incomplete subscription also blocks plan changes. If the billing portal will not let you switch plans (for example from Creator to Starter) because your subscription shows Incomplete, contact support to cancel the incomplete subscription first. As a last resort, create a fresh account with a different email at [blotato.com/pricing](https://www.blotato.com/pricing) and select the plan you want there. *** ## Why does it say "Your subscription payment is past due" if I have a trial? The two most common reasons are: 1. You generated an API key, which activates your paid subscription immediately. Blotato free trial includes everything except API access. The API is limited to paying users to help reduce spammy content. Before you generate an API key, there is a large sign explaining this, plus a confirmation popup requiring you to confirm. 2. Your 7-day free trial has ended. To manage your subscription, go to [Settings > Billing](https://my.blotato.com/settings/billing) and click "Open Billing Portal." More details: * [What's included in the Free Trial?](https://help.blotato.com/settings/billing-and-credits#whats-included-in-the-free-trial) * [Pricing](https://www.blotato.com/pricing) *** ## I don't see a prompt for my use case? You can import your own prompts in Blotato or request a custom prompt here: ## How do I use blotato to write long-form content? You can import your own prompts in Blotato or request a custom prompt here: ## How do I teach AI to use my voice? Edit existing prompts or import your own prompts to make the output sound more like you: [Make Output Sound Like You](https://help.blotato.com/tips-and-tricks/make-output-sound-like-you) *** ## How do I make my visuals match my brand voice? 1. Set up your brand kit in [Settings > My Brand](https://my.blotato.com/settings/brand) 2. Open the [Blotato AI Agent](https://my.blotato.com/agent) and describe what you want 3. The AI Agent reads your Brand Kit and generates on-brand visuals and copy 4. Chat with the AI to refine -- ask for different colors, text changes, or style adjustments If you have more than one brand voice, select the one you want from the **Brand Voice** dropdown in the AI Agent before generating. See [Manage multiple brand voices](/tips-and-tricks/manage-multiple-brand-voices). You can also create visuals directly in Claude Code and Antigravity: [Watch tutorial](https://youtu.be/3HVH2Iuplqo) For the full list of Brand Kit fields, see: [Brand Kit](/settings/brand-kit) *** ## How do I set up my Brand Kit? 1. Go to [Settings > My Brand](https://my.blotato.com/settings/brand) 2. Fill in your brand name, website, business description, ideal customers, and posting topics 3. Optionally upload brand visuals (images) and brand documents (PDFs, slide decks) 4. Blotato uses this information when generating visuals (images, videos, carousels, infographics) Brand Kit only applies when using "Create Everything with AI Agent" -- not when selecting a specific template directly. For the full list of Brand Kit fields, see: [Brand Kit](/settings/brand-kit) *** ## How do I control what people or style appear in my AI-generated videos? 1. Go to [Settings > My Brand](https://my.blotato.com/settings/brand) 2. In "Describe your ideal customers", describe the people you want featured in your content (e.g., "professional Black women in urban settings") 3. In "What do you post about?", include visual style direction alongside your topics 4. Upload reference images in "Brand Visuals" that match the look you want The AI Agent reads your Brand Kit before generating each scene. Use the [Blotato AI Agent](https://my.blotato.com/agent) to create visuals with your Brand Kit applied. Brand Kit does not apply when selecting a specific template directly. For one-off adjustments, chat with the AI Agent to describe the changes you want, or open the video editor, click a GREEN clip, and edit the prompt directly. For full Brand Kit setup, see: [Brand Kit](/settings/brand-kit) *** ## Instagram says "We restrict certain activity to protect our community" This error comes from Instagram, not Blotato. Instagram flagged your account or content based on risk/spam scores. To fix: 1. Reduce the number of hashtags in your caption 2. Shorten your caption length 3. Increase the time between posts (at least 30 minutes apart) 4. If none of the above works, post manually on Instagram for a few days to warm up your account This error is more common with new Instagram accounts or accounts that post frequently via third-party apps. See: [Error Reference](/support/errors) *** ## Where do I find new features or release notes? Blotato does not have a changelog page. To stay updated: * Check in-app notifications when they appear * Browse the [Help Center](https://help.blotato.com) for updated documentation *** ## Can I generate avatar videos or UGC-style videos in Blotato? Blotato does not offer native avatar or UGC video generation (e.g., providing a picture of a person wearing a specific outfit and having them talk). You have 2 options: 1. Use Blotato's Veo3 model to generate avatar-style videos with AI-generated characters. 2. Use avatar apps like HeyGen outside of Blotato, then use Blotato to schedule and publish the videos. See: [How do you use HeyGen with Blotato?](#how-do-you-use-heygen-with-blotato) *** ## How do you use HeyGen with Blotato? To use HeyGen with Blotato, you have 2 options:\ ​\ 1\. Make your avatar video in the Heygen web app, download the completed video, and attach it to your post in blotato, as shown in this screenshot: ![](/files/ZInRWtohKgPe0lhOwI9s)\ ​\ 2\. Use make.com to setup an automated flow to generate Heygen avatar videos, then post them to social media platforms automatically via blotato's API. Here is the step-by-step tutorial how to do this: ## How do I add a long link to a post? If you're adding a long link or URL to a post on short-text platforms like Twitter, Threads, or Bluesky, I recommend using a free link shortener, such as Bitly or Shorturl. I don’t have automatic link shortening as a feature in Blotato yet. On Instagram and Facebook, put your link in the **First Comment** field instead of the caption. Blotato auto-posts it right after the post publishes. See [How do I add a first comment to a post?](#how-do-i-add-a-first-comment-to-a-post). ## What does the red "Disconnected" banner mean? If you **keep getting a "Disconnected" message** -- it appears constantly, or your connection keeps dropping -- this is the notification below, and it is **not** a social account problem. The red "Disconnected" banner in the top-right corner of Blotato is a real-time connection notification. It means your browser's live connection to Blotato's servers was temporarily interrupted. Wait a few minutes -- Blotato automatically reconnects and the message disappears. If it persists, refresh the page (Ctrl/Cmd + Shift + R). This notification does not mean your social accounts are disconnected. Your social accounts, scheduled posts, and settings are unaffected. ## Do you have to fill out the text input box for Tiktok videos and Instagram Reels? You don't need to put text in the box, but I highly recommend putting an SEO optimized caption there. 35% of my weekly Tiktok traffic comes from search, so putting additional details in your video's description helps bring in new viewers over time. Here's an example caption from one of my tiktoks:\ ​\ """\ Top seven AI tools to build AI agent teams without coding required. These are all low-code platforms for building multi agents AI teams. As AI shifts towards more autonomy, it’ll be interesting to see if these platforms can evolve.\ ​\ \- what are the best low code platforms to build AI agents?\ \- top AI tools to build AI agent teams?\ \- recommended AI agent builder platforms for businesses?\ ​\ \#ai #artificialintelligence #aitools\ """ ## How many hashtags should I use? Use a maximum of 5 hashtags on Instagram, TikTok, and Facebook. More than 5 reduces your reach on these platforms. You don't need hashtags on other platforms. LinkedIn, Twitter, Threads, Bluesky, YouTube, and Pinterest do not benefit from hashtags and they are generally frowned upon. ## What does this error mean? "TikTok video is missing the subtitle track." \ Right now, Blotato can only analyze Tiktoks that have a subtitle track. Most Tiktok videos do have subtitle tracks, so I recommend trying with a different video. I will improve this in the future, so that Blotato automatically transcribes videos that don't have a subtitle track. ## How do I set a custom cover image for Instagram Reels? 1. Create your post with a video attached 2. On the publish screen, expand the advanced options 3. Add your cover image URL in the "Cover Image" field 4. Publish as usual The cover image must be a publicly accessible URL and under 8MB. For n8n / Make.com users, this field is in the advanced options of the Blotato Publish node. For REST API / MCP users, see: [Publish Post API Reference](/api/publish-post) For TikTok cover images, see: [TikTok Custom Thumbnails](/platforms/tiktok/faqs#how-do-i-set-a-custom-thumbnail-for-tiktok) ## Can you upload multiple photos? You can upload multiple photos to a social media post for several platforms (Facebook, Linkedin, etc.) ... BUT not a photo slideshow for Tiktok or Reels (see below). ## How do I make carousels or slideshows in Blotato? ### In Blotato Web App 1. Go to [Videos > New](https://my.blotato.com/videos/new) 2. Select a carousel or slideshow template (e.g., "Image Slideshow with Text Overlays") 3. Enter your prompt and click "Generate Video" for a quick AI-generated version **To use your own images:** 1. Click "Need more customization? Click to see advanced options" 2. For each slide, choose "Upload Image" from the Image Source dropdown 3. Upload your image (max 20MB) 4. Optionally add text overlay for each slide 5. Click "+ Add Slide" to add more slides 6. Click "Generate Video" when done ### In n8n or Make Use the Blotato CREATE VISUAL node to generate carousels and slideshows from templates: 1. Add a Blotato node and select "Visual" > "Create" 2. Select a template from the dropdown list 3. Keep default inputs and click Execute to instantly make a carousel 4. Update inputs one-by-one to customize 5. Check the [API Dashboard](https://my.blotato.com/api-dashboard) to see the JSON payload for each template Tip: Browse all available templates at to see how they work before building your automation. You can also upload a photo or image to TikTok. Make sure it's not PNG format, because TikTok's API does not support PNG. *** ## Can I post trial reels to Instagram? Yes. Trial reels are shared with non-followers first, letting you test content before promoting it to your followers. ### Using Blotato Web App 1. Create your post and attach a video 2. Select Instagram as the platform 3. On the scheduling screen, look for the "Trial Reel" option 4. Choose your graduation strategy: * Manual: You decide when to promote the reel to your followers * Auto (performance-based): Instagram promotes the reel based on performance 5. Schedule or publish the post ### Using Blotato API (n8n / Make.com) 1. Set `target.targetType` to `"instagram"` and `target.mediaType` to `"reel"` 2. Add the `target.trial` object with a `graduationStrategy`: * `"MANUAL"` -- you manually promote the reel to followers * `"SS_PERFORMANCE"` -- Instagram auto-promotes based on performance 3. Submit the post Example: ```json { "post": { "accountId": "98434", "content": { "text": "Testing this with new audiences first", "mediaUrls": ["https://example.com/video.mp4"], "platform": "instagram" }, "target": { "targetType": "instagram", "mediaType": "reel", "trial": { "graduationStrategy": "SS_PERFORMANCE" } } } } ``` Trial reels only apply to Instagram Reels (video posts). They have no effect on image posts or stories. See: [Publish Post API](/api/publish-post) ## How do you convert the SEO-optimized outline into a I'm using the SEO Optimized Article Outline Prompt. When I have the result, I would like to use the outline to create the blog content based on that outline. How can I do that? \ Simply copy/paste the SEO-optimized outline and add new Text context in Blotato. Then use a different prompt to write your full blog post. ## What does the "Include Sources" toggle button do? Enabling the "Include Sources?" toggle will append all your source links to the bottom of your post. If your source doesn't have a link (e.g. Text or Perplexity), then no link will be appended. ## What does this Tiktok error mean: "Error uploading images to Tiktok: The request post info is empty or incorrect"? Here's how to troubleshoot this error: 1. If posting an image, make sure it's in JPG format (not PNG) and the standard 9:16 aspect ratio. 2. If posting a video, make sure it's in MP4 format (not MOV) and the standard 9:16 aspect ratio. 3. Make sure you have text for the video caption. 4. Test posting to Tiktok with this sample video: *** ## Can I comment on posts with Blotato? / Does Blotato support commenting? Yes, for Instagram and Facebook. Blotato reads and posts comments on your published Instagram and Facebook Page posts through the [Comments API](/api/comments) and the [MCP tools](/api/mcp/tools). You can: * Read the comments on your published Instagram and Facebook posts, including audience replies and your own. * Post a top-level comment on your published Instagram and Facebook posts. * Reply to a top-level comment on your published Instagram and Facebook posts. You can also auto-post a **first comment** on your Instagram and Facebook posts when you publish, set through the web app, API, or MCP. A common use is putting a link in the first comment. See [How do I add a first comment to a post?](#how-do-i-add-a-first-comment-to-a-post). To answer commenters automatically, set up a [DM automation](/features/dm-automations). When someone comments a keyword on your Instagram or Facebook post, Blotato sends them a direct message. Blotato does NOT support: * Comments on unsupported platforms (Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, YouTube). * Commenting on other people's posts. * Replies to replies. You can reply to a top-level comment, but not to a reply. * Automated public reply bots posting comments back to your audience at scale. * Cold direct messaging to people who never contacted you. For LinkedIn engagement automation, Blotato has no equivalent. PhantomBuster covers it (but it's risky). *** ## Can I read or send direct messages (DMs) with Blotato? Yes, for Instagram and Facebook. Blotato reads and sends direct messages on your Instagram account and Facebook Page through the [Messages API](/api/messages) and the [MCP tools](/api/mcp/tools). You can: * Read your conversations and messages. * Reply to people who already have a conversation with you. * Send a private reply to a comment on your posts. * Reply automatically with a [DM automation](/features/dm-automations) when someone comments on your post or messages you. Blotato does NOT support: * Messaging on platforms other than Instagram and Facebook. * Cold outreach to people who have not engaged with you first. The social platform limits who you can message and when. You reply within a 24-hour window after someone messages you, or send a private reply to their comment. Sending a message to a new person counts toward your plan's monthly active-contacts limit. See [Messages API](/api/messages). *** ## Why doesn't my DM automation trigger when I comment on my own post? Blotato skips comments posted by the same Instagram account or Facebook Page connected to the automation. Your own comment does not start a run or send a direct message, even when it contains the correct keyword. Test the automation from a different account: 1. Activate the automation. 2. Sign in to a different Instagram or Facebook account. 3. Comment on the target post using one of the trigger keywords. 4. Confirm the other account receives the direct message. 5. Open the automation and review its runs and logs if no message arrives. See [Test a Comment Trigger](/features/dm-automations#test-a-comment-trigger). *** ## Why don't the buttons show up in my DM automation message? Instagram shows DM buttons in the Instagram mobile app only. Someone reading your message on instagram.com in a desktop browser sees the text with no buttons under it. Instagram sets this behavior, not Blotato. To work around this, you can paste the same URL into the message text instead. Use a button or a plain-text URL, not both. A message carrying both leaves the URL unclickable on desktop, so a desktop reader ends up with no working link at all. * If your audience reads mostly on mobile, keep the link button. * If your audience reads mostly on desktop, remove the button and put the URL in the message text instead. On a follow gate the button is a confirm button, not a link, so removing it is not an option. Ask for a typed reply in the gate message instead, for example "Reply FOLLOWING once you have." Blotato runs the follower check on any reply. If button taps register for nobody on any device, reconnect the account in [Settings > Social Accounts](https://my.blotato.com/settings). Blotato subscribes your account to button-tap events at connect time, and an account connected before DM automations landed does not reliably receive them. See [DM Automations](/features/dm-automations#write-the-message). *** ## Can I require someone to follow me before my DM automation sends the link? Yes, on Instagram. Turn on **Ask for a follow** in the automation. Blotato sends your gate message with a confirm button, waits up to 1 hour for a reply, then checks whether the person follows you. A follower gets your link. Someone who does not follow gets the gate message again. Points to expect: * Only Instagram supports follow gating. * The gate message always goes out first. Instagram grants Blotato access to follower status once the person opens a DM thread with your account, so Blotato asks first and checks second. * Instagram withholds follower status for someone who never granted profile access. Blotato sends your link rather than blocking them. * **Reconnect the account if you connected it before follow gating landed.** Blotato subscribes your account to button-tap events at connect time, so an older connection does not reliably receive the tap and runs stall until they expire. Reconnect in [Settings > Social Accounts](https://my.blotato.com/settings). * **Ask for a typed reply in the gate message.** Instagram shows DM buttons in the mobile app only, so a desktop reader sees no button. Blotato runs the follower check on any reply, so wording like "Reply FOLLOWING once you have" moves a desktop reader forward the same way the button moves a mobile reader. See [Ask for a Follow](/features/dm-automations#ask-for-a-follow-instagram-only). *** ## Can I collect email addresses through my DM automation? Yes, on Instagram and Facebook Pages. Turn on **Ask for an email address** in the automation. Blotato sends your gate message, waits up to 1 hour for a reply, and reads the first email address out of it. A reply holding no address returns the gate message. To receive the address, turn on **Call a webhook** on the same automation. Blotato posts `{"email": "them@example.com"}` to your endpoint once your message sends. The Blotato inbox does not show captured addresses, so the webhook is the only way to read one. See [Ask for an Email Address](/features/dm-automations#ask-for-an-email-address). *** ## Do I need a Button label and Web URL when collecting email addresses? No. **Button label** and **Web URL** create an optional link button in the direct message. Keep the button only when you want the recipient to open a page. For an automation that collects an email address and sends it to n8n, Zapier, Make.com, or a CRM: 1. Click **Remove** beside each link button. 2. Turn on **Ask for an email address**. 3. Turn on **Call a webhook**. 4. Enter your n8n, Zapier, Make.com, or CRM endpoint in the **Webhook URL** field. The Web URL opens when a recipient taps a link button. The Webhook URL receives the captured email after the direct message goes out. See [Write the Message](/features/dm-automations#write-the-message). *** ## Does Blotato have a built-in CRM or lead capture? Can I connect my CRM (like Follow Up Boss)? Blotato is a publishing and scheduling tool, not a CRM. It holds no contact records you browse, no deal stages, and no direct CRM integration. There is no direct CRM integration, but you have three options: * Use Zapier or Make.com to connect your social media DMs, comments, or lead forms directly to your CRM (for example, Follow Up Boss). The automation tool handles lead capture, and Blotato handles publishing. * Use DM automations to notify your CRM when a user shares their email. See [DM automations](/features/dm-automations). * To notify your CRM or any custom system when a post publishes, use Blotato's **webhook** publish target. This is separate from the DM automation webhook. See [Publish Post -- Webhook target](/api/publish-post#webhook). *** ## Can you add analytics to the dashboard so I can measure my metrics? Is there an analytics dashboard? Analytics already exists in Blotato, so you do not need to request it as a new feature. Go to [Published](https://my.blotato.com/published) to see each published post with its metrics (views, likes, comments, shares, reach, watch time, and more) on 8 platforms: X (Twitter), Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest. Analytics for LinkedIn are not available yet. Analytics is included on all paid plans. The **Top Performing** tab ranks your best posts by views, likes, comments, or reach. For the full breakdown and the API endpoints, see [Does Blotato have analytics?](#does-blotato-have-analytics-how-do-i-track-views-and-engagement) below. *** ## Does Blotato have analytics? How do I track views and engagement? Yes. Blotato tracks engagement analytics (views, likes, comments, shares, reach, watch time, and more) for your published posts on 8 platforms: X (Twitter), Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest. Analytics for LinkedIn are not available yet. It is available on all paid plans. In the web app: 1. Go to [Published](https://my.blotato.com/published). 2. The **All** tab shows each published post with its metrics. 3. The **Top Performing** tab ranks your best posts by views, likes, comments, or reach. Via the API: 1. [List Top Performing Posts](/api/analytics) (`GET /v2/analytics`) returns your best posts ranked by likes, comments, views, or reach. 2. [Get Post Analytics](/api/analytics) (`GET /v2/posts/{id}/analytics`) returns metrics and snapshot history for a single published post. See the [Analytics API reference](/api/analytics) for the full list of metrics and examples. Fair usage limits may apply in the future. *** ## Why don't my YouTube or TikTok analytics show? Are they coming? YouTube and TikTok analytics are supported. Analytics track engagement for 8 platforms: X (Twitter), Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest. Only **LinkedIn is not available yet**. If your Instagram or Facebook stats appear but your YouTube or TikTok stats do not, the usual causes are: the post published before analytics support existed for that platform (older posts do not backfill), the first collection checkpoint has not passed yet, or the account was connected before analytics launched and needs to be reconnected in [Settings](https://my.blotato.com/settings) to grant analytics permissions. For LinkedIn, use LinkedIn's native analytics for now. Blotato is adding more platforms over time. *** ## Why do my analytics show "not available" or no data yet? Analytics are collected on a delay and under specific conditions: 1. Analytics need a paid plan. On the free trial, or if your plan does not include analytics, posts show "Analytics not available." 2. Data is not instant. Blotato collects the first metrics on a schedule after a post publishes (around 2 hours on Creator and Agency, up to 1 day on Starter), then again at later checkpoints. A post published minutes ago shows no metrics until the first checkpoint passes. 3. Analytics exist only for posts published while analytics was active on your account. Older posts do not backfill. 4. Your connected account must be valid. If the social account is disconnected or its token expired, Blotato stops collecting. Reconnect the account in [Settings](https://my.blotato.com/settings) with the blue "Reconnect" button. 5. **Reconnect accounts connected before analytics launched.** Analytics is a new feature that needs updated permissions. If you connected a social account before analytics was added and its posts stay stuck on "Analytics pending," reconnect that account in [Settings](https://my.blotato.com/settings) to grant the new analytics permissions. This is the most common reason an Instagram or Facebook post shows "pending" for days on a paid plan. If you already reconnected, no further action is needed. The first batch of metrics appears within 24-48 hours of reconnecting. 6. Instagram analytics require a Business or Creator account connected through Facebook, the same requirement as Instagram publishing. 7. Analytics for LinkedIn are not available yet, so LinkedIn posts will not show metrics. Analytics work for X (Twitter), Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest. LinkedIn is not available yet. *** ## Which analytics metrics does my plan include? Your plan sets the depth of metrics Blotato returns. **Creator and Agency** return every metric Blotato collects, including video-depth metrics, breakdowns by reaction type, and rate metrics. **Starter** returns 25 metrics: 1. All 17 common metrics: views, impressions, reach, likes, comments, replies, shares, saves, clicks, follows, plays, profile visits, profile activity, navigations, total interactions, total watch time, and average watch time. 2. Twitter/X: retweets and quote tweets. 3. Bluesky: reposts and quote posts. 4. Threads: reposts and quote posts. 5. LinkedIn: first-level comments. 6. Pinterest: reactions. See the [Analytics Metrics Reference](/api/analytics/analytics-metrics) for the field-level list. *** ## How often do analytics refresh? Blotato does not refresh analytics continuously. It collects a snapshot of each post's metrics at fixed checkpoints, measured from when the post publishes. The number of checkpoints depends on your plan. Starter: * 1 day after publish * 7 days after publish Creator: * 2 hours after publish * 1 day after publish * 7 days after publish * 30 days after publish Agency: * 2 hours after publish * 6 hours after publish * 1 day after publish * 7 days after publish * 14 days after publish * 30 days after publish * 90 days after publish Each checkpoint adds a small random delay to spread out collection, so exact timing varies by a few minutes to a few hours. The Published page and the API return the latest snapshot Blotato collected. They do not pull live data from the social platform. Posts that spike early can receive extra checkpoints beyond your plan's schedule. *** ## Why is my YouTube view count in Blotato lower than on YouTube? Blotato and the YouTube watch page count views differently, so the two numbers never match exactly. Blotato reads lower. **The watch page count** updates in near real time and includes views YouTube has not validated yet. **Blotato's count** comes from the YouTube Analytics API, which reports only finalized views. YouTube filters out spam and invalid playback traffic, then batch-processes what remains. To confirm this yourself, open YouTube Studio: 1. The **realtime** card matches the watch page 2. The **Analytics** tab matches what Blotato reports Blotato requests metrics for the video's full lifetime, from its publish date through today. YouTube has not finalized the most recent days yet, so those days contribute partially or not at all. The gap is widest on a new video and narrows at each later checkpoint as YouTube finalizes more data. One video at one moment: 12.7K on the watch page, 11K through Blotato. The Blotato number rises at later checkpoints. Gap size varies by video. Two separate delays stack here: * YouTube's validation delay, described above * Blotato's [collection schedule](#how-often-do-analytics-refresh) -- Blotato returns the latest snapshot it collected, not a live figure Neither is a bug and no action is needed. *** ## Can I send clients a link to connect their social accounts? (Agency feature) This feature is planned for the Agency plan. Agencies will be able to send clients a simple authentication link to connect their social accounts to Blotato without the client needing to log into Blotato. This is an **agency feature**, not whitelabeling. Your clients connect their accounts to Blotato (the Blotato brand is visible). You manage their content through your Blotato dashboard. This is not available yet. For now, agencies either connect client social accounts under one Blotato login (up to the plan's account limit) or have each client sign up for a separate Blotato account with a shared email address. See: [Can I manage multiple client accounts as an agency?](#can-i-manage-multiple-client-accounts-as-an-agency) *** ## Do you offer whitelabeling? No. Blotato does not offer whitelabeling, and there are no plans to add whitelabeling. **Whitelabeling** means rebranding Blotato as your own product with your own branding, logo, and domain. Your customers would never see the Blotato name. This is NOT supported. **Agency features** (managing client social accounts within Blotato) are different from whitelabeling and are planned for the Agency plan. See: [Can I send clients a link to connect their social accounts?](#can-i-send-clients-a-link-to-connect-their-social-accounts-agency-feature) If you need true whitelabeling (your own branded product), check out alternatives like Ayrshare. *** ## What IP address do posts come from? Posts originate from Blotato's cloud servers, not from your device or home network. Blotato uses official platform APIs with OAuth authentication. Social platforms identify your account through secure tokens, not IP addresses. ### Common concerns 1. **Posts come from a different country than me** * Platforms expect server-side posting. Location mismatch carries no penalty. 2. **Will my posts get less distribution in my country? (geo/reach)** * No. Publishing through the official platform APIs is different from posting from a random device: your posts keep the same geography and distribution as posts published normally from your own device. The platform ties distribution to your account, not to the server that submitted the post. 3. **Account risk or shadow bans from unfamiliar IPs** * Risk comes from content behavior and policy violations, not IP origin. 4. **Shared IP with other Blotato users** * Shared IPs are standard across SaaS tools that post content at scale (Buffer, Hootsuite, etc.). ### Why IP address does not matter * Blotato publishes through official, platform-approved API endpoints * Platforms recognize the authorized app, not a personal device * IP location does not affect reach, trust, or account safety * This works the same way as other scheduling tools like Buffer or Hootsuite *** ## Why do my Instagram Reels show on the main feed? Instagram defaults all Reels to appear on your main feed. This is Instagram's behavior, not a Blotato setting. In the Blotato web app, all video posts to Instagram are published as Reels. Instagram then shows them on your feed by default. If you are using the Blotato API, you can control this with the `shareToFeed` parameter in the Publish endpoint. See: [Publish Post API](/api/publish-post) *** ## Can I use Blotato for adult or adult-adjacent content? Does Blotato have settings to avoid shadowbans or restrictions? Blotato does not have settings or a feature to avoid getting flagged for adult-adjacent content. Blotato publishes through each platform's official API. Whether a post gets restricted is decided by the platform's own content policy, not by anything Blotato toggles on its side. What helps, and is in your control: 1. Warm up any new account before you automate it. Automating a brand new account is the fastest way to get flagged as a bot. Log in daily, engage manually, and post by hand for a few weeks first. See [Social Accounts](/settings/social-accounts). 2. Keep your posting frequency within safe daily limits per platform. Recommended maximums are in the [growth best practices guide](/tips-and-tricks/growth-best-practices). 3. Frame captions, hashtags, and on-screen text in educational or wellness terms rather than explicit ones. The algorithms read the text as much as the visuals. 4. Watch for shadowban signals, such as views collapsing across several posts, so you catch a restriction early. See [TikTok FAQs](/platforms/tiktok/faqs). *** ## Does Blotato train on my uploaded content? No. Blotato does not train AI models on your uploaded images, videos, or text content. When you upload media or generate content, Blotato processes it to create your posts and videos. Your content is stored in your account and is not used to train, fine-tune, or improve any AI models. Blotato uses third-party AI providers (OpenAI, Anthropic, Flux, Kling, etc.) to generate images and videos. These providers have their own data handling policies. Blotato sends your prompts and Brand Kit settings to these providers for generation, but does not share your uploaded media files with them. *** ## What is AI Twin? AI Twin generates text content (captions, posts) in your writing style based on your Brand Kit and Brand Voice settings. It does not generate a talking-head video avatar of you. To create videos with an AI-generated voice narrating your content, use the "AI Video with AI Voice" template in [Videos > New](https://my.blotato.com/videos/new). This creates videos with AI voiceover (powered by ElevenLabs), not a visual avatar. For talking-head avatar videos, use a dedicated avatar tool like HeyGen or Synthesia, then upload the video to Blotato for publishing. See: [Does Blotato offer AI avatars or AI clones?](/features/videos/faqs#does-blotato-offer-ai-avatars-or-ai-clones) *** ## When do you livestream? Check here for the latest schedule: [sabrina.dev/p/livestream](https://sabrina.dev/p/livestream) *** ## Someone claiming to be Sabrina messaged me on social media -- is it a scam? Yes. Messages from "Sabrina" on Facebook, Instagram, or other social platforms offering an app, an investment, or a private deal are impersonation scams. Sabrina does not send private messages on social media offering an app or asking for money. 1. Do not click links or send money or personal details 2. Report the profile on the platform where it contacted you 3. Real Blotato messages come from the in-app chat at [my.blotato.com](https://my.blotato.com) or from emails on the blotato.com domain (for example ) If you are unsure whether a message is real, ask in the in-app chat (orange circle in the bottom right corner). *** ## Why is my Pinterest account not verified? Your Pinterest still looks pretty new. You MUST warm it up for 2 weeks before connecting to 3rd party posting tools like Blotato. Failing to do this often results in being shadowbanned or flagged by Pinterest. Start posting 1 pin per day manually, then gradually ramp up to 2, then 3, etc. pins per day. Once you get 100+ views per month, then reconnect your Pinterest account with Blotato and it will be automatically verified. Blotato no longer verifies Pinterest accounts manually. There is no request to send. Verification happens automatically once you reconnect with 100+ monthly views. There is no manual override -- the 100 monthly views threshold is the only unlock criterion. See also: [Pinterest API access is temporarily restricted](/support/errors), [Brand New Accounts (Warm-Up Guide)](/platforms/tiktok/brand-new-accounts). *** ## How do I find my Pinterest Board ID? You need a Board ID to publish a pin to a specific board. ### Using Blotato Web App 1. Go to [Settings](https://my.blotato.com/settings). 2. Scroll down to your connected Pinterest account. 3. Select a Board from the dropdown. 4. Blotato copies that Board's ID to your clipboard automatically. ### Using Blotato API (n8n / Make.com) 1. Call `GET /v2/users/me/accounts?platform=pinterest` and use `items[].id` as your `accountId`. 2. Call `GET /v2/social/pinterest/boards?accountId={accountId}`. 3. Use `items[].id` as `target.boardId` when you publish. See: [List Pinterest Boards](/api/accounts) ## Why does my Pinterest board list return empty ({"items":\[]})? If the boards endpoint returns no boards: 1. Confirm you connected the correct Pinterest account. 2. Confirm the board is a standard, public board visible in Pinterest itself. 3. Get the Board ID directly from the web app: Settings > your Pinterest account > select Board (steps above). 4. New Pinterest accounts need a 2-3 week manual warm-up and validation before boards appear through automation. See [Why is my Pinterest account not verified?](#why-is-my-pinterest-account-not-verified). ## Does Blotato offer a GDPR Data Processing Agreement (DPA)? No. Blotato does not currently provide a signed Data Processing Agreement (DPA). # DM Automations DM Automations send an Instagram or Facebook direct message when someone comments on your content or sends your account a message. You manage automations in the Blotato web app or through an AI tool connected to Blotato MCP. DM Automations are available on every paid plan. An automation sends one message by default. Three optional steps extend it: a follow gate holds the message back until the person follows your Instagram account, an email gate holds it back until they reply with an email address, and a webhook calls your own endpoint once the message goes out. Blotato runs them in a fixed order: follow gate, email gate, your message, webhook. See [DM Automations](/features/dm-automations) for the full walkthrough. ## Supported Platforms * Instagram * Facebook Pages Blotato does not support SMS, WhatsApp, or other messaging channels for DM Automations. Reconnect accounts added before messaging/comments/follow gating launched so Blotato receives the required messaging permissions. * [Connect Instagram](/settings/social-accounts/instagram) * [Connect Facebook](/settings/social-accounts/facebook) ## Using the Blotato Web App 1. Open [DM Automations](https://my.blotato.com/dm-automations). 2. Create a new automation. 3. Select an Instagram account or Facebook Page. 4. Choose a comment-received or message-received trigger. 5. For a comment trigger, choose one specific post or every post. 6. Add the keywords or phrases that trigger the automation. Leave the field empty to match any text. 7. Write the direct message. 8. If you want recipients to open a link, add up to three link buttons with a button label and web URL. Skip this step for a text-only message or an email-to-webhook flow. The web app pre-fills each link button with a sample label and URL. Replace both with your own — for example, a lead-magnet download, landing page, or artifact link.
DM Automation editor showing three link buttons pre-filled with sample labels and URLs to be replaced

Link buttons come pre-filled with sample values. Replace the label and URL in each one with your own link.

Link buttons are optional. The button label is the text a recipient sees, and the Web URL is the page the button opens. Click **Remove** beside a link button to delete it. The Web URL is separate from the Webhook URL that sends automation data to your endpoint. **For Instagram, buttons only show in the Instagram mobile app.** Someone reading your DM on instagram.com in a desktop browser sees the message text with no buttons under it. Instagram sets this behavior, and no Blotato setting changes it. To work around this issue, you can add the URL directly in the message text, and Instagram will render it as a clickable link. **For Instagram, use a button or a plain-text URL, not both.** A message carrying both leaves the URL unclickable on desktop, so a desktop reader ends up with no working link at all. Keep the button for a mostly mobile audience. For a mostly desktop audience, remove the button and put the URL in the message text instead. 9. For Instagram, turn on **Ask for a follow** to hold the message back until the person follows you. Write the gate message and the button label, up to 20 characters. Facebook automations reject a follow gate. Reconnect the account first if you connected it before DM automations and follow gating landed, and ask for a typed reply in the gate message so desktop readers advance without a button. 10. Turn on **Ask for an email address** to hold the message back until the person replies with an email. Write the gate message. Blotato saves the first email address in their reply to the contact. 11. Turn on **Call a webhook** to notify your own system once the message goes out. Pick the method, enter a public `http(s)` URL, and add any headers your endpoint needs. 12. Activate the automation. 13. Review its triggered, completed, and failed totals. Someone who never answers a gate leaves the run open for 1 hour, then the run ends as expired. Expired runs count toward triggered and toward neither completed nor failed. Blotato delivers a captured email address through the webhook body, and the Blotato inbox and Messages API do not show it.
Blotato DM Automation editor showing a comment keyword trigger, direct message, link buttons, and automation statistics

Create and review a DM Automation in the Blotato web app.

Keywords ignore upper and lower case and match whole words. `PRICE` matches `price`, while `price` does not match `pricey`. The automation runs when the comment or message contains any configured keyword. ## Test a Comment Trigger **Your own comments do not trigger a DM automation.** Test from a different Instagram or Facebook account: 1. Activate the automation. 2. Sign in to a different account. 3. Comment on the target post using one of the trigger keywords. 4. Confirm the other account receives the direct message. ## Using ChatGPT, Claude, Hermes, OpenClaw, or Another MCP Client 1. Complete the [Blotato MCP setup](/api/mcp/setup). 2. Start a new chat in your AI tool. 3. Ask: "Walk me through how to set up Blotato DM Automations." 4. Describe the automation you want. Include: * The Instagram account or Facebook Page. * The automation name. * The comment or message trigger. * The target post, or state that the automation applies to every post. * The trigger keywords. * The direct-message text. * Up to three link-button labels and URLs. * A follow gate for Instagram, with its message and button label. * An email gate, with its message. * A webhook, with its method, URL, and headers. Your AI tool works with Blotato MCP to create, update, list, activate, deactivate, and archive DM Automations, including the follow gate, the email gate, and the webhook. It also retrieves automation analytics, execution runs, and logs. Follow [Turn One Comment Into a CRM Lead](/features/dm-automations#example-turn-one-comment-into-a-crm-lead) for a complete comment-to-DM example with email capture, a CRM webhook, copy-and-paste prompts, and testing steps.
Claude creating and activating a Facebook DM Automation through Blotato MCP

Describe the trigger, message, and links to create a DM Automation with Claude.

To review performance, ask your AI tool for analytics for one automation or a group of automations. The response includes triggered, completed, and failed totals by platform.
Claude showing Instagram and Facebook DM Automation analytics from Blotato

Retrieve DM Automation analytics through Claude.

## Active Contacts Each new person reached through a DM Automation counts toward your plan's monthly active-contact limit. Each contact is unique within one connected social account. If the same person interacts with two connected Facebook Pages, they count as two active contacts. Reaching the same person again through the same connected account during the monthly window does not add another contact. An automation with a follow gate or an email gate sends more than one message to the same person. Those extra messages reach a contact you already counted, so the person still counts once. Gates and webhooks add no charge and consume no credits. Deleting a conversation or automation does not reset monthly usage. The count resets at the start of the next monthly window. See [Active Contacts](/settings/billing-and-credits#active-contacts) for plan limits. ## Related API Features Use [Messages](/api/messages) to list conversations, read messages, send individual replies, and check delivery status. Use [Comments](/api/comments) to list and reply to comments. Set the follow gate, email gate, and webhook through the API with the `followGate`, `emailGate`, and `webhook` fields on [Create DM Automation](/api/dm-automations#create-dm-automation). # API Quickstart ## Get Started with Blotato API The Blotato API allows you to: * publish and schedule posts directly to social media platforms * supports text, image, videos, reels, slideshows, carousels, threads, and stories * create images, videos, slideshows, and carousels programmatically via templates It is limited to paying subscribers in order to reduce spam and service abuse, keeping Blotato's integration in good standing with the social platforms. *** ## Plans That Include API | Plan | API Access | | ---------- | ---------- | | Free Trial | No | | Starter | Yes | | Creator | Yes | | Agency | Yes | API access is included on every paid plan. Generating an API key from Settings > API immediately ends a free trial and activates your paid Starter subscription. *** ## Base URLs Blotato has two base URLs. Use the one that matches your integration: | Integration | Base URL | | ------------------------------------------------------------------------------------- | -------------------------------- | | REST API (direct HTTP, n8n, Make) | `https://backend.blotato.com/v2` | | MCP Server (ChatGPT, Claude Code, Claude Cowork, Claude Desktop, Cursor, Antigravity) | `https://mcp.blotato.com/mcp` | `api.blotato.com` is **not a valid base URL**. If your AI tool reports a DNS error for `api.blotato.com`, it guessed wrong. Use one of the two URLs above. *** ## 1. Get Your API Key :exclamation:**IMPORTANT: this will end your free trial immediately and start your paid subscription.** Go to [Settings](https://my.blotato.com/settings) > API > click "Generate API Key". *** ## 2. Connect Social Accounts Go to [Settings](https://my.blotato.com/settings) and connect your social accounts. If you get stuck, more information here: {% embed url="" %} *** ## 3. Install the Official Blotato Node ### n8n 1. Go to your n8n Admin Panel > Settings 2. Enable Verified Community Nodes 3. Open any workflow 4. Click the "+" icon in the top right corner 5. Search for "Blotato" 6. Click Install For self-hosted n8n, see: [Self-Hosted n8n Users](https://help.blotato.com/api/n8n/n8n-blotato-node#self-hosted-n8n-users) ### Make 1. Open any scenario in Make 2. Click the "+" icon to add a module 3. Search for "Blotato" 4. Select the Blotato module *** ## 4. Setup Your First Automation! **New to building automations?** Start here: * [Build Your First AI Automation](/api/templates/11-build-your-first-ai-automation) - Learn how to extract content from any source and publish to social media Choose your preferred integration path: * [MCP Server](/api/mcp) - control Blotato from ChatGPT, Claude.ai, Claude Desktop, Claude Code, Cursor, and more with natural language * [n8n - post everywhere](/api/templates/1-post-everywhere) * [Make - post everywhere](/api/templates/1-post-everywhere) * [REST API - OpenAPI reference](/api/openapi-reference) and [Examples Below](#raw-rest-api-calls-examples) Blotato has official Make.com and n8n nodes. Zapier coming soon! Check out more workflow automation templates here: {% embed url="" %} *** ## 5. Troubleshoot Errors Use the API Dashboard and click on each request to see full payload, response, and error message: **API Dashboard (for debugging):** **FIX MY AUTOMATION (n8n only):** On a failed n8n request in the API Dashboard, click the green **FIX MY AUTOMATION** button and Blotato AI will attempt to fix your n8n workflow automatically. This feature is for n8n only -- it does not work for Make, Claude, MCP, or direct REST API calls. Full walkthrough: [Fix My Automation](/api/n8n/faqs#first-step-click-fix-my-automation-in-the-api-dashboard-n8n-only). *** ## Raw REST API Calls - Examples ### Authentication To authenticate API requests, include your Blotato API key in the request headers. **Authentication Header** ``` blotato-api-key: YOUR_API_KEY ``` Requests without a valid API key will be rejected and 401 error will be returned. Your API key sometimes ends with one or more `=` characters (base64 padding). The `=` is part of your key. Copy the full key including the trailing `=`. When you paste it into a shell, `.env` file, or script, wrap it in single quotes (for example `'abc123=='`), because `=` is a special character in those contexts. A dropped or stripped trailing `=` is the most common cause of a 401 error. ### Step 0: Get Your Account IDs Before publishing, fetch your connected accounts to get the `accountId`: ``` GET https://backend.blotato.com/v2/users/me/accounts HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` Use the `id` from the response as your `accountId`. For Facebook and LinkedIn, also fetch subaccounts to get `pageId`. See [Accounts reference](/api/accounts) for details. ### Post to a Platform Immediately ``` POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "Hello, world!", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } ``` ### Post at a Scheduled Time ``` POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "Scheduled post example", "mediaUrls": [], "platform": "facebook" }, "target": { "targetType": "facebook", "pageId": "987654321" } }, "scheduledTime": "2025-03-10T15:30:00Z" } ``` To schedule at the user's next available calendar slot instead of a specific time, replace `scheduledTime` with `useNextFreeSlot: true`. Both are top-level fields, not inside `post`. See [Publish Post](/api/publish-post) for all scheduling options. ### Post a Twitter Thread with Multiple Posts ``` POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "This is the first tweet in the thread.", "mediaUrls": [], "platform": "twitter", "additionalPosts": [ { "text": "Here's the second tweet, adding more info.", "mediaUrls": [] }, { "text": "And here's the third tweet to conclude!", "mediaUrls": [] } ] }, "target": { "targetType": "twitter" } } } ``` ### Attach Media to Post (images and videos) Pass any publicly accessible image/video URL into the `mediaUrls` parameter. No upload step required. Blotato handles the media transfer. For local files without a public URL, use the [Presigned Upload](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) endpoint to upload directly to Blotato. No Google Drive or S3 needed. ``` POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "Check out this image!", "mediaUrls": [ "https://example.com/image.jpg" ], "platform": "instagram" }, "target": { "targetType": "instagram" } } } ``` The optional Upload Media endpoint is still available if you need to host media on Blotato's servers. See [Upload Media](/api/publish-post/upload-media-v2-media). *** ## For AI Agents If you are an AI agent or LLM integration, start with the plain-text API reference: [API Reference for LLMs](/api/llm) This contains the full API specification in a format optimized for LLMs, including all endpoints, parameters, status values, and a complete workflow pseudocode. For async workflow patterns and code examples, see [Protocol and Recipes](/api/workflows). For the full endpoint reference, see [API Reference](https://github.com/Blotato-Inc/help.blotato.com/blob/main/api/api-reference/README.md). # API Reference for LLMs This is the machine-readable API reference for AI agents and LLM integrations. ``` BLOTATO API REFERENCE ===================== IMPORTANT: CHECK HOW YOU ARE CONNECTED - If you have blotato_create_post, blotato_list_accounts, etc. as MCP tools: You are connected via MCP. Call those tools directly. You do NOT need HTTP endpoints, base URLs, or auth headers. See tool descriptions for parameters. MCP tools reference: https://help.blotato.com/api/mcp/tools - If you are making HTTP requests directly (no MCP tools available): Use the REST API reference below. REST API: Base URL: https://backend.blotato.com/v2 Auth Header: blotato-api-key: YOUR_API_KEY Content-Type: application/json API KEY FORMAT: Your key sometimes ends with one or more "=" characters (base64 padding). The "=" is part of the key. Send it exactly. Do not strip, trim, or URL-encode it. In shells, .env files, and scripts, wrap the key in single quotes (for example 'abc123=='), because "=" is a special character in those contexts. A 401 or "invalid API key" almost always means the key sent does not match, and a dropped trailing "=" is the most common cause. Verify with GET /users/me. All creation operations are ASYNC. Submit a request, then poll for status. Docs: https://help.blotato.com/api/start OpenAPI: https://help.blotato.com/api/api-reference/openapi-reference Errors: https://help.blotato.com/support/errors ================================================================================ MCP TOOL → REST API MAPPING (for reference only) ================================================================================ blotato_get_user → GET /users/me blotato_list_accounts → GET /users/me/accounts blotato_get_credits → GET /credits blotato_buy_credits → POST /credits blotato_create_post → POST /posts blotato_get_post_status → GET /posts/:postSubmissionId blotato_list_posts → GET /posts blotato_list_top_posts → GET /analytics blotato_get_post_analytics → GET /posts/:id/analytics blotato_list_comments → GET /comments blotato_get_comment → GET /comments/:commentId blotato_post_comment → POST /comments blotato_list_conversations → GET /conversations blotato_get_conversation → GET /conversations/:conversationId blotato_list_messages → GET /messages blotato_get_message → GET /messages/:messageId blotato_send_message → POST /messages blotato_list_automations → GET /dm-automations blotato_create_automation → POST /dm-automations blotato_update_automation → PATCH /dm-automations/:id blotato_delete_automation → DELETE /dm-automations/:id blotato_list_automation_runs → GET /dm-automations/:id/runs blotato_list_automation_logs → GET /dm-automations/:id/logs blotato_get_automation_analytics → GET /dm-automations/:id/analytics blotato_create_source → POST /source-resolutions-v3 (polls internally) blotato_get_source_status → GET /source-resolutions-v3/:id blotato_list_visual_templates → GET /videos/templates blotato_create_visual → POST /videos/from-templates blotato_get_visual_status → GET /videos/creations/:id blotato_list_schedules → GET /schedules blotato_get_schedule → GET /schedules/:id blotato_update_schedule → PATCH /schedules/:id blotato_delete_schedule → DELETE /schedules/:id blotato_list_pinterest_boards → GET /social/pinterest/boards blotato_create_presigned_upload_url → POST /media/uploads ================================================================================ REST API ENDPOINTS ================================================================================ USER INFO & CONNECTED ACCOUNTS GET /users/me - Verify API key, get user info GET /users/me/accounts - List connected social accounts (get accountId) GET /users/me/accounts/:accountId/subaccounts - Get Facebook/LinkedIn pageId GET /social/pinterest/boards?accountId=ID - List Pinterest boards (get boardId) CREDITS (billing) GET /credits - Get credit balance, account email, and pricing (price per 1,000 credits, min/max purchase quantity) POST /credits - Create a Stripe Checkout link to buy credits (quantity 1000-10000). Returns checkoutUrl. Creating the link does NOT charge; a human completes payment in the browser. Confirm the account email first (credits are non-transferable). 10 req/hour PUBLISHING POST /posts - Create/publish a post (30 req/min) GET /posts - List posts: scheduled/published/failed, cursor-paginated (60 req/min) GET /posts/:postSubmissionId - Poll post status (60 req/min) ANALYTICS (Published Post Metrics) Collected for twitter/instagram/facebook/threads/bluesky/tiktok/youtube/pinterest. LinkedIn returns no metrics yet. GET /analytics - Top performing published posts (sortBy likes_count/comments_count/views_count/reach_count, default views_count; since/until/platform/limit) GET /posts/:id/analytics - Latest metrics + snapshot history for one published post (id = published post id, not postSubmissionId) GET /published-posts - Search published posts (query/platform) with latest analytics snapshot attached Metrics: every field is optional; counts are strings, rates are numbers, breakdowns are objects. Full metric list (common + platform-specific + plan-specific): https://help.blotato.com/api/analytics-metrics COMMENTS (Instagram, Facebook) GET /comments - List comments on your Instagram and Facebook posts, cursor-paginated (60 req/min). Filters: postId, parentCommentId, accountId, platform, since, until GET /comments/:commentId - Get a single comment (60 req/min). Poll to check comment status POST /comments - Post a top-level comment, or a reply when parentCommentId is set, on a published Instagram or Facebook post (30 req/min) MESSAGING (Instagram, Facebook) GET /conversations - List direct-message conversations, cursor-paginated (60 req/min) GET /conversations/:conversationId - Get a single conversation (60 req/min) GET /messages - List messages, cursor-paginated (60 req/min) GET /messages/:messageId - Get a single message (60 req/min). Poll to check send status POST /messages - Send a direct message or a private reply to a comment, optionally with buttons or quick replies; async, poll GET /messages/:messageId until sent|failed (30 req/min) DM AUTOMATIONS (Instagram, Facebook) TESTING: Own comments never trigger an automation. Test comment-received from a different Instagram or Facebook account. GET /dm-automations - List DM automations, cursor-paginated (60 req/min) GET /dm-automations/:id - Get a single DM automation (60 req/min) POST /dm-automations - Create a DM automation (30 req/min) PATCH /dm-automations/:id - Update a DM automation; body is { "patch": { ... } } (30 req/min) DELETE /dm-automations/:id - Archive a DM automation; returns 200 with the archived flow (30 req/min) GET /dm-automations/:id/runs - List execution runs, cursor-paginated (60 req/min) GET /dm-automations/:id/logs - List execution logs, cursor-paginated; filter with flowRunId (60 req/min) GET /dm-automations/:id/analytics - All-time run totals (60 req/min) VISUALS POST /videos/from-templates - Create visual from template (30 req/min) GET /videos/creations/:id - Poll visual status GET /videos/templates - List available templates DELETE /videos/:id - Delete a video SOURCES (Content Extraction) POST /source-resolutions-v3 - Extract content from URL/text (30 req/min) GET /source-resolutions-v3/:id - Poll source status (60 req/min) SCHEDULES (Content Calendar) GET /schedules - List future scheduled posts (cursor-paginated) GET /schedules/:id - Get a single scheduled post PATCH /schedules/:id - Update scheduled post (content and/or time) DELETE /schedules/:id - Delete scheduled post and cancel publishing job SCHEDULE SLOTS (Recurring Time Windows) GET /schedule/slots - List all scheduling slots POST /schedule/slots - Create one or more slots PATCH /schedule/slots/:id - Update slot targets (platforms/accounts) DELETE /schedules/slots/:id - Delete a slot POST /schedule/slots/next-available - Find next open slot for a platform/account MEDIA POST /media - Upload media from URL (30 req/min, optional) POST /media/uploads - Get presigned upload URL for local files (120 req/min) ================================================================================ STEP 0: GET ACCOUNTS (always do this first) ================================================================================ GET /users/me/accounts GET /users/me/accounts?platform=twitter (filter by platform) Response: { "items": [ { "id": "98432", "platform": "twitter", "fullname": "Jane", "username": "jane" } ] } For Facebook/LinkedIn, also fetch subaccounts to get pageId. For YouTube, also fetch subaccounts to get playlistIds. GET /users/me/accounts/98432/subaccounts Response: { "items": [ { "id": "123456789", "accountId": "98432", "name": "My Business Page" } ] } Use items[].id as target.pageId when publishing to Facebook or LinkedIn. For YouTube accounts, subaccounts return playlists. Use items[].id values as target.playlistIds (array). For Pinterest, fetch boards to get boardId: GET /social/pinterest/boards?accountId={accountId} Response: { "items": [{ "id": "1234567890123456789", "name": "Summer Outfits" }] } Use items[].id as target.boardId when publishing a pin. ================================================================================ PUBLISHING A POST ================================================================================ SUPPORTED PUBLISHING PLATFORMS Instagram, TikTok, LinkedIn, Facebook, X (Twitter), Threads, Bluesky, Pinterest, and YouTube. This list is exhaustive for the Blotato web app, API, MCP, and Cowork. Blotato does not publish to platforms outside this list. POST /posts Minimal payload (Twitter): { "post": { "accountId": "98432", "content": { "text": "Hello world", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } RULES: - content.platform and target.targetType must be set to the same value - mediaUrls is required. Pass [] for text-only posts. Pass public URLs for media. - accountId comes from GET /users/me/accounts - No upload step needed. Pass any public URL in mediaUrls. - If a media post fails, check [Media Requirements](media.md) before retrying. Verify the target platform supports the media type, attachment count, file extension, dimensions, duration, and file size. - For local files without a public URL, use POST /media/uploads to get a presigned upload URL: 1. POST /media/uploads with {"filename": "photo.jpg"} -> returns {presignedUrl, publicUrl} 2. PUT the file binary to presignedUrl with correct Content-Type header Claude Cowork/Desktop: If an MCP upload reports "Access to this website is blocked by your network egress settings," open Settings -> Capabilities -> Allow network egress, select "Package managers only" or "Allow all," add database.blotato.io under Additional allowed domains, click Add, then restart Claude. 3. Use publicUrl in mediaUrls when publishing Max file size depends on plan (see [Plan Limits](../settings/billing-and-credits.md#plan-limits)). No Google Drive or S3 needed. SCHEDULING (optional, top-level fields alongside "post"): - scheduledTime: ISO 8601 timestamp with timezone offset (e.g., "2026-03-04T16:30:00+00:00") to publish at a specific time. If provided, useNextFreeSlot is ignored. - useNextFreeSlot: true to schedule at the user's next available calendar slot. Requires at least one calendar slot configured for the target platform. - If NEITHER scheduledTime NOR useNextFreeSlot is provided, the post PUBLISHES IMMEDIATELY. - Both fields MUST be root-level (siblings of "post"). If nested inside "post", "options", or any other object, they are IGNORED and the post publishes immediately. Publish immediately (no scheduling fields): { "post": { "accountId": "98432", "content": {...}, "target": {...} } } Schedule at user's next free calendar slot: { "post": { "accountId": "98432", "content": {...}, "target": {...} }, "useNextFreeSlot": true } Schedule at a specific time: { "post": { "accountId": "98432", "content": {...}, "target": {...} }, "scheduledTime": "2025-12-25T15:00:00Z" } WRONG (do NOT nest scheduling fields inside "post" or "options"): { "post": { "accountId": "98432", "content": {...}, "target": {...}, "useNextFreeSlot": true } } { "post": { "accountId": "98432", "content": {...}, "target": {...} }, "options": { "scheduledTime": "2026-03-04T16:30:00+00:00" } } THREADS (Twitter, Bluesky, Threads): Use content.additionalPosts[] to create a thread in a single API call. The first tweet goes in content.text. Additional tweets go in additionalPosts[]. { "post": { "accountId": "98432", "content": { "text": "First tweet in the thread (1/3)", "mediaUrls": [], "platform": "twitter", "additionalPosts": [ { "text": "Second tweet (2/3)", "mediaUrls": [] }, { "text": "Third tweet (3/3)", "mediaUrls": [] } ] }, "target": { "targetType": "twitter" } } } Each additionalPosts[] entry has: text (string), mediaUrls (array of strings). Blotato handles reply chaining. You do NOT need to capture tweet IDs. Works for: twitter, bluesky, threads. PLATFORM-SPECIFIC TARGET FIELDS (set these inside "target" alongside "targetType"): twitter: (no extra fields required) linkedin: pageId (optional) - LinkedIn Company Page ID from subaccounts endpoint. Omit for personal profile. carousels (LinkedIn Document / PDF carousel): pass 2-10 image URLs (JPG, PNG) in content.mediaUrls and Blotato auto-builds a LinkedIn Document carousel — LinkedIn's modern PDF-based carousel format, viewers swipe through pages like a PDF. This is the same format you'd use for Instagram carousels — pass the same image URLs to LinkedIn and Blotato handles the conversion. Videos are not supported in carousels. Max 10 images. facebook: pageId (REQUIRED) - from GET /users/me/accounts/{accountId}/subaccounts mediaType - "reel" REQUIRED for videos (regular feed videos no longer supported), "story" for Stories, omit for text/image posts. Stories require one video or image attachment (only the first is used if multiple provided). link (optional) - URL to attach as link preview firstComment (optional) - auto-posts as the first comment right after publishing. Up to 8000 chars. Posts and reels only, NOT stories. Reel video specs: MP4/MOV/AVI, max 1 GB, min 540x960, 9:16, 3-90s, 24-60 fps, H.264/H.265 (VP9/AV1 ok), AAC LC audio 128kbps+ 48kHz stereo instagram: mediaType (optional) - "reel" or "story". Default: "reel". No effect on image posts. altText (optional) - alt text for images, up to 1000 characters collaborators (optional) - array of Instagram handles (without @), max 3. Single image posts and reels only - NOT supported on carousels (multi-media posts), which will fail to publish. coverImageUrl (optional) - cover image URL for reels, max 8MB shareToFeed (optional) - boolean, share the reel to feed audioName (optional) - custom audio name for reels (can only set once) firstComment (optional) - auto-posts as the first comment right after publishing. Up to 2200 chars. Posts, carousels, and reels, NOT stories. Useful for links. trial (optional) - object for trial reels (shown to non-followers first). Only for reels. graduationStrategy (REQUIRED inside trial) - "MANUAL" or "SS_PERFORMANCE" MANUAL = you promote to followers manually. SS_PERFORMANCE = Instagram auto-promotes based on performance. tiktok (ALL of these are REQUIRED): privacyLevel - "SELF_ONLY", "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR" disabledComments - boolean disabledDuet - boolean disabledStitch - boolean isBrandedContent - boolean isYourBrand - boolean isAiGenerated - boolean (optional) title - for image posts, max 90 chars (optional) autoAddMusic - boolean, for photo posts only (optional) isDraft - boolean, save as draft (optional) imageCoverIndex - number, cover image index for carousels (starts from 0) (optional) videoCoverTimestamp - number, milliseconds for video cover frame pinterest: boardId (REQUIRED) - from GET /social/pinterest/boards?accountId={accountId} title (optional) altText (optional) link (optional) threads: replyControl (optional) - "everyone", "accounts_you_follow", "mentioned_only" bluesky: (no extra fields required) youtube: title (REQUIRED) - video title privacyStatus (REQUIRED) - "private", "public", "unlisted" shouldNotifySubscribers (REQUIRED) - boolean isMadeForKids (optional) - boolean, default false containsSyntheticMedia (optional) - boolean, for AI-generated content playlistIds (optional) - array of playlist IDs to add the video to. Get from GET /users/me/accounts/{accountId}/subaccounts thumbnailUrl (optional) - publicly accessible image URL for custom thumbnail. Requires verified YouTube account with custom thumbnail capabilities. YouTube "description" comes from the content.text field. Tags are not supported. webhook: url (REQUIRED) - the webhook URL Response: { "postSubmissionId": "uuid" } Poll: GET /posts/{postSubmissionId} Status values: "in-progress" | "scheduled" | "published" | "failed" - scheduled: response includes "scheduledTime" - published: response includes "publicUrl" - failed: response includes "errorMessage" ================================================================================ CREATING VISUALS ================================================================================ POST /videos/from-templates RECOMMENDED: Use "prompt" to describe what you want. Set "inputs" to {}. AI fills in the template inputs automatically from your prompt. Do NOT manually construct the "inputs" object unless you have a specific reason. templateId: Use the bare UUID from the templates list (e.g., "77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd"). Do NOT use the full path format (e.g., "/base/v2/quote-card/.../v1"). CORRECT: { "templateId": "77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd", "inputs": {}, "prompt": "Create 5 motivational quotes about entrepreneurship", "render": true } Optional fields: title - string, human-readable title for the generated video WRONG (do not manually fill inputs, use prompt instead): { "templateId": "77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd", "inputs": { "text": "Slide 1: ..." }, "render": true } Response: { "item": { "id": "vid_123", "status": "queueing" } } Poll: GET /videos/creations/{id} Status values: "queueing" | "generating-script" | "script-ready" | "generating-media" | "media-ready" | "exporting" | "done" | "creation-from-template-failed" Terminal states: "done" (success) or "creation-from-template-failed" (failure) When done: response includes "mediaUrl" and/or "imageUrls" Use mediaUrl or imageUrls in your publish request's mediaUrls field. Discover templates: GET /videos/templates?fields=id,name,description,inputs Template reference: https://help.blotato.com/api/visuals ================================================================================ EXTRACTING CONTENT (SOURCES) ================================================================================ POST /source-resolutions-v3 Body MUST contain a "source" object. Do NOT put fields at the top level. source.sourceType (REQUIRED, no auto-detection): - "text" - Transform raw text (uses source.text) - "article" - Extract from article URL (uses source.url) - "youtube" - Extract from YouTube URL (uses source.url) - "twitter" - Extract from Twitter/X URL (uses source.url) - "tiktok" - Extract from TikTok URL (uses source.url) - "perplexity-query" - AI web research (uses source.text) - "audio" - Extract from audio URL (uses source.url) - "pdf" - Extract from PDF URL (uses source.url) CORRECT: { "source": { "sourceType": "youtube", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } } WRONG (missing "source" wrapper): { "sourceType": "youtube", "url": "..." } Response: { "id": "src_123" } Poll: GET /source-resolutions-v3/{id} Status values: "queued" | "processing" | "completed" | "failed" When completed: response includes "content" and "title" ================================================================================ MANAGING SCHEDULED POSTS ================================================================================ List scheduled posts: GET /schedules?limit=20&cursor=OPTIONAL_CURSOR Response: { "items": [ { "id": "sch_abc123", "scheduledAt": "2026-04-01T14:00:00.000Z", "account": { "id": "98432", "name": "Jane Smith", "username": "janesmith", "profileImageUrl": "https://...", "subaccountId": null, "subId": null, "subaccountName": null }, "draft": { "accountId": "98432", "content": { "text": "...", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } ], "count": "12", "cursor": "eyJzY2hlZHVsZWRBd..." } NOTE: "draft" has the same structure as the "post" object in POST /posts. NOTE: "scheduledAt" is the response field name. "scheduledTime" is the input field name for updates. Get single schedule: GET /schedules/:id Response: { "schedule": { ...same fields as list item... } } Update schedule (content, time, or both): PATCH /schedules/:id { "patch": { "scheduledTime": "2026-04-05T10:00:00Z", "draft": { "accountId": "98432", "content": { "text": "Updated text", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } } Response: 204 No Content RULES: - At least one of scheduledTime or draft must be provided. - scheduledTime must be valid ISO 8601 and in the future. - draft must be a COMPLETE post object (accountId, content, target). The endpoint does NOT merge partial drafts. If you pass an incomplete draft, the update silently no-ops on the draft side. Recommended flow: GET /schedules/:id first, edit the returned object in place, then PATCH the whole object back. - DO NOT also call POST /posts (or blotato_create_post) when editing a schedule. PATCH /schedules/:id updates the existing schedule in place. Calling create publishes a separate post and you end up with duplicates at publish time. - The update endpoint does NOT accept useNextFreeSlot. To reschedule to the next available slot, first call POST /schedule/slots/next-available to get the time, then pass it as scheduledTime. Delete schedule: DELETE /schedules/:id Response: 204 No Content (publishing job is also cancelled) ================================================================================ SCHEDULE SLOTS (Content Calendar Time Windows) ================================================================================ Slots define recurring posting times. When you publish with useNextFreeSlot: true, the system finds the next open slot for the target platform and schedules the post. HOW SLOTS AND SCHEDULES RELATE: 1. Slots define your posting cadence (e.g., "Monday 9 AM for Twitter"). 2. useNextFreeSlot: true (on POST /posts) picks the next open slot. 3. A slot is "occupied" when a scheduled post is queued at that time. 4. Manage what is queued (schedules) and when (slots) separately. List slots: GET /schedule/slots Response: { "items": [ { "id": "slot_1", "hour": 9, "minute": 0, "day": "monday", "selectedTargets": [ { "platform": "twitter", "accountId": "98432", "subaccountId": null } ] } ] } Create slots: POST /schedule/slots { "slots": [ { "hour": 9, "minute": 0, "day": "monday", "selectedTargets": [ { "platform": "twitter", "accountId": "98432", "subaccountId": null } ] } ] } Response: 201 Created (returns created slots with IDs) Update slot targets: PATCH /schedule/slots/:id { "patch": { "selectedTargets": [ { "platform": "twitter", "accountId": "98432", "subaccountId": null } ] } } Response: 204 No Content Delete slot: DELETE /schedules/slots/:id Response: 204 No Content NOTE: Fails if the slot has future scheduled content. Delete the schedules first. Find next available slot: POST /schedule/slots/next-available { "platform": "twitter", "accountId": "98432", "subaccountId": null } Response: { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } } Use this when rescheduling a post to the next free slot: 1. POST /schedule/slots/next-available -> get slotTime 2. PATCH /schedules/:id -> set scheduledTime to slotTime ================================================================================ MANAGE COMMENTS ================================================================================ Comments are public comments your audience leaves on your published posts, plus comments you post back through Blotato. Supported platforms: instagram, facebook Notes: - Blotato does not backfill. It captures comments from when the account connects. - Comments are retained for up to 45 days. - Lists and posts top-level comments and one level of replies (no reply to a reply). List comments: GET /comments?limit=20&cursor=OPTIONAL_CURSOR&accountId=OPTIONAL_ACCOUNT_ID&postId=OPTIONAL_POST_ID&since=ISO_8601&until=ISO_8601 Response: { "items": [ , ... ], "cursor": "..." } Post a comment: POST /comments { "postId": "id-of-post-to-leave-comment-on", "text": "Comment text", "parentCommentId": "optional-id-of-comment-to-reply-to" } Response: a object with status "queued" PLATFORM-SPECIFIC FIELDS: instagram: text limit: 2200 characters facebook: text limit: 8000 characters comments post to your Facebook Page posts Poll: GET /comments/:commentId Status values: "queued" | "processing" | "posted" | "failed" | "deleted" - posted: live on the platform - failed: response includes errorMessage and errorCode : { "id": "cmt_abc123", "accountId": "98434", "platform": "instagram", "postId": "post_xyz789", // null if not published through Blotato "parentCommentId": null, // set when this comment is a reply "platformPostId": "17851234567890", "platformCommentId": "17899876543210", // null until posted "authorId": "1784000000", // null if unknown "isAuthor": false, // true = you authored it, false = audience "text": "Love this!", "status": "posted", "errorCode": null, "errorMessage": null, "createdAt": "2026-07-01T12:34:56Z" } NOTE: Replying to a new audience member counts toward the monthly active-contacts limit (starter 1,000 / creator 6,000 / agency 15,000). ================================================================================ MANAGE PRIVATE MESSAGES ================================================================================ Messages are private, direct messages sent through the platform inbox (DMs). Read conversations and messages, and send a direct message or a private reply to a comment. Supported platforms: instagram, facebook Notes: - Messages are retained for up to 45 days. - You reply to people who already messaged you. No cold outreach. - Platforms apply strict messaging windows. Review "MESSAGING WINDOWS" before sending messages. - Reaching a new person counts toward the monthly active-contacts limit (starter 1,000 / creator 6,000 / agency 15,000). List conversations: GET /conversations?limit=20&cursor=OPTIONAL_CURSOR&accountId=OPTIONAL_ACCOUNT_ID&platform=OPTIONAL_PLATFORM Response: { "items": [ , ... ], "cursor": "..." } Get a conversation: GET /conversations/:conversationId Response: a object : { "id": "cnv_abc123", "accountId": "98434", "platform": "instagram", "participants": [ { "id": "1784000000", "name": "Jamie", "username": "jamie", "profileImageUrl": null } ], "createdAt": "2026-07-01T12:00:00Z", "updatedAt": "2026-07-02T09:30:00Z" } List messages: GET /messages?limit=20&cursor=OPTIONAL_CURSOR&conversationId=OPTIONAL_CONVERSATION_ID&platform=OPTIONAL_PLATFORM Response: { "items": [ , ... ], "cursor": "..." } Send a message: POST /messages { "accountId": "required-account-id", "recipientId": "id-of-contact-to-send-message-to", "text": "Thanks for reaching out!", "target": { "targetType": "instagram" } } PLATFORM-SPECIFIC FIELDS: instagram: text limit: 1000 bytes Direct message, reply to a contact within the 24-hour window: recipientId: the incoming message's senderId target.targetType: "instagram" Private reply to a comment, once, within 7 days of the comment: recipientId: the comment's authorId target.targetType: "instagram" target.commentId: "id-of-comment-to-reply-to" facebook: text limit: 2000 characters target.pageId (the Facebook Page to send from) is required on every Facebook message Direct message, reply to a contact within the 24-hour window: recipientId: the incoming message's senderId target.targetType: "facebook" target.pageId: "id-of-page-to-send-from" Private reply to a comment, once, within 7 days of the comment: recipientId: the comment's authorId target.targetType: "facebook" target.pageId: "id-of-page-to-send-from" target.commentId: "id-of-comment-to-reply-to" Poll: GET /messages/:messageId Status values: "queued" | "processing" | "sent" | "delivered" | "failed" - sent / delivered: handed to / delivered by the platform - failed: response includes errorMessage and errorCode : { "id": "msg_abc123", "conversationId": "cnv_abc123", // null when not linked to a conversation "platform": "instagram", "direction": "incoming", // "incoming" received, "outgoing" you sent "senderId": "1784000000", // null if unknown "recipientId": "17841400000000000", "text": "Hi! Is this available?", "payload": null, // rich content, see BUTTONS AND QUICK REPLIES "status": "delivered", "errorCode": null, "errorMessage": null, "createdAt": "2026-07-02T09:30:00Z" } BUTTONS AND QUICK REPLIES (instagram, facebook): Set on target. Mutually exclusive - send buttons OR quickReplies, never both (422). Buttons (1-3, pinned under the message): "target": { "targetType": "instagram", "attachment": { "type": "button", "buttons": [ { "type": "web_url", "title": "View pricing", "url": "https://example.com" }, { "type": "postback", "title": "Talk to sales", "payload": "SALES" } ] } } - type: "web_url" (opens a link) or "postback" (reports the tap back). No phone buttons. - title: 1-20 characters - url: required for web_url, starts with https:// - payload: required for postback, 1-1000 characters - text is REQUIRED and capped at 640 characters when buttons are set - INSTAGRAM: buttons render in the Instagram mobile app only. A recipient reading the conversation on instagram.com in a desktop browser sees the text with no buttons. Send an attachment OR a URL inside text, never both - a message carrying both leaves the URL in text unclickable on desktop. For a desktop audience, drop the attachment and put the URL in text. Quick replies (1-13 tappable chips, disappear after a tap or a typed reply): "target": { "targetType": "instagram", "quickReplies": [ { "title": "Small", "payload": "SIZE_S" }, { "title": "Large", "payload": "SIZE_L" } ] } - title: 1-20 characters - payload: 1-1000 characters - text is REQUIRED and non-empty Reading a tap: both chip taps and postback taps arrive as the next INCOMING message carrying payload.selection, but they reach you differently: - Quick reply: the tap sends a REAL TEXT MESSAGE. text holds the chip label, and payload.selection is attached alongside it. { "text": "Large", "payload": { "selection": { "type": "quick-reply", "payload": "SIZE_L" } } } - Postback: NO text message is sent. The tap is recorded as an incoming message with text set to the button label, plus payload.selection. { "text": "Talk to sales", "payload": { "selection": { "type": "postback", "payload": "SALES" } } } - Branch on selection.payload, NOT on text. Two chips sharing a label are distinguishable only by payload. - selection.payload is the string you set. A postback carries null when you set no payload; a quick reply always carries one. - web_url buttons produce NO selection - Blotato subscribes your account to the postback webhook when you connect it. If you connected your account before buttons were launched, reconnect in Settings > Social Accounts to start receiving postback events. Quick replies need no reconnect. Outgoing messages you sent echo their own payload.attachment / payload.quickReplies. MESSAGING WINDOWS: - Standard DM: reply within 24 hours of the person's last message. - Private reply to a comment: set target.commentId. Allowed once, within 7 days of the comment. After it, message the person again only after they open a new 24-hour window. ================================================================================ MANAGE DM AUTOMATIONS ================================================================================ A DM automation sends a direct message when someone comments on your post or sends your account a message. Text plus up to 3 link buttons. Optional steps run in a FIXED order around that message: followGate (instagram only) -> emailGate -> dmMessage -> webhook Supported platforms: instagram, facebook Notes: - A comment trigger answers with a PRIVATE REPLY to the comment (one per comment, within 7 days). A message trigger answers with a standard DM (24-hour window). - Your own comments and the messages your account sends never start a run. - Link buttons are optional. Set buttons to [] for a text-only message or an email-to-webhook flow. A button title is the text the recipient sees, and its url is the page the button opens. - A button url and webhook.url serve different purposes. webhook.url receives captured email data after the DM sends. - No cold outreach. An automation answers people who contact you first. - An automation is created as a draft unless isActive is true. - While a run waits on a contact's reply, their next DM RESUMES that run instead of starting a new one. A button tap never starts a run. - Every DM an automation sends counts toward the monthly active-contacts limit. List automations: GET /dm-automations?limit=20&cursor=OPTIONAL_CURSOR Response: { "items": [ , ... ], "cursor": "..." } Create an automation: POST /dm-automations { "accountId": "required-account-id", "platform": "instagram", // "instagram" | "facebook" "target": { "targetType": "instagram" }, // facebook also needs "pageId" "name": "Auto-DM links from comments", // 1-60 characters "trigger": { "type": "comment-received", // or "message-received" "keywords": ["price", "link"], // [] matches every comment/message "postId": null // comment triggers only, see below }, "dmMessage": "Tap below for the link.", // 1-640 characters "buttons": [ // REQUIRED field, pass [] for none { "type": "url", "title": "View link", "url": "https://example.com" } ], "followGate": { // OPTIONAL, instagram only "message": "Follow me, then tap below.", // 1-640 characters "buttonTitle": "I'm following" // <= 20 chars, this is the default }, "emailGate": { // OPTIONAL, both platforms "message": "Reply with your email." // 1-640 characters }, "webhook": { // OPTIONAL, both platforms "method": "POST", // GET|POST|PUT|PATCH|DELETE "url": "https://example.com/hooks/leads", // public http(s), <= 2048 chars "headers": { "X-Api-Key": "secret" } // optional }, "isActive": true // default false (draft) } Response: 201 { "flow": } GATE AND WEBHOOK RULES: - followGate: INSTAGRAM ONLY. Sends the gate message with a confirm button, waits up to 1 HOUR for a reply, then checks follower status. Not following -> gate message again. Following or UNKNOWN status -> proceed. UNKNOWN means the contact never granted profile access, and Blotato proceeds rather than blocking them. A confirmed follow is cached 30 days; a negative result is never cached. Passing followGate on a facebook automation -> 422 (20303). ANY reply advances the gate - the follower check runs on the contact's next DM whatever it says, so the button tap is a shortcut, not a requirement. SETUP: the account must be subscribed to button-tap events, which happens at CONNECT time. An account connected before DM automations and follow gating landed does not reliably receive taps and runs reach "expired" - the user must reconnect it in Settings > Social Accounts. DESKTOP: Instagram renders the confirm button in the mobile app only. Write the gate message to ask for a typed reply (e.g. "Reply FOLLOWING once you have") so a desktop audience advances without a button. - emailGate: sends the gate message, waits up to 1 HOUR, reads the FIRST email address out of the reply. No address found -> gate message again. Found -> saved to the contact, then proceed. Shape is validated, deliverability is not. The captured address is NOT returned by GET /conversations or GET /messages - a webhook is the only way to read it. - webhook: called AFTER dmMessage sends. Every method except GET carries a JSON body with Content-Type: application/json: with emailGate -> { "email": "them@example.com" } without emailGate -> {} GET carries no body. The host must resolve to a PUBLIC address - private, loopback, link-local and cloud metadata ranges are rejected. Redirects are NOT followed. Timeout 10s. Response body read is capped at 16 KB. A non-2xx response is logged and the run STILL COMPLETES. A blocked address, DNS failure or timeout fails the run. Update an automation (patch is NESTED under "patch"): PATCH /dm-automations/:id { "patch": { "dmMessage": "New text", "buttons": [], "isActive": true } } Patchable: name, trigger, dmMessage, buttons, followGate, emailGate, webhook, isActive. Pass null for trigger, followGate, emailGate or webhook to REMOVE it. accountId, platform, and target are fixed at creation. Content changes to a LIVE automation publish immediately. Changes to a draft stay saved until isActive is true. A live automation needs a trigger - to clear it, pass isActive false in the same request. Archive an automation: DELETE /dm-automations/:id Response: 200 { "flow": } // status archived, trigger stops listening : { "id": "flow_abc123", "accountId": "98434", "name": "Auto-DM links from comments", "platform": "instagram", "target": { "targetType": "instagram" }, "trigger": { "type": "comment-received", "keywords": ["price"], "postId": null, "isActive": true }, "dmMessage": "Tap below for the link.", "buttons": [ { "type": "url", "title": "View link", "url": "https://example.com" } ], "followGate": { "message": "Follow me, then tap below.", "buttonTitle": "I'm following" }, "emailGate": { "message": "Reply with your email." }, "webhook": { "method": "POST", "url": "https://example.com/hooks/leads" }, "isActive": true, "publishedVersionId": "ver_001", // null for a draft "createdAt": "2026-08-01T12:00:00Z", "updatedAt": "2026-08-02T09:30:00Z" } TRIGGER RULES: - type "comment-received": fires on a comment on your post or reel. - type "message-received": fires on a DM someone sends your account. - keywords: case-insensitive, whole-word match, tolerant of line breaks inside a multi-word keyword. Any one keyword matching fires the automation. [] matches all. - postId (comment triggers only): the BLOTATO post id from GET /published-posts. Per-post targeting works on posts published through Blotato. Set null to watch every post and reel on the account. - Buttons in an automation are type "url" only. For postback buttons or quick replies, send the message yourself with POST /messages. - The followGate confirm button is a postback button Blotato manages - you set its label only. - INSTAGRAM: automation buttons show in the Instagram mobile app only. Put a button OR a URL inside dmMessage, never both - a message carrying both leaves the URL unclickable on desktop. For a desktop audience, pass buttons: [] and put the URL in dmMessage. INSPECT ACTIVITY: GET /dm-automations/:id/runs?limit=20&cursor=OPTIONAL_CURSOR Response: { "items": [ , ... ], "cursor": "..." } : { "id": "run_abc123", "contactId": "1784000000", // platform id of the person "platform": "instagram", "status": "failed", // running | waiting | completed | expired | superseded | failed "error": { "code": 20102, "message": "Messaging window has expired" }, "createdAt": "2026-08-02T09:30:00Z", "updatedAt": "2026-08-02T09:30:04Z" } GET /dm-automations/:id/logs?flowRunId=OPTIONAL_RUN_ID&limit=20&cursor=OPTIONAL_CURSOR Response: { "items": [ , ... ], "cursor": "..." } : { "id": "log_abc123", "flowRunId": "run_abc123", "nodeId": "nd_9fJ2", // null for run-level entries "level": "info", // info | warning | error "message": "Queued message for send", "context": { "messageId": "msg_abc123" }, "createdAt": "2026-08-02T09:30:01Z" } GET /dm-automations/:id/analytics Response: { "analytics": { "triggered": 412, "completed": 398, "failed": 9 } } A run stays open until its message settles, so completed + failed is sometimes lower than triggered. ERRORS: - 404: automation or connected account not found - 422: invalid for publishing (code 20303), or missing connected account (code 5000) ================================================================================ COMPLETE WORKFLOW (for AI agents) ================================================================================ 1. accounts = GET /users/me/accounts For Facebook or LinkedIn: also GET /users/me/accounts/{accountId}/subaccounts Use subaccount id as target.pageId (REQUIRED for Facebook, optional for LinkedIn) For YouTube: also GET /users/me/accounts/{accountId}/subaccounts to get playlist IDs Use subaccount ids as target.playlistIds (optional, array) For Pinterest: also GET /social/pinterest/boards?accountId={accountId} Use board id as target.boardId (REQUIRED for Pinterest) 2. sourceId = POST /source-resolutions-v3 { source: { sourceType, url/text } } 3. POLL: GET /source-resolutions-v3/{sourceId} until status = "completed" 4. videoId = POST /videos/from-templates { templateId, prompt, render: true } 5. POLL: GET /videos/creations/{videoId} until status = "done" 6. postSubmissionId = POST /posts { post: { accountId, content, target }, scheduledTime?: "ISO8601" } scheduledTime and useNextFreeSlot go OUTSIDE "post", at the root level. Omit both to publish immediately. 7. POLL: GET /posts/{postSubmissionId} until status = "published" 8. DONE: use publicUrl from step 7 ================================================================================ PLAN LIMITS ================================================================================ Blotato has three plans (starter, creator, agency). Each plan enforces: starter creator agency Max connected social accounts 20 40 100 Max media upload size 400 MB 1 GB 1 GB Queued scheduled posts 200 1000 3000 Scheduling horizon (months) 9 9 9 Active contacts per month 1,000 6,000 15,000 Analytics metric fields 25 all all Analytics checkpoints/post 2 18 20 Active contacts are unique per connected social account. The same person reached through two connected Facebook Pages counts as two active contacts. Reaching the same person again through the same connected account during the monthly window does not add another contact. The scheduling horizon is 9 months on EVERY plan. It does not scale with the plan. A DM sent by a DM automation counts toward active contacts like any other send. Facebook Pages and LinkedIn Company Pages count toward the cap. * Facebook: Each page counts as one account (the login does not count) * LinkedIn: Each profile and each connected company Page each count as one account. For synchronous calls like POST /posts, exceeding a plan limit returns HTTP 422. For asynchronous calls like POST /media, errors surface asynchronously and the records associated with the job will transition to status "failed". ================================================================================ RATE LIMITS ================================================================================ POST /posts: 30 requests / minute GET /posts/:id: 60 requests / minute POST /videos/from-templates: 30 requests / minute POST /source-resolutions-v3: 30 requests / minute GET /source-resolutions-v3/:id: 60 requests / minute POST /media: 30 requests / minute POST /media/uploads: 120 requests / minute GET /users/me/accounts: No limit GET /users/me: No limit 429 response means rate limit exceeded. Check "message" for retry timing. ================================================================================ COMMON MISTAKES ================================================================================ 1. Scheduling fields nested inside "post": scheduledTime and useNextFreeSlot are ROOT-LEVEL fields, siblings of "post". WRONG: { "post": { ..., "scheduledTime": "2025-12-25T15:00:00Z" } } RIGHT: { "post": { ... }, "scheduledTime": "2025-12-25T15:00:00Z" } If nested inside "post", the post publishes immediately instead of scheduling. 2. Missing pageId for Facebook: Facebook REQUIRES target.pageId. You must call GET /users/me/accounts/{accountId}/subaccounts to get the pageId before publishing. Without it, the request fails. 3. content.platform and target.targetType mismatch: These two fields must have the same value (e.g., both "twitter"). 4. Using template path instead of UUID for templateId: WRONG: "templateId": "/base/v2/quote-card/.../v1" RIGHT: "templateId": "77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd" 5. Manually filling template inputs instead of using prompt: Set "inputs": {} and describe what you want in "prompt". AI fills the inputs. 6. Wrong accounts endpoint path: WRONG: GET /accounts or GET /v2/accounts RIGHT: GET /users/me/accounts There is no /accounts endpoint. Always use the full path /users/me/accounts. ``` # Workflows Most Blotato API operations are asynchronous. You must follow the **Submit -> Poll -> Result** pattern. ## System Prompt for Agents You can use the following snippet to instruct your AI agent on how to interact with Blotato: > **Blotato API Protocol**: All creation operations (posts, videos, sources) are **async**. > > 1. Call the `CREATE` endpoint. Record the ID from the 201 response (`id` for sources, `item.id` for videos, `postSubmissionId` for posts). A scheduled post also returns `scheduledTime`, the resolved UTC publish time. > 2. Loop every 2-5 seconds calling the `GET` endpoint with that ID. > 3. Continue polling while status is processing (see status values below). > 4. Succeed when status reaches a terminal state. > > **Terminal Status Values by Operation**: > > * **Sources**: `completed` (success) or `failed` > * **Videos**: `done` (success) or `creation-from-template-failed` > * **Posts**: `published` (success) or `failed` > > **All Video Status Values** (in order): `queueing` -> `generating-script` -> `script-ready` -> `generating-media` -> `media-ready` -> `exporting` -> `done` > > **Always fetch accounts first**: `GET /v2/users/me/accounts` to get `accountId` for publishing. To get `pageId` for Facebook/LinkedIn or `playlistIds` for YouTube, also fetch `GET /v2/users/me/accounts/{accountId}/subaccounts`. > > **Set `content.platform` and `target.targetType` to the same value** (e.g., both `"twitter"`). > > **Content Calendar**: `GET /v2/schedules` to list scheduled posts. `PATCH /v2/schedules/:id` to update content or time. `DELETE /v2/schedules/:id` to cancel. `GET /v2/schedule/slots` for recurring time slots. > > Full reference: *** ## 1. Create Source -> Get Source **Goal**: Research a topic or extract content from a URL so Blotato can generate related visuals. **Endpoints**: * Create: `POST /v2/source-resolutions-v3` * Poll: `GET /v2/source-resolutions-v3/:id` **Source Types**: * `youtube`, `tiktok`, `article`, `pdf`, `audio`, `twitter` - Extract content from a URL (each type requires a `url` field) * `text` - Transform raw text content with optional AI instructions * `perplexity-query` - AI-powered web research on any topic (requires a `text` field) ```mermaid sequenceDiagram participant Agent participant API Note over Agent: 1. Submit Source (URL, Text, or Query) Agent->>API: POST /v2/source-resolutions-v3
{ source: { sourceType: "...", ... } } API-->>Agent: 201 Created { id: "src_123" } Note over Agent: 2. Poll for Extraction loop Every 2-5 Seconds Agent->>API: GET /v2/source-resolutions-v3/src_123 API-->>Agent: { status: "processing" } Note over Agent: Wait... end Note over Agent: 3. Receive Result API-->>Agent: { status: "completed", content: "Extracted text...", title: "..." } ``` ### Example Payloads **From YouTube URL**: ```json { "source": { "sourceType": "youtube", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } } ``` **From AI Research Query** (use this for agents to research topics): ```json { "source": { "sourceType": "perplexity-query", "text": "latest trends in AI-generated content for social media" } } ``` **From Text with Custom Instructions**: ```json { "source": { "sourceType": "text", "text": "Your raw content here..." }, "customInstructions": "Summarize in 5 bullet points for Instagram carousel" } ``` *** ## 2. Create Visual -> Get Visual **Goal**: Generate a video or image from a template. **Endpoints**: * Create: `POST /v2/videos/from-templates` * Poll: `GET /v2/videos/creations/:id` * Templates: `GET /v2/videos/templates?fields=id,name,description,inputs` ### Discovering Templates If you don't have a specific template ID, retrieve available templates: ```json GET https://backend.blotato.com/v2/videos/templates?fields=id,name,description,inputs&search=carousel ``` **Recommendation for Agents**: If freely deciding which template to use, carousel templates are versatile and work well for most content repurposing scenarios. See [all visual templates](/api/visuals) for IDs and specs. ### Visual Generation Flow ```mermaid sequenceDiagram participant Agent participant API Note over Agent: 0. (Optional) Discover Templates Agent->>API: GET /v2/videos/templates API-->>Agent: List of templates with IDs Note over Agent: 1. Submit Generation Request Agent->>API: POST /v2/videos/from-templates
{ templateId: "...", inputs: {...}, prompt: "..." } API-->>Agent: 201 Created { item: { id: "vid_456", status: "queueing" } } Note over Agent: 2. Poll for Rendering loop Every 5 Seconds Agent->>API: GET /v2/videos/creations/vid_456 API-->>Agent: { item: { status: "generating-media" } } Note over Agent: Wait... end Note over Agent: 3. Receive Media URLs API-->>Agent: { item: { status: "done", mediaUrl: "https://...", imageUrls: [...] } } ``` ### Example Payload (with AI Prompt) ```json { "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f", "inputs": {}, "prompt": "Create a 5-slide carousel about productivity tips", "render": true } ``` ### Example Payload (with Manual Inputs) ```json { "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f", "inputs": { "title": "My Viral Video", "images": ["https://..."] }, "render": true } ``` *** ## 3. Create Post -> Get Post **Goal**: Publish content to a social platform. **Endpoints**: * Create: `POST /v2/posts` * Poll: `GET /v2/posts/:postSubmissionId` * Account Lookup: `GET /v2/users/me/accounts` ([docs](/api/accounts)) * Subaccounts (for pageId): `GET /v2/users/me/accounts/:accountId/subaccounts` ([docs](/api/accounts#list-subaccounts-pages)) > **n8n / Make.com users**: Use the official Blotato **Get Post** node (select "Post" > "Get") instead of raw HTTP requests. It handles authentication and response parsing automatically. [Install guide](/api/start#n8n) > \[!IMPORTANT] **Prerequisites**: > > 1. **`accountId`**: Get this from `GET /v2/users/me/accounts`. Always fetch the user's accounts before publishing. See [Accounts reference](/api/accounts). > 2. **`pageId`** (Facebook/LinkedIn): Get this from `GET /v2/users/me/accounts/{accountId}/subaccounts`. See [How to Get the Right IDs](/api/accounts#how-to-get-the-right-ids-for-publishing). > 3. **`mediaUrls`**: Pass URLs directly from the **Visual Workflow** (outputs `mediaUrl` and `imageUrls`). No upload step required. > 4. **`content.platform` and `target.targetType`**: Set both to the same platform value (e.g., both `"twitter"`). ### Step 0: Fetch Available Accounts (Always Do This First) ``` GET https://backend.blotato.com/v2/users/me/accounts ``` Response: ```json { "items": [ { "id": "98432", "platform": "twitter", "fullname": "Jane Smith", "username": "janesmith" } ] } ``` For Facebook/LinkedIn, also fetch subaccounts to get the `pageId`. For YouTube, fetch subaccounts to get `playlistIds`: ``` GET https://backend.blotato.com/v2/users/me/accounts/98432/subaccounts ``` See [Accounts reference](/api/accounts) for full details. ### Publish Flow ```mermaid sequenceDiagram participant Agent participant API Note over Agent: 0. Fetch User Accounts Agent->>API: GET /v2/users/me/accounts API-->>Agent: List of accounts with IDs Note over Agent: 1. Submit Post Agent->>API: POST /v2/posts
{ post: { accountId, content, target } } API-->>Agent: 201 Created { postSubmissionId: "sub_789" } Note over Agent: 2. Poll for Publishing loop Every 2 Seconds Agent->>API: GET /v2/posts/sub_789 API-->>Agent: { status: "in-progress" } Note over Agent: Wait... end Note over Agent: 3. Success API-->>Agent: { status: "published", publicUrl: "https://twitter.com/..." } ``` ### Example Payload ```json { "post": { "accountId": "98432", "content": { "text": "Hello world!", "mediaUrls": ["https://database.blotato.io/user_1/media/vid_456.mp4"], "platform": "twitter" }, "target": { "targetType": "twitter" } } } ``` Get `accountId` from `GET /v2/users/me/accounts`. Set `content.platform` and `target.targetType` to the same value. To schedule instead of publishing immediately, add `useNextFreeSlot` or `scheduledTime` as a top-level field (sibling of `post`, not inside it). See [Publish Post](/api/publish-post#request-body) for details. *** ## Complete End-to-End Workflow (Recommended for AI Agents) This is the standard content creation sequence: research topic → create visual → publish to social. ```mermaid graph TD A["Step 0: Fetch User Accounts
GET /v2/users/me/accounts"] --> B["Step 1: Create Source
POST /v2/source-resolutions-v3"] B --> C["Step 2: Poll Source
GET /v2/source-resolutions-v3/:id
Until status = completed"] C --> D["Step 3: Create Visual
POST /v2/videos/from-templates
Use source content in prompt"] D --> E["Step 4: Poll Visual
GET /v2/videos/creations/:id
Until status = done"] E --> F["Step 5: Create Post
POST /v2/posts
Use mediaUrl from step 4"] F --> G["Step 6: Poll Post
GET /v2/posts/:postSubmissionId
Until status = published"] G --> H["Done! Post is live"] style A fill:#e1f5ff style H fill:#c8e6c9 ``` ### Pseudocode for Agents ``` 1. accountsList = GET /v2/users/me/accounts 2. sourceId = POST /v2/source-resolutions-v3 (specify sourceType: youtube, article, text, etc.) 3. LOOP: source = GET /v2/source-resolutions-v3/:sourceId - IF status = "completed": BREAK - IF status = "failed": STOP, report error - ELSE: WAIT 2-5 seconds, retry 4. videoId = POST /v2/videos/from-templates (use source.content in prompt) 5. LOOP: video = GET /v2/videos/creations/:videoId - IF status = "done": BREAK - IF status = "creation-from-template-failed": STOP, report error - ELSE: WAIT 5 seconds, retry 6. postSubmissionId = POST /v2/posts (accountId from step 1, mediaUrl/imageUrls from step 5) - Set content.platform and target.targetType to the same value 7. LOOP: post = GET /v2/posts/:postSubmissionId - IF status = "published": BREAK - IF status = "failed": STOP, check errorMessage - ELSE: WAIT 2 seconds, retry 8. RETURN: post.publicUrl ``` *** ## 4. Managing the Content Calendar **Goal**: View, update, reschedule, or delete scheduled posts. Manage the recurring time slots that define your posting cadence. **How Slots and Schedules Work Together**: 1. **Slots** define recurring time windows (e.g., "Monday 9 AM for Twitter"). Create them with `POST /v2/schedule/slots`. 2. When you publish with `useNextFreeSlot: true`, Blotato finds the next open slot matching the target platform and queues the post at that time. 3. A slot is "occupied" when a scheduled post is already queued at that time. The next `useNextFreeSlot` call skips occupied slots. 4. **Schedules** are the queued posts. **Slots** are the time windows. Manage them separately. **Endpoints**: * Schedules: `GET /v2/schedules`, `GET /v2/schedules/:id`, `PATCH /v2/schedules/:id`, `DELETE /v2/schedules/:id` ([docs](/api/schedules)) * Slots: `GET /v2/schedule/slots`, `POST /v2/schedule/slots`, `PATCH /v2/schedule/slots/:id`, `DELETE /v2/schedules/slots/:id`, `POST /v2/schedule/slots/next-available` ([docs](/api/schedule-slots)) ### Schedule Response Shape The `draft` field in a schedule is the same shape as the `post` object in [Publish Post](/api/publish-post): ```json { "id": "sch_abc123", "scheduledAt": "2026-04-01T14:00:00.000Z", "account": { "id": "98432", "name": "Jane Smith", "username": "janesmith", "profileImageUrl": "https://...", "subaccountId": null, "subId": null, "subaccountName": null }, "draft": { "accountId": "98432", "content": { "text": "Scheduled post content", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } ``` > **Note**: The response uses `scheduledAt` for the publish time. The update endpoint accepts `scheduledTime` as the input field name. ### Rescheduling to the Next Free Slot The `PATCH /v2/schedules/:id` endpoint accepts `scheduledTime` but not `useNextFreeSlot`. To move a post to the next available slot: ``` 1. POST /v2/schedule/slots/next-available Body: { "platform": "twitter", "accountId": "98432" } Response: { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } } 2. PATCH /v2/schedules/sch_abc123 Body: { "patch": { "scheduledTime": "2026-04-02T09:00:00Z" } } ``` ### Pseudocode for Calendar Management ``` 1. schedules = GET /v2/schedules (paginate with cursor if needed) 2. Display scheduled posts to user (scheduledAt, account info, draft content) 3. To reschedule: PATCH /v2/schedules/:id { patch: { scheduledTime: "new ISO 8601" } } 4. To update content: PATCH /v2/schedules/:id { patch: { draft: { full post object } } } 5. To delete: DELETE /v2/schedules/:id 6. To reschedule to next free slot: a. nextSlot = POST /v2/schedule/slots/next-available { platform, accountId } b. PATCH /v2/schedules/:id { patch: { scheduledTime: nextSlot.slot.slotTime } } ``` *** ## Error Handling All asynchronous operations can fail during processing. Handle failures gracefully: ### Status Failure When polling returns `status: "failed"`, check the error message: **Source Failure** (Get Source endpoint): ```json { "status": "failed", "message": "Unable to extract content from URL" } ``` **Video Failure** (Get Visual Status endpoint): ```json { "item": { "status": "creation-from-template-failed" } } ``` **Post Failure** (Get Post Status endpoint): ```json { "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "failed", "errorMessage": "Invalid account credentials" } ``` ### Retry Strategy * **Don't retry automatically on failure** - most failures are permanent * **Log the error message** and report it to the user * **Inform user** that the operation failed and provide next steps * **Only retry on temporary network errors** (5xx status codes), not on 4xx errors *** ## Platform-Specific Setup Different platforms require different fields and have different requirements. See detailed guides: * [**Instagram Setup**](/settings/social-accounts/instagram) - Reels, Stories, Collaborators, Alt Text * [**LinkedIn Setup**](/settings/social-accounts/linkedin) - Company Pages, Professional Network * [**Facebook Setup**](/settings/social-accounts/facebook) - Page ID, Media Types * [**Platform Requirements**](/tips-and-tricks/social-platform-requirements) - All platforms at a glance When publishing, always include the required fields for the target platform: * **Facebook**: `target.pageId` (required), `target.mediaType` -- required `"reel"` for videos (regular feed videos no longer supported), optional `"story"` for Stories, omit for text/image posts * **LinkedIn**: `target.pageId` (optional) * **Pinterest**: `target.boardId` (required) * **YouTube**: `target.playlistIds` (optional - array of playlist IDs from subaccounts) * **TikTok**: `target.privacyLevel`, `target.disabledComments`, etc. (required) * **Instagram**: `target.mediaType` (optional - default is "reel") * **Twitter, Threads, Bluesky**: Minimal required fields # Account ## List Connected Accounts ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/users/me/accounts` **Method:** `GET` ### Description Returns all social media accounts connected to your Blotato account. Use this to get the `accountId` required for [publishing posts](/api/publish-post). ### Query Parameters | Field | Type | Required | Description | | ---------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `platform` | `string` | No | Filter by platform. Values: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube` | The `platform` values here are the same values used in `content.platform` and `target.targetType` when publishing. ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "98432", "platform": "twitter", "fullname": "Jane Smith", "username": "janesmith" }, { "id": "98433", "platform": "facebook", "fullname": "Jane Smith", "username": "janesmith" } ] } ``` | Field | Type | Description | | ------------------ | -------- | -------------------------------------------------------- | | `items` | `array` | List of connected accounts | | `items[].id` | `string` | Account ID. Use this as `accountId` when publishing. | | `items[].platform` | `string` | Platform type (e.g., `twitter`, `facebook`, `instagram`) | | `items[].fullname` | `string` | Display name of the account | | `items[].username` | `string` | Username or handle | If no accounts are returned, the user needs to connect social accounts in [Blotato Settings](https://my.blotato.com/settings). ### Examples #### List all accounts ```http GET https://backend.blotato.com/v2/users/me/accounts HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Filter by platform ```http GET https://backend.blotato.com/v2/users/me/accounts?platform=instagram HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` *** ## List Subaccounts (Pages) ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/users/me/accounts/:accountId/subaccounts` **Method:** `GET` ### Description Returns subaccounts for a connected account. Subaccounts include Facebook Pages, LinkedIn Company Pages, and YouTube Playlists. Use this to get the `pageId` required for publishing to Facebook/LinkedIn, or `playlistIds` for adding YouTube videos to playlists. ### Path Parameters | Field | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------------- | | `accountId` | `string` | Yes | The account ID from the List Accounts endpoint | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "123456789", "accountId": "98433", "name": "My Business Page" } ] } ``` | Field | Type | Description | | ------------------- | -------- | ----------------------------------------------------------------------------------- | | `items` | `array` | List of subaccounts | | `items[].id` | `string` | Subaccount ID. Use this as `target.pageId` when publishing to Facebook or LinkedIn. | | `items[].accountId` | `string` | Parent account ID | | `items[].name` | `string` | Name of the page | If subaccounts is empty, the user needs to connect a Facebook Page, LinkedIn Company Page, or YouTube account in [Blotato Settings](https://my.blotato.com/settings). ### Example ```http GET https://backend.blotato.com/v2/users/me/accounts/98433/subaccounts HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` *** ## How to Get the Right IDs for Publishing Different platforms need different IDs. Here is how to get them for each platform. ### Twitter, Instagram, TikTok, Threads, Bluesky These platforms need only an `accountId`: 1. Call `GET /v2/users/me/accounts?platform=twitter` (replace with your platform) 2. Use `items[].id` as `accountId` in your publish request 3. If multiple accounts are returned, use `fullname` or `username` to identify the correct one, or ask the user which account to use ### YouTube YouTube needs an `accountId`. To add videos to playlists, also fetch subaccounts to get playlist IDs: 1. Call `GET /v2/users/me/accounts?platform=youtube` 2. Use `items[].id` as `accountId` 3. Call `GET /v2/users/me/accounts/{accountId}/subaccounts` 4. Use `items[].id` values as `target.playlistIds` in your publish request 5. `playlistIds` is optional -- omit it to publish without adding to a playlist ### Facebook Facebook requires both `accountId` and `pageId`: 1. Call `GET /v2/users/me/accounts?platform=facebook` 2. Use `items[].id` as `accountId` 3. Call `GET /v2/users/me/accounts/{accountId}/subaccounts` 4. Use `items[].id` as `target.pageId` in your publish request 5. If multiple pages are returned, use `name` to identify the correct one, or ask the user which page to use **Full example:** ``` 1. GET /v2/users/me/accounts?platform=facebook Response: { "items": [{ "id": "98433", "platform": "facebook", ... }] } 2. GET /v2/users/me/accounts/98433/subaccounts Response: { "items": [{ "id": "123456789", "name": "My Business Page" }] } 3. POST /v2/posts with: { "post": { "accountId": "98433", "content": { "text": "Hello!", "mediaUrls": [], "platform": "facebook" }, "target": { "targetType": "facebook", "pageId": "123456789" } } } ``` ### LinkedIn Company Page To post to a LinkedIn Company Page instead of your personal profile: 1. Call `GET /v2/users/me/accounts?platform=linkedin` 2. Use `items[].id` as `accountId` 3. Call `GET /v2/users/me/accounts/{accountId}/subaccounts` 4. Use `items[].id` as `target.pageId` 5. If you skip `pageId`, the post goes to your personal LinkedIn profile ### Pinterest Pinterest requires a `boardId`. Fetch boards with the List Pinterest Boards endpoint: 1. Call `GET /v2/users/me/accounts?platform=pinterest` 2. Use `items[].id` as `accountId` 3. Call `GET /v2/social/pinterest/boards?accountId={accountId}` 4. Use `items[].id` as `target.boardId` in your publish request 5. If multiple boards are returned, use `name` to identify the correct one, or ask the user which board to use > Web app shortcut: you can also grab a Board ID without the API. Go to [Settings](https://my.blotato.com/settings), scroll to your Pinterest account, and select a Board -- Blotato copies its Board ID to your clipboard. Use this if the boards endpoint returns an empty list. **Full example:** ``` 1. GET /v2/users/me/accounts?platform=pinterest Response: { "items": [{ "id": "98436", "platform": "pinterest", ... }] } 2. GET /v2/social/pinterest/boards?accountId=98436 Response: { "items": [{ "id": "1234567890123456789", "name": "Summer Outfits" }] } 3. POST /v2/posts with: { "post": { "accountId": "98436", "content": { "text": "Check out this pin!", "mediaUrls": ["https://example.com/image.jpg"], "platform": "pinterest" }, "target": { "targetType": "pinterest", "boardId": "1234567890123456789" } } } ``` *** ## List Pinterest Boards ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/social/pinterest/boards` **Method:** `GET` ### Description Returns boards owned by a connected Pinterest account. Use this to get the `boardId` required when publishing a pin. ### Query Parameters | Field | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------------------------- | | `accountId` | `string` | Yes | Blotato Pinterest account ID from `GET /users/me/accounts`. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "1234567890123456789", "name": "Summer Outfits" } ] } ``` | Field | Type | Description | | -------------- | -------- | ------------------------------------------------------------- | | `items` | `array` | List of Pinterest boards (max 250) | | `items[].id` | `string` | Board ID. Use this as `target.boardId` when publishing a pin. | | `items[].name` | `string` | Display name of the board on Pinterest | ### Example ```http GET https://backend.blotato.com/v2/social/pinterest/boards?accountId=98436 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` # User Info ## User Info /v2/users/me ### General Fetches the current user's information, including subscription status. This endpoint is useful for verifying that your API key is valid and referencing your own `userId`. ### Endpoints **GET** `/v2/users/me` #### Response Keys | Name | Type | Description | | -------------------- | -------- | --------------------------------------------------------------- | | `id` | `string` | The unique ID of the user. | | `subscriptionStatus` | `string` | The user's subscription status (e.g., `active`, `generic_pro`). | | `apiKey` | `string` | **\[Sensitive]** The user's API key. | *** ## Examples ### Get verification info ```http GET https://backend.blotato.com/v2/users/me HTTP/1.1 blotato-api-key: blt_... ``` **Response 200 OK** ```json { "id": "e931cdad-0c31-4191-8930-745a76c8e31a", "subscriptionStatus": "active_pro", "apiKey": "blt_..." } ``` # Voice IDs Below is the list of available AI voices from Elevenlabs. Simply pass in the Voice ID you want to use in your API request. All voices use ElevenLabs' `eleven_multilingual_v2` model, which supports multiple languages. To generate a voiceover in Spanish, French, Portuguese, or another supported language, write your script in that language — no additional parameter needed. The voice output language matches the script language automatically. Custom ElevenLabs voices are not available as a native voiceId parameter in the Blotato API yet. Native API support is on the roadmap. Workaround: Generate your ElevenLabs audio via the [ElevenLabs API](https://elevenlabs.io/docs/api-reference) separately, then pass the audio URL into the "Combine Existing Clips" template in the Create Visual node. This template accepts an optional audio/music URL, letting you combine any video with any custom voice. To use custom voices in the web app, create your video at [Videos > New](https://my.blotato.com/videos/new) after adding your ElevenLabs API key in [Settings](https://my.blotato.com/settings). ## voiceName vs voiceId Templates use different voice fields depending on the version: * **"AI Video with AI Voice" template**: Uses `voiceName` -- pass the display name of the voice (e.g., `"Brian"` or `"Brian (American, deep)"`). The template matches the name to the correct ElevenLabs voice. * **Older templates and direct API calls**: Use `voiceId` -- pass the full ElevenLabs voice ID string from the table below (e.g., `"elevenlabs/eleven_multilingual_v2/nPczCjzI2devNBz1zQrb"`). If you are using n8n or Make.com, the official Blotato nodes show a dropdown for voice selection, so you do not need to copy IDs manually. ## Available Voices The following ElevenLabs voices are available via the Blotato API:
IDNameTags
elevenlabs/eleven_multilingual_v2/Xb7hH8MSUJpSbSDYk0k2Alicefemale, middle-aged, British, confident, news
elevenlabs/eleven_multilingual_v2/9BWtsMINqrJLrRacOk9xAriafemale, middle-aged, American, expressive, social media
elevenlabs/eleven_multilingual_v2/pqHfZKP75CvOlQylNhV4Billmale, old, American, trustworthy, narration
elevenlabs/eleven_multilingual_v2/nPczCjzI2devNBz1zQrbBrianmale, middle-aged, American, deep, narration
elevenlabs/eleven_multilingual_v2/N2lVS1w4EtoT3dr4eOWOCallummale, middle-aged, Transatlantic, intense, characters
elevenlabs/eleven_multilingual_v2/IKne3meq5aSn9XLyUdCDCharliemale, middle aged, Australian, natural, conversational
elevenlabs/eleven_multilingual_v2/XB0fDUnXU5powFXDhCwaCharlottefemale, young, Swedish, seductive, characters
elevenlabs/eleven_multilingual_v2/iP95p4xoKVk53GoZ742BChrismale, middle-aged, American, casual, conversational
elevenlabs/eleven_multilingual_v2/onwK4e9ZLuTAKqWW03F9Danielmale, middle-aged, British, authoritative, news
elevenlabs/eleven_multilingual_v2/cjVigY5qzO86Huf0OWalEricmale, middle-aged, American, friendly, conversational
elevenlabs/eleven_multilingual_v2/JBFqnCBsd6RMkjVDRZzbGeorgemale, middle aged, British, warm, narration
elevenlabs/eleven_multilingual_v2/cgSgspJ2msm6clMCkdW9Jessicafemale, young, American, expressive, conversational
elevenlabs/eleven_multilingual_v2/FGY2WhTYpPnrIDTdsKH5Laurafemale, young, American, upbeat, social media
elevenlabs/eleven_multilingual_v2/TX3LPaxmHKxFdv7VOQHJLiammale, young, American, articulate, narration
elevenlabs/eleven_multilingual_v2/pFZP5JQG7iQjIQuC4BkuLilyfemale, middle-aged, British, warm, narration
elevenlabs/eleven_multilingual_v2/XrExE9yKIg1WjnnlVkGXMatildafemale, middle-aged, American, friendly, narration
elevenlabs/eleven_multilingual_v2/SAz9YHcvj6GT2YYXdXwwRivernon-binary, middle-aged, American, confident, social media
elevenlabs/eleven_multilingual_v2/CwhRBWXzGAHq8TQ4Fs17Rogermale, middle-aged, American, confident, social media
elevenlabs/eleven_multilingual_v2/EXAVITQu4vr4xnSDxMaLSarahfemale, young, American, soft, news
elevenlabs/eleven_multilingual_v2/bIHbv24MWmeRgasZH58oWillmale, young, American, friendly, social media
# Credits Blotato credits pay for AI generations such as videos and images. Use these endpoints to check your remaining credit balance, see current pricing, and buy more credits. Two endpoints: * [Get Credit Balance](#get-credit-balance) — `GET /v2/credits` * [Buy Credits](#buy-credits) — `POST /v2/credits` Credits belong to a single account and are non-transferable. Confirm the account email from [Get Credit Balance](#get-credit-balance) before you buy, so the credits land on the account you intend. *** ## Get Credit Balance ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/credits` **Method:** `GET` ### Description Returns your remaining credits, the email of the account the API key belongs to, and current purchase pricing. ### Response **Status Code:** `200 OK` | Field | Type | Description | | ------------------------ | --------- | ------------------------------------------------------------------ | | `creditsRemaining` | `integer` | Credits left on the account. | | `accountEmail` | `string` | Email of the account the API key belongs to. | | `purchaseQuantityRange` | `object` | Allowed purchase range, with `min` and `max` credits per purchase. | | `pricePer1000CreditsUsd` | `number` | Price in US dollars per 1,000 credits. | Example response: ```json { "creditsRemaining": 54688, "accountEmail": "user@example.com", "purchaseQuantityRange": { "min": 1000, "max": 10000 }, "pricePer1000CreditsUsd": 6.0 } ``` ### Errors | Status | Reason | | ------ | --------------------------- | | `401` | Missing or invalid API key. | | `500` | Server error. | *** ## Buy Credits ### Endpoint **URL:** `/credits` **Method:** `POST` ### Description Creates a Stripe Checkout link to buy credits. Creating the link does not charge anything. The account owner opens the link in a browser and completes payment there, and the purchased credits land on this account. Buy between 1,000 and 10,000 credits per request. Confirm the account email from [Get Credit Balance](#get-credit-balance) first, since credits are non-transferable between accounts. ### Request Body | Field | Type | Required | Description | | ---------- | --------- | -------- | ----------------------------------------- | | `quantity` | `integer` | Yes | Credits to buy. Between 1,000 and 10,000. | | `referral` | `string` | No | Optional referral code. | ### Response **Status Code:** `201 Created` | Field | Type | Description | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `checkoutUrl` | `string` | Stripe Checkout URL. Open it in a browser to complete payment. No charge happens until checkout completes. | Example response: ```json { "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_123" } ``` ### Errors | Status | Reason | | ------ | ---------------------------------------------------------------------------------- | | `400` | The quantity is outside the 1,000 to 10,000 range, or the request body is invalid. | | `401` | Missing or invalid API key. | | `429` | Rate limit exceeded (10 requests per hour). | | `500` | Server error. | *** ## Pricing Credits cost $6.00 per 1,000 credits. Read the current price from [Get Credit Balance](#get-credit-balance) (`pricePer1000CreditsUsd`), since pricing changes over time. # Post ## Publishing a Post ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/posts` **Method:** `POST` **Rate Limit:** 30 requests / minute ### Description Publish a new post to a social media platform. The request must include the post content, target platform, and an `accountId` (fetched from `GET /v2/users/me/accounts`). After submitting, poll [Get Post Status](/api/publish-post/get-post) with the returned `postSubmissionId` to track publishing progress. ### Before You Start 1. Fetch your connected accounts: `GET /v2/users/me/accounts` ([docs](/api/accounts)) 2. Fetch your subaccounts to get `pageId` for Facebook/LinkedIn and `playlistIds` for YouTube: `GET /v2/users/me/accounts/{accountId}/subaccounts` ([docs](/api/accounts#list-subaccounts-pages)). 3. Set `content.platform` and `target.targetType` to the same platform value (e.g., both `"twitter"`) *** ### Request Body The request body has two top-level fields: `post` (required) and optional scheduling fields. Do not nest scheduling fields inside `post`. | Field | Type | Required | Description | | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `post` | `object` | Yes | The post content and metadata. | | `scheduledTime` | `string` | No | ISO 8601 timestamp with timezone offset (e.g., `2026-03-04T16:30:00+00:00`). If provided, `useNextFreeSlot` is ignored. | | `useNextFreeSlot` | `boolean` | No | Schedule at the next available slot time. Defaults to `false`. Requires at least one calendar slot configured for the target platform. | **Scheduling behavior:** * If `scheduledTime` is set: the post is scheduled for that time. `useNextFreeSlot` is ignored. * If `useNextFreeSlot` is `true` (and no `scheduledTime`): the post is scheduled at the next available calendar slot for that platform. * If neither `scheduledTime` nor `useNextFreeSlot` is provided: **the post publishes immediately.** * Both fields must be **root-level** (siblings of `post`). If they are nested inside `post`, `options`, or any other object, they are ignored and the post publishes immediately. ### `post` Object | Field | Type | Required | Description | | ----------- | -------- | -------- | --------------------------------------------------------------------- | | `accountId` | `string` | Yes | The account ID from `GET /v2/users/me/accounts`. | | `content` | `object` | Yes | The content of the post. See `content` below. | | `target` | `object` | Yes | The target platform and platform-specific fields. See `target` below. | ### `content` Object | Field | Type | Required | Description | | ----------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `string` | Yes | The text content of the post. | | `mediaUrls` | `array of strings` | Yes | Array of media URLs. Pass any publicly accessible URL -- no upload step required. Pass `[]` for text-only posts. | | `platform` | `string` | Yes | Must match `target.targetType`. Values: `twitter`, `linkedin`, `facebook`, `instagram`, `pinterest`, `tiktok`, `threads`, `bluesky`, `youtube`, `other` | | `additionalPosts` | `array` | No | Additional posts for threads (Twitter, Bluesky, Threads). Each has `text` and `mediaUrls`. | `other` is reserved for publishing to a custom webhook. It does not represent another native social platform. ### `target` Object The `target` object requires `targetType` and platform-specific fields. Set `targetType` to match `content.platform`. #### Quick Reference: Required Fields Per Platform | Platform | `targetType` | Required Fields | Optional Fields | | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | Twitter | `"twitter"` | (none) | (none) | | LinkedIn | `"linkedin"` | (none) | `pageId` | | Facebook | `"facebook"` | `pageId` | `mediaType`, `link`, `firstComment` | | Instagram | `"instagram"` | (none) | `mediaType`, `altText`, `collaborators`, `coverImageUrl`, `shareToFeed`, `audioName`, `trial`, `firstComment` | | TikTok | `"tiktok"` | `privacyLevel`, `disabledComments`, `disabledDuet`, `disabledStitch`, `isBrandedContent`, `isYourBrand`, `isAiGenerated` | `title`, `autoAddMusic`, `isDraft`, `imageCoverIndex`, `videoCoverTimestamp` | | Pinterest | `"pinterest"` | `boardId` | `title`, `altText`, `link` | | Threads | `"threads"` | (none) | `replyControl` | | Bluesky | `"bluesky"` | (none) | (none) | | YouTube | `"youtube"` | `title`, `privacyStatus`, `shouldNotifySubscribers` | `isMadeForKids`, `containsSyntheticMedia`, `playlistIds`, `thumbnailUrl` | | Webhook | `"webhook"` | `url` | (none) | *** #### Twitter | Field | Type | Required | | ------------ | ----------- | -------- | | `targetType` | `"twitter"` | Yes | #### LinkedIn | Field | Type | Required | Description | | ------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------- | | `targetType` | `"linkedin"` | Yes | | | `pageId` | `string` | No | LinkedIn Company Page ID from [subaccounts](/api/accounts#list-subaccounts-pages). Omit to post to personal profile. | **Carousels:** Pass 2-10 image URLs (JPG, PNG) in `content.mediaUrls`. Blotato auto-builds a LinkedIn Document carousel (LinkedIn's modern PDF-based carousel format — viewers swipe through pages). Videos cannot be mixed into a carousel. #### Facebook | Field | Type | Required | Description | | -------------- | --------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `targetType` | `"facebook"` | Yes | | | `pageId` | `string` | Yes | Facebook Page ID from [subaccounts](/api/accounts#list-subaccounts-pages). | | `mediaType` | `"reel"` or `"story"` | See description | Video posts must use `"reel"` (regular feed videos no longer supported). Set `"story"` for Stories. Omit (default) for text-only or image posts. Stories require one video or image attachment; if more than one is provided, only the first is used. See [Facebook Reel requirements](/tips-and-tricks/social-platform-requirements#facebook). | | `link` | `string` | No | URL to attach as a link preview. | | `firstComment` | `string` | No | Auto-posts this text as the first comment right after the post publishes. Up to 8000 characters. Works on feed posts and reels, not Stories. | #### Instagram | Field | Type | Required | Description | | --------------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `targetType` | `"instagram"` | Yes | | | `mediaType` | `"reel"` or `"story"` | No | Default: `"reel"`. Has no effect on image posts. | | `altText` | `string` | No | Alt text for images. Up to 1000 characters. | | `collaborators` | `array of strings` | No | Instagram handles to tag (max 3). Do not include the @ sign. Single image posts and reels only - **not supported on carousels** (multi-media posts), which will fail to publish. | | `coverImageUrl` | `string` | No | Cover image URL for reels. Max 8MB. | | `shareToFeed` | `boolean` | No | Share the reel to the Instagram feed. Only applies to reels. | | `audioName` | `string` | No | Custom audio name for reels. You can only set this once per reel. | | `trial` | `object` | No | Settings for trial reels. Trial reels are shown to non-followers first. Only applies to reels. See `trial` object below. | | `firstComment` | `string` | No | Auto-posts this text as the first comment right after the post publishes. Up to 2200 characters. Works on posts, carousels, and reels, not Stories. Useful for putting a link in the first comment. | **`trial` Object** | Field | Type | Required | Description | | -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `graduationStrategy` | `string` | Yes | `"MANUAL"` (you promote to followers manually) or `"SS_PERFORMANCE"` (Instagram auto-promotes based on performance). | #### TikTok | Field | Type | Required | Description | | --------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `targetType` | `"tiktok"` | Yes | | | `privacyLevel` | `string` | Yes | `SELF_ONLY`, `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, or `FOLLOWER_OF_CREATOR` | | `disabledComments` | `boolean` | Yes | | | `disabledDuet` | `boolean` | Yes | | | `disabledStitch` | `boolean` | Yes | | | `isBrandedContent` | `boolean` | Yes | Set `true` only for a paid partnership with a third-party brand. Adds TikTok's paid-partnership disclosure. Set `false` for organic content. | | `isYourBrand` | `boolean` | Yes | Set `true` when the post promotes your own brand, product, or business. This drives TikTok's "Promotional content" disclosure. Set `false` for organic content. | | `isAiGenerated` | `boolean` | Yes | Set `true` when the content is AI-generated. This drives TikTok's AI-generated label. Set `false` for content you filmed or made yourself. | | `title` | `string` | No | Title for image posts. Max 90 characters. No effect on videos. | | `autoAddMusic` | `boolean` | No | Add music to photo posts. No effect on videos. Default: `false`. | | `isDraft` | `boolean` | No | Post as a draft. Drafts appear in TikTok mobile app notifications, not the Drafts folder. | | `imageCoverIndex` | `number` | No | Index (starting from 0) of image to use as cover for carousels. | | `videoCoverTimestamp` | `number` | No | Timestamp in milliseconds to use as video cover. | For organic content that is not sponsored and not AI-generated, set `isBrandedContent`, `isYourBrand`, and `isAiGenerated` to `false`. Set `isYourBrand` to `true` only to promote your own brand, and `isAiGenerated` to `true` only for AI-generated content. Each field maps to a separate TikTok content disclosure, so set only the ones that apply. #### Pinterest | Field | Type | Required | Description | | ------------ | ------------- | -------- | ------------------------------------------------------------------------------------------ | | `targetType` | `"pinterest"` | Yes | | | `boardId` | `string` | Yes | Pinterest Board ID. [Get from List Pinterest Boards](/api/accounts#list-pinterest-boards). | | `title` | `string` | No | Pin title. | | `altText` | `string` | No | Pin alt text. | | `link` | `string` | No | Pin URL link. | Pinterest "description" comes from the `content.text` field. #### Threads | Field | Type | Required | Description | | -------------- | ----------- | -------- | ------------------------------------------------------ | | `targetType` | `"threads"` | Yes | | | `replyControl` | `string` | No | `everyone`, `accounts_you_follow`, or `mentioned_only` | #### Bluesky | Field | Type | Required | | ------------ | ----------- | -------- | | `targetType` | `"bluesky"` | Yes | #### YouTube | Field | Type | Required | Description | | ------------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `targetType` | `"youtube"` | Yes | | | `title` | `string` | Yes | Video title. | | `privacyStatus` | `string` | Yes | `private`, `public`, or `unlisted` | | `shouldNotifySubscribers` | `boolean` | Yes | | | `isMadeForKids` | `boolean` | No | Default: `false` | | `containsSyntheticMedia` | `boolean` | No | Whether media contains AI-generated content. | | `playlistIds` | `array of strings` | No | YouTube playlist IDs to add the video to. Get from [subaccounts](/api/accounts#list-subaccounts-pages). | | `thumbnailUrl` | `string` | No | Publicly accessible image URL to use as the video thumbnail. Requires a verified YouTube account with custom thumbnail capabilities. | YouTube "description" comes from the `content.text` field. Tags are not supported -- YouTube recommends against relying on tags for discovery ([source](https://support.google.com/youtube/answer/146402?hl=en)). #### Webhook | Field | Type | Required | Description | | ------------ | ----------- | -------- | -------------------------------------- | | `targetType` | `"webhook"` | Yes | | | `url` | `string` | Yes | The webhook URL to send the post data. | *** ### Response **Status Code:** `201 Created` ```json { "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "scheduledTime": "2025-03-10T15:30:00Z" } ``` | Field | Type | Description | | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- | | `postSubmissionId` | `string` | ID of the post submission. Use it to poll [Get Post Status](/api/publish-post/get-post) for publishing progress. | | `scheduledTime` | `string` | The resolved UTC time the post publishes. Absent when the post publishes immediately. | `scheduledTime` tells you the slot Blotato picked when you send `useNextFreeSlot: true`, so you read the scheduled time without a follow-up call. Failed posts are visible at . The most common cause of failed posts is incorrect JSON structure. *** ### Examples #### 1. Simplest Post (Twitter, text only) ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "Hello, world!", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } ``` #### 2. Instagram Post with Images ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98434", "content": { "text": "Check out these photos!", "mediaUrls": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ], "platform": "instagram" }, "target": { "targetType": "instagram", "firstComment": "Full guide: https://blotato.com" } } } ``` Posting multiple images to Instagram creates a carousel. `firstComment` auto-posts as the first comment right after the post goes live, a common way to share a link without putting it in the caption. #### 3. Facebook Page Post ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98433", "content": { "text": "New product announcement!", "mediaUrls": ["https://example.com/product.jpg"], "platform": "facebook" }, "target": { "targetType": "facebook", "pageId": "123456789" } } } ``` Get `accountId` and `pageId` from the [Accounts endpoints](/api/accounts#facebook). #### 4. TikTok Post (all required fields) ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98435", "content": { "text": "Tips for productivity", "mediaUrls": ["https://example.com/video.mp4"], "platform": "tiktok" }, "target": { "targetType": "tiktok", "privacyLevel": "PUBLIC_TO_EVERYONE", "disabledComments": false, "disabledDuet": false, "disabledStitch": false, "isBrandedContent": false, "isYourBrand": false, "isAiGenerated": true } } } ``` #### 5. Scheduled Post ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "This will go live later", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } }, "scheduledTime": "2025-12-25T15:00:00Z" } ``` #### 6. Twitter Thread ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "Here is a thread about AI content creation (1/3)", "mediaUrls": [], "platform": "twitter", "additionalPosts": [ { "text": "First, research your topic using reliable sources (2/3)", "mediaUrls": [] }, { "text": "Then, create visuals and publish across platforms (3/3)", "mediaUrls": [] } ] }, "target": { "targetType": "twitter" } } } ``` Threads work for Twitter, Bluesky, and Threads. #### 7. Schedule at Next Free Slot ```json POST https://backend.blotato.com/v2/posts HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "post": { "accountId": "98432", "content": { "text": "Scheduled to the next free slot", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } }, "useNextFreeSlot": true } ``` `useNextFreeSlot` and `scheduledTime` are top-level fields, not inside `post`. # Get Post Status ## Check Post Status ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/posts/:postSubmissionId` **Method:** `GET` **Rate Limit:** 60 requests / minute ### Description Poll this endpoint to check the publishing status of a post. After submitting a post with [Create Post](/api/publish-post), use the returned `postSubmissionId` to track its progress. ### Request #### Path Parameters | Field | Type | Required | Description | | ------------------ | -------- | -------- | ------------------------------------------------------------ | | `postSubmissionId` | `string` | Yes | The post submission ID returned by the Create Post endpoint. | ### Responses #### Success Response **Status Code:** `200 OK` The response shape depends on the current status: **Published (terminal - success):** ```json { "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "published", "publicUrl": "https://x.com/user/status/123456" } ``` **Failed (terminal - error):** ```json { "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "failed", "errorMessage": "Unsupported media type" } ``` **In Progress (keep polling):** ```json { "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "in-progress" } ``` **Scheduled (queued for a future time):** ```json { "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "scheduled", "scheduledTime": "2025-03-10T15:30:00Z" } ``` #### Response Keys | Field | Type | Description | | ------------------ | -------- | ----------------------------------------------------------------------- | | `postSubmissionId` | `string` | The post submission ID. | | `status` | `string` | One of: `in-progress`, `scheduled`, `published`, `failed`. | | `scheduledTime` | `string` | The scheduled publish time. Present when status is `scheduled`. | | `publicUrl` | `string` | The live URL of the published post. Present when status is `published`. | | `errorMessage` | `string` | Description of the failure. Present when status is `failed`. | ### Polling Strategy 1. Poll every 2 seconds after submitting a post. 2. Continue while status is `in-progress`. 3. If status is `scheduled`, the post is queued for the returned `scheduledTime`. 4. Stop when status is `published` (success) or `failed` (error). 5. Do not retry on `failed` -- most failures are permanent. Check `errorMessage` for details. Failed posts are also visible at . ### Example ```http GET https://backend.blotato.com/v2/posts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` # List Posts ## List Posts ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/posts` **Method:** `GET` **Rate Limit:** 60 requests / minute ### Description Returns the current user's posts (scheduled, published, and failed) within a time window, ordered by post time (most recent first). Supports cursor-based pagination and filtering by status and platform. To check the status of a single post by its `postSubmissionId`, use [Get Post Status](/api/publish-post/get-post) instead. ### Query Parameters | Field | Type | Required | Description | | ---------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `since` | `string` | No | Only include posts whose post time is on or after this ISO 8601 timestamp. Defaults to 7 days ago. | | `until` | `string` | No | Only include posts whose post time is on or before this ISO 8601 timestamp. Defaults to 7 days from now. | | `limit` | `integer` | No | Number of items per page. Min: 1, Max: 250. Default: 50. | | `cursor` | `string` | No | Pagination cursor from a previous response. Pass it to fetch the next page. | | `status` | `string[]` | No | Filter by status. One or more of `scheduled`, `published`, `failed`. Pass multiple values to include any of them. Omit to include all statuses. | | `platform` | `string[]` | No | Filter by social media platform. One or more of `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube`. Pass multiple values to include any of them. Omit to include all platforms. | Array query parameters are repeated, e.g. `?status=scheduled&status=published`. ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "98432", "postTime": "2026-04-01T14:00:00.000Z", "platform": "twitter", "text": "Scheduled post content", "mediaUrls": [], "state": { "type": "scheduled" } }, { "id": "98431", "postTime": "2026-03-30T09:15:00.000Z", "platform": "instagram", "text": "Check out this image!", "mediaUrls": ["https://example.com/image1.jpg"], "state": { "type": "published", "postUrl": "https://instagram.com/p/abc123" } }, { "id": "98430", "postTime": "2026-03-29T11:00:00.000Z", "platform": "tiktok", "text": "Failed upload", "mediaUrls": ["https://example.com/clip.mp4"], "state": { "type": "failed", "errorMessage": "Unsupported media type" } } ], "cursor": "MjAyNi0wMy0yOVQxMTowMDow..." } ``` #### Response Keys | Field | Type | Description | | ------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `items` | `array` | List of posts within the time window, ordered by `postTime` descending. | | `items[].id` | `string` | The post's identifier. Distinct per `state.type`: scheduled posts use the schedule ID, published posts use the published post ID, failed posts use the failed post ID. | | `items[].postTime` | `string` | ISO 8601 UTC timestamp. For scheduled posts this is the planned publish time; for published posts it is when the post was published; for failed posts it is when the failure was recorded. | | `items[].platform` | `string` | Social media platform. | | `items[].text` | `string` | The post text. | | `items[].mediaUrls` | `string[]` | URLs of attached media (images, video). Empty when text-only. | | `items[].state` | `object` | Discriminated union; see below. | | `cursor` | `string` | Pagination cursor. Pass this as the `cursor` query parameter to fetch the next page. Absent when there are no more pages. | #### `state` object The shape depends on `state.type`: **Scheduled** ```json { "type": "scheduled" } ``` **Published** ```json { "type": "published", "postUrl": "https://instagram.com/p/abc123" } ``` | Field | Type | Description | | --------- | ---------------- | ---------------------------------------------------------------------------- | | `postUrl` | `string \| null` | The live URL of the published post. Null if the platform did not return one. | **Failed** ```json { "type": "failed", "errorMessage": "Unsupported media type" } ``` | Field | Type | Description | | -------------- | ---------------- | ------------------------------------------ | | `errorMessage` | `string \| null` | Human-readable description of the failure. | ### Errors | Status | Reason | | ------ | -------------------------------------------- | | `422` | Invalid `since`, `until`, or `cursor` value. | ### Examples #### Default request ```http GET https://backend.blotato.com/v2/posts HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Only published Twitter posts in the last 30 days ```http GET https://backend.blotato.com/v2/posts?since=2026-04-12T00:00:00Z&status=published&platform=twitter HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Scheduled or published, multi-platform ```http GET https://backend.blotato.com/v2/posts?status=scheduled&status=published&platform=twitter&platform=instagram HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Walking pages ```http GET https://backend.blotato.com/v2/posts?limit=100 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` If the response contains a `cursor`, pass it on the next request: ```http GET https://backend.blotato.com/v2/posts?limit=100&cursor=MjAyNi0wMy0yOVQxMTowMDow... HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` When the response omits `cursor`, you have reached the end of the list. # List Published Posts List your published posts, filtered by text and platform, with each post's latest analytics snapshot attached. Use this to find a published post and its `id`, or to browse recent posts with their current metrics. For engagement rankings and full metric history, see [Analytics](/api/analytics). ## Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/published-posts` **Method:** `GET` ## Description Returns your published posts, newest or oldest first, filtered by an optional full-text query and platform. Each item carries its latest metrics snapshot. Results use offset-based pagination with a total `count`. ## Query Parameters | Field | Type | Required | Description | | ---------- | --------- | -------- | -------------------------------------------------------------- | | `query` | `string` | No | Full-text search over post content. Omit to include all posts. | | `platform` | `string` | No | Filter to one platform. Omit to include all platforms. | | `sortBy` | `string` | No | Sort order: `newest` or `oldest`. Default `newest`. | | `offset` | `integer` | No | Number of posts to skip before the page. Default 0. | | `limit` | `integer` | No | Number of posts to return. Min: 1, Max: 100. Default: 20. | ## Response **Status Code:** `200 OK` ```json { "items": [ { "id": "98431", "content": "Check out this image!", "postUrl": "https://instagram.com/p/abc123", "platform": "instagram", "createdAt": "2026-05-30T09:15:00.000Z", "mediaUrls": ["https://example.com/image1.jpg"], "latestMetrics": { "fetchedAt": "2026-06-11T12:00:00.000Z", "metrics": { "likesCount": "1240", "reachCount": "53000" } }, "metricsHistory": [] } ], "count": 137 } ``` | Field | Type | Description | | ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | | `items` | `array` | Published posts for this page. | | `items[].id` | `string` | The published post id. Pass it to [Get Post Analytics](/api/analytics#get-post-analytics) for full metric history. | | `items[].content` | `string` | The post text. | | `items[].postUrl` | `string or null` | Live URL of the published post. Null if the platform did not return one. | | `items[].platform` | `string` | Social media platform. | | `items[].createdAt` | `string` | ISO 8601 timestamp when the post was published. | | `items[].mediaUrls` | `string[]` | URLs of attached media. Empty when text-only. | | `items[].latestMetrics` | `object` | The most recent metrics snapshot. Absent if no metrics have been collected yet. See [Metrics](/api/analytics#metrics). | | `items[].metricsHistory` | `array` | Collected snapshots, oldest first. Each is `{ fetchedAt, metrics }`. | | `count` | `integer` | Total number of posts matching your search, across all pages. | To page through results, increase `offset` by `limit` on each call until `offset` reaches `count`. ## Errors | Status | Reason | | ------ | --------------------------------------------- | | `422` | Invalid `sortBy`, `offset`, or `limit` value. | ## Example ```http GET https://backend.blotato.com/v2/published-posts?query=summer&platform=instagram&limit=20 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` # Upload Media ## Upload is Now Optional You no longer need to upload media to Blotato before publishing. You can pass any publicly accessible image/video URL directly into the `mediaUrls` parameter in the Publish node. Blotato handles the media transfer automatically. For local files without a public URL, use the [Presigned Upload](#presigned-upload-local-files) endpoint below. This lets you upload directly to Blotato without needing Google Drive, S3, or any other intermediate storage. Upload size depends on your plan (see [Plan Limits](/settings/billing-and-credits#plan-limits)). The legacy Upload Media endpoint is still available if you prefer to use it, or if you need to host media on Blotato's servers. *** ## Upload Media ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/media` **Method:** `POST` ### Description This endpoint allows users to upload media by providing a URL. The uploaded media will be processed and stored, returning a new media URL that is used to publish a new post. Most of the platforms require validated URLs for posting images. You can upload: * publicly accessible URLs * base64 encoded image data Media uploads are subject to your plan's upload size limit. See [Plan Limits](/settings/billing-and-credits#plan-limits) for more details. If you are using the n8n "Binary Data" upload option, the file size limit is 15MB. For larger files, use the [Presigned Upload](#presigned-upload-local-files) endpoint above (no external hosting needed), or host your media on Google Drive, AWS S3, or another cloud storage service and pass the URL instead. ### Request #### Request Body
FieldTypeRequiredDescription
urlstring✅The URL of the media to upload.
### Responses #### Success Response **Status Code:** `201 Created` **Response Body:** ``` { "url": "https://database.blotato.com/path-to-uploaded-media.jpg" } ``` #### Error Responses **Internal Server Error** **Status Code:** `500 Internal Server Error` ``` { "code": 9999, "message": "An unknown error occurred." } ``` **Too Many Requests** Media upload has a user-level rate limit of 30 requests / minute. **Status Code:** `429 Too many requests` ``` { "statusCode": 429, "message": "Rate limit exceeded, retry in 49 seconds" } ``` #### Error Codes The following client error codes may be returned: | Code | Description | | ------ | -------------- | | `9999` | Unknown error. | ### Examples #### 1. Upload Media ``` POST https://backend.blotato.com/v2/media HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "url": "https://example.com/image.jpg" } ``` **Response:** ``` { "url": "https://database.blotato.com/d1655c49-0bc4-4dd0-88b2-323ce0069fa4.jpg" } ``` ## Presigned Upload (Local Files) Upload local files directly to Blotato without hosting them on Google Drive or S3 first. This is the recommended approach for MCP users and anyone working with local files. ### Endpoint **URL:** `/media/uploads` **Method:** `POST` **Rate limit:** 120 requests per minute ### Request #### Request Body | Field | Type | Required | Description | | ---------- | -------- | -------- | ----------------------------------------------------------------------------------------- | | `filename` | `string` | Yes | Filename with extension (e.g., "photo.jpg", "video.mp4"). Used to determine content type. | ### Response **Status Code:** `201 Created` ```json { "presignedUrl": "https://...", "publicUrl": "https://..." } ``` * `presignedUrl` -- upload your file here via HTTP PUT. Expires after a short period. * `publicUrl` -- the final public URL to use in `mediaUrls` when publishing. ### Complete Example: Upload a Local File and Post It Three steps: get the presigned URL, upload the file, then publish the post. **Step 1: Get a presigned upload URL** ```bash curl -X POST https://backend.blotato.com/v2/media/uploads \ -H "Content-Type: application/json" \ -H "blotato-api-key: YOUR_API_KEY" \ -d '{"filename": "product-photo.jpg"}' ``` Response: ```json { "presignedUrl": "https://database.blotato.com/storage/v1/object/upload/sign/...", "publicUrl": "https://database.blotato.com/storage/v1/object/public/.../product-photo.jpg" } ``` **Step 2: Upload the file to the presigned URL** ```bash curl -X PUT "PRESIGNED_URL_FROM_STEP_1" \ -H "Content-Type: image/jpeg" \ --data-binary @product-photo.jpg ``` Use the correct Content-Type for your file (image/jpeg, image/png, video/mp4, etc.). **Step 3: Publish a post using the public URL** ```bash curl -X POST https://backend.blotato.com/v2/posts \ -H "Content-Type: application/json" \ -H "blotato-api-key: YOUR_API_KEY" \ -d '{ "post": { "accountId": "YOUR_ACCOUNT_ID", "content": { "text": "Check out this product!", "mediaUrls": ["PUBLIC_URL_FROM_STEP_1"], "platform": "instagram" }, "target": { "targetType": "instagram" } } }' ``` Max file size depends on your plan. See: [Plan Limits](/settings/billing-and-credits#plan-limits) for more details. The presigned URL expires after a short period -- upload the file immediately after receiving it. ### Troubleshooting: presigned PUT fails in Claude Cowork or Claude Desktop If `POST /v2/media/uploads` returns a `presignedUrl` but the **PUT step** to that URL fails with a sandbox, proxy, network egress, or "Stream closed" error, this is a Claude Cowork / Claude Desktop sandbox restriction, not a Blotato API issue. Fix it by allowlisting `database.blotato.io` in Cowork's network egress settings. Full steps: [Presigned upload PUT fails / "Sandbox error" / network egress blocked](/api/mcp/faqs#presigned-upload-put-fails-sandbox-error-network-egress-blocked-in-claude-cowork-or-claude-desktop). For Claude Code (sandbox not user-configurable), skip the local upload entirely and pass a public URL into `mediaUrls` directly. *** ## Using Google Drive as a Media Source Google Drive share links open a viewer page, not a direct file. Blotato needs a direct file URL to fetch and read media. ### Set sharing permissions For automation workflows (n8n, Make.com), set the entire Google Drive **folder** to "Anyone with the link" as Viewer. All files inside that folder inherit the same permission, so you do not need to set permissions on each file individually. For one-off uploads, set the individual file to "Anyone with the link" as Viewer. ### Common Google Drive URL Errors **Folder URLs don't work**: If your link looks like `/drive/folders/...`, it's a folder link. Blotato needs a direct link to a specific file, not a folder. **Preview URLs don't work reliably**: If your link ends with `/view?...`, it points to Google Drive's preview page, not the raw file. ### Use the direct download URL format For Google Drive files, including large videos, first replace the standard share link with this format: ``` https://drive.usercontent.google.com/download?id={FILE_ID}&export=download&confirm=t ``` Replace `{FILE_ID}` with the ID from your share link. For example, if your share link is: ``` https://drive.google.com/file/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ/view ``` The file ID is `1aBcDeFgHiJkLmNoPqRsTuVwXyZ`, so the direct URL is: ``` https://drive.usercontent.google.com/download?id=1aBcDeFgHiJkLmNoPqRsTuVwXyZ&export=download&confirm=t ``` Make sure the file is shared with "Anyone with the link" as Viewer. The `confirm=t` parameter requests the file download from Google Drive. Blotato does not impose a 100 MB Google Drive cutoff. The file still must fit your Blotato plan's upload limit and the destination platform's media limit. ### Seeing error "Google Drive can't scan this file for viruses"? Google Drive sometimes returns a virus-scan warning page instead of the file for large videos. Blotato converts Google Drive share links to the direct download format above, but Google Drive might still return the warning page.
If the direct download URL still returns the warning page, use the [Presigned Upload](#presigned-upload-local-files) flow, frame.io, AWS S3, or Google Cloud Storage. These options avoid the Google Drive warning page. # Media Requirements ## Twitter ### General Guidelines * **Max Character Length**: For regular accounts the character limit is 280 characters. For Premium accounts the character limit is 25,000 characters. * **Media Attachments per Tweet**: You can attach up to 4 photos, 1 animated GIF, or 1 video in a single Tweet. * If you see a 429 error from Twitter, you are posting too much. Twitter has a per user limit of 100 requests per 24 hours. ### Image Specifications * **Supported Formats**: JPG, PNG, GIF, WEBP * **File Size Limit**: Images must be ≤ 5 MB; animated GIFs must be ≤ 15 MB. * **Animated GIF Recommendations**: * **Resolution**: ≤ 1280x1080 pixels * **Frame Count**: ≤ 350 frames * **Total Pixels**: Width × Height × Number of Frames ≤ 300 million pixels * **File Size**: ≤ 15 MB For larger GIFs, use the chunked upload endpoint with `media_category=tweet_gif` to enable asynchronous processing. ### Video Specifications **Recommended Settings**: * **Codec**: H.264 High Profile * **Frame Rates**: 30 FPS or 60 FPS * **Resolutions**: * 1280x720 (landscape) * 720x1280 (portrait) * 720x720 (square) Subscribed users can upload 1080p videos and receive 1080p playback; unsubscribed users are limited to 720p. * **Bitrates**: * **Video**: Minimum 5,000 kbps * **Audio**: Minimum 128 kbps * **Audio Codec**: AAC Low Complexity (LC) * **Aspect Ratios**: 16:9 (landscape or portrait), 1:1 (square) **Advanced Constraints**: * **Frame Rate**: ≤ 60 FPS * **Dimensions**: Between 32x32 and 1280x1024 pixels * **File Size**: ≤ 512 MB * **Duration**: Between 0.5 seconds and 140 seconds\* * **Aspect Ratio Range**: Between 1:3 and 3:1 * **Pixel Aspect Ratio**: 1:1 * **Pixel Format**: YUV 4:2:0 * **Audio Channels**: Mono or Stereo; 5.1 or greater is not supported * **GOP Structure**: Closed GOP required; open GOP is not supported * **Scan Type**: Progressive scan only; interlaced video is not supported \* If your video doesn't meet Twitter's specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ## Instagram ### General Guidelines * **Caption Length**: Instagram captions are limited to 2200 characters. ### Image Specifications * **Format**: JPEG, PNG * **File Size**: Maximum of 8 MB * **Aspect Ratio**: Must be within a 4:5 to 1.91:1 range * **Minimum Width**: 320 pixels (images will be scaled up to this width if smaller) * **Maximum Width**: 1440 pixels (images will be scaled down to this width if larger) For optimal display, it's recommended to use square images with a 1:1 aspect ratio. This ensures that your content utilizes the maximum area on the platform. ### Video Specifications * **Format**: MP4 and MOV. * **File Size**: Maximum of 300 MB * **Duration**: * Minimum: 3 seconds * Maximum: * Reel: 15 minutes\* * Story: 60 seconds * **Aspect Ratio**: Must be within a 4:5 to 1.91:1 range * **Minimum Width**: 320 pixels * **Maximum Width**: 1440 pixels Blotato checks Instagram video bitrate and resolution before publishing: * Videos above 25 Mbps are re-encoded at 20 Mbps. * Videos above 1080p are downscaled while preserving their aspect ratio. This includes 4K video. * Conversion is limited to videos no longer than 120 seconds. Longer videos must meet Instagram's bitrate and resolution requirements before you submit them. To skip conversion, export at 1080p or lower with a video bitrate of 25 Mbps or lower. Similar to images, using a 1:1 aspect ratio for videos is recommended to maximize on-screen display area. \* If your video doesn't meet Instagram's specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ### Carousel Specifications * **Composition**: Images, videos, or a mix of both. * **Number of Items**: 2 to 10. * **Aspect Ratio Cropping**: All carousel items are cropped based on the first image. The default aspect ratio is 1:1. * **Video Aspect Ratio:** 1:1 (square), 4:5 (portrait), and 1.91:1 (landscape) Each item within the carousel must adhere to the respective image and video specifications outlined above. ## LinkedIn ### General Guidelines * **Character Limit per Post**: LinkedIn allows up to 3000 characters per post. ### Image Specifications * **Supported Formats**: JPG, GIF, and PNG. * **File Size Limit**: Images must be ≤ 5 MB. * **Pixel Count**: Images should have less than 36,152,320 pixels. * **Animated GIF Constraints**: * **Frame Limit**: GIFs support up to 250 frames. For optimal display, it's recommended to use images with a 1.91:1 aspect ratio, such as 1200 x 627 pixels. This ensures that your content utilizes the maximum area on the platform. ### Video Specifications * **Supported Format**: MP4. * **File Size**: Between 75 KB and 500 MB. * **Duration**: Between 3 seconds and 30 minutes.\* * **Resolution**: Minimum of 256 x 144 pixels; maximum of 4096 x 2304 pixels. * **Aspect Ratios**: * **Landscape**: 16:9 * **Portrait**: 9:16 * **Square**: 1:1 * **Frame Rate**: Up to 60 frames per second (fps). * **Bitrate**: Up to 30 Mbps. For optimal display across devices, consider using a square (1:1) aspect ratio with a resolution of 1080 x 1080 pixels. This format adapts well to both mobile and desktop environments. \* If your video doesn't meet LinkedIn's specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ## Facebook ### General Guidelines * **Graph API Endpoints**: Max character limit is 63,206 characters ### Image Specifications * **Supported Formats**: JPEG, PNG, GIF, BMP, and TIFF. * **File Size Limit**: Up to 30 MB. * **Recommended Resolution**: At least 1080 pixels wide. * **Aspect Ratios**: * **Square**: 1:1 * **Portrait**: 4:5 * **Landscape**: 1.91:1 * **Additional Recommendations**: * Use images with minimal text overlay to avoid reduced delivery. * Ensure images are clear and not pixelated or blurry. * For PNG files, keep the file size below 1 MB to prevent pixelation. ### Video Specifications All Facebook videos publish as **Reels**. Regular Facebook feed video posts are no longer supported. * **Supported Formats**: MP4, MOV, AVI. * **File Size Limit**: Up to 1 GB. * **Duration**: Between 3 seconds and 90 seconds. * **Minimum Resolution**: 540 x 960 pixels (width x height). * **Aspect Ratio**: 9:16. * **Frame Rate**: 24 to 60 frames per second. * **Additional Recommendations**: * Use high-quality audio and include captions to enhance accessibility. * For videos with text overlays, ensure the text is within the safe zone to prevent cropping, especially on mobile devices. * Shorter videos (15 seconds or less) are more likely to capture viewer attention. ## TikTok ### Description Specifications * **Character Limit**: The character limit is 2200 characters. ### Video Specifications * **Supported Formats**: MP4 (recommended), WebM, and MOV. * **Codecs**: H.264 (recommended), H.265, VP8, VP9. * **Frame Rate**: Minimum of 23 FPS; maximum of 60 FPS. * **Resolution**: Minimum of 360 pixels for both height and width; maximum of 4096 pixels for both height and width. * **Duration**: Up to 10 minutes.\* * **File Size**: Maximum of 4 GB. \* If your video doesn't meet TikTok's specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ### Image Specifications * **Supported Formats**: WebP, JPEG. * **Resolution**: Maximum of 1080 pixels. * **File Size**: Maximum of 20 MB per image. ## Pinterest ### Description Specifications * **Description Character Limit**: 800 characters. * **Title Character Limit**: 100 characters. * **Alt Text Character Limit**: 800 characters. * **URL Link Character Limit**: 2048 characters. ### Image Specifications * **Supported Formats**: PNG, JPEG. * **File Size**: Maximum of 20 MB per image. ### Video Specifications * **Supported Formats**: MP4 (recommended), MOV. * **Codecs**: H.264 (recommended), H.265. * **Resolution**: 240p minimum * **Duration**: Minimum 4 seconds, Maximum 5 minutes.\* * **Audio**: Optional, but advisable. * **File Size**: Maximum of 2 GB. \* If your video doesn't meet Pinterest's specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ### Carousel Specifications * **Number of Items**: 2 to 5 images. ## Threads ### Image Specifications * **Supported Formats**: JPEG and PNG * **File Size**: Maximum of 8 MB * **Resolution**: * **Minimum Width**: 320 pixels (scaled up if smaller) * **Maximum Width**: 1440 pixels (scaled down if larger) * **Height**: Varies depending on width and aspect ratio * **Aspect Ratio**: Between 10:1 and 1:10 * **Color Space**: sRGB (Images in other color spaces will be converted to sRGB) ### Video Specifications * **Supported Formats**: * **Container**: MP4 (MPEG-4 Part 14) or MOV * **Video Codec**: H.264 or HEVC (progressive scan, closed GOP, 4:2:0 chroma subsampling) * **Audio Codec**: AAC, maximum 48 kHz sample rate, mono or stereo * **Resolution**: * **Maximum Width**: 1920 pixels * **Aspect Ratio**: Between 0.01:1 and 10:1 (9:16 recommended to avoid cropping or blank space) * **Frame Rate**: Between 23 and 60 FPS * **Bitrates**: * **Video Bitrate**: Variable bitrate (VBR), up to 100 Mbps * **Audio Bitrate**: Maximum 128 kbps * **Duration**: Between 1 second and 5 minutes (300 seconds)\* * **File Size**: Maximum of 1 GB \* If your video doesn't meet Threads' specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ### Text and Media Post Limitations * **Text Posts**: Limited to 500 characters per post * **Media Per Post**: 1 image or video per Threads post. The Threads API does not support carousel posts, so a `mediaUrls` array with more than one item fails with the error "Threads only supports a single image or a video". * **Posting Multiple Images**: Publish a thread instead, with one image per post. Put each extra post in the `additionalPosts` array with a single item in its `mediaUrls`: post 1 contains image 1, post 2 contains image 2, and so on. ## Bluesky **Post Character Limit**: 300 characters per post **Image Guidelines:** * **Up to 4 images** * **Single and multiple image posts**: * Square: 1080 x 1080 pixels * Landscape: 1200 x 627 pixels * Portrait: 627 x 1200 pixels **Video Guidelines:** * **Supported formats**: MP4, WebM, and MOV * **Videos per post**: 1 * The public media URL must end in `.mp4`, `.webm`, or `.mov` so Blotato recognizes it as a video. * Blotato uploads the video to Bluesky's video service and waits for processing before publishing the post. ## YouTube ### Video Specifications * **Supported Formats**: YouTube accepts various video formats, including MP4, MOV, AVI, WMV, FLV, 3GPP, and WebM. [elfsight.com](https://elfsight.com/blog/requirements-uploading-video-youtube/?utm_source=chatgpt.com) * **Recommended Format**: MP4 with H.264 video codec and AAC-LC audio codec is recommended for optimal quality and file size. [support.google.com](https://support.google.com/youtube/answer/1722171?hl=en\&utm_source=chatgpt.com) * **Resolution and Aspect Ratio**: * Standard aspect ratio: 16:9. * Recommended resolutions: * 2160p (4K): 3840x2160 * 1440p (2K): 2560x1440 * 1080p (Full HD): 1920x1080 * 720p (HD): 1280x720 * 480p (SD): 854x480 * 360p: 640x360 * 240p: 426x240 * For videos intended for sale or rental, a minimum resolution of 1920x1080 is required.[support.google.com](https://support.google.com/youtube/answer/4603579?hl=en\&utm_source=chatgpt.com) * **Frame Rate**: Content should be encoded and uploaded in the same frame rate it was recorded. Common frame rates include 24, 25, 30, 48, 50, and 60 frames per second. [support.google.com](https://support.google.com/youtube/answer/1722171?hl=en\&utm_source=chatgpt.com) * **Bitrate**: Choose H.264 encoding for the best balance of quality and file size. Keep the bitrate between 8 Mbps (1080p) and 35 Mbps (4K). [zebracat.ai](https://www.zebracat.ai/post/best-video-format-youtube-updated-guide?utm_source=chatgpt.com) * **File Size and Duration**: Verified accounts can upload videos up to 256 GB or 12 hours\*, whichever is less. [en.wikipedia.org](https://en.wikipedia.org/wiki/List_of_YouTube_features?utm_source=chatgpt.com) \* If your video doesn't meet YouTube's specifications, Blotato will attempt to convert it for you. In this case, the video must be shorter than 120 seconds. ### Image Specifications * **Channel Art (Banner Image)**: * Recommended dimensions: 2560x1440 pixels. * Safe area for text and logos: 1546x423 pixels (centered). * Accepted file types: JPG, GIF, BMP, or PNG. * Maximum file size: 6 MB.[adobe.com](https://www.adobe.com/express/discover/sizes/youtube?utm_source=chatgpt.com) * **Profile Picture**: * Recommended dimensions: 800x800 pixels. * Aspect ratio: 1:1. * Accepted file types: JPG, PNG, GIF, BMP. * Maximum file size: 2 MB.[plannthat.com](https://www.plannthat.com/youtube-video-sizes/?utm_source=chatgpt.com) * **Video Thumbnails**: * Recommended dimensions: 1280x720 pixels. * Minimum width: 640 pixels. * Aspect ratio: 16:9. * Accepted file types: JPG, GIF, BMP, or PNG. * Maximum file size: 2 MB.[shopify.com](https://www.shopify.com/blog/youtube-thumbnail-size?utm_source=chatgpt.com) ### Text Specifications * **Video Titles**: * Maximum length: 100 characters. * Ensure titles are concise, descriptive, and include relevant keywords. * **Video Descriptions**: * Maximum length: 5,000 characters. * Provide detailed information about the video content, including relevant links and timestamps. * **Tags**: * Use relevant keywords to improve searchability. * Avoid using excessive or misleading tags. # Analytics Blotato collects engagement analytics for your published posts on 8 platforms: Twitter/X, Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest. Analytics for LinkedIn are not available yet. Two read-only endpoints expose this data: * [List Top Performing Posts](#list-top-performing-posts) — `GET /v2/analytics` * [Get Post Analytics](#get-post-analytics) — `GET /v2/posts/{id}/analytics` Analytics is available on all paid plans, both in the [Blotato web app](https://my.blotato.com/published) (the **All** and **Top Performing** tabs on the Published page) and via the API documented below. Fair usage limits may apply in the future. For a web-app and AI-agent walkthrough, see [Analytics](/features/analytics). Both endpoints return the latest snapshot Blotato has already collected. They do not trigger a fresh fetch from the social platform. ### Using analytics from Make.com or n8n The official Blotato Make.com module does not include analytics yet. To pull analytics from a Make scenario, call the two endpoints on this page with Make's HTTP module, passing your API key in the `blotato-api-key` header. The same approach works in n8n with the HTTP Request node. ### Collection schedule Blotato collects a snapshot of each post's metrics at fixed checkpoints, measured from when the post publishes. The number of checkpoints depends on your plan. | Checkpoint after publish | Starter | Creator | Agency | | ------------------------ | :-----: | :-----: | :----: | | 2 hours | | ✓ | ✓ | | 6 hours | | | ✓ | | 1 day | ✓ | ✓ | ✓ | | 7 days | ✓ | ✓ | ✓ | | 14 days | | | ✓ | | 30 days | | ✓ | ✓ | | 90 days | | | ✓ | Each checkpoint adds a small random delay to spread out collection, so exact timing varies by a few minutes to a few hours. Posts that spike early can receive extra checkpoints beyond your plan's schedule. ### Posts stuck on "Analytics pending" If posts on a supported platform stay on "Analytics pending" for days on a paid plan, the connected account most likely predates the analytics feature. Analytics needs updated account permissions, so reconnect the social account in [Settings](https://my.blotato.com/settings) to grant them. This applies to accounts (Instagram, Facebook, and others) connected before analytics launched. New metrics collect from the next checkpoint after you reconnect. If you already reconnected, no further action is needed. The first batch of metrics appears within 24-48 hours of reconnecting, then collection follows your plan's checkpoint schedule above. ### YouTube view counts trail the public count For YouTube, Blotato reads the YouTube Analytics API, which reports only finalized views after YouTube filters spam and invalid traffic. The count on the YouTube watch page updates in near real time and includes views YouTube has not validated yet, so it reads higher. The two numbers are not expected to match, and the gap narrows as YouTube finalizes more data. See: [Why is my YouTube view count in Blotato lower than on YouTube?](/support/faqs#why-is-my-youtube-view-count-in-blotato-lower-than-on-youtube) *** ## List Top Performing Posts ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/analytics` **Method:** `GET` ### Description Returns your top performing published posts, ordered by the requested metric over a time range. Each item includes its latest metrics snapshot and full snapshot history. ### Query Parameters | Field | Type | Required | Description | | ---------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `since` | `string` | No | Only include posts published on or after this ISO 8601 timestamp. Defaults to 30 days ago. | | `until` | `string` | No | Only include posts published on or before this ISO 8601 timestamp. Defaults to now. | | `platform` | `string` | No | Filter to one platform: `twitter`, `instagram`, `facebook`, `threads`, `bluesky`, `tiktok`, `youtube`, or `pinterest`. Omit to include all platforms. Analytics for `linkedin` are not available yet, so filtering to it returns no metrics. | | `sortBy` | `string` | No | Metric to rank by. One of `likes_count`, `comments_count`, `views_count`, `reach_count`. Default: `views_count`. | | `limit` | `integer` | No | Number of posts to return. Min: 1, Max: 100. Default: 20. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "98431", "content": "Check out this image!", "postUrl": "https://instagram.com/p/abc123", "platform": "instagram", "createdAt": "2026-05-30T09:15:00.000Z", "mediaUrls": ["https://example.com/image1.jpg"], "latestMetrics": { "fetchedAt": "2026-06-11T12:00:00.000Z", "metrics": { "likesCount": "1240", "commentsCount": "85", "reachCount": "53000", "savesCount": "310" } }, "metricsHistory": [ { "fetchedAt": "2026-06-10T12:00:00.000Z", "metrics": { "likesCount": "1190", "reachCount": "51200" } }, { "fetchedAt": "2026-06-11T12:00:00.000Z", "metrics": { "likesCount": "1240", "reachCount": "53000" } } ] } ] } ``` #### Response Keys | Field | Type | Description | | ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------- | | `items` | `array` | Published posts, ordered by the requested `sortBy` metric (highest first). | | `items[].id` | `string` | The published post id. Pass this to [Get Post Analytics](#get-post-analytics). | | `items[].content` | `string` | The post text. | | `items[].postUrl` | `string \| null` | Live URL of the published post. Null if the platform did not return one. | | `items[].platform` | `string` | Social media platform. | | `items[].createdAt` | `string` | ISO 8601 timestamp when the post was published. | | `items[].mediaUrls` | `string[]` | URLs of attached media. Empty when text-only. | | `items[].latestMetrics` | `object` | The most recent metrics snapshot. Absent if no metrics have been collected yet. See [Metrics](#metrics). | | `items[].metricsHistory` | `array` | All collected snapshots, oldest first. Each is `{ fetchedAt, metrics }`. | ### Errors | Status | Reason | | ------ | ----------------------------------------------------- | | `422` | Invalid `since`, `until`, `sortBy`, or `limit` value. | ### Example ```http GET https://backend.blotato.com/v2/analytics?sortBy=views_count&platform=instagram&limit=10 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` *** ## Get Post Analytics ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/posts/{id}/analytics` **Method:** `GET` ### Description Returns the latest metrics and full snapshot history for a single published post. The `id` is the published post id, which you get from the `items[].id` field of [List Top Performing Posts](#list-top-performing-posts) or [List Posts](/api/publish-post/list-posts) (published items). It is not the `postSubmissionId` returned when you publish. If your request returns only `postSubmissionId`, `status`, and `publicUrl` with no metrics fields, you called [Get Post Status](/api/publish-post/get-post) instead of this analytics endpoint. Get Post checks publish status with the `postSubmissionId`. Analytics uses the published post id from List Posts or List Top Performing Posts. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | `string` | Yes | The published post id (e.g. `12345`) from the `items[].id` field of [List Top Performing Posts](#list-top-performing-posts) or [List Posts](/api/publish-post/list-posts). This is not the `postSubmissionId` you get when you publish -- passing the `postSubmissionId` calls [Get Post Status](/api/publish-post/get-post) instead and returns `status` and `publicUrl` with no metrics. | ### Response **Status Code:** `200 OK` ```json { "publishedPostId": "12345", "platform": "instagram", "lastFetchedAt": "2026-06-11T12:00:00.000Z", "lastError": null, "metrics": { "viewsCount": "18400", "likesCount": "920", "commentsCount": "47", "reachCount": "56200" }, "history": [ { "fetchedAt": "2026-06-10T12:00:00.000Z", "metrics": { "viewsCount": "12100", "likesCount": "640" } }, { "fetchedAt": "2026-06-11T12:00:00.000Z", "metrics": { "viewsCount": "18400", "likesCount": "920" } } ] } ``` #### Response Keys | Field | Type | Description | | ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `publishedPostId` | `string` | The id of the published post. | | `platform` | `string` | Social media platform. | | `lastFetchedAt` | `string \| null` | ISO 8601 timestamp of the last snapshot stored successfully. A failed fetch leaves this unchanged, so it reflects the last success, not the last attempt. Check `lastError` for the most recent failure. | | `lastError` | `string \| null` | The last error Blotato hit while fetching metrics for this post, if any. | | `metrics` | `object \| null` | Latest metrics snapshot. See [Metrics](#metrics) and [Empty vs null metrics](#empty-vs-null-metrics). | | `history` | `array` | All collected snapshots, oldest first. Each is `{ fetchedAt, metrics }`. | ### Errors | Status | Reason | | ------ | -------------------------------------------------------------------------------------------------------------- | | `404` | No published post with that `id`, it does not belong to your account, or your plan does not include analytics. | ### Example ```http GET https://backend.blotato.com/v2/posts/12345/analytics HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` *** ## Metrics Every metric field is optional and only appears when the platform reports it for that post. Count metrics are returned as strings to preserve large integers (e.g. `"18400"`). Rate and percentage metrics are returned as numbers, and breakdown metrics (such as `facebookPostReactionsByType`) return an object mapping each bucket to a count, e.g. `{ "like": "13", "haha": "2" }`. A metric value of `0` is real and is always returned. It means zero, not missing. ### Empty vs null metrics An empty `metrics` object (`{}`) is not the same as `metrics: null`. * `metrics: null` -- no analytics snapshot has been stored yet. * `metrics: {}` -- a snapshot exists, but no metric values are being returned. Two causes: every value came back empty from the platform, or your plan returns a reduced metric set. Common metrics like `viewsCount`, `likesCount`, and `reachCount` apply across platforms. Each platform also returns its own metrics, prefixed with the platform name — for example `twitterRetweetsCount` or `blueskyRepostsCount`. See the [Metrics Reference](/api/analytics/analytics-metrics) for the full list of common and platform-specific metrics. Platform-specific coverage depends on your plan. The Starter plan returns a limited set of these metrics. The Creator and Agency plans return every platform-specific metric and breakdown. See the [Metrics Reference](/api/analytics/analytics-metrics) for the field-level breakdown. Inspect the `metrics` object in the response for the set available for your post. *** ## Related * [List Posts](/api/publish-post/list-posts) — list scheduled, published, and failed posts; published items carry the `id` used by Get Post Analytics. * [List Published Posts](/api/publish-post/list-published-posts) — full-text search over your published posts with the latest analytics snapshot attached. # Metrics Reference This page lists every metric field that can appear in an analytics snapshot returned by [List Top Performing Posts](/api/analytics#list-top-performing-posts) and [Get Post Analytics](/api/analytics#get-post-analytics). Metrics live inside a snapshot's `metrics` object: ```json { "fetchedAt": "2026-06-11T12:00:00.000Z", "metrics": { "viewsCount": "18400", "likesCount": "920", "twitterRetweetsCount": "45" } } ``` ### How to read this reference * **Every field is optional.** A metric only appears when the platform reports it for that specific post and when it's covered under your Blotato plan, so most snapshots contain a small subset of the fields below. * **Counts are strings.** Count metrics are returned as strings (e.g. `"18400"`) to preserve large integers without precision loss. * **Rates and percentages are numbers.** Ratios (`0`–`1`) and percentages (`0`–`100`) are returned as JSON numbers. * **Breakdown metrics are objects.** A breakdown maps each bucket to a count string, e.g. `{ "like": "13", "haha": "2" }`. On the Published page these render as a bar chart with one bar per bucket. * **Per-media metrics are arrays.** A few Twitter video metrics are arrays indexed by media position in the post (upload order across the whole thread). Entries are `null` for media items that are not videos. Analytics are currently collected for **Twitter/X, Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest**. Instagram and TikTok report only the [common metrics](#common-metrics) and have no platform-specific fields. The LinkedIn fields below are part of the API schema but are not populated yet. *** ## Common metrics Reported across platforms whenever the platform exposes them. | Field | Type | Description | Starter | Creator | Agency | | ---------------------- | -------- | -------------------------------------------------- | :-----: | :-----: | :----: | | `viewsCount` | `string` | Views. | ✓ | ✓ | ✓ | | `impressionsCount` | `string` | Impressions. | ✓ | ✓ | ✓ | | `reachCount` | `string` | Unique accounts reached. | ✓ | ✓ | ✓ | | `likesCount` | `string` | Likes. | ✓ | ✓ | ✓ | | `commentsCount` | `string` | Comments. | ✓ | ✓ | ✓ | | `repliesCount` | `string` | Replies. | ✓ | ✓ | ✓ | | `sharesCount` | `string` | Shares. | ✓ | ✓ | ✓ | | `savesCount` | `string` | Saves / bookmarks. | ✓ | ✓ | ✓ | | `clicksCount` | `string` | Link or content clicks. | ✓ | ✓ | ✓ | | `followsCount` | `string` | Follows gained from the post. | ✓ | ✓ | ✓ | | `playsCount` | `string` | Video / audio plays. | ✓ | ✓ | ✓ | | `profileVisitsCount` | `string` | Profile visits driven by the post. | ✓ | ✓ | ✓ | | `profileActivityCount` | `string` | Profile actions driven by the post. | ✓ | ✓ | ✓ | | `navigationsCount` | `string` | In-post navigation actions (e.g. carousel swipes). | ✓ | ✓ | ✓ | | `interactionsSum` | `string` | Total interactions. | ✓ | ✓ | ✓ | | `viewTimeMsSum` | `string` | Total watch time, milliseconds. | ✓ | ✓ | ✓ | | `watchTimeMsAvg` | `string` | Average watch time, milliseconds. | ✓ | ✓ | ✓ | *** ## Twitter / X Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | ---------------------- | -------- | ------------- | :-----: | :-----: | :----: | | `twitterRetweetsCount` | `string` | Retweets. | ✓ | ✓ | ✓ | | `twitterQuotesCount` | `string` | Quote tweets. | ✓ | ✓ | ✓ | Per-media video metrics. Each is an array indexed by media position in the post; `null` entries mark non-video media. | Field | Type | Description | Starter | Creator | Agency | | ------------------------------------------- | -------------------- | -------------------------------------- | :-----: | :-----: | :----: | | `twitterPerMediaVideoViewsCount` | `(string \| null)[]` | Video views per media item. | | ✓ | ✓ | | `twitterPerMediaVideoPlaybackStartCount` | `(string \| null)[]` | Playbacks started per media item. | | ✓ | ✓ | | `twitterPerMediaVideoPlayback25Count` | `(string \| null)[]` | Playbacks reaching 25% per media item. | | ✓ | ✓ | | `twitterPerMediaVideoPlayback50Count` | `(string \| null)[]` | Playbacks reaching 50% per media item. | | ✓ | ✓ | | `twitterPerMediaVideoPlayback75Count` | `(string \| null)[]` | Playbacks reaching 75% per media item. | | ✓ | ✓ | | `twitterPerMediaVideoPlaybackCompleteCount` | `(string \| null)[]` | Playbacks completed per media item. | | ✓ | ✓ | *** ## Bluesky Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | --------------------- | -------- | ------------ | :-----: | :-----: | :----: | | `blueskyRepostsCount` | `string` | Reposts. | ✓ | ✓ | ✓ | | `blueskyQuotesCount` | `string` | Quote posts. | ✓ | ✓ | ✓ | *** ## Threads Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | --------------------- | -------- | ------------ | :-----: | :-----: | :----: | | `threadsRepostsCount` | `string` | Reposts. | ✓ | ✓ | ✓ | | `threadsQuotesCount` | `string` | Quote posts. | ✓ | ✓ | ✓ | *** ## Facebook Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | ----------------------------------- | -------- | ------------------------------------------------------------ | :-----: | :-----: | :----: | | `facebookPostMediaViewsCount` | `string` | Media views on the post. | | ✓ | ✓ | | `facebookPostMediaViewsUniqueCount` | `string` | Unique media views on the post. | | ✓ | ✓ | | `facebookPostReactionsByType` | `object` | Reactions broken down by type (e.g. `like`, `love`, `haha`). | | ✓ | ✓ | Video and Reels metrics. | Field | Type | Description | Starter | Creator | Agency | | --------------------------------------------------- | -------- | ---------------------------------------------------------------- | :-----: | :-----: | :----: | | `facebookBlueReelsPlaysCount` | `string` | Reel plays. | | ✓ | ✓ | | `facebookFbReelsReplaysCount` | `string` | Reel replays. | | ✓ | ✓ | | `facebookFbReelsTotalPlaysCount` | `string` | Total reel plays (plays plus replays). | | ✓ | ✓ | | `facebookPostVideoWatchTimeMsAvg` | `string` | Average video watch time, milliseconds. | | ✓ | ✓ | | `facebookPostVideoFollowersCount` | `string` | Followers gained from the video. | | ✓ | ✓ | | `facebookPostVideoLikesByReactionType` | `object` | Video likes broken down by reaction type. | | ✓ | ✓ | | `facebookPostVideoSocialActionsByType` | `object` | Video social actions broken down by type. | | ✓ | ✓ | | `facebookPostVideoViewTimeMsSum` | `string` | Total video view time, milliseconds. | | ✓ | ✓ | | `facebookTotalVideoViewsCount` | `string` | Total video views. | | ✓ | ✓ | | `facebookTotalVideoViewsUniqueCount` | `string` | Unique video views. | | ✓ | ✓ | | `facebookTotalVideoViewsAutoplayedCount` | `string` | Autoplayed video views. | | ✓ | ✓ | | `facebookTotalVideoViewsClickedToPlayCount` | `string` | Click-to-play video views. | | ✓ | ✓ | | `facebookTotalVideoViewsSoundOnCount` | `string` | Video views with sound on. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsCount` | `string` | Complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsUniqueCount` | `string` | Unique complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsAutoplayedCount` | `string` | Autoplayed complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsClickedToPlayCount` | `string` | Click-to-play complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsOrganicCount` | `string` | Organic complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsOrganicUniqueCount` | `string` | Unique organic complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsPaidCount` | `string` | Paid complete video views. | | ✓ | ✓ | | `facebookTotalVideoCompleteViewsPaidUniqueCount` | `string` | Unique paid complete video views. | | ✓ | ✓ | | `facebookTotalVideoViews10sCount` | `string` | Video views of at least 10 seconds. | | ✓ | ✓ | | `facebookTotalVideoViews10sUniqueCount` | `string` | Unique 10-second video views. | | ✓ | ✓ | | `facebookTotalVideoViews10sAutoplayedCount` | `string` | Autoplayed 10-second video views. | | ✓ | ✓ | | `facebookTotalVideoViews10sClickedToPlayCount` | `string` | Click-to-play 10-second video views. | | ✓ | ✓ | | `facebookTotalVideoViews10sOrganicCount` | `string` | Organic 10-second video views. | | ✓ | ✓ | | `facebookTotalVideoViews10sPaidCount` | `string` | Paid 10-second video views. | | ✓ | ✓ | | `facebookTotalVideoViews10sSoundOnCount` | `string` | 10-second video views with sound on. | | ✓ | ✓ | | `facebookTotalVideoViews15sCount` | `string` | Video views of at least 15 seconds. | | ✓ | ✓ | | `facebookTotalVideoViews60sExcludesShorterCount` | `string` | Video views of at least 60 seconds (excludes shorter). | | ✓ | ✓ | | `facebookTotalVideoWatchTimeMsAvg` | `string` | Average total video watch time, milliseconds. | | ✓ | ✓ | | `facebookTotalVideoViewTimeMsSum` | `string` | Total video view time, milliseconds. | | ✓ | ✓ | | `facebookTotalVideoViewTimeOrganicMsSum` | `string` | Organic video view time, milliseconds. | | ✓ | ✓ | | `facebookTotalVideoViewTimePaidMsSum` | `string` | Paid video view time, milliseconds. | | ✓ | ✓ | | `facebookTotalVideoStoriesByActionType` | `object` | Video stories (shares/comments/etc.) broken down by action type. | | ✓ | ✓ | | `facebookTotalVideoReactionsByType` | `object` | Video reactions broken down by type. | | ✓ | ✓ | | `facebookTotalVideoViewTimeMsByAgeBucketAndGender` | `object` | Video view time broken down by age bucket and gender. | | ✓ | ✓ | | `facebookTotalVideoViewTimeMsByRegionId` | `object` | Video view time broken down by region. | | ✓ | ✓ | | `facebookTotalVideoViewsByDistributionType` | `object` | Video views broken down by distribution type. | | ✓ | ✓ | *** ## LinkedIn Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | --------------------------------- | -------- | ----------------------------------------------------------------- | :-----: | :-----: | :----: | | `linkedinFirstLevelCommentsCount` | `string` | First-level comments (excludes replies). | ✓ | ✓ | ✓ | | `linkedinReactionsByType` | `object` | Reactions broken down by type (e.g. `like`, `praise`, `empathy`). | | ✓ | ✓ | *** ## Pinterest Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | --------------------------------- | -------- | ---------------------------------------------- | :-----: | :-----: | :----: | | `pinterestPinClicksCount` | `string` | Pin clicks. | | ✓ | ✓ | | `pinterestReactionsCount` | `string` | Reactions. | ✓ | ✓ | ✓ | | `pinterestVideoP95ViewsCount` | `string` | Video views reaching 95% of the video. | | ✓ | ✓ | | `pinterestVideo10sViewsCount` | `string` | Video views of at least 10 seconds. | | ✓ | ✓ | | `pinterestVideoMrcViewsCount` | `string` | MRC-standard video views. | | ✓ | ✓ | | `pinterestVideoV50WatchTimeMsSum` | `string` | Watch time for views past 50%, milliseconds. | | ✓ | ✓ | | `pinterestSaveRate` | `number` | Saves divided by impressions, a `0`–`1` ratio. | | ✓ | ✓ | *** ## YouTube YouTube metrics come from the YouTube Analytics API, which reports only finalized views after YouTube filters spam and invalid traffic. `viewsCount` for a YouTube post therefore reads lower than the count on the YouTube watch page, and the gap narrows as YouTube finalizes more data. See: [Analytics](/api/analytics#youtube-view-counts-trail-the-public-count). Post-level metrics. | Field | Type | Description | Starter | Creator | Agency | | -------------------------------------------- | -------- | ----------------------------------------------------------- | :-----: | :-----: | :----: | | `youtubeDislikesCount` | `string` | Dislikes. | | ✓ | ✓ | | `youtubeSubscribersLostCount` | `string` | Subscribers lost from the video. | | ✓ | ✓ | | `youtubeVideosAddedToPlaylistsCount` | `string` | Times the video was added to a playlist. | | ✓ | ✓ | | `youtubeVideosRemovedFromPlaylistsCount` | `string` | Times the video was removed from a playlist. | | ✓ | ✓ | | `youtubeRedViewsCount` | `string` | YouTube Premium (Red) views. | | ✓ | ✓ | | `youtubeRedViewTimeMsSum` | `string` | YouTube Premium (Red) watch time, milliseconds. | | ✓ | ✓ | | `youtubeEngagedViewsCount` | `string` | Engaged views. | | ✓ | ✓ | | `youtubeAverageViewPercentage` | `number` | Average percentage of the video watched, `0`–`100`. | | ✓ | ✓ | | `youtubeCardClicksCount` | `string` | Card clicks. | | ✓ | ✓ | | `youtubeCardImpressionsCount` | `string` | Card impressions. | | ✓ | ✓ | | `youtubeCardClickRate` | `number` | Card clicks divided by impressions, a `0`–`1` ratio. | | ✓ | ✓ | | `youtubeCardTeaserClicksCount` | `string` | Card teaser clicks. | | ✓ | ✓ | | `youtubeCardTeaserImpressionsCount` | `string` | Card teaser impressions. | | ✓ | ✓ | | `youtubeCardTeaserClickRate` | `number` | Card teaser clicks divided by impressions, a `0`–`1` ratio. | | ✓ | ✓ | | `youtubeAnnotationClicksCount` | `string` | Annotation clicks. | | ✓ | ✓ | | `youtubeAnnotationClickableImpressionsCount` | `string` | Clickable annotation impressions. | | ✓ | ✓ | | `youtubeAnnotationClosesCount` | `string` | Annotation closes. | | ✓ | ✓ | | `youtubeAnnotationClosableImpressionsCount` | `string` | Closable annotation impressions. | | ✓ | ✓ | | `youtubeAnnotationImpressionsCount` | `string` | Annotation impressions. | | ✓ | ✓ | | `youtubeAnnotationClickThroughRate` | `number` | Annotation click-through rate, a `0`–`1` ratio. | | ✓ | ✓ | | `youtubeAnnotationCloseRate` | `number` | Annotation close rate, a `0`–`1` ratio. | | ✓ | ✓ | *** ## Related * [Analytics](/api/analytics) — the two endpoints that return these metrics. * [List Top Performing Posts](/api/analytics#list-top-performing-posts) — `GET /v2/analytics` * [Get Post Analytics](/api/analytics#get-post-analytics) — `GET /v2/posts/{id}/analytics` # Comments Blotato allows you to read and post comments on your published Instagram posts and Facebook Page posts. Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, and YouTube are not supported at this time. Three endpoints let you list, read, and post comments: * [List Comments](#list-comments) — `GET /v2/comments` * [Get Comment](#get-comment) — `GET /v2/comments/:commentId` * [Post Comment](#post-comment) — `POST /v2/comments` Comments are available on all paid plans. To manage Instagram and Facebook comments in the Blotato web app, see [Comments and Messaging Inbox](/features/inbox). Blotato does not backfill comments. It starts capturing comments once your account has comments enabled and you connect or reconnect your account. Comments left before then do not appear in these endpoints. Blotato retains comments for up to 45 days. Comments older than 45 days are not available through these endpoints. The `/comments` endpoints cover two directions: * **Inbound comments** your audience leaves on your posts. These have `isAuthor: false`. * **Outbound comments** you post through Blotato. These have `isAuthor: true`. The comments API lists and posts top-level comments and one level of replies. You can reply to a top-level comment on your post, but you cannot reply to a reply. ## Before You Start Blotato must have permissions to read and post comments on your account before you can use the Blotato comments endpoints. If you connected your account before comments launched, reconnect it so Blotato has the new permission. * For Instagram, see [Connect Instagram](/settings/social-accounts/instagram). * For Facebook, see [Connect Facebook](/settings/social-accounts/facebook). *** ## List Comments ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/comments` **Method:** `GET` ### Description Returns your comments across connected accounts, ordered by creation time (most recent first). Use cursor-based pagination and the optional filters below. ### Query Parameters | Field | Type | Required | Description | | ----------------- | --------- | -------- | ------------------------------------------------------------------- | | `limit` | `integer` | No | Maximum comments to return (1-250). Default 50. | | `cursor` | `string` | No | Cursor from a previous response. Pass it to fetch the next page. | | `platform` | `array` | No | Filter by platform. Values: `instagram`, `facebook`. | | `accountId` | `string` | No | Filter to a single connected account. | | `parentCommentId` | `string` | No | Filter to direct replies to a single comment. | | `postId` | `string` | No | Filter to comments on a single Blotato-published post. | | `since` | `string` | No | Only include comments created on or after this ISO 8601 timestamp. | | `until` | `string` | No | Only include comments created on or before this ISO 8601 timestamp. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "cmt_abc123", "accountId": "98434", "platform": "instagram", "postId": "post_xyz789", "platformPostId": "17851234567890", "platformCommentId": "17899876543210", "authorId": "1784000000", "isAuthor": false, "text": "Love this!", "status": "posted", "errorCode": null, "errorMessage": null, "createdAt": "2026-07-01T12:34:56Z" } ], "cursor": "eyJz..." } ``` | Field | Type | Description | | -------- | -------- | ----------------------------------------------------------------- | | `items` | `array` | List of comments. See [Comment Object](#comment-object). | | `cursor` | `string` | Cursor for the next page. Absent when there are no more comments. | *** ## Get Comment ### Endpoint **URL:** `/comments/:commentId` **Method:** `GET` ### Description Fetches a single comment by its Blotato ID. The comment is an inbound reply from your audience or an outbound comment you posted through Blotato. ### Path Parameters | Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------- | | `commentId` | `string` | Yes | Blotato ID of the comment. | ### Response **Status Code:** `200 OK` Returns a [Comment Object](#comment-object). *** ## Post Comment ### Endpoint **URL:** `/comments` **Method:** `POST` ### Description Posts a comment on one of your published posts, or a reply to an existing top-level comment when you pass `parentCommentId`. Blotato queues the comment and posts it in the background, so the response returns status `queued`. Poll [Get Comment](#get-comment) with the returned `id` to confirm the comment reached `posted` or `failed`. ### Request Body ```json { "postId": "post_xyz789", "text": "Thanks everyone!" } ``` | Field | Type | Required | Description | | ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `postId` | `string` | Yes | Blotato ID of the published post to comment on. Get it from [List Posts](/api/publish-post/list-posts), from items whose `state.type` is `published`. | | `text` | `string` | Yes | Plain-text comment body. Instagram allows up to 2200 characters, Facebook up to 8000. | | `parentCommentId` | `string` | No | Blotato ID of a top-level, posted comment on the same post to reply to. Replies to replies are not supported. | ### Response **Status Code:** `201 Created` Returns a [Comment Object](#comment-object) with status `queued`. ### Errors | Status | Reason | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `404` | The published post or parent comment was not found, or comments are not enabled for your account. | | `422` | The post's platform does not support comments, the comment exceeds the platform's character limit, the parent comment is invalid, or you reached your plan's monthly active-contacts limit (error code `20101`). | | `429` | Rate limit exceeded (30 requests per minute). | ### Replies and Your Contacts Limit Replying to a comment from your audience counts the person as an active contact for the month, and your plan limits how many active contacts you reach. When you pass the limit, Post Comment returns `422` with error code `20101`. Replying to your own comment does not count. See [Active Contacts](/settings/billing-and-credits#active-contacts) for the definition and per-plan limits. *** ## Comment Object | Field | Type | Description | | ------------------- | ----------------- | --------------------------------------------------------------------------------------------- | | `id` | `string` | Blotato comment ID. | | `accountId` | `string` | ID of the connected account the comment belongs to. | | `platform` | `string` | `instagram` or `facebook`. | | `postId` | `string or null` | Blotato ID of the post, when published through Blotato. | | `parentCommentId` | `string or null` | Blotato ID of the parent comment when this comment is a reply. `null` for top-level comments. | | `platformPostId` | `string` | Social platform (e.g. Instagram) ID of the parent post. | | `platformCommentId` | `string or null` | Social platform (e.g. Instagram) ID of the comment. | | `authorId` | `string or null` | Social platform (e.g. Instagram) ID of the comment author. | | `isAuthor` | `boolean` | `true` when your connected account authored the comment. `false` for an audience reply. | | `text` | `string` | Comment text. | | `status` | `string` | Comment status. See [Status Values](#status-values). | | `errorCode` | `integer or null` | Set only when status is `failed`. See [Comments Errors](/support/errors#comments-errors). | | `errorMessage` | `string or null` | Set only when status is `failed`. | | `createdAt` | `string` | ISO 8601 timestamp when the comment was created. | ### Status Values | Status | Meaning | | ------------ | --------------------------------- | | `queued` | Accepted and waiting to post. | | `processing` | Posting to the social platform. | | `posted` | Live on the social platform. | | `failed` | Did not post. See `errorMessage`. | | `deleted` | Removed from the social platform. | ### Rate Limits | Endpoint | Limit | | -------------------------- | -------- | | `GET /comments` | 60 / min | | `GET /comments/:commentId` | 60 / min | | `POST /comments` | 30 / min | # Messages Blotato allows you to read and send direct messages on your Instagram account and Facebook Page. Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, and YouTube are not supported at this time. Five endpoints let you list conversations, read a conversation, list messages, read a message, and send a message: * [List Conversations](#list-conversations) — `GET /v2/conversations` * [Get Conversation](#get-conversation) — `GET /v2/conversations/:conversationId` * [List Messages](#list-messages) — `GET /v2/messages` * [Get Message](#get-message) — `GET /v2/messages/:messageId` * [Send Message](#send-message) — `POST /v2/messages` Messages are available on all paid plans. To manage Instagram and Facebook conversations in the Blotato web app, see [Comments and Messaging Inbox](/features/inbox). To send automatic replies after a comment or incoming message, use [DM Automations](/support/dm-automations). You manage these automations in the web app or through an AI tool connected to Blotato MCP. Each message has a `direction`: * **Incoming messages** your contacts send you. These have `direction: "incoming"`. * **Outgoing messages** you send through Blotato. These have `direction: "outgoing"`. You reply to people who already have a conversation with you. You send to a `recipientId` taken from an existing conversation or an incoming message, not to an arbitrary user. The social platform limits who you can message and when. See [Messaging Windows](#messaging-windows). Blotato retains messages for up to 45 days. Messages older than 45 days are not available through these endpoints. ## Before You Start Blotato must have permissions to read and send messages on your account before you can use the Blotato messaging endpoints. If you connected your account before messaging launched, reconnect it so Blotato has the new permission. * For Instagram, see [Connect Instagram](/settings/social-accounts/instagram). * For Facebook, see [Connect Facebook](/settings/social-accounts/facebook). *** ## List Conversations ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/conversations` **Method:** `GET` ### Description Returns your conversations across connected accounts, ordered by most recent activity. Use cursor-based pagination and the optional filters below. ### Query Parameters | Field | Type | Required | Description | | ----------- | --------- | -------- | ---------------------------------------------------------------- | | `limit` | `integer` | No | Maximum conversations to return (1-250). Default 50. | | `cursor` | `string` | No | Cursor from a previous response. Pass it to fetch the next page. | | `platform` | `string` | No | Filter by platform. Values: `instagram`, `facebook`. | | `accountId` | `string` | No | Filter to a single connected account. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "cnv_abc123", "accountId": "98434", "platform": "instagram", "participants": [ { "id": "1784000000", "name": "Jamie Rivera", "username": "jamie.rivera", "profileImageUrl": "https://example.com/avatar.jpg" } ], "createdAt": "2026-07-01T12:00:00Z", "updatedAt": "2026-07-02T09:30:00Z" } ], "cursor": "eyJz..." } ``` | Field | Type | Description | | -------- | -------- | ----------------------------------------------------------------------- | | `items` | `array` | List of conversations. See [Conversation Object](#conversation-object). | | `cursor` | `string` | Cursor for the next page. Absent when there are no more conversations. | *** ## Get Conversation ### Endpoint **URL:** `/conversations/:conversationId` **Method:** `GET` ### Description Fetches a single conversation by its Blotato ID. ### Path Parameters | Field | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------- | | `conversationId` | `string` | Yes | Blotato ID of the conversation. | ### Response **Status Code:** `200 OK` Returns a [Conversation Object](#conversation-object). *** ## List Messages ### Endpoint **URL:** `/messages` **Method:** `GET` ### Description Returns your messages across connected accounts, ordered by creation time (most recent first). Use cursor-based pagination and the optional filters below. ### Query Parameters | Field | Type | Required | Description | | ---------------- | --------- | -------- | ---------------------------------------------------------------- | | `limit` | `integer` | No | Maximum messages to return (1-250). Default 50. | | `cursor` | `string` | No | Cursor from a previous response. Pass it to fetch the next page. | | `conversationId` | `string` | No | Filter to messages in a single conversation. | | `platform` | `array` | No | Filter by platform. Values: `instagram`, `facebook`. | | `accountId` | `string` | No | Filter to a single connected account. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "msg_abc123", "conversationId": "cnv_abc123", "platform": "instagram", "direction": "incoming", "senderId": "1784000000", "recipientId": "17841400000000000", "text": "Hi! Is this still available?", "status": "delivered", "errorCode": null, "errorMessage": null, "createdAt": "2026-07-02T09:30:00Z" } ], "cursor": "eyJz..." } ``` | Field | Type | Description | | -------- | -------- | ----------------------------------------------------------------- | | `items` | `array` | List of messages. See [Message Object](#message-object). | | `cursor` | `string` | Cursor for the next page. Absent when there are no more messages. | *** ## Get Message ### Endpoint **URL:** `/messages/:messageId` **Method:** `GET` ### Description Fetches a single message by its Blotato ID. Poll this after [Send Message](#send-message) to check whether an outgoing message reached `sent` or `failed`. ### Path Parameters | Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------- | | `messageId` | `string` | Yes | Blotato ID of the message. | ### Response **Status Code:** `200 OK` Returns a [Message Object](#message-object). *** ## Send Message ### Endpoint **URL:** `/messages` **Method:** `POST` ### Description Sends a direct message to one recipient. Blotato queues the message and sends it in the background, so the response returns status `queued`. Poll [Get Message](#get-message) with the returned `id` to confirm the message reached `sent` or `failed`. Send to a `recipientId` taken from an existing conversation or an incoming message. The social platform limits who you can message and when. See [Messaging Windows](#messaging-windows). ### Request Body ```json { "accountId": "98434", "recipientId": "1784000000", "text": "Thanks for reaching out! Yes, it's available.", "target": { "targetType": "instagram" } } ``` | Field | Type | Required | Description | | ------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accountId` | `string` | Yes | Blotato ID of the connected account the message is sent from. | | `recipientId` | `string` | Yes | Social platform (e.g. Instagram) ID of the recipient. Get it from an existing conversation or incoming message. | | `text` | `string` | Yes | Plain-text message body. Instagram messages are limited to 1000 bytes, Facebook to 2000 characters. With buttons attached, the limit drops to 640 characters. See [Buttons and Quick Replies](#buttons-and-quick-replies). | | `target` | `object` | Yes | Where and how to send. See [Target](#target). | ### Target | Field | Type | Required | Description | | -------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `targetType` | `string` | Yes | Value: `instagram` or `facebook`. | | `pageId` | `string` | For Facebook | ID of the Facebook Page to send from, from [subaccounts](/api/accounts#list-subaccounts-pages). Required when `targetType` is `facebook`. | | `commentId` | `string` | No | Blotato comment ID. When set, Blotato delivers the message as a private reply to that comment instead of a direct message. | | `attachment` | `object` | No | Up to 3 call-to-action buttons pinned under the message. See [Buttons and Quick Replies](#buttons-and-quick-replies). | | `quickReplies` | `array` | No | Up to 13 tappable reply chips shown under the message. See [Buttons and Quick Replies](#buttons-and-quick-replies). | | `responseType` | `string` | No | How the message fits the platform's messaging window: `RESPONSE`, `UPDATE`, or `MESSAGE_TAG`. Default `RESPONSE`. See [Messaging Windows](#messaging-windows). | | `tag` | `string` | No | Required when `responseType` is `MESSAGE_TAG` (e.g. `HUMAN_AGENT`). | ### Buttons and Quick Replies Facebook and Instagram support buttons and quick replies in direct messages. Set `target.attachment` for buttons, or `target.quickReplies` for chips. The two are mutually exclusive: a request carrying both is rejected with `422`. For any platform-applied limitations, see: * [Instagram Limitations](/platforms/instagram/limitations#direct-messages-and-dm-automations) * [Facebook Limitations](/platforms/facebook/limitations#direct-messages-and-dm-automations) #### Buttons Buttons sit under the message and stay there. Up to 3 buttons are supported. **Instagram Limitation:** Instagram only renders buttons in the Instagram mobile app. A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons. Send an `attachment` or a URL inside `text`, not both. A message carrying both leaves the URL in `text` unclickable on desktop, so a desktop recipient ends up with no working link. For a primarily desktop audience, drop the `attachment` and put the URL in `text`. ```json { "accountId": "98434", "recipientId": "1784000000", "text": "Thanks for reaching out! Pick an option below.", "target": { "targetType": "instagram", "attachment": { "type": "button", "buttons": [ { "type": "web_url", "title": "View pricing", "url": "https://example.com/pricing" }, { "type": "postback", "title": "Talk to sales", "payload": "SALES" } ] } } } ``` | Field | Type | Required | Description | | --------- | -------- | -------- | ---------------- | | `type` | `string` | Yes | Value: `button`. | | `buttons` | `array` | Yes | 1 to 3 buttons. | Each button has: | Field | Type | Required | Description | | --------- | -------- | -------------- | --------------------------------------------------------------- | | `type` | `string` | Yes | `web_url` opens a link. `postback` reports the tap back to you. | | `title` | `string` | Yes | Button label, 1 to 20 characters. | | `url` | `string` | For `web_url` | Link the button opens. Starts with `https://`. | | `payload` | `string` | For `postback` | Value echoed back on tap, 1 to 1000 characters. | With buttons set, `text` is required and limited to 640 characters. #### Quick Replies Quick replies are tappable chips offered as canned answers. They disappear once the person taps one or types their own message. Pass 1 to 13. ```json { "accountId": "98434", "recipientId": "1784000000", "text": "What size do you need?", "target": { "targetType": "instagram", "quickReplies": [ { "title": "Small", "payload": "SIZE_S" }, { "title": "Medium", "payload": "SIZE_M" }, { "title": "Large", "payload": "SIZE_L" } ] } } ``` | Field | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------- | | `title` | `string` | Yes | Chip label, 1 to 20 characters. | | `payload` | `string` | Yes | Value echoed back on tap, 1 to 1000 characters. | Quick replies require non-empty message `text`. #### Reading a Tap A quick-reply tap and a postback tap both arrive as the next **incoming** message carrying `payload.selection`, but they reach you differently. Quick replies send a real text message. `text` holds the chip label, adn Blotato attaches `payload.selection` alongside it. ```json { "id": "msg_def456", "direction": "incoming", "text": "Your chip label", "payload": { "selection": { "type": "quick-reply", "payload": "The chip payload" } } } ``` Postbacks do not send a text message. Blotato records the tap as an incoming message, sets `text` to the button label, and attaches `payload.selection`. ```json { "id": "msg_ghi789", "direction": "incoming", "text": "Your button label", "payload": { "selection": { "type": "postback", "payload": "SALES" } } } ``` | Field | Value | Meaning | | ------------------- | ------------- | ----------------------------------------------------------------------------------------------- | | `selection.type` | `quick-reply` | The person tapped a chip. `text` is the chip label. | | `selection.type` | `postback` | The person tapped a button you attached. `text` is the button label. | | `selection.payload` | your string | The `payload` you set on the chip or button. A postback carries `null` when you set no payload. | Branch on `selection.payload`, not on `text`. Two chips that share a label are distinguishable only by their payload. A `web_url` button produces no selection. The link opens and nothing comes back. Blotato subscribes your account to the postback webhook when you connect it. If you connected your account before buttons were launched, [reconnect](https://my.blotato.com/settings) to start receiving postback events. Quick-reply taps need no reconnect. ### Response **Status Code:** `201 Created` Returns a [Message Object](#message-object) with status `queued`. ### Errors Send Message returns `201` on success, `422` when the request is rejected, and `429` when you exceed 30 requests per minute. Messaging is available on every plan, so there is no "not enabled" rejection, and this endpoint does not return `404`. A connected account that is missing or expired surfaces after the message is queued, as a `failed` message. A `422` means one of: * The message exceeds the platform's character limit. Instagram allows 1000 bytes, Facebook 2000 characters, and either drops to 640 characters when buttons are set. * You passed both `attachment` and `quickReplies`. Send one or the other. * You set buttons or quick replies without message `text`. * The messaging window has closed. * The comment you are replying to is invalid, or it already received a private reply. * You reached your plan's monthly active-contacts limit (error code 20101). * `responseType` is `MESSAGE_TAG` and you did not set `tag`. Message-send failures that happen after the message is queued do not return an error here. The message reaches status `failed` with an `errorCode` and `errorMessage`. See [Messaging Errors](/support/errors#messaging-errors). *** ## Messaging Windows The social platform limits who you can message and when. You reply to people who already have a conversation with you, not arbitrary users. * **Standard window:** send a `RESPONSE` within 24 hours of the contact's last message. * **Private reply to a comment:** set `commentId` on the target to reply once, within 7 days of the comment. * **Outside the window:** set `responseType` to `MESSAGE_TAG` with an approved `tag` (e.g. `HUMAN_AGENT`) to send a permitted follow-up. These windows come from the social platform, not Blotato. A message sent outside an allowed window reaches status `failed`. Sending a message to a new person also counts toward your plan's monthly active-contacts limit. See [Active Contacts](/settings/billing-and-credits#active-contacts). *** ## Conversation Object | Field | Type | Description | | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Blotato conversation ID. | | `accountId` | `string` | ID of the connected account this conversation belongs to. | | `platform` | `string` | `instagram` or `facebook`. | | `participants` | `array` | The other people in the conversation. Each has `id`, `name`, `username`, and `profileImageUrl`, any of which may be `null`. | | `createdAt` | `string` | ISO 8601 timestamp when the conversation started. | | `updatedAt` | `string` | ISO 8601 timestamp of the most recent activity. | *** ## Message Object | Field | Type | Description | | ---------------- | ----------------- | ------------------------------------------------------------------------------------------- | | `id` | `string` | Blotato message ID. | | `conversationId` | `string or null` | Blotato ID of the parent conversation. | | `platform` | `string` | `instagram` or `facebook`. | | `direction` | `string` | `incoming` for messages you receive, `outgoing` for messages you send. | | `senderId` | `string or null` | Social platform (e.g. Instagram) ID of the sender. | | `recipientId` | `string` | Social platform (e.g. Instagram) ID of the recipient. | | `text` | `string` | Message text. | | `payload` | `object or null` | Rich content on the message. See [Payload](#payload). | | `status` | `string` | Message status. See [Status Values](#status-values). | | `errorCode` | `integer or null` | Set only when status is `failed`. See [Messaging Errors](/support/errors#messaging-errors). | | `errorMessage` | `string or null` | Set only when status is `failed`. | | `createdAt` | `string` | ISO 8601 timestamp when the message was created. | ### Payload `payload` is `null` on a plain-text message. Otherwise it holds one or more of: | Field | Type | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `attachment` | `object` | Buttons you attached to an outgoing message. See [Buttons](#buttons). | | `quickReplies` | `array` | Quick-reply chips you attached to an outgoing message. See [Quick Replies](#quick-replies). | | `selection` | `object` | Set on an incoming message where the person tapped a postback button or a quick reply. Holds `type` (`postback` or `quick-reply`) and your `payload` string. See [Reading a Tap](#reading-a-tap). | ### Status Values An outgoing message you send moves through `queued`, `processing`, then `sent`, or `failed` if it does not go through. An incoming message you receive shows as `delivered`. | Status | Meaning | | ------------ | ------------------------------------- | | `queued` | Accepted and waiting to send. | | `processing` | Sending to the social platform. | | `sent` | Handed to the social platform. | | `delivered` | An incoming message delivered to you. | | `failed` | Did not send. See `errorMessage`. | ### Rate Limits | Endpoint | Limit | | ------------------------------------ | -------- | | `GET /conversations` | 60 / min | | `GET /conversations/:conversationId` | 60 / min | | `GET /messages` | 60 / min | | `GET /messages/:messageId` | 60 / min | | `POST /messages` | 30 / min | # DM Automations A DM automation sends a direct message when someone comments on your post or sends you a message. Blotato supports DM automations on Instagram and Facebook Pages. Twitter/X, TikTok, LinkedIn, Pinterest, Threads, Bluesky, and YouTube are not supported at this time. Eight endpoints let you manage automations and inspect their activity: * [List DM Automations](#list-dm-automations) — `GET /v2/dm-automations` * [Get DM Automation](#get-dm-automation) — `GET /v2/dm-automations/:id` * [Create DM Automation](#create-dm-automation) — `POST /v2/dm-automations` * [Update DM Automation](#update-dm-automation) — `PATCH /v2/dm-automations/:id` * [Delete DM Automation](#delete-dm-automation) — `DELETE /v2/dm-automations/:id` * [List Runs](#list-runs) — `GET /v2/dm-automations/:id/runs` * [List Logs](#list-logs) — `GET /v2/dm-automations/:id/logs` * [Get Analytics](#get-analytics) — `GET /v2/dm-automations/:id/analytics` For the web app walkthrough, see [DM Automations](/features/dm-automations). ## Before You Start Blotato needs permission to read comments and read and send messages on your account. If you connected your account before comments, messaging, or (for Instagram) follow gating launched, reconnect it so Blotato has the new permissions. * For Instagram, see [Connect Instagram](/settings/social-accounts/instagram). * For Facebook, see [Connect Facebook](/settings/social-accounts/facebook). ## How an Automation Runs 1. Someone comments on your post or sends your account a message. 2. Blotato matches the event against every live automation on the account. 3. A match starts a **run** for each live automation. 4. If the automation has a follow gate or email gate, Blotato waits for the contact to complete it. 5. Blotato sends the DM, then calls the webhook if one is configured. 6. The run reaches `completed`, `failed`, `expired`, or `superseded`. A comment trigger answers with a **private reply to the comment**. A message trigger answers with a standard DM. Your own comments and the messages your account sends never start a run. ### Testing a Comment Trigger Test from a different Instagram or Facebook account. A comment posted by the same account connected to the automation is skipped, even when its text matches a trigger keyword. ### Optional Steps Set `followGate`, `emailGate`, or `webhook` to extend the run. Blotato runs the steps in a fixed order: 1. **Follow gate** (`followGate`, Instagram only). Sends the gate message with a confirm button, waits up to 1 hour for a reply, then checks whether the contact follows the account. A contact who does not follow gets the gate message again. 2. **Email gate** (`emailGate`). Sends the gate message, waits up to 1 hour for a reply, and reads the first email address out of it. A reply holding no email address returns the gate message. A match saves to the contact. 3. **Your message** (`dmMessage` plus `buttons`). 4. **Webhook** (`webhook`). Calls your endpoint after the message sends. A run waiting on a gate reaches `expired` when the contact never answers inside the window, and `superseded` when a newer run starts waiting on the same contact. While a run waits on a contact's reply, their next DM resumes the waiting run instead of starting a new run. A button tap never starts a run. *** ## List DM Automations ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/dm-automations` **Method:** `GET` ### Description Returns your DM automations, ordered by creation time (most recent first). Use cursor-based pagination. ### Query Parameters | Field | Type | Required | Description | | -------- | --------- | -------- | ---------------------------------------------------------------- | | `limit` | `integer` | No | Maximum automations to return (1-250). Default 50. | | `cursor` | `string` | No | Cursor from a previous response. Pass it to fetch the next page. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "flow_abc123", "accountId": "98434", "name": "Auto-DM links from comments", "platform": "instagram", "target": { "targetType": "instagram" }, "trigger": { "type": "comment-received", "keywords": ["price", "link"], "postId": "post_xyz789", "isActive": true }, "dmMessage": "Thanks for the interest! Tap below for the link.", "buttons": [ { "type": "url", "title": "View link", "url": "https://blotato.com" } ], "emailGate": { "message": "Reply with your email and I will send it over." }, "followGate": { "message": "Follow this account, then tap below.", "buttonTitle": "I'm following" }, "webhook": { "method": "POST", "url": "https://example.com/blotato-webhook", "headers": { "x-source": "blotato" } }, "isActive": true, "publishedVersionId": "ver_001", "createdAt": "2026-08-01T12:00:00Z", "updatedAt": "2026-08-02T09:30:00Z" } ], "cursor": "eyJz..." } ``` | Field | Type | Description | | -------- | -------- | ----------------------------------------------------------------------- | | `items` | `array` | List of automations. See [DM Automation Object](#dm-automation-object). | | `cursor` | `string` | Cursor for the next page. Absent when there are no more automations. | *** ## Get DM Automation ### Endpoint **URL:** `/dm-automations/:id` **Method:** `GET` ### Description Fetches a single automation by its Blotato ID, including its trigger and the message it sends. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | ----------------------------- | | `id` | `string` | Yes | Blotato ID of the automation. | ### Response **Status Code:** `200 OK` ```json { "flow": { "id": "flow_abc123", "...": "..." } } ``` The `flow` object is a [DM Automation Object](#dm-automation-object). *** ## Create DM Automation ### Endpoint **URL:** `/dm-automations` **Method:** `POST` ### Description Creates a DM automation. When its trigger fires, the automation sends one direct message: text plus up to 3 link buttons. You can gate the message behind an Instagram follow check, ask for an email address first, or call a webhook after the message sends. * Set `followGate` (Instagram only) to gate the message behind a follow check. * Set `emailGate` to gate it behind the contact replying with an email address. * Set `webhook` to call an external endpoint once the message sends. An automation is created as a draft unless you pass `isActive: true`. ### Request Body ```json { "accountId": "98434", "platform": "instagram", "target": { "targetType": "instagram" }, "name": "Auto-DM links from comments", "trigger": { "type": "comment-received", "keywords": ["price", "link"], "postId": null }, "dmMessage": "Thanks for the interest! Tap below for the link.", "buttons": [ { "type": "url", "title": "View link", "url": "https://blotato.com" } ], "followGate": { "message": "Follow the account, then tap below.", "buttonTitle": "I'm following" }, "emailGate": { "message": "Reply with your email and I'll send the link." }, "webhook": { "method": "POST", "url": "https://example.com/hooks/leads", "headers": { "X-Api-Key": "secret" } }, "isActive": true } ``` | Field | Type | Required | Description | | ------------ | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `accountId` | `string` | Yes | Blotato ID of the connected account the automation runs on. | | `platform` | `string` | Yes | `instagram` or `facebook`. | | `target` | `object` | Yes | Where the automation listens and sends. See [Target](#target). | | `name` | `string` | Yes | Automation label, 1-60 characters. | | `dmMessage` | `string` | Yes | Message text, 1-640 characters. | | `buttons` | `array` | Yes | Up to 3 link buttons. Pass `[]` for a plain-text message. See [Button Object](#button-object). | | `trigger` | `object or null` | No | The event the automation listens for. See [Trigger Object](#trigger-object). | | `followGate` | `object or null` | No | Instagram only. Holds the message back until the contact follows the account. See [Follow Gate Object](#follow-gate-object). | | `emailGate` | `object or null` | No | Holds the message back until the contact replies with an email address. See [Email Gate Object](#email-gate-object). | | `webhook` | `object or null` | No | Endpoint Blotato calls once the message sends. See [Webhook Object](#webhook-object). | | `isActive` | `boolean` | No | `true` publishes the automation immediately. Default `false`. | An automation needs a trigger, a non-empty `dmMessage` of 640 characters or fewer, and a valid `http(s)` URL on every button before it goes live. A gate you set needs its own `message`, and a webhook you set needs a valid `http(s)` `url`. ### Response **Status Code:** `201 Created` ```json { "flow": { "id": "flow_abc123", "isActive": true, "...": "..." } } ``` *** ## Update DM Automation ### Endpoint **URL:** `/dm-automations/:id` **Method:** `PATCH` ### Description Updates an automation. Each field present in the patch replaces that field. Omitted fields stay unchanged. Pass `null` for `trigger`, `followGate`, `emailGate`, or `webhook` to remove it. The connected account, platform, and target are fixed at creation. To run on a different account, create a new automation. ### Request Body The patch is nested under a `patch` key. ```json { "patch": { "dmMessage": "New reply text", "buttons": [], "isActive": true } } ``` | Field | Type | Required | Description | | ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `name` | `string` | No | New automation label, 1-60 characters. | | `trigger` | `object or null` | No | Replaces the trigger. See [Trigger Object](#trigger-object). | | `dmMessage` | `string` | No | Replaces the message text, 1-640 characters. | | `buttons` | `array` | No | Replaces the buttons. Pass `[]` to remove every button. | | `followGate` | `object or null` | No | Replaces the follow gate. Pass `null` to remove it. Instagram only. See [Follow Gate Object](#follow-gate-object). | | `emailGate` | `object or null` | No | Replaces the email gate. Pass `null` to remove it. See [Email Gate Object](#email-gate-object). | | `webhook` | `object or null` | No | Replaces the webhook. Pass `null` to remove it. See [Webhook Object](#webhook-object). | | `isActive` | `boolean` | No | `true` publishes the automation. `false` moves it to draft. Omit to keep the current state. | Content changes to a live automation publish as soon as the request succeeds. Content changes to a draft stay saved until you pass `isActive: true`. A live automation needs a trigger. To clear the trigger, pass `isActive: false` in the same request. ### Response **Status Code:** `200 OK` ```json { "flow": { "id": "flow_abc123", "...": "..." } } ``` *** ## Delete DM Automation ### Endpoint **URL:** `/dm-automations/:id` **Method:** `DELETE` ### Description Archives an automation. Its trigger stops listening and the automation stops firing. Runs already in flight finish. ### Response **Status Code:** `200 OK` Returns the archived [DM Automation Object](#dm-automation-object). *** ## List Runs ### Endpoint **URL:** `/dm-automations/:id/runs` **Method:** `GET` ### Description Returns the execution runs of one automation, ordered by start time (most recent first). A run is one execution: one comment or message matched the trigger, and Blotato acted on it. Use this endpoint to check whether an automation fires and why a reply did not go out. ### Query Parameters | Field | Type | Required | Description | | -------- | --------- | -------- | ---------------------------------------------------------------- | | `limit` | `integer` | No | Maximum runs to return (1-250). Default 50. | | `cursor` | `string` | No | Cursor from a previous response. Pass it to fetch the next page. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "run_abc123", "contactId": "1784000000", "platform": "instagram", "status": "failed", "error": { "code": 20102, "message": "Messaging window has expired" }, "createdAt": "2026-08-02T09:30:00Z", "updatedAt": "2026-08-02T09:30:04Z" } ], "cursor": "eyJz..." } ``` See [Run Object](#run-object). *** ## List Logs ### Endpoint **URL:** `/dm-automations/:id/logs` **Method:** `GET` ### Description Returns the execution logs written as an automation's runs progress, ordered by creation time (most recent first). Pass `flowRunId` to narrow the logs to a single run. ### Query Parameters | Field | Type | Required | Description | | ----------- | --------- | -------- | ----------------------------------------------------------------------------- | | `flowRunId` | `string` | No | Only return logs belonging to this run. Omit to return logs across every run. | | `limit` | `integer` | No | Maximum logs to return (1-250). Default 50. | | `cursor` | `string` | No | Cursor from a previous response. Pass it to fetch the next page. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "log_abc123", "flowRunId": "run_abc123", "nodeId": "nd_9fJ2", "level": "info", "message": "Queued message for send", "context": { "messageId": "msg_abc123" }, "createdAt": "2026-08-02T09:30:01Z" } ], "cursor": "eyJz..." } ``` See [Log Object](#log-object). *** ## Get Analytics ### Endpoint **URL:** `/dm-automations/:id/analytics` **Method:** `GET` ### Description Returns all-time run totals for one automation. ### Response **Status Code:** `200 OK` ```json { "analytics": { "triggered": 412, "completed": 398, "failed": 9 } } ``` | Field | Type | Description | | ----------- | --------- | ---------------------------------------------- | | `triggered` | `integer` | Runs started by a matching comment or message. | | `completed` | `integer` | Runs where the DM settled as sent. | | `failed` | `integer` | Runs where the DM did not send. | A run stays open until its message settles, so `completed` plus `failed` is sometimes lower than `triggered`. *** ## DM Automation Object | Field | Type | Description | | -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Blotato automation ID. | | `accountId` | `string` | ID of the connected account the automation runs on. | | `name` | `string` | Automation label. | | `platform` | `string` | `instagram` or `facebook`. | | `target` | `object` | See [Target](#target). | | `trigger` | `object` | The event the automation listens for. Absent when no trigger is set. See [Trigger Object](#trigger-object). | | `dmMessage` | `string` | Message text sent when the trigger fires. | | `buttons` | `array` | Link buttons attached to the message. See [Button Object](#button-object). | | `followGate` | `object` | Follow gate on the automation. Absent when no follow gate is set. See [Follow Gate Object](#follow-gate-object). | | `emailGate` | `object` | Email gate on the automation. Absent when no email gate is set. See [Email Gate Object](#email-gate-object). | | `webhook` | `object` | Webhook on the automation. Absent when no webhook is set. See [Webhook Object](#webhook-object). | | `isActive` | `boolean` | `true` when the automation is live and listening. | | `publishedVersionId` | `string or null` | ID of the published version. `null` for a draft. | | `createdAt` | `string` | ISO 8601 timestamp when the automation was created. | | `updatedAt` | `string` | ISO 8601 timestamp of the most recent edit. | ### Target | Field | Type | Required | Description | | ------------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `targetType` | `string` | Yes | `instagram` or `facebook`. | | `pageId` | `string` | For Facebook | ID of the Facebook Page, from [subaccounts](/api/accounts#list-subaccounts-pages). Required when `targetType` is `facebook`. | ### Trigger Object | Field | Type | Required | Description | | ---------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | `comment-received` or `message-received`. | | `keywords` | `array` | Yes | Words or phrases the comment or message must contain. Pass `[]` to fire on every comment or message. | | `postId` | `string or null` | No | Comment triggers only. Blotato ID of the post to watch. `null` watches every post and reel on the account. | | `isActive` | `boolean` | No | `false` stops the trigger listening while the automation stays published. Default `true`. | Keyword matching ignores case, matches whole words, and tolerates line breaks inside a multi-word keyword. A comment or message fires the automation when it contains any one of the keywords. `postId` is a **Blotato** post ID, so per-post targeting works on posts published through Blotato. Get it from [List Published Posts](/api/publish-post/list-published-posts). To act on a post published outside Blotato, leave `postId` as `null` and rely on keywords. ### Button Object | Field | Type | Required | Description | | ------- | -------- | -------------- | -------------------------------------------------------- | | `type` | `string` | Yes | `url`. Link buttons are the only type `buttons` accepts. | | `title` | `string` | Yes | Button label, up to 20 characters. | | `url` | `string` | Yes to publish | `http(s)` URL the button opens. | To send quick-reply chips or postback buttons, use [Send Message](/api/messages#buttons-and-quick-replies). **Instagram renders buttons in the Instagram mobile app only.** A recipient reading the DM on instagram.com in a desktop browser sees the message text with no buttons. To work around this issue, you can add the URL directly to the message text, and Instagram will render it as a clickable link. Set `buttons` or put a URL inside `dmMessage`, not both, since a message carrying both leaves the URL unclickable on desktop. For a desktop audience, pass `buttons: []` and put the URL in `dmMessage`. See [Instagram Limitations](/platforms/instagram/limitations#buttons-and-quick-replies). ### Follow Gate Object Instagram only. Holds `dmMessage` back until the contact follows the account. | Field | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------------------------------------------------------------- | | `message` | `string` | Yes | Gate message text, 1-640 characters. Blotato sends it with a confirm button under it. | | `buttonTitle` | `string` | No | Label on the confirm button, up to 20 characters. Default `I'm following`. | Blotato sends the gate message, waits up to 1 hour for a reply, then reads the contact's follower status. A contact who follows receives `dmMessage`. A contact who does not receives the gate message again. * **The gate message always goes first.** Instagram grants access to follower status once the contact opens a DM thread with the account, so the gate message precedes the check. * **An unknown follower status sends `dmMessage`.** Instagram withholds follower status for a contact who never granted profile access, and Blotato proceeds rather than blocking them. * **A confirmed follow lasts 30 days.** Blotato reuses the result for 30 days. A negative result is never reused. * **The confirm button is a postback button Blotato manages.** You set its label only. See [Instagram Limitations](/platforms/instagram/limitations#dm-automations). * **Any reply advances the gate.** Blotato runs the follower check on the contact's next DM, whatever it says. The tap is a shortcut, not a requirement. * **The account needs a button-tap subscription.** Blotato subscribes the account at connect time. An account connected before DM automations and follow gating landed does not reliably receive a tap, and runs reach `expired`. Reconnect the account to fix it. * **Instagram renders the confirm button in the mobile app only.** A contact reading on instagram.com in a desktop browser sees the gate message with nothing to tap. Write `message` to ask for a typed reply, for example "Reply FOLLOWING once you have", so a desktop audience still advances. ### Email Gate Object Holds `dmMessage` back until the contact replies with an email address. | Field | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------ | | `message` | `string` | Yes | Gate message text, 1-640 characters. | Blotato sends the gate message, waits up to 1 hour for a reply, and reads the first email address out of it. A reply holding no email address returns the gate message and Blotato waits again. A match saves to the contact and `dmMessage` sends. Blotato checks the shape of the address, not whether the mailbox exists. Read a captured address through the [Webhook Object](#webhook-object). ### Webhook Object Endpoint Blotato calls after `dmMessage` sends. | Field | Type | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------------------------------- | | `method` | `string` | Yes | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. | | `url` | `string` | Yes | Public `http(s)` endpoint, 1-2048 characters. | | `headers` | `object` | No | String keys and string values sent with the request, for example an API key. | Every method except `GET` carries a JSON body with `Content-Type: application/json`. `GET` carries no body. With `emailGate` set on the automation: ```json { "email": "them@example.com" } ``` With no `emailGate`: ```json {} ``` | Rule | Behavior | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Address | The host must resolve to a public address. Private, loopback, link-local, and cloud metadata ranges return error code 20304. | | Protocol | `http` and `https` only. | | Redirects | Blotato does not follow them. Point the automation at the final URL. | | Timeout | 10 seconds. | | Response body | Blotato reads the first 16 KB. | | Error response | A non-2xx status gets logged with its status, and the run still completes. | | Failure | A blocked address, a DNS failure, or a timeout fails the run with error code 20304. | | Headers | Redacted from run logs, so a key never lands in a log entry. | This webhook is separate from the [webhook publish target](/api/publish-post), which sends post content to your endpoint at publish time. ### Run Object | Field | Type | Description | | ----------- | -------- | ------------------------------------------------------------------ | | `id` | `string` | Blotato run ID. Pass it as `flowRunId` to [List Logs](#list-logs). | | `contactId` | `string` | Social platform ID of the person who triggered the run. | | `platform` | `string` | `instagram` or `facebook`. | | `status` | `string` | See [Run Status Values](#run-status-values). | | `error` | `object` | Set only when status is `failed`. Holds `code` and `message`. | | `createdAt` | `string` | ISO 8601 timestamp when the run started. | | `updatedAt` | `string` | ISO 8601 timestamp of the most recent run update. | #### Run Status Values | Status | Meaning | | ------------ | --------------------------------------------------------------------------------- | | `running` | Executing a step. | | `waiting` | Waiting for the DM to settle, or waiting on the contact to answer a gate. | | `completed` | The DM sent. | | `expired` | The contact never answered a gate inside the 1-hour window. Nothing further sent. | | `superseded` | A newer run started waiting on the same contact, so this one stopped. | | `failed` | The DM did not send. Read `error`. | | `expired` | The run waited too long for the contact to complete a gate. | | `superseded` | A newer matching event replaced this run. | ### Log Object | Field | Type | Description | | ----------- | ---------------- | --------------------------------------------------------------- | | `id` | `string` | Blotato log ID. | | `flowRunId` | `string` | ID of the run this log belongs to. | | `nodeId` | `string or null` | ID of the step the log came from. `null` for run-level entries. | | `level` | `string` | `info`, `warning`, or `error`. | | `message` | `string` | Description of the step. | | `context` | `object` | Step-specific details, for example the message ID. | | `createdAt` | `string` | ISO 8601 timestamp when the log was written. | *** ## Platform Rules Instagram and Facebook set these rules, not Blotato. A message outside an allowed window reaches status `failed` on the run. * **Comment trigger.** Blotato answers with a private reply to the comment. Both platforms allow one private reply per comment, within 7 days of the comment. A comment that already received a private reply, through Blotato or another tool, rejects the second reply. * **Message trigger.** Blotato replies within 24 hours of the person's last message. * **No cold outreach.** An automation only answers people who comment or message first. * **A reply during a gate continues the run.** While a run waits on a contact's answer, their next DM resumes the waiting run instead of starting a new one. A button tap never starts a run. See [Messaging Windows](/api/messages#messaging-windows). ## Active Contacts Every DM an automation sends counts toward your plan's monthly active-contacts limit, the same as a message sent through [Send Message](/api/messages#send-message). Reaching the same person twice in a month counts once. See [Active Contacts](/settings/billing-and-credits#active-contacts). *** ## Errors | Status | Reason | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `404` | The automation was not found. Returned by [Get DM Automation](#get-dm-automation) and [Delete DM Automation](#delete-dm-automation) only. | | `422` | The automation is invalid for publishing (error code 20303), or the connected account is missing (error code 5000). Setting `followGate` on a `facebook` automation returns 20303. | | `500` | Unexpected server error. | A webhook failure surfaces on the run, not on the request. A blocked address, a DNS failure, or a timeout fails the run with error code 20304. See [Error Reference](/support/errors#dm-automation-errors). ## Rate Limits | Endpoint | Limit | | ----------------------------------- | -------- | | `GET /dm-automations` | 60 / min | | `GET /dm-automations/:id` | 60 / min | | `POST /dm-automations` | 30 / min | | `PATCH /dm-automations/:id` | 30 / min | | `DELETE /dm-automations/:id` | 30 / min | | `GET /dm-automations/:id/runs` | 60 / min | | `GET /dm-automations/:id/logs` | 60 / min | | `GET /dm-automations/:id/analytics` | 60 / min | # Visual ## Migrating from the Old API Format If you are getting this error: `body.textToImageModel must be object, body.imageToVideoModel must NOT be valid` Your workflow is using an outdated request format. The old `POST /v2/videos/creations` endpoint with `textToImageModel` and `imageToVideoModel` as string fields no longer works. Switch to the template system using `POST /v2/videos/from-templates`: 1. Browse available templates at [my.blotato.com/videos/new](https://my.blotato.com/videos/new) 2. In n8n or Make, replace the old node with the Blotato "Create Visual" node 3. Select your template from the dropdown (start with a carousel — it renders in seconds) 4. Open the [API Dashboard](https://my.blotato.com/api-dashboard) to inspect the exact JSON payload each template expects 5. Override inputs one by one to customize For AI story videos, choose the template named "AI Video with AI Voice." See also: [n8n FAQ — textToImageModel and imageToVideoModel](https://help.blotato.com/api/n8n/faqs#im-using-an-older-template-with-texttoimagemodel-and-imagetovidemodel-parameters-do-these-still-work) *** ## Creating a Visual ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/videos/from-templates` **Method:** `POST` ### Description This endpoint creates a new visual (image or video) from a template. Templates define the structure and input parameters for generating visuals like slideshows, quote cards, tweet cards, and more. You can provide input parameters manually, or use the optional `prompt` parameter to have AI automatically fill in the template inputs based on your description. Brand Kit settings from the web app are NOT applied automatically to API template calls. To get on-brand results, include your brand instructions directly in the `prompt` parameter (e.g., "use blue and white colors, modern minimalist style"). See [Brand Kit](/settings/brand-kit) for details. ### Request #### Request Body
FieldTypeRequiredDescription
templateIdstring✅The ID of the template to use. Get available templates from the /v2/videos/templates endpoint.
inputsobject✅Template-specific input parameters. Structure depends on the selected template. Can be an empty object {} if using the prompt parameter.
isDraftboolean❌Save as draft without rendering. Default: false.
promptstring❌Optional natural language prompt to auto-fill template inputs using AI. When provided, AI interprets your description and fills in the inputs automatically. Any manually provided inputs take precedence over AI-generated values.
renderboolean❌Whether to render the visual immediately. Default: true.
titlestring❌A human-readable title for the generated video.
useBrandKitboolean❌Applies your brand colors, tone, and style to the generated visual. Requires a brand kit configured in the web app. See Brand Kit.
### Getting Available Templates To list all available templates and their input specifications: ``` GET https://backend.blotato.com/v2/videos/templates?fields=id,name,description,inputs ``` **Query Parameters:** | Field | Type | Description | | -------- | -------- | --------------------------------------------------------------------------------------------------------- | | `fields` | `string` | Comma-separated list of fields to include. Use `id,name,description,inputs` to get full template details. | | `search` | `string` | Optional regex term to filter templates by name or description. | | `id` | `string` | Optional template ID to get a specific template. | ### Responses #### Success Response **Status Code:** `201 Created` Visual creation is scheduled on the queue. To check status, poll the [Get Visual Status](/api/create-video/find-video) endpoint. **Response Body:** ```json { "item": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "queueing" } } ``` #### Error Responses **Not Found** **Status Code:** `404 Not Found` ```json { "message": "Unknown template ID" } ``` **Too Many Requests** Visual creation has a user-level rate limit of 30 requests / minute. **Status Code:** `429 Too many requests` ```json { "statusCode": 429, "message": "Rate limit exceeded, retry in 49 seconds" } ``` ### Examples #### 1. Create a Visual Using AI Prompt (Recommended) The easiest way to create visuals is using the `prompt` parameter. AI will interpret your description and fill in the template inputs automatically. ```json POST https://backend.blotato.com/v2/videos/from-templates HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f", "inputs": {}, "prompt": "Create a 5-slide carousel about productivity tips for remote workers. Use a modern, professional style with blue tones.", "render": true } ``` #### 2. Create a Visual with Manual Inputs You can also specify inputs manually for full control: ```json POST https://backend.blotato.com/v2/videos/from-templates HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f", "inputs": { "slides": [ { "imageSource": "https://example.com/image1.jpg", "textOverlay": "Slide 1: Introduction" }, { "imageSource": "A serene mountain landscape at sunset", "textOverlay": "Slide 2: AI-generated image" } ], "textPosition": "center", "aiImageModel": "replicate/recraft-ai/recraft-v3" }, "render": true } ``` #### 3. Combine Prompt with Manual Overrides You can use `prompt` for most inputs while manually specifying certain values: ```json POST https://backend.blotato.com/v2/videos/from-templates HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "5903b592-1255-43b4-b9ac-f8ed7cbf6a5f", "inputs": { "textPosition": "bottom", "textColor": "#FFFFFF" }, "prompt": "Create a 3-slide motivational carousel about morning routines", "render": true } ``` In this example, AI fills in the slides content, but `textPosition` and `textColor` use your manual values. ### Available Templates Browse all templates with parameters and examples in the [Visual Templates](/api/visuals) catalog. You can also use the `/v2/videos/templates` endpoint to get the current list programmatically. Common templates include: | Template Type | Description | | ---------------------------- | ------------------------------------------------ | | Image Slideshow | Create slideshows from images with text overlays | | Instagram Carousel Slideshow | AI-generated image carousels from text prompts | | Quote Card | Generate quote cards with stylized backgrounds | | Tweet Card | Create visual cards from tweet-style content | | Tutorial Carousel | Step-by-step tutorial visuals | | AI Story Video | AI-generated story videos with narration | | Combine Clips | Merge multiple video clips | ### Template Input Types Templates use various input types: | Type | Description | Example | | --------- | ----------------------------- | ----------------------------------- | | `text` | Plain text string | `"Hello world"` | | `number` | Numeric value | `42` | | `boolean` | True/false | `true` | | `enum` | Choice from predefined values | `"top"` \| `"center"` \| `"bottom"` | | `image` | Image URL | `"https://example.com/image.jpg"` | | `video` | Video URL | `"https://example.com/video.mp4"` | | `color` | Hex color code | `"#FF5733"` | | `array` | List of items | `[{...}, {...}]` | | `object` | Nested object | `{ "key": "value" }` | ### Troubleshooting AI video renders take up to 10-15 minutes. A long render is normal and does not mean the request failed. Keep polling until the status reads `done`. If your AI agent reports the render as stuck or failing, nudge it to check the status again before retrying. If you're still having trouble generating a visual, navigate to `https://my.blotato.com/videos/` to view and manually edit it. ### Polling for Status After creating a visual, poll the [Get Visual Status](/api/create-video/find-video) endpoint to check its status: ``` GET https://backend.blotato.com/v2/videos/creations/ ``` Status values (in order): * `queueing` - Waiting to be processed * `generating-script` - AI is generating the script * `script-ready` - Script is ready, generating media * `generating-media` - Media is being generated * `media-ready` - Media is ready, exporting * `exporting` - Final export in progress * `done` - Complete. Use `mediaUrl` or `imageUrls` from the response. * `creation-from-template-failed` - Generation failed See [Get Visual Status](/api/create-video/find-video) for full response details. # Get Visual Status ## Check Visual Creation Status ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/videos/creations/:id` **Method:** `GET` ### Description Poll this endpoint to check the status of a visual creation. After submitting a request with [Create Visual](/api/create-video), use the returned `id` to track its progress. ### Request #### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | --------------------------------------------- | | `id` | `string` | Yes | The video/visual ID returned by Create Visual | ### Response **Status Code:** `200 OK` #### Status Values | Status | Description | | ------------------------------- | ------------------------------------------------------ | | `queueing` | Request is queued. Keep polling. | | `generating-script` | AI is generating the script. Keep polling. | | `script-ready` | Script is ready, generating media. Keep polling. | | `generating-media` | Media is being generated. Keep polling. | | `media-ready` | Media is ready, exporting. Keep polling. | | `exporting` | Final export in progress. Keep polling. | | `done` | Complete. `mediaUrl` and/or `imageUrls` are available. | | `creation-from-template-failed` | Creation failed. | #### Response: Done (success) ```json { "item": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "done", "createdAt": "2025-03-10T15:30:00Z", "mediaUrl": "https://database.blotato.io/user_1/media/video.mp4", "imageUrls": ["https://database.blotato.io/user_1/media/slide1.jpg", "https://database.blotato.io/user_1/media/slide2.jpg"] } } ``` * `mediaUrl`: URL of the rendered video. Use this in `mediaUrls` when publishing. * `imageUrls`: Array of image URLs (for slideshows/carousels). Use these in `mediaUrls` when publishing. #### Response: In Progress ```json { "item": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "generating-media", "createdAt": "2025-03-10T15:30:00Z", "mediaUrl": null, "imageUrls": null } } ``` #### Response: Failed ```json { "item": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "creation-from-template-failed", "createdAt": "2025-03-10T15:30:00Z", "mediaUrl": null, "imageUrls": null } } ``` ### Polling Pattern ``` 1. Create visual: POST /videos/from-templates -> get item.id 2. Poll: GET /videos/creations/{id} 3. If status is NOT "done" and NOT "creation-from-template-failed": wait 5 seconds, go to step 2 4. If status = "done": use mediaUrl or imageUrls 5. If status = "creation-from-template-failed": stop, creation failed ``` ### How Long It Takes Most visuals finish within a few minutes. AI video renders take up to 10-15 minutes. A long render is normal and does not mean the request failed. Keep polling until the status reads `done`. Only treat a render as failed when the status returns `creation-from-template-failed`. If a render never reaches `done`, submit a fresh create request. ### Example ```http GET https://backend.blotato.com/v2/videos/creations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` ### Error Response **Status Code:** `404 Not Found` ```json { "statusCode": 404, "message": "Not found" } ``` # Delete Video ## Deleting a single video ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/videos/:id` **Method:** `DELETE` ### Description Delete the video. Useful for cleaning up old, unused videos. ### Request #### Request Params The request path parameters must contain the following fields: | Field | Type | Required | Description | | ----- | -------- | -------- | ----------- | | `id` | `string` | ✅ | Video ID | ### Responses #### Success Response **Status Code:** `204 No Content` The video has been deleted successfully. **Response Body:** ``` { "id": "VIDEO ID", } ``` #### Error Responses **Status Code:** `500 Internal server error` ``` { "statusCode": 500, "message": "Something went wrong" } ``` # Visual Templates Create images and videos using pre-built templates with the [Create Visual API endpoint](/api/create-video). ## How to Use Templates 1. Choose a template from the categories below 2. Copy the UUID from the template ID (e.g., from `/base/v2/quote-card/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd/v1`, use `77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd`) 3. Send a POST request to `/v2/videos/from-templates` with the UUID as `templateId`, set `inputs` to `{}`, and describe what you want in `prompt` ### Example Request Use the `prompt` parameter to describe what you want. Set `inputs` to `{}`. AI fills in the template inputs automatically. Use the bare UUID as the `templateId` (not the full path). ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd", "inputs": {}, "prompt": "Create 5 motivational quotes about entrepreneurship", "render": true } ``` ### LLM-Friendly Reference For LLM integrations, see [API Reference for LLMs](/api/llm) for a plain text reference with all endpoints and parameters. *** ## Image Slideshows Create image slideshows with text overlays. Images uploaded or AI-generated. | Template | ID | Output | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------- | | [Image Slideshow with Text Overlays](/api/visuals/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f) | `/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1` | Slideshow | | [Instagram Carousel Slideshow](/api/visuals/53cfec04-2500-41cf-8cc1-ba670d2c341a) | `53cfec04-2500-41cf-8cc1-ba670d2c341a` | Slideshow | *** ## Quote Cards Quote card carousels with various background styles. | Template | ID | Output | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------- | | [Quote Card with Monocolor Background](/api/visuals/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd) | `/base/v2/quote-card/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd/v1` | Slideshow | | [Quote Card with Paper Background and Highlight](/api/visuals/f941e306-76f7-45da-b3d9-7463af630e91) | `/base/v2/quote-card/f941e306-76f7-45da-b3d9-7463af630e91/v1` | Slideshow | *** ## Tweet Cards Twitter/X-style quote cards with minimal or photo/video backgrounds. | Template | ID | Output | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------- | | [Tweet Card with Minimal Style](/api/visuals/ba413be6-a840-4e60-8fd6-0066d3b427df) | `/base/v2/tweet-card/ba413be6-a840-4e60-8fd6-0066d3b427df/v1` | Slideshow | | [Tweet Card with Photo/Video Background](/api/visuals/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66) | `/base/v2/tweet-card/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66/v1` | Slideshow | *** ## Tutorial Carousels Step-by-step tutorial visuals with customizable styling. | Template | ID | Output | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --------- | | [Tutorial Carousel with Minimalist Flat Style](/api/visuals/2491f97b-1b47-4efa-8b96-8c651fa7b3d5) | `/base/v2/tutorial-carousel/2491f97b-1b47-4efa-8b96-8c651fa7b3d5/v1` | Slideshow | | [Tutorial Carousel with Monocolor Background](/api/visuals/e095104b-e6c5-4a81-a89d-b0df3d7c5baf) | `/base/v2/tutorial-carousel/e095104b-e6c5-4a81-a89d-b0df3d7c5baf/v1` | Slideshow | *** ## Images with Text Combine images and text overlays in various styles. | Template | ID | Output | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------- | | [Image Slideshow with Prominent Text](/api/visuals/0ddb8655-c3da-43da-9f7d-be1915ca7818) | `/base/v2/images-with-text/0ddb8655-c3da-43da-9f7d-be1915ca7818/v1` | Slideshow | | [When X then Y Text Slideshow](/api/visuals/c9892c3b-fa75-4ade-821a-a50ff8456230) | `/base/v2/images-with-text/c9892c3b-fa75-4ade-821a-a50ff8456230/v1` | Video | | [Video of Images and Text with Minimal Style](/api/visuals/3ed4bb92-dbfe-45e6-9dc8-605b77f70506) | `/base/v2/images-with-text/3ed4bb92-dbfe-45e6-9dc8-605b77f70506/v1` | Video | *** ## Video Editor Combine and edit video clips with titles, captions, and music. | Template | ID | Output | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------ | | [Combine Clips and Apply Basic Edits](/api/visuals/c306ae43-1dcc-4f45-ac2b-88e75430ffd8) | `/base/v2/combine-clips/c306ae43-1dcc-4f45-ac2b-88e75430ffd8/v1` | Video | *** ## AI Videos AI-powered video generation with voiceovers and narration. | Template | ID | Output | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------ | | [AI Video with AI Voice](/api/visuals/5903fe43-514d-40ee-a060-0d6628c5f8fd) | `/base/v2/ai-story-video/5903fe43-514d-40ee-a060-0d6628c5f8fd/v1` | Video | | [AI Selfie Talking Video with Consistent Character](/api/visuals/57f5a565-fd17-458b-be43-4a2d8ccaca75) | `/base/v2/ai-selfie-video/57f5a565-fd17-458b-be43-4a2d8ccaca75/v1` | Video | *** ## AI Avatar AI avatar videos with generated B-roll footage. | Template | ID | Output | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------ | | [AI Avatar with AI Generated B-roll](/api/visuals/7c26a1cd-d5b3-42da-9c73-2413333873b3) | `/base/v2/ai-avatar-broll/7c26a1cd-d5b3-42da-9c73-2413333873b3/v1` | Video | *** ## AI-Generated Infographics (V1 Legacy) AI-powered infographic templates that generate single images based on text descriptions. Each template applies a unique visual style to your content. ### News and Media | Template | ID | Output | | ------------------------------------------------------------------------------ | ------------------------------------------------------ | ------ | | [TV Wall Infographic](/api/visuals/013904bf-6b3b-43f4-bb1f-f1964a38c29b) | `/video-template/013904bf-6b3b-43f4-bb1f-f1964a38c29b` | Image | | [Newspaper Infographic](/api/visuals/07a5b5c5-387c-49e3-86b1-de822cd2dfc7) | `/video-template/07a5b5c5-387c-49e3-86b1-de822cd2dfc7` | Image | | [Breaking News](/api/visuals/8800be71-52df-4ac7-ac94-df9d8a494d0f) | `/video-template/8800be71-52df-4ac7-ac94-df9d8a494d0f` | Image | | [Movie Theater Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) | `/video-template/b88c8273-6406-48c6-85e7-096119aefe30` | Image | ### Urban and Street | Template | ID | Output | | ------------------------------------------------------------------------------- | ------------------------------------------------------ | ------ | | [Graffiti Mural Infographic](/api/visuals/3598483b-c148-4276-a800-eede85c1c62f) | `/video-template/3598483b-c148-4276-a800-eede85c1c62f` | Image | | [Bus Ad Infographic](/api/visuals/f9c0e470-9288-4958-8cdd-64772ed93c05) | `/video-template/f9c0e470-9288-4958-8cdd-64772ed93c05` | Image | | [Billboard Infographic](/api/visuals/76b3b959-bdbe-440d-8428-984219353f18) | `/video-template/76b3b959-bdbe-440d-8428-984219353f18` | Image | ### Education | Template | ID | Output | | ------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------ | | [Classroom Chalkboard Infographic](/api/visuals/d9495026-3945-44f6-8b44-07c28c492e6d) | `/video-template/d9495026-3945-44f6-8b44-07c28c492e6d` | Image | | [Whiteboard Infographic](/api/visuals/ae868019-820d-434c-8fe1-74c9da99129a) | `/video-template/ae868019-820d-434c-8fe1-74c9da99129a` | Image | | [Chalkboard Infographic](/api/visuals/fcd64907-b103-46f8-9f75-51b9d1a522f5) | `/video-template/fcd64907-b103-46f8-9f75-51b9d1a522f5` | Image | ### Outdoor | Template | ID | Output | | ------------------------------------------------------------------------------ | ------------------------------------------------------ | ------ | | [Trail Marker Infographic](/api/visuals/29ebb2bd-02b7-4317-8bb8-c30eb938e47c) | `/video-template/29ebb2bd-02b7-4317-8bb8-c30eb938e47c` | Image | | [Constellation Infographic](/api/visuals/5307053e-046b-4c9b-b1ca-38725d2ddcdd) | `/video-template/5307053e-046b-4c9b-b1ca-38725d2ddcdd` | Image | ### Creative | Template | ID | Output | | ------------------------------------------------------------------------------- | ------------------------------------------------------ | --------- | | [Manga Panel Infographic](/api/visuals/49c61370-a706-4b82-98f7-62d557d1c66d) | `/video-template/49c61370-a706-4b82-98f7-62d557d1c66d` | Image | | [T-Shirt Infographic](/api/visuals/476f8920-8749-4ff7-9c91-470d54c3c03e) | `/video-template/476f8920-8749-4ff7-9c91-470d54c3c03e` | Image | | [Futuristic Flyer](/api/visuals/8fa8545e-8955-4a89-a868-cf45023d6cc5) | `/video-template/8fa8545e-8955-4a89-a868-cf45023d6cc5` | Image | | [Book Page Infographic](/api/visuals/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b) | `/video-template/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b` | Image | | [Single Centered Text Quote](/api/visuals/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0) | `/video-template/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0` | Slideshow | ### Tech | Template | ID | Output | | --------------------------------------------------------------------------- | ------------------------------------------------------ | ------ | | [Steampunk Infographic](/api/visuals/7b7104f1-d277-4993-ad3a-e5883c4b776d) | `/video-template/7b7104f1-d277-4993-ad3a-e5883c4b776d` | Image | | [Top Secret Infographic](/api/visuals/b8707b58-a106-44af-bb12-e30507e561af) | `/video-template/b8707b58-a106-44af-bb12-e30507e561af` | Image | ### Historical | Template | ID | Output | | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------ | | [Egyptian Hieroglyph Infographic](/api/visuals/a7b0d128-8478-4b34-9647-a0778b6517d0) | `/video-template/a7b0d128-8478-4b34-9647-a0778b6517d0` | Image | | [Cave Painting Infographic](/api/visuals/82ee75b6-597b-43a8-86bc-e4395e7c9c44) | `/video-template/82ee75b6-597b-43a8-86bc-e4395e7c9c44` | Image | *** ## Don't See a Template for Your Use Case? Submit a support ticket and describe the type of visual you need. To submit a ticket, click the orange circle button inside Blotato. Include the following in your request: * A description of the visual format you need (e.g., "listicle carousel with numbered items") * The platform you plan to post on (e.g., Instagram, TikTok, LinkedIn) * A link to an example of the format, if available *** ## See Also * [Create Visual API Reference](/api/create-video) * [Get Visual Status API Reference](/api/create-video/find-video) * [Media Requirements](https://github.com/Blotato-Inc/help.blotato.com/blob/main/api/media.md) # Image Slideshow with Text Overlays Create image slideshows with customizable text overlays. Images uploaded or AI-generated. ## When to Use This Template * You want to create a carousel or slideshow with images (your own uploads or AI-generated) and text on each slide * You are a brand, marketer, or creator making Instagram carousels, TikTok slideshows, or LinkedIn carousels with visual + text content * You have product photos, portfolio images, or event photos and want to add captions or descriptions to each * You want AI to generate themed images with text for a quick carousel on any topic ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------------ | | Template ID | `/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1` | | Output Type | Slideshow | | Category | Image Slideshows | ## Parameters | Parameter | Type | Required | Default | Description | | ------------------------- | ------ | -------- | --------------------------- | ---------------------------------------------------- | | slides | array | Yes | - | Array of slide objects. Min: 1, Max: 50 | | slides\[].imageSource | union | Yes | - | Upload image URL or AI prompt text to generate image | | slides\[].textOverlay | string | No | "" | Text to display on slide. Max: 300 chars | | aiImageModel | enum | No | fal-ai/imagen4/preview/fast | AI model for generating images. See values below | | textPosition | enum | No | top | Values: top, center, bottom | | customTextPositionPercent | number | No | - | Override preset position with custom % (0-100) | | textStyle | enum | No | modern | Values: minimal, elegant, modern | | textColor | color | No | #000000 | Hex color for text | | aspectRatio | enum | No | 9:16 | Values: 16:9, 1:1, 4:5, 9:16 | | slideDuration | number | No | 5 | Seconds per slide. Range: 1-10 | | transition | enum | No | none | Values: none, fade, slide, zoom | ### Available AI Image Models Pass one of these values as `aiImageModel` to control which AI model generates your images. Each model has a different credit cost. See [AI Video Credits](/features/videos/ai-video-credits) for pricing. | Value | Label | Credits/Image | | ------------------------------------------------ | ------------------------ | ------------- | | `replicate/black-forest-labs/flux-schnell` | Cheapest | 1 | | `replicate/black-forest-labs/flux-dev` | Good | 10 | | `replicate/black-forest-labs/flux-1.1-pro` | Great | 15 | | `replicate/black-forest-labs/flux-1.1-pro-ultra` | Best for Images | 20 | | `replicate/recraft-ai/recraft-v3` | Best for Realistic Image | 15 | | `replicate/ideogram-ai/ideogram-v2` | Best for Text | 30 | | `replicate/luma/photon` | Good | 10 | | `openai/gpt-image-1` | OpenAI GPT Image | 25 | | `fal-ai/nano-banana` | Nano Banana | 15 | | `fal-ai/nano-banana/edit` | Nano Banana Edit | 15 | | `fal-ai/nano-banana-pro` | Nano Banana Pro | 50 | | `fal-ai/nano-banana-pro/edit` | Nano Banana Pro Edit | 50 | | `fal-ai/imagen4/preview/fast` | Imagen 4 Fast (default) | 7 | | `fal-ai/bytedance/seedream/v4.5/text-to-image` | Seedream v4.5 | 15 | | `fal-ai/bytedance/seedream/v4.5/edit` | Seedream v4.5 Edit | 15 | ## Example 1: AI-Powered with Prompt Use the `prompt` parameter to let AI fill in all inputs automatically. ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1", "inputs": {}, "prompt": "Create a 5-slide carousel about productivity tips for remote workers. Use a modern professional style with blue tones.", "render": true } ``` ## Example 2: Manual Inputs Specify all inputs manually for full control. ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1", "inputs": { "slides": [ { "imageSource": "https://example.com/image1.jpg", "textOverlay": "Step 1: Plan Your Day" }, { "imageSource": "A minimalist desk setup with laptop and coffee", "textOverlay": "Step 2: Create Your Workspace" }, { "imageSource": "https://example.com/image3.jpg", "textOverlay": "Step 3: Take Regular Breaks" } ], "textPosition": "bottom", "textStyle": "elegant", "aspectRatio": "4:5", "transition": "fade" }, "render": true } ``` ## Example 3: Hybrid Approach Use prompt for content with manual style overrides. ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/image-slideshow/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f/v1", "inputs": { "textPosition": "center", "textColor": "#FFFFFF", "aspectRatio": "1:1" }, "prompt": "Create a 4-slide motivational carousel about morning routines with energetic imagery", "render": true } ``` ## Related Templates * [Image Slideshow with Prominent Text](/api/visuals/0ddb8655-c3da-43da-9f7d-be1915ca7818) * [When X then Y Text Slideshow](/api/visuals/c9892c3b-fa75-4ade-821a-a50ff8456230) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Instagram Carousel Slideshow Create AI-generated image carousels for Instagram. Provide a text prompt for each slide and AI generates the images. Choose from three image models: Nano Banana Pro (default), Nano Banana 2, or Seedream v4.5. ## When to Use This Template * You want AI-generated images for each slide of an Instagram carousel * You need a carousel where each slide has a different AI image based on a specific prompt * You are creating educational, infographic, or visual storytelling carousels * You want to control the AI image model and aspect ratio ## Template Information | Property | Value | | ----------- | -------------------------------------- | | Template ID | `53cfec04-2500-41cf-8cc1-ba670d2c341a` | | Output Type | Slideshow | | Category | Image Slideshows | ## Parameters | Parameter | Type | Required | Default | Description | | ------------ | ----- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | | slidePrompts | array | Yes | - | Array of text prompts. Each entry becomes the AI image for that slide. Min: 1, Max: 10. Each prompt: 5-1000 chars | | model | enum | No | nano-banana-pro | AI model for image generation. Values: `nano-banana-pro`, `nano-banana-2`, `bytedance/seedream/v4.5/text-to-image` | | aspectRatio | enum | No | 4:5 | Aspect ratio for generated images. Values: `1:1`, `4:5`, `5:4`, `16:9`, `9:16` | ## Example 1: AI-Powered with Prompt Use the `prompt` parameter to let AI fill in the slide prompts automatically. ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "53cfec04-2500-41cf-8cc1-ba670d2c341a", "inputs": {}, "prompt": "Create a 5-slide Instagram carousel about the dangers of smoking with vivid infographic-style images", "render": true } ``` ## Example 2: Manual Inputs Specify each slide prompt for full control. ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "53cfec04-2500-41cf-8cc1-ba670d2c341a", "inputs": { "slidePrompts": [ "A dense infographic on dangers of smoking", "A vibrant infographic on benefits of meditation", "A colorful chart showing daily exercise statistics", "A minimalist diagram of healthy eating habits" ], "model": "nano-banana-pro", "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach Use prompt for slide content with manual model and aspect ratio overrides. ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "53cfec04-2500-41cf-8cc1-ba670d2c341a", "inputs": { "model": "nano-banana-2", "aspectRatio": "1:1" }, "prompt": "Create a 4-slide carousel about morning routine tips with bright, energetic imagery", "render": true } ``` ## Related Templates * [Image Slideshow with Text Overlays](/api/visuals/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f) - Includes text overlays on each slide * [Image Slideshow with Prominent Text](/api/visuals/0ddb8655-c3da-43da-9f7d-be1915ca7818) - Large text over images ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Quote Card with Monocolor Background Create quote card carousels with a clean monocolor paper background. ## When to Use This Template * You want a clean, text-only carousel of quotes with a solid color background * You are a coach, motivational creator, or thought leader sharing quotes on Instagram, LinkedIn, or Twitter/X * You do not need images -- text-only quote cards with a simple design * You want to batch-produce quote carousels from a list of quotes or let AI generate them ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------- | | Template ID | `/base/v2/quote-card/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd/v1` | | Output Type | Slideshow | | Category | Quote Cards | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | font | enum | No | font-sans | Font family. Values: font-sans, font-serif, font-mono, font-retro, font-montserrat, font-quicksand, font-philosopher, font-poppins, font-raleway, font-opensans, font-lato, font-oswald, font-playfair, font-roboto, font-ptsans, font-dmsans, font-nunito, font-comfortaa, font-worksans, font-fjallaone, font-rubik, font-barlow, font-bebasnue, font-caveat, font-pacifico | | title | string | Yes | Inspirational Quotes | Title for the carousel. Max: 50 chars | | quotes | array | Yes | - | List of quote strings. Each quote becomes a card. Min: 1, Max: 100. Each quote: 10-500 chars | | aspectRatio | enum | No | 4:5 | Values: 4:5, 1:1, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/quote-card/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd/v1", "inputs": {}, "prompt": "Create 5 motivational quotes about entrepreneurship and building businesses", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/quote-card/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd/v1", "inputs": { "title": "Daily Wisdom", "quotes": [ "Be careful who you let speak into your life. Not all opinions are qualified.", "People will question your choices...especially the ones too scared to make their own.", "Take advice from people who have receipts, not opinions." ], "font": "font-playfair", "aspectRatio": "1:1" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/quote-card/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd/v1", "inputs": { "title": "Leadership Lessons", "font": "font-montserrat" }, "prompt": "Generate 4 powerful quotes about leadership and team management", "render": true } ``` ## Related Templates * [Quote Card with Paper Background and Highlight](/api/visuals/f941e306-76f7-45da-b3d9-7463af630e91) * [Tweet Card with Minimal Style](/api/visuals/ba413be6-a840-4e60-8fd6-0066d3b427df) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Quote Card with Paper Background and Highlight Create quote card carousels with paper background and highlighter effect on text. ## When to Use This Template * You want quote cards with a paper texture background and colored highlighter effect on text * You are creating "listicle" or "advice" style carousels that mimic a handwritten or notebook feel * Popular format for Instagram carousels in the coaching, self-improvement, and personal development space ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------- | | Template ID | `/base/v2/quote-card/f941e306-76f7-45da-b3d9-7463af630e91/v1` | | Output Type | Slideshow | | Category | Quote Cards | ## Parameters | Parameter | Type | Required | Default | Description | | ---------------- | ------ | -------- | --------------------------------------------------- | ----------------------------------------------------------- | | font | enum | No | font-sans | Font family. 24 options available | | title | string | Yes | I'm 35.\nIf You're in Your\n30s or 40s,\nRead This: | Title text. Max: 50 chars | | quotes | array | Yes | - | List of quote strings. Min: 1, Max: 100. Each: 10-500 chars | | highlighterColor | color | No | #008000 | Highlighter color behind text | | paperBackground | enum | No | White paper | Values: White paper, Yellow paper, Light paper | | aspectRatio | enum | No | 4:5 | Values: 4:5, 1:1, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/quote-card/f941e306-76f7-45da-b3d9-7463af630e91/v1", "inputs": {}, "prompt": "Create a viral quote carousel about life lessons for people in their 30s", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/quote-card/f941e306-76f7-45da-b3d9-7463af630e91/v1", "inputs": { "title": "Hard Truths About Success", "quotes": [ "I wasted my 20s building other people's dreams. At 35, I started building my own.", "People will question your choices...especially the ones too scared to make their own.", "Take advice from people who have receipts, not opinions." ], "highlighterColor": "#FFD700", "paperBackground": "Yellow paper", "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/quote-card/f941e306-76f7-45da-b3d9-7463af630e91/v1", "inputs": { "highlighterColor": "#FF6B6B", "paperBackground": "Light paper" }, "prompt": "Generate 5 quotes about overcoming self-doubt and building confidence", "render": true } ``` ## Related Templates * [Quote Card with Monocolor Background](/api/visuals/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd) * [Tweet Card with Minimal Style](/api/visuals/ba413be6-a840-4e60-8fd6-0066d3b427df) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Tweet Card with Minimal Style Create Twitter/X-style quote cards with a minimal design. ## When to Use This Template * You want to repurpose tweets or X posts as carousel slides styled to look like actual tweets * You are cross-posting Twitter/X content to Instagram, LinkedIn, or TikTok as a slideshow * You want to quote an influencer or public figure in the familiar tweet card format * Supports dark and light themes to match your brand ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------- | | Template ID | `/base/v2/tweet-card/ba413be6-a840-4e60-8fd6-0066d3b427df/v1` | | Output Type | Slideshow | | Category | Tweet Cards | ## Parameters | Parameter | Type | Required | Default | Description | | ------------ | ------- | -------- | ------------- | -------------------------------------------------------------------- | | quotes | array | Yes | - | List of quotes. Min: 1, Max: 100. Each: 10-280 chars (Twitter limit) | | authorName | string | Yes | Dean Graziosi | Name of person quoted. Max: 60 chars | | handle | string | Yes | deangraziosi | Social handle without @. Max: 50 chars | | profileImage | image | No | - | Profile photo URL | | verified | boolean | No | true | Show verified badge | | theme | enum | No | dark | Values: dark, light | | aspectRatio | enum | No | 4:5 | Values: 4:5, 1:1, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tweet-card/ba413be6-a840-4e60-8fd6-0066d3b427df/v1", "inputs": {}, "prompt": "Create 5 tweet-style quotes about building a personal brand on social media", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tweet-card/ba413be6-a840-4e60-8fd6-0066d3b427df/v1", "inputs": { "quotes": [ "Be careful who you let speak into your life. Not all opinions are qualified.", "People will question your choices...especially the ones too scared to make their own.", "Take advice from people who have receipts, not opinions." ], "authorName": "Alex Hormozi", "handle": "AlexHormozi", "profileImage": "https://example.com/alex-profile.jpg", "verified": true, "theme": "dark", "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tweet-card/ba413be6-a840-4e60-8fd6-0066d3b427df/v1", "inputs": { "authorName": "Your Name", "handle": "yourhandle", "theme": "light" }, "prompt": "Generate 4 motivational tweets about starting a business", "render": true } ``` ## Related Templates * [Tweet Card with Photo/Video Background](/api/visuals/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66) * [Quote Card with Monocolor Background](/api/visuals/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Tweet Card with Photo/Video Background Create Twitter/X-style quote cards with a photo or video background. ## When to Use This Template * Same as the minimal tweet card, but with your own photo or video as the background behind each tweet card * You want a more visual, branded look for tweet-style quote carousels * Useful for lifestyle, travel, or fitness creators who want tweet quotes overlaid on their own imagery ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------- | | Template ID | `/base/v2/tweet-card/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66/v1` | | Output Type | Slideshow | | Category | Tweet Cards | ## Parameters | Parameter | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------------- | ---------------------------------------------------- | | backgroundMedia | image | No | - | Background image or video URL | | quotes | array | Yes | - | List of quotes. Min: 1, Max: 100. Each: 10-280 chars | | authorName | string | Yes | Dean Graziosi | Name of person quoted. Max: 60 chars | | handle | string | Yes | deangraziosi | Social handle without @. Max: 50 chars | | profileImage | image | No | - | Profile photo URL | | theme | enum | No | light | Values: light, dark | | cardPosition | enum | No | bottom | Values: top, middle, bottom | | verified | boolean | No | true | Show verified badge | | enableBackdropBlur | boolean | No | false | Add blur effect behind card | | accentColor | color | No | #C4A484 | Background shape color | | cardBackgroundColor | color | No | #FFFFFF | Card background color | | textColor | color | No | #0F1419 | Quote text color | | aspectRatio | enum | No | 4:5 | Values: 4:5, 1:1, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tweet-card/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66/v1", "inputs": {}, "prompt": "Create 4 inspirational tweet cards about perseverance with mountain scenery backgrounds", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tweet-card/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66/v1", "inputs": { "backgroundMedia": "https://images.unsplash.com/photo-1506905925346-21bda4d32df4", "quotes": [ "Be careful who you let speak into your life.", "People will question your choices.", "Take advice from people who have receipts." ], "authorName": "Dean Graziosi", "handle": "deangraziosi", "theme": "light", "cardPosition": "bottom", "enableBackdropBlur": true, "accentColor": "#C4A484", "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tweet-card/9714ae5c-7e6b-4878-be4a-4b1ba5d0cd66/v1", "inputs": { "backgroundMedia": "https://example.com/nature-background.jpg", "authorName": "Your Brand", "handle": "yourbrand", "cardPosition": "middle", "enableBackdropBlur": true }, "prompt": "Generate 5 quotes about work-life balance", "render": true } ``` ## Related Templates * [Tweet Card with Minimal Style](/api/visuals/ba413be6-a840-4e60-8fd6-0066d3b427df) * [Quote Card with Paper Background](/api/visuals/f941e306-76f7-45da-b3d9-7463af630e91) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Tutorial Carousel with Minimalist Flat Style Create step-by-step tutorial carousels with a minimalist flat design style. ## When to Use This Template * You are creating step-by-step educational or how-to carousels * You want a structured format with a title slide, numbered content slides, and a CTA slide with your profile info * Popular format for LinkedIn and Instagram carousels in business, marketing, and tech education * Includes built-in CTA buttons (e.g., "Follow for more tips", "Share", "Bookmark") and a profile slide ## Template Information | Property | Value | | ----------- | -------------------------------------------------------------------- | | Template ID | `/base/v2/tutorial-carousel/2491f97b-1b47-4efa-8b96-8c651fa7b3d5/v1` | | Output Type | Slideshow | | Category | Tutorial Carousels | ## Parameters | Parameter | Type | Required | Default | Description | | ------------------ | ------ | -------- | ------------------------------------- | -------------------------------------------------- | | font | enum | No | font-sans | Font family. 24 options available | | mainTitle | string | Yes | 3 Ways to Grow Faster on Instagram | Main title. 5-50 chars | | authorName | string | Yes | Alex Hormozi | Author name. Max: 60 chars | | ctaButtonText | string | Yes | Swipe Right | CTA button text. Max: 50 chars | | contentItems | array | Yes | - | Content items. Min: 1. Each: 10-300 chars | | backgroundColor | color | No | #F5D5C8 | Main background color | | borderColor | color | No | #000000 | Border frame color | | textColor | color | No | #000000 | Main text color | | ctaTitle | string | Yes | Share your thoughts in comments below | CTA title. 5-150 chars | | ctaActions | array | Yes | - | Action buttons. Min: 1, Max: 100. Each: 1-50 chars | | profileName | string | Yes | Alex Hormozi | Profile name. Max: 60 chars | | profileTitle | string | Yes | Brand Strategist | Profile title. Max: 80 chars | | profileDescription | string | Yes | - | Profile description. 10-250 chars | | profileCta | string | Yes | Follow for more tips | Profile CTA. Max: 50 chars | | profileImage | image | No | - | Profile image URL | | aspectRatio | enum | No | 1:1 | Values: 1:1, 4:5, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tutorial-carousel/2491f97b-1b47-4efa-8b96-8c651fa7b3d5/v1", "inputs": {}, "prompt": "Create a tutorial carousel about 5 ways to improve your LinkedIn profile for job seekers", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tutorial-carousel/2491f97b-1b47-4efa-8b96-8c651fa7b3d5/v1", "inputs": { "mainTitle": "3 Ways to Grow Faster on Instagram", "authorName": "Alex Hormozi", "ctaButtonText": "Swipe Right", "contentItems": [ "Stop chasing vanity metrics. Focus on getting 100 true fans who buy from you", "Document your process, not results. Show the messy middle where real learning happens", "Reply to every DM for your first 1,000 followers. This builds loyalty money cannot buy" ], "backgroundColor": "#F5D5C8", "borderColor": "#000000", "ctaTitle": "Share your thoughts in comments below", "ctaActions": ["Leave a like", "Share to help others", "Bookmark for later"], "profileName": "Alex Hormozi", "profileTitle": "Brand Strategist", "profileDescription": "I share daily posts to help you scale your business 10x faster.", "profileCta": "Follow for more tips", "aspectRatio": "1:1" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tutorial-carousel/2491f97b-1b47-4efa-8b96-8c651fa7b3d5/v1", "inputs": { "authorName": "Your Name", "profileName": "Your Name", "profileTitle": "Your Title", "backgroundColor": "#E8F4F8", "aspectRatio": "4:5" }, "prompt": "Create a 4-step tutorial about email marketing best practices", "render": true } ``` ## Related Templates * [Tutorial Carousel with Monocolor Background](/api/visuals/e095104b-e6c5-4a81-a89d-b0df3d7c5baf) * [Image Slideshow with Prominent Text](/api/visuals/0ddb8655-c3da-43da-9f7d-be1915ca7818) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Tutorial Carousel with Monocolor Background Create tutorial carousels with monocolor backgrounds and structured content slides. ## When to Use This Template * Same structured tutorial format as the minimalist flat style, but with customizable monocolor backgrounds and accent colors * You want brand-colored tutorial carousels with heading + description per slide * Includes a hashtag on the intro slide, useful for niche-specific LinkedIn and Instagram content * Includes a CTA slide with profile image, description, and action buttons ## Template Information | Property | Value | | ----------- | -------------------------------------------------------------------- | | Template ID | `/base/v2/tutorial-carousel/e095104b-e6c5-4a81-a89d-b0df3d7c5baf/v1` | | Output Type | Slideshow | | Category | Tutorial Carousels | ## Parameters | Parameter | Type | Required | Default | Description | | ------------------------------- | ------- | -------- | ---------------------------------- | ------------------------------------------------- | | font | enum | No | font-sans | Font family. 24 options | | hashtag | string | Yes | #personalbranding | Hashtag in upper left. Max: 30 chars | | title | string | Yes | 3 Ways to Grow Faster on Instagram | Main title. 5-50 chars | | introBackgroundColor | color | No | #fe6616 | Intro slide background | | contentSlides | array | Yes | - | Content slide objects. Min: 1, Max: 100 | | contentSlides\[].heading | string | Yes | - | Slide heading. 5-50 chars | | contentSlides\[].description | string | Yes | - | Slide description. 10-400 chars | | contentSlides\[].hasAccentLines | boolean | No | false | Show decorative accent lines | | contentBackgroundColor | color | No | #FFFFFF | Content slides background | | accentColor | color | No | #fe6616 | Accent elements color | | authorName | string | Yes | Alex Hormozi | Author name. Max: 60 chars | | companyName | string | Yes | @AlexHormozi | Company/handle. Max: 60 chars | | ctaGreeting | string | Yes | Hi, I'm Alex | CTA greeting. Max: 80 chars | | ctaDescription | string | Yes | - | CTA description. 10-200 chars | | ctaButtons | array | Yes | - | Button labels. Min: 1, Max: 100. Each: 1-30 chars | | ctaBackgroundColor | color | No | #7217fe | CTA slide background | | profileImage | image | No | - | Profile image URL | | aspectRatio | enum | No | 4:5 | Values: 4:5, 1:1, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tutorial-carousel/e095104b-e6c5-4a81-a89d-b0df3d7c5baf/v1", "inputs": {}, "prompt": "Create a tutorial carousel about 4 steps to start freelancing successfully", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tutorial-carousel/e095104b-e6c5-4a81-a89d-b0df3d7c5baf/v1", "inputs": { "hashtag": "#contentcreation", "title": "3 Steps to Better Content", "introBackgroundColor": "#fe6616", "contentSlides": [ { "heading": "Step 1: Research", "description": "Spend 30 minutes each day reading what your audience discusses. Note their pain points and questions.", "hasAccentLines": false }, { "heading": "Step 2: Create", "description": "Write content that addresses one specific problem. Keep it actionable and clear.", "hasAccentLines": true } ], "authorName": "Alex Hormozi", "companyName": "@AlexHormozi", "ctaGreeting": "Hi, I'm Alex", "ctaDescription": "Follow me for actionable tips on content creation and business!", "ctaButtons": ["Repost", "Share"], "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/tutorial-carousel/e095104b-e6c5-4a81-a89d-b0df3d7c5baf/v1", "inputs": { "hashtag": "#marketing", "authorName": "Your Brand", "companyName": "@yourbrand", "accentColor": "#3B82F6", "ctaBackgroundColor": "#1E40AF" }, "prompt": "Generate a 5-step guide to creating viral TikTok content", "render": true } ``` ## Related Templates * [Tutorial Carousel with Minimalist Flat Style](/api/visuals/2491f97b-1b47-4efa-8b96-8c651fa7b3d5) * [Image Slideshow with Text Overlays](/api/visuals/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Image Slideshow with Prominent Text Create image slideshows with prominent text overlays. 3.2M views, 3,800 likes. ## When to Use This Template * You want AI-generated images with large, prominent text overlays for a news-style or story-style carousel * You are creating "did you know" content, news recaps, or information-heavy slideshows for Instagram or TikTok * All images are AI-generated from prompts -- you do not upload your own images with this template ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------------- | | Template ID | `/base/v2/images-with-text/0ddb8655-c3da-43da-9f7d-be1915ca7818/v1` | | Output Type | Slideshow | | Category | Images with Text | ## Parameters | Parameter | Type | Required | Default | Description | | --------------- | ------ | -------- | ------- | ----------------------------------------- | | slides | array | Yes | - | Slide objects. Min: 1, Max: 20 | | slides\[].image | string | Yes | - | AI prompt to generate image. 20-400 chars | | slides\[].text | string | Yes | - | Text overlay. 30-200 chars | | slideDuration | number | No | 5 | Seconds per slide. Range: 1-10 | | aspectRatio | enum | No | 4:5 | Values: 16:9, 1:1, 4:5, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/0ddb8655-c3da-43da-9f7d-be1915ca7818/v1", "inputs": {}, "prompt": "Create a 4-slide news story about a tech startup that raised $100M in funding", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/0ddb8655-c3da-43da-9f7d-be1915ca7818/v1", "inputs": { "slides": [ { "image": "A professional business person at a modern startup office with computers", "text": "Parag Agarwal, removed by Elon Musk as Twitter CEO, built an AI company valued at $740M" }, { "image": "Modern tech infrastructure with servers and AI visualization", "text": "After leaving Twitter, he founded Parallel Web Systems. The company builds AI infrastructure for web search." }, { "image": "Social media and AI concept with digital connections", "text": "We share informative AI content you will not find anywhere else" } ], "slideDuration": 5, "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/0ddb8655-c3da-43da-9f7d-be1915ca7818/v1", "inputs": { "slideDuration": 6, "aspectRatio": "9:16" }, "prompt": "Create a 5-slide story about the rise of remote work in tech companies", "render": true } ``` ## Related Templates * [Image Slideshow with Text Overlays](/api/visuals/5903b592-1255-43b4-b9ac-f8ed7cbf6a5f) * [When X then Y Text Slideshow](/api/visuals/c9892c3b-fa75-4ade-821a-a50ff8456230) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # When X then Y Text Slideshow Show examples of "When X happens, then Y happens" scenarios with AI-generated images. 2.7M views, 2,700 likes. ## When to Use This Template * You are creating comparison or "what they say vs. what you should say" content * Popular format for business tips, negotiation advice, mindset shifts, and before/after scenarios * You want a structured side-by-side comparison layout with AI-generated images * Works for coaches, consultants, and educators on TikTok, Instagram, and LinkedIn ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------------- | | Template ID | `/base/v2/images-with-text/c9892c3b-fa75-4ade-821a-a50ff8456230/v1` | | Output Type | Video | | Category | Images with Text | ## Parameters | Parameter | Type | Required | Default | Description | | ------------------------------------- | ------ | -------- | ------- | -------------------------------------------- | | firstSlideText | string | Yes | - | Hook text for first slide. 30-70 chars | | firstSlideImagePrompt | string | Yes | - | AI prompt for first slide image. 1-400 chars | | comparisonTextTop | string | Yes | - | Top comparison label. 1-50 chars | | comparisonTextBottom | string | Yes | - | Bottom comparison label. 1-50 chars | | lastSlideText | string | Yes | - | Text for last slide. 1-350 chars | | lastSlideImagePrompt | string | Yes | - | AI prompt for last slide image. 1-400 chars | | slides | array | Yes | - | Comparison slides. Min: 1, Max: 20 | | slides\[].topComparisonExampleText | string | Yes | - | Top example. 20-200 chars | | slides\[].bottomComparisonExampleText | string | Yes | - | Bottom example. 20-200 chars | | slideDuration | number | No | 5 | Seconds per slide. Range: 1-10 | | aspectRatio | enum | No | 4:5 | Values: 16:9, 1:1, 4:5, 9:16 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/c9892c3b-fa75-4ade-821a-a50ff8456230/v1", "inputs": {}, "prompt": "Create a video about negotiation phrases every founder should know, comparing what clients say vs how you should respond", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/c9892c3b-fa75-4ade-821a-a50ff8456230/v1", "inputs": { "firstSlideText": "Negotiation phrases every founder should know", "firstSlideImagePrompt": "Professional business meeting with two people shaking hands", "comparisonTextTop": "When they say:", "comparisonTextBottom": "You say:", "slides": [ { "topComparisonExampleText": "Your pricing does not fit our budget right now", "bottomComparisonExampleText": "Help me understand what you are working with." }, { "topComparisonExampleText": "We need to think about it", "bottomComparisonExampleText": "What specific concerns do you want to address?" }, { "topComparisonExampleText": "Your competitor is cheaper", "bottomComparisonExampleText": "What would make the extra investment worthwhile for you?" } ], "lastSlideText": "Follow for more business tips", "lastSlideImagePrompt": "Successful entrepreneur celebrating a closed deal", "slideDuration": 5, "aspectRatio": "4:5" }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/c9892c3b-fa75-4ade-821a-a50ff8456230/v1", "inputs": { "comparisonTextTop": "What beginners think:", "comparisonTextBottom": "What experts know:", "aspectRatio": "9:16" }, "prompt": "Create a video comparing beginner vs expert mindsets in investing with 4 examples", "render": true } ``` ## Related Templates * [Image Slideshow with Prominent Text](/api/visuals/0ddb8655-c3da-43da-9f7d-be1915ca7818) * [Video of Images and Text with Minimal Style](/api/visuals/3ed4bb92-dbfe-45e6-9dc8-605b77f70506) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Video of Images and Text with Minimal Style Create videos combining images and text with minimal styling. ## When to Use This Template * You have your own images and want to create a video (not a slideshow) that cycles through them — with or without text overlays and a watermark * You are a photographer, real estate agent, or e-commerce seller who wants to turn product or property images into a video * You want a branded watermark on the output video (optional — set to empty to remove) ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------------- | | Template ID | `/base/v2/images-with-text/3ed4bb92-dbfe-45e6-9dc8-605b77f70506/v1` | | Output Type | Video | | Category | Images with Text | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | -------- | -------------------------------- | | watemark | string | No | Watemark | Watermark text | | textBgColor | color | No | #FFA500 | Background color for text | | titles | array | No | - | Array of title strings. Max: 100 | | texts | array | No | - | Array of text strings. Max: 100 | | images | array | No | - | Array of image URLs. Max: 100 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/3ed4bb92-dbfe-45e6-9dc8-605b77f70506/v1", "inputs": {}, "prompt": "Create a video showcasing 3 luxury real estate properties with descriptions", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/3ed4bb92-dbfe-45e6-9dc8-605b77f70506/v1", "inputs": { "watemark": "@YourBrand", "textBgColor": "#FFA500", "titles": [ "Creative Slide", "Modern Template" ], "texts": [ "Add engaging content easily and quickly. Capture attention instantly!", "Perfect for social media and presentations. Bring your designs to life with motion text." ], "images": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ] }, "render": true } ``` ## Example 3: Hybrid Approach ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/images-with-text/3ed4bb92-dbfe-45e6-9dc8-605b77f70506/v1", "inputs": { "watemark": "@mybrand", "textBgColor": "#3B82F6" }, "prompt": "Create a video about 4 tips for better sleep with calming imagery", "render": true } ``` ## Customization Tips All parameters in this template are optional. To hide elements you don't need: | To hide this | Do this | | --------------------- | ----------------------------------------------------------------------------------------------- | | Watermark | Set `watemark` to `""` (empty string). Note: the parameter name is `watemark`, not `watermark`. | | Titles | Omit the `titles` parameter, or pass an empty array `[]` | | Text overlays | Omit the `texts` parameter, or pass an empty array `[]` | | Text background color | Omit `textBgColor` (only visible when titles/texts are present) | If you want a video of your images with no overlays at all, set `watemark` to `""` and omit `titles` and `texts`. ## Related Templates * [Image Slideshow with Prominent Text](/api/visuals/0ddb8655-c3da-43da-9f7d-be1915ca7818) * [When X then Y Text Slideshow](/api/visuals/c9892c3b-fa75-4ade-821a-a50ff8456230) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Combine Clips and Apply Basic Edits Stitch video clips together with titles, captions, background music, and transitions. ## When to Use This Template * You have your own video clips (recorded on your phone, from a camera, or downloaded) and want to stitch them together into one video * You want to add a title card, auto-generated captions, background music, or transitions to existing footage * You are a content creator, real estate agent, or business owner who films your own clips and needs light editing before posting to TikTok, Instagram Reels, or YouTube Shorts * You do NOT need AI to generate any visuals -- you are bringing your own footage ## Using the Web App 1. Go to [Videos > New](https://my.blotato.com/videos/new) 2. Select **Combine Clips and Apply Basic Edits** from the template list 3. Click **Advanced Settings** under the Generate Video button 4. Add your video clips in the clip input fields 5. Configure titles, captions, music, and transitions 6. Click **Generate Video** ## Template Information | Property | Value | | ----------- | ---------------------------------------------------------------- | | Template ID | `/base/v2/combine-clips/c306ae43-1dcc-4f45-ac2b-88e75430ffd8/v1` | | Output Type | Video | | Category | Video Editor | ## Parameters | Parameter | Type | Required | Default | Description | | ------------------------- | ------- | -------- | --------------- | ------------------------------------------------------ | | videoClips | array | Yes | - | Video clips to stitch. Min: 1, Max: 20 | | videoClips\[].url | video | Yes | - | URL of video clip | | trimSilence | boolean | No | false | Trim silence at start/end | | titleConfig | object | No | - | Title overlay configuration | | titleConfig.enabled | boolean | No | false | Enable title overlay | | titleConfig.text | string | No | Your Title Here | Title text | | titleConfig.position | enum | No | top | Values: top, center, bottom | | titleConfig.duration | number | No | 4 | Seconds to display. Range: 1-10 | | titleConfig.style | enum | No | minimal | Values: minimal, bold, elegant, modern | | captionsConfig | object | No | - | Captions configuration | | captionsConfig.enabled | boolean | No | false | Enable captions | | captionsConfig.style | enum | No | minimal | Values: minimal, bold, highlight, tiktok | | captionsConfig.position | enum | No | bottom | Values: top, center, bottom | | musicConfig | object | No | - | Background music configuration | | musicConfig.enabled | boolean | No | false | Enable background music | | musicConfig.url | string | No | - | Music file URL (MP3/WAV) | | musicConfig.volume | number | No | 30 | Volume level. Range: 0-100 | | transitionConfig | object | No | - | Transition configuration | | transitionConfig.type | enum | No | none | Values: none, fade, crossfade, slide, zoom | | transitionConfig.duration | number | No | 0.5 | Seconds. Range: 0-2 | | maxDuration | number | No | 0 | Max output duration in seconds. 0 = no limit. Max: 600 | | aspectRatio | enum | No | 9:16 | Values: 16:9, 9:16, 1:1, 4:5 | ## Example 1: Basic Clip Combination ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/combine-clips/c306ae43-1dcc-4f45-ac2b-88e75430ffd8/v1", "inputs": { "videoClips": [ { "url": "https://example.com/clip1.mp4" }, { "url": "https://example.com/clip2.mp4" }, { "url": "https://example.com/clip3.mp4" } ], "aspectRatio": "9:16" }, "render": true } ``` ## Example 2: Full Featured Edit ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/combine-clips/c306ae43-1dcc-4f45-ac2b-88e75430ffd8/v1", "inputs": { "videoClips": [ { "url": "https://example.com/intro.mp4" }, { "url": "https://example.com/main-content.mp4" }, { "url": "https://example.com/outro.mp4" } ], "trimSilence": true, "titleConfig": { "enabled": true, "text": "My Amazing Video", "position": "center", "duration": 3, "style": "bold" }, "captionsConfig": { "enabled": true, "style": "tiktok", "position": "bottom" }, "musicConfig": { "enabled": true, "url": "https://example.com/background-music.mp3", "volume": 25 }, "transitionConfig": { "type": "crossfade", "duration": 0.5 }, "maxDuration": 60, "aspectRatio": "9:16" }, "render": true } ``` ## Example 3: With Captions and Transitions ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/combine-clips/c306ae43-1dcc-4f45-ac2b-88e75430ffd8/v1", "inputs": { "videoClips": [ { "url": "https://example.com/clip1.mp4" }, { "url": "https://example.com/clip2.mp4" } ], "captionsConfig": { "enabled": true, "style": "highlight", "position": "center" }, "transitionConfig": { "type": "fade", "duration": 0.8 }, "aspectRatio": "1:1" }, "render": true } ``` ## Related Templates * [AI Video with AI Voice](/api/visuals/5903fe43-514d-40ee-a060-0d6628c5f8fd) * [AI Avatar with AI Generated B-roll](/api/visuals/7c26a1cd-d5b3-42da-9c73-2413333873b3) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # AI Video with AI Voice Create AI-narrated videos with generated or uploaded media. 8.9M views, trending template. ## When to Use This Template * You have a script or topic and want Blotato to generate a full video with AI images, voiceover, and captions * You want to create faceless story videos, educational explainers, or narrated content without filming yourself * You are making content for TikTok, Instagram Reels, or YouTube Shorts and need AI to handle image generation and voiceover * You want to upload your own media for some scenes and use AI-generated images for others (hybrid approach) * Use advanced options to control the exact image prompt and voiceover script per scene ## Template Information | Property | Value | | ----------- | ----------------------------------------------------------------- | | Template ID | `/base/v2/ai-story-video/5903fe43-514d-40ee-a060-0d6628c5f8fd/v1` | | Output Type | Video | | Category | AI Videos | ## Parameters | Parameter | Type | Required | Default | Description | | --------------------- | ------- | -------- | --------------------------- | -------------------------------------------------- | | scenes | array | Yes | - | Scene objects. Min: 1, Max: 20 | | scenes\[].mediaSource | union | Yes | - | Upload video URL or AI prompt for image generation | | scenes\[].script | string | Yes | - | Voiceover text for this scene | | voiceName | enum | No | Brian (American, deep) | ElevenLabs voice. See voice options below | | aiImageModel | enum | No | fal-ai/imagen4/preview/fast | AI model for image generation. See values below | | animateAiImages | boolean | No | false | Convert AI images to animated videos | | captionPosition | enum | No | center | Values: top, center, bottom | | highlightColor | color | No | #FFFF00 | Highlighted word color in captions | | transition | enum | No | none | Values: none, fade, slide, zoom | | aspectRatio | enum | No | 9:16 | Values: 16:9, 1:1, 4:5, 9:16 | | trimToVoiceover | boolean | No | true | Trim video to match voiceover duration | ### Available AI Image Models Pass one of these values as `aiImageModel` to control which AI model generates your images. Each model has a different credit cost. See [AI Video Credits](/features/videos/ai-video-credits) for pricing. | Value | Label | Credits/Image | | ------------------------------------------------ | ------------------------ | ------------- | | `replicate/black-forest-labs/flux-schnell` | Cheapest | 1 | | `replicate/black-forest-labs/flux-dev` | Good | 10 | | `replicate/black-forest-labs/flux-1.1-pro` | Great | 15 | | `replicate/black-forest-labs/flux-1.1-pro-ultra` | Best for Images | 20 | | `replicate/recraft-ai/recraft-v3` | Best for Realistic Image | 15 | | `replicate/ideogram-ai/ideogram-v2` | Best for Text | 30 | | `replicate/luma/photon` | Good | 10 | | `openai/gpt-image-1` | OpenAI GPT Image | 25 | | `fal-ai/nano-banana` | Nano Banana | 15 | | `fal-ai/nano-banana/edit` | Nano Banana Edit | 15 | | `fal-ai/nano-banana-pro` | Nano Banana Pro | 50 | | `fal-ai/nano-banana-pro/edit` | Nano Banana Pro Edit | 50 | | `fal-ai/imagen4/preview/fast` | Imagen 4 Fast (default) | 7 | | `fal-ai/bytedance/seedream/v4.5/text-to-image` | Seedream v4.5 | 15 | | `fal-ai/bytedance/seedream/v4.5/edit` | Seedream v4.5 Edit | 15 | ### Available Voices Alice (British, confident), Aria (American, expressive), Bill (American, trustworthy), Brian (American, deep), Callum (Transatlantic, intense), Charlie (Australian, natural), Charlotte (Swedish, seductive), Chris (American, casual), Daniel (British, authoritative), Eric (American, friendly), George (British, warm), Jessica (American, expressive), Laura (American, upbeat), Liam (American, articulate), Lily (British, warm), Matilda (American, friendly), River (American, confident), Roger (American, confident), Sarah (American, soft), Will (American, friendly) ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-story-video/5903fe43-514d-40ee-a060-0d6628c5f8fd/v1", "inputs": {}, "prompt": "Create a 3-scene video about the history of coffee, from ancient Ethiopia to modern cafes", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-story-video/5903fe43-514d-40ee-a060-0d6628c5f8fd/v1", "inputs": { "scenes": [ { "mediaSource": "A serene winter landscape with snow-covered mountains and a frozen lake", "script": "Welcome to this amazing journey. Let me show you something incredible." }, { "mediaSource": "A golden retriever playing happily in a sunny meadow", "script": "Every moment is an opportunity to create something beautiful." }, { "mediaSource": "A cozy coffee shop interior with warm lighting and books", "script": "And remember, the best stories are yet to be told." } ], "voiceName": "Brian (American, deep)", "captionPosition": "center", "highlightColor": "#FFFF00", "transition": "fade", "aspectRatio": "9:16" }, "render": true } ``` ## Example 3: Hybrid with Custom Voice ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-story-video/5903fe43-514d-40ee-a060-0d6628c5f8fd/v1", "inputs": { "voiceName": "Alice (British, confident)", "captionPosition": "bottom", "highlightColor": "#00FF00", "animateAiImages": true, "aspectRatio": "1:1" }, "prompt": "Create a 4-scene video about the benefits of meditation for busy professionals", "render": true } ``` ## Example 4: Mixed Media Sources ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-story-video/5903fe43-514d-40ee-a060-0d6628c5f8fd/v1", "inputs": { "scenes": [ { "mediaSource": "https://example.com/my-uploaded-video.mp4", "script": "Here is my introduction using uploaded footage." }, { "mediaSource": "A futuristic cityscape with flying cars and neon lights", "script": "Now imagine what the future could look like." } ], "voiceName": "Daniel (British, authoritative)", "aspectRatio": "16:9" }, "render": true } ``` ## Related Templates * [AI Selfie Talking Video](/api/visuals/57f5a565-fd17-458b-be43-4a2d8ccaca75) * [AI Avatar with AI Generated B-roll](/api/visuals/7c26a1cd-d5b3-42da-9c73-2413333873b3) * [Combine Clips and Apply Basic Edits](/api/visuals/c306ae43-1dcc-4f45-ac2b-88e75430ffd8) ## See Also * [Create Visual API Reference](/api/create-video) * [Voice IDs Reference](/api/accounts/voice-ids) * [All Visual Templates](/api/visuals) # AI Selfie Talking Video with Consistent Character Create AI-generated selfie-style talking videos with a consistent character across all scenes. ## When to Use This Template * You want a consistent AI-generated character (not your real face) appearing across all scenes * You are creating POV-style, vlog-style, or first-person narration videos where a character "talks to the camera" * You want to experiment with different art styles (realistic, anime, watercolor, cyberpunk) for your character * You do not want to show your face on camera but want a character-driven video for TikTok or Instagram ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------------ | | Template ID | `/base/v2/ai-selfie-video/57f5a565-fd17-458b-be43-4a2d8ccaca75/v1` | | Output Type | Video | | Category | AI Videos | ## Parameters | Parameter | Type | Required | Default | Description | | --------------------- | ------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------------- | | scenes | array | Yes | - | Scene objects. Min: 1, Max: 100 | | scenes\[].description | string | Yes | - | Visual description of the scene | | scenes\[].narration | string | Yes | - | Narration text for the scene | | style | enum | No | realistic | Visual style. Values: realistic, cartoon, anime, watercolor, oil-painting, sketch, cyberpunk, fantasy, minimalist | | characterDescription | union | Yes | - | Text description or image reference of character | | aspectRatio | enum | No | 9:16 | Values: 16:9, 9:16, 1:1 | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-selfie-video/57f5a565-fd17-458b-be43-4a2d8ccaca75/v1", "inputs": {}, "prompt": "Create a 3-scene travel vlog style video of a young adventurer exploring ancient temples in Southeast Asia", "render": true } ``` ## Example 2: Manual Inputs with Text Description ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-selfie-video/57f5a565-fd17-458b-be43-4a2d8ccaca75/v1", "inputs": { "scenes": [ { "description": "A lone traveler stands at the edge of a misty cliff, looking out at the vast ocean below", "narration": "Welcome to my journey. I will take you through some of the most breathtaking places I have ever seen." }, { "description": "The traveler walks through an ancient forest with towering trees and dappled sunlight", "narration": "This forest is one of my favorite spots. The light filtering through the leaves is magical." }, { "description": "A mysterious temple appears through the fog, its entrance glowing with soft golden light", "narration": "And here we are at the ancient temple. It has been standing for centuries, holding countless stories." } ], "style": "realistic", "characterDescription": "A young adventurer wearing a weathered cloak and carrying an old leather backpack", "aspectRatio": "9:16" }, "render": true } ``` ## Example 3: With Image Reference ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-selfie-video/57f5a565-fd17-458b-be43-4a2d8ccaca75/v1", "inputs": { "scenes": [ { "description": "Character standing in a modern office with city skyline visible through windows", "narration": "Welcome to my channel! Today I am sharing my productivity tips." }, { "description": "Character at a coffee shop with laptop and notebook", "narration": "First tip: always start your day with a clear plan." } ], "style": "realistic", "characterDescription": "https://example.com/my-character-reference.jpg", "aspectRatio": "9:16" }, "render": true } ``` ## Example 4: Anime Style ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-selfie-video/57f5a565-fd17-458b-be43-4a2d8ccaca75/v1", "inputs": { "style": "anime", "characterDescription": "A cheerful anime girl with pink hair and school uniform", "aspectRatio": "9:16" }, "prompt": "Create a 3-scene video about studying tips for students", "render": true } ``` ## Related Templates * [AI Video with AI Voice](/api/visuals/5903fe43-514d-40ee-a060-0d6628c5f8fd) * [AI Avatar with AI Generated B-roll](/api/visuals/7c26a1cd-d5b3-42da-9c73-2413333873b3) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # AI Avatar with AI Generated B-roll Create AI avatar videos with automatically generated B-roll footage that complements the narration. ## When to Use This Template * You have a talking head video (from HeyGen, a webcam, or your phone) and want to add AI-generated b-roll footage that matches your narration * You are a coach, educator, or thought leader who records yourself speaking and wants to make the video more engaging with relevant visuals * You want to enhance existing avatar or webcam footage for LinkedIn, YouTube, or Instagram without manually sourcing b-roll ## Template Information | Property | Value | | ----------- | ------------------------------------------------------------------ | | Template ID | `/base/v2/ai-avatar-broll/7c26a1cd-d5b3-42da-9c73-2413333873b3/v1` | | Output Type | Video | | Category | AI Avatar | ## Parameters | Parameter | Type | Required | Default | Description | | -------------- | ----- | -------- | ------- | ------------------------------------------ | | avatarVideoUrl | video | Yes | - | Video URL of avatar speaking the narration | ## How It Works 1. Upload a video of your avatar speaking (e.g., a talking head video) 2. The system analyzes the narration and automatically generates relevant B-roll footage 3. The B-roll is intelligently cut into the avatar video to create an engaging final product ## Example 1: Basic Usage ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-avatar-broll/7c26a1cd-d5b3-42da-9c73-2413333873b3/v1", "inputs": { "avatarVideoUrl": "https://example.com/my-avatar-speaking.mp4" }, "render": true } ``` ## Example 2: With Hosted Video ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/base/v2/ai-avatar-broll/7c26a1cd-d5b3-42da-9c73-2413333873b3/v1", "inputs": { "avatarVideoUrl": "https://storage.example.com/videos/talking-head-video.mp4" }, "render": true } ``` ## Tips for Best Results 1. Record a clear talking head video with good audio quality 2. Speak at a moderate pace to allow for B-roll insertion 3. Use natural pauses in your narration 4. Ensure consistent lighting and framing in your avatar video ## Related Templates * [AI Video with AI Voice](/api/visuals/5903fe43-514d-40ee-a060-0d6628c5f8fd) * [AI Selfie Talking Video](/api/visuals/57f5a565-fd17-458b-be43-4a2d8ccaca75) * [Combine Clips and Apply Basic Edits](/api/visuals/c306ae43-1dcc-4f45-ac2b-88e75430ffd8) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # TV Wall Infographic Generate an infographic displayed across a massive 32x32 grid of TV screens, creating a stunning video wall installation effect. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/013904bf-6b3b-43f4-bb1f-f1964a38c29b` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------ | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text at the bottom of the image. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/013904bf-6b3b-43f4-bb1f-f1964a38c29b", "inputs": {}, "prompt": "Create an infographic about the benefits of remote work", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/013904bf-6b3b-43f4-bb1f-f1964a38c29b", "inputs": { "description": "5 Ways AI is Transforming Healthcare: From early diagnosis to personalized treatment plans, AI is revolutionizing medicine", "footerText": "Follow @HealthTech for more insights" }, "render": true } ``` ## Related Templates * [Newspaper Infographic](/api/visuals/07a5b5c5-387c-49e3-86b1-de822cd2dfc7) * [Breaking News](/api/visuals/8800be71-52df-4ac7-ac94-df9d8a494d0f) * [Movie Theater Infographic](/api/visuals/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Newspaper Infographic Generate a classic newspaper-style infographic image with masthead, columns, and headlines using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/07a5b5c5-387c-49e3-86b1-de822cd2dfc7` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------ | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text at the bottom of the image. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/07a5b5c5-387c-49e3-86b1-de822cd2dfc7", "inputs": {}, "prompt": "Create a newspaper-style article about rising coffee prices", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/07a5b5c5-387c-49e3-86b1-de822cd2dfc7", "inputs": { "description": "BREAKING: New Study Reveals Morning Routines of Highly Successful People - Wake up early, exercise, and practice gratitude", "footerText": "Subscribe for daily insights" }, "render": true } ``` ## Related Templates * [TV Wall Infographic](/api/visuals/013904bf-6b3b-43f4-bb1f-f1964a38c29b) * [Breaking News](/api/visuals/8800be71-52df-4ac7-ac94-df9d8a494d0f) * [Movie Theater Infographic](/api/visuals/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Breaking News Generate a TV news broadcast style infographic with a professional news anchor, breaking news chyron, and lower third ticker using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/8800be71-52df-4ac7-ac94-df9d8a494d0f` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ----------------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text that appears in the news ticker. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/8800be71-52df-4ac7-ac94-df9d8a494d0f", "inputs": {}, "prompt": "Create breaking news about a major tech company announcement", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/8800be71-52df-4ac7-ac94-df9d8a494d0f", "inputs": { "description": "BREAKING: Scientists Discover New Method for Clean Energy - Revolutionary solar technology could power entire cities", "footerText": "Follow @ScienceNews for updates" }, "render": true } ``` ## Related Templates * [TV Wall Infographic](/api/visuals/013904bf-6b3b-43f4-bb1f-f1964a38c29b) * [Newspaper Infographic](/api/visuals/07a5b5c5-387c-49e3-86b1-de822cd2dfc7) * [Movie Theater Infographic](/api/visuals/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Movie Theater Infographic Generate an infographic illustrated on the pages of an open book, styled like a vintage encyclopedia or beautifully typeset reference book. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/b88c8273-6406-48c6-85e7-096119aefe30` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ----------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text as a footnote. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/b88c8273-6406-48c6-85e7-096119aefe30", "inputs": {}, "prompt": "Create an encyclopedia page about ancient civilizations", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/b88c8273-6406-48c6-85e7-096119aefe30", "inputs": { "description": "The Art of Storytelling: From oral traditions to written word, how humans have shared knowledge across generations", "footerText": "Continue reading at Library.com" }, "render": true } ``` ## Related Templates * [Manga Panel Infographic](/api/visuals/49c61370-a706-4b82-98f7-62d557d1c66d) * [Newspaper Infographic](/api/visuals/07a5b5c5-387c-49e3-86b1-de822cd2dfc7) * [Single Centered Text Quote](/api/visuals/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Graffiti Mural Infographic Generate a graffiti mural infographic image that looks like a photograph of massive street art painted on the side of a building in a busy urban area. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/3598483b-c148-4276-a800-eede85c1c62f` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text spray-painted at the bottom. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/3598483b-c148-4276-a800-eede85c1c62f", "inputs": {}, "prompt": "Create a street art infographic about urban sustainability", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/3598483b-c148-4276-a800-eede85c1c62f", "inputs": { "description": "Street Art Revolution: How murals are transforming cities and giving communities a voice through public art", "footerText": "@UrbanArtDaily | Share the love" }, "render": true } ``` ## Related Templates * [Bus Ad Infographic](/api/visuals/f9c0e470-9288-4958-8cdd-64772ed93c05) * [Billboard Infographic](/api/visuals/76b3b959-bdbe-440d-8428-984219353f18) * [T-Shirt Infographic](/api/visuals/476f8920-8749-4ff7-9c91-470d54c3c03e) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Bus Ad Infographic Generate an infographic printed as a full bus wrap advertisement on a double decker bus, photographed on a busy city street. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/f9c0e470-9288-4958-8cdd-64772ed93c05` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text on the bus wrap. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/f9c0e470-9288-4958-8cdd-64772ed93c05", "inputs": {}, "prompt": "Create a bus ad about public transportation benefits", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/f9c0e470-9288-4958-8cdd-64772ed93c05", "inputs": { "description": "Go Green, Ride the Bus: Reduce your carbon footprint by 75% when you choose public transit over driving alone", "footerText": "Learn more at GreenCommute.com" }, "render": true } ``` ## Related Templates * [Graffiti Mural Infographic](/api/visuals/3598483b-c148-4276-a800-eede85c1c62f) * [Billboard Infographic](/api/visuals/76b3b959-bdbe-440d-8428-984219353f18) * [T-Shirt Infographic](/api/visuals/476f8920-8749-4ff7-9c91-470d54c3c03e) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Billboard Infographic Generate a billboard-style infographic that looks like a giant outdoor billboard being constructed by workers, with bold impactful text visible from far away. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/76b3b959-bdbe-440d-8428-984219353f18` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ---------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text printed on the billboard. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/76b3b959-bdbe-440d-8428-984219353f18", "inputs": {}, "prompt": "Create a billboard about career growth tips", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/76b3b959-bdbe-440d-8428-984219353f18", "inputs": { "description": "Your Future Starts Today: 3 Skills Every Professional Needs - Leadership, Communication, Adaptability", "footerText": "Visit CareerBoost.io" }, "render": true } ``` ## Related Templates * [Graffiti Mural Infographic](/api/visuals/3598483b-c148-4276-a800-eede85c1c62f) * [Bus Ad Infographic](/api/visuals/f9c0e470-9288-4958-8cdd-64772ed93c05) * [T-Shirt Infographic](/api/visuals/476f8920-8749-4ff7-9c91-470d54c3c03e) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Classroom Chalkboard Infographic Generate a classroom chalkboard infographic image with a teacher explaining content drawn in colored chalk, photographed from the back of a classroom full of students. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/d9495026-3945-44f6-8b44-07c28c492e6d` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ----------------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text at the bottom of the chalkboard. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/d9495026-3945-44f6-8b44-07c28c492e6d", "inputs": {}, "prompt": "Create a classroom lesson about the solar system", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/d9495026-3945-44f6-8b44-07c28c492e6d", "inputs": { "description": "The Scientific Method: Observation, Hypothesis, Experiment, Analysis, Conclusion - How great discoveries are made", "footerText": "Follow @ScienceClass for more lessons" }, "render": true } ``` ## Related Templates * [Whiteboard Infographic](/api/visuals/ae868019-820d-434c-8fe1-74c9da99129a) * [Chalkboard Infographic](/api/visuals/fcd64907-b103-46f8-9f75-51b9d1a522f5) * [Book Page Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Whiteboard Infographic Generate a whiteboard infographic image based on a detailed text description using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/ae868019-820d-434c-8fe1-74c9da99129a` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ----------------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text at the bottom of the whiteboard. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/ae868019-820d-434c-8fe1-74c9da99129a", "inputs": {}, "prompt": "Create a whiteboard diagram explaining agile methodology", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/ae868019-820d-434c-8fe1-74c9da99129a", "inputs": { "description": "Project Management 101: Plan, Execute, Monitor, Close - The four phases every successful project follows", "footerText": "Save this for later!" }, "render": true } ``` ## Related Templates * [Classroom Chalkboard Infographic](/api/visuals/d9495026-3945-44f6-8b44-07c28c492e6d) * [Chalkboard Infographic](/api/visuals/fcd64907-b103-46f8-9f75-51b9d1a522f5) * [Book Page Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Chalkboard Infographic Generate a chalkboard-style infographic image based on a detailed text description using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/fcd64907-b103-46f8-9f75-51b9d1a522f5` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ----------------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text at the bottom of the chalkboard. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/fcd64907-b103-46f8-9f75-51b9d1a522f5", "inputs": {}, "prompt": "Create a chalkboard infographic about healthy eating habits", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/fcd64907-b103-46f8-9f75-51b9d1a522f5", "inputs": { "description": "The Food Pyramid Reimagined: Vegetables, proteins, whole grains, and healthy fats for optimal nutrition", "footerText": "Share with someone who needs this" }, "render": true } ``` ## Related Templates * [Classroom Chalkboard Infographic](/api/visuals/d9495026-3945-44f6-8b44-07c28c492e6d) * [Whiteboard Infographic](/api/visuals/ae868019-820d-434c-8fe1-74c9da99129a) * [Book Page Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Trail Marker Infographic Generate an infographic carved into a wooden trail marker in a serene nature setting using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/29ebb2bd-02b7-4317-8bb8-c30eb938e47c` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------ | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text carved at the bottom. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/29ebb2bd-02b7-4317-8bb8-c30eb938e47c", "inputs": {}, "prompt": "Create a trail marker about hiking safety tips", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/29ebb2bd-02b7-4317-8bb8-c30eb938e47c", "inputs": { "description": "Leave No Trace: Pack it in, pack it out. Stay on marked trails. Respect wildlife. Preserve nature for future generations", "footerText": "Explore more at NatureTrails.com" }, "render": true } ``` ## Related Templates * [Constellation Infographic](/api/visuals/5307053e-046b-4c9b-b1ca-38725d2ddcdd) * [Cave Painting Infographic](/api/visuals/82ee75b6-597b-43a8-86bc-e4395e7c9c44) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Constellation Infographic Generate a constellation-style infographic on a breathtaking starry night sky, where data points become stars connected by glowing constellation lines. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/5307053e-046b-4c9b-b1ca-38725d2ddcdd` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | -------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text glowing at the horizon. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/5307053e-046b-4c9b-b1ca-38725d2ddcdd", "inputs": {}, "prompt": "Create a celestial map showing the journey of personal growth", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/5307053e-046b-4c9b-b1ca-38725d2ddcdd", "inputs": { "description": "The Constellation of Success: Vision connects to Action, Action connects to Persistence, Persistence leads to Achievement", "footerText": "Reach for the stars" }, "render": true } ``` ## Related Templates * [Trail Marker Infographic](/api/visuals/29ebb2bd-02b7-4317-8bb8-c30eb938e47c) * [Futuristic Flyer](/api/visuals/8fa8545e-8955-4a89-a868-cf45023d6cc5) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Manga Panel Infographic Generate a black and white manga-style panel infographic where characters deliver content through dialogue in classic Japanese comic art style. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/49c61370-a706-4b82-98f7-62d557d1c66d` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ---------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text in the final panel. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/49c61370-a706-4b82-98f7-62d557d1c66d", "inputs": {}, "prompt": "Create a manga explaining how to start a side hustle", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/49c61370-a706-4b82-98f7-62d557d1c66d", "inputs": { "description": "The Art of Productivity: A young professional learns from a wise mentor how to manage time, set priorities, and achieve work-life balance", "footerText": "Follow for more life lessons!" }, "render": true } ``` ## Related Templates * [T-Shirt Infographic](/api/visuals/476f8920-8749-4ff7-9c91-470d54c3c03e) * [Book Page Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) * [Single Centered Text Quote](/api/visuals/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # T-Shirt Infographic Generate an infographic printed on a t-shirt worn by an attractive person using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/476f8920-8749-4ff7-9c91-470d54c3c03e` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ----------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text on the shirt design. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/476f8920-8749-4ff7-9c91-470d54c3c03e", "inputs": {}, "prompt": "Create a graphic tee about coffee culture", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/476f8920-8749-4ff7-9c91-470d54c3c03e", "inputs": { "description": "Code. Sleep. Repeat. The developer lifestyle - debugging by day, dreaming in syntax by night", "footerText": "@DevLife | Wear your passion" }, "render": true } ``` ## Related Templates * [Graffiti Mural Infographic](/api/visuals/3598483b-c148-4276-a800-eede85c1c62f) * [Manga Panel Infographic](/api/visuals/49c61370-a706-4b82-98f7-62d557d1c66d) * [Futuristic Flyer](/api/visuals/8fa8545e-8955-4a89-a868-cf45023d6cc5) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Futuristic Flyer Generate a cyberpunk-inspired futuristic flyer image with neon glow effects, holographic elements, and sci-fi aesthetics using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/8fa8545e-8955-4a89-a868-cf45023d6cc5` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | --------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Flyer topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text with neon styling. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/8fa8545e-8955-4a89-a868-cf45023d6cc5", "inputs": {}, "prompt": "Create a cyberpunk flyer about the future of technology", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/8fa8545e-8955-4a89-a868-cf45023d6cc5", "inputs": { "description": "NEURAL LINK 2077: The future of human-computer interaction. Brain implants, augmented reality, digital consciousness", "footerText": "Join the revolution at CyberTech.io" }, "render": true } ``` ## Related Templates * [Steampunk Infographic](/api/visuals/7b7104f1-d277-4993-ad3a-e5883c4b776d) * [Top Secret Infographic](/api/visuals/b8707b58-a106-44af-bb12-e30507e561af) * [Constellation Infographic](/api/visuals/5307053e-046b-4c9b-b1ca-38725d2ddcdd) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Book Page Infographic Generate an infographic displayed on a giant movie theater screen, photographed from the back rows of a packed cinema audience. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text that appears like movie subtitles. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b", "inputs": {}, "prompt": "Create a cinematic infographic about the history of filmmaking", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/f8f1ebe4-a9f5-4ec8-be63-21214656cd4b", "inputs": { "description": "The Evolution of Cinema: From silent films to streaming, explore 100 years of movie magic and technological innovation", "footerText": "Subscribe for more film history" }, "render": true } ``` ## Related Templates * [TV Wall Infographic](/api/visuals/013904bf-6b3b-43f4-bb1f-f1964a38c29b) * [Newspaper Infographic](/api/visuals/07a5b5c5-387c-49e3-86b1-de822cd2dfc7) * [Breaking News](/api/visuals/8800be71-52df-4ac7-ac94-df9d8a494d0f) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Single Centered Text Quote A simple slideshow with a single centered text quote on a solid background. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0` | | Output Type | Slideshow | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------ | | quotes | array | Yes | - | List of quote strings. Each quote becomes a separate card in the carousel. Min: 1, Max: 20 | | quotes\[] | string | Yes | - | Individual quote text. Length: 10-350 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0", "inputs": {}, "prompt": "Create 5 motivational quotes about perseverance", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0", "inputs": { "quotes": [ "Be careful who you let speak into your life. Not all opinions are qualified.", "People will question your choices...especially the ones too scared to make their own.", "Take advice from people who have receipts, not just opinions.", "Your energy introduces you before you even speak.", "Stop explaining yourself to people who are committed to misunderstanding you." ] }, "render": true } ``` ## Example 3: Single Quote ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/9f4e66cd-b784-4c02-b2ce-e6d0765fd4c0", "inputs": { "quotes": [ "The only way to do great work is to love what you do." ] }, "render": true } ``` ## Related Templates * [Quote Card Monocolor](/api/visuals/77f65d2b-48cc-4adb-bfbb-5bc86f8c01bd) * [Quote Card Paper + Highlight](/api/visuals/f941e306-76f7-45da-b3d9-7463af630e91) * [Book Page Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Steampunk Infographic Generate a steampunk-style infographic image with Victorian-era mechanical aesthetics, clockwork gears, and aged parchment textures using AI image generation. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/7b7104f1-d277-4993-ad3a-e5883c4b776d` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ---------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text on brass nameplate. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/7b7104f1-d277-4993-ad3a-e5883c4b776d", "inputs": {}, "prompt": "Create a steampunk blueprint about the mechanics of time travel", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/7b7104f1-d277-4993-ad3a-e5883c4b776d", "inputs": { "description": "The Automaton's Guide to Productivity: Gears of efficiency, springs of motivation, and the clockwork of daily routines", "footerText": "Crafted by @VictorianInventor" }, "render": true } ``` ## Related Templates * [Futuristic Flyer](/api/visuals/8fa8545e-8955-4a89-a868-cf45023d6cc5) * [Top Secret Infographic](/api/visuals/b8707b58-a106-44af-bb12-e30507e561af) * [Egyptian Hieroglyph Infographic](/api/visuals/a7b0d128-8478-4b34-9647-a0778b6517d0) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Top Secret Infographic Generate a classified government document style infographic image using AI image generation, styled as a top secret briefing laid on a desk. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/b8707b58-a106-44af-bb12-e30507e561af` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | -------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Declassification notice text. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/b8707b58-a106-44af-bb12-e30507e561af", "inputs": {}, "prompt": "Create a classified briefing about the secrets of successful entrepreneurs", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/b8707b58-a106-44af-bb12-e30507e561af", "inputs": { "description": "PROJECT ALPHA: Classified intelligence reveals the 5 hidden habits of high performers. Eyes only. Need to know basis.", "footerText": "Authorized for public release" }, "render": true } ``` ## Related Templates * [Steampunk Infographic](/api/visuals/7b7104f1-d277-4993-ad3a-e5883c4b776d) * [Futuristic Flyer](/api/visuals/8fa8545e-8955-4a89-a868-cf45023d6cc5) * [Newspaper Infographic](/api/visuals/07a5b5c5-387c-49e3-86b1-de822cd2dfc7) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Egyptian Hieroglyph Infographic Generate an ancient Egyptian hieroglyph-style infographic image with carved and painted visuals on sandstone, featuring pharaohs, gods, and hieroglyphic symbols. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/a7b0d128-8478-4b34-9647-a0778b6517d0` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ---------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text carved at the base. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/a7b0d128-8478-4b34-9647-a0778b6517d0", "inputs": {}, "prompt": "Create an Egyptian temple wall about the secrets of ancient wisdom", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/a7b0d128-8478-4b34-9647-a0778b6517d0", "inputs": { "description": "The Wisdom of the Pharaohs: Balance in all things, patience like the Nile, and vision like the Eye of Horus", "footerText": "Blessed by Ra | Share this wisdom" }, "render": true } ``` ## Related Templates * [Cave Painting Infographic](/api/visuals/82ee75b6-597b-43a8-86bc-e4395e7c9c44) * [Steampunk Infographic](/api/visuals/7b7104f1-d277-4993-ad3a-e5883c4b776d) * [Book Page Infographic](/api/visuals/b88c8273-6406-48c6-85e7-096119aefe30) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Cave Painting Infographic Generate a cave painting style infographic image that looks like ancient art on rough stone walls, using earthy pigment colors and primitive hand-drawn elements. ## Template Information | Property | Value | | ----------- | ------------------------------------------------------ | | Template ID | `/video-template/82ee75b6-597b-43a8-86bc-e4395e7c9c44` | | Output Type | Image | | Category | AI-Generated Infographics | ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------------------------------------- | ------------------------------------------------------------------- | | description | string | Yes | 10 Tips for Effective Time Management | Infographic topic and content. Length: 10-500 characters | | footerText | string | Yes | Follow me for more helpful content | Call to action text painted at the bottom. Length: 2-100 characters | ## Example 1: AI-Powered with Prompt ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/82ee75b6-597b-43a8-86bc-e4395e7c9c44", "inputs": {}, "prompt": "Create a prehistoric cave painting about the fundamentals of teamwork", "render": true } ``` ## Example 2: Manual Inputs ```json POST https://backend.blotato.com/v2/videos/from-templates Content-Type: application/json blotato-api-key: YOUR_API_KEY { "templateId": "/video-template/82ee75b6-597b-43a8-86bc-e4395e7c9c44", "inputs": { "description": "Ancient Wisdom: Work together like the hunt, share like the tribe, and celebrate like the fire circle", "footerText": "Pass this knowledge to your clan" }, "render": true } ``` ## Related Templates * [Egyptian Hieroglyph Infographic](/api/visuals/a7b0d128-8478-4b34-9647-a0778b6517d0) * [Trail Marker Infographic](/api/visuals/29ebb2bd-02b7-4317-8bb8-c30eb938e47c) * [Chalkboard Infographic](/api/visuals/fcd64907-b103-46f8-9f75-51b9d1a522f5) ## See Also * [Create Visual API Reference](/api/create-video) * [All Visual Templates](/api/visuals) # Schedule ## Managing Scheduled Posts Scheduled posts are created via [Publish Post](/api/publish-post) using `scheduledTime` or `useNextFreeSlot`. These endpoints let you list, inspect, update, and delete scheduled posts before they publish. To manage the recurring time slots themselves (the calendar grid), see [Schedule Slots](/api/schedule-slots). *** ## List Scheduled Posts ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/schedules` **Method:** `GET` ### Description Returns all scheduled posts for the current user. Only future posts are returned, ordered by scheduled time (ascending). Supports cursor-based pagination. The web app does not have a built-in calendar filter for one brand, account, or page. To build a custom filtered calendar, list scheduled posts with this endpoint, then filter the returned `items` by `account.id`, `account.subaccountId`, `account.subId`, or `account.subaccountName`. ### Query Parameters | Field | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------- | | `limit` | `integer` | No | Number of items per page. Min: 1, Max: 50. Default: 20. | | `cursor` | `string` | No | Pagination cursor from a previous response. | ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "sch_abc123", "scheduledAt": "2026-04-01T14:00:00.000Z", "account": { "id": "98432", "name": "Jane Smith", "username": "janesmith", "profileImageUrl": "https://...", "subaccountId": null, "subId": null, "subaccountName": null }, "draft": { "accountId": "98432", "content": { "text": "Scheduled post content", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } ], "count": "12", "cursor": "eyJzY2hlZHVsZWRBd..." } ``` | Field | Type | Description | | --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | | `items` | `array` | List of scheduled posts | | `items[].id` | `string` | Schedule ID. Use this for get, update, and delete operations. | | `items[].scheduledAt` | `string` | ISO 8601 UTC timestamp for when the post will publish. | | `items[].account` | `object or null` | The target social account. Null if the account was disconnected. | | `items[].draft` | `object` | The post payload. Same structure as the `post` object in [Publish Post](/api/publish-post). | | `count` | `string` | Total number of future scheduled posts. | | `cursor` | `string` | Pagination cursor. Pass this as the `cursor` query parameter to fetch the next page. Absent when there are no more pages. | ### Example ```http GET https://backend.blotato.com/v2/schedules?limit=10 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` With pagination: ```http GET https://backend.blotato.com/v2/schedules?limit=10&cursor=eyJzY2hlZHVsZWRBd... HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` *** ## Get Scheduled Post ### Endpoint **URL:** `/schedules/:id` **Method:** `GET` ### Description Returns a single scheduled post by ID. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | --------------------------------------------------- | | `id` | `string` | Yes | Schedule ID from the List Scheduled Posts endpoint. | ### Response **Status Code:** `200 OK` ```json { "schedule": { "id": "sch_abc123", "scheduledAt": "2026-04-01T14:00:00.000Z", "account": { "id": "98432", "name": "Jane Smith", "username": "janesmith", "profileImageUrl": "https://...", "subaccountId": null, "subId": null, "subaccountName": null }, "draft": { "accountId": "98432", "content": { "text": "Scheduled post content", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } } ``` Returns `404` if the schedule does not exist or belongs to another user. *** ## Update Scheduled Post ### Endpoint **URL:** `/schedules/:id` **Method:** `PATCH` ### Description Update a scheduled post's content, scheduled time, or both. At least one field is required. The scheduled time must be in the future. When the scheduled time changes, the publishing job is re-queued for the new time. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | --------------------------------------------------- | | `id` | `string` | Yes | Schedule ID from the List Scheduled Posts endpoint. | ### Request Body ```json { "patch": { "scheduledTime": "2026-04-05T10:00:00Z", "draft": { "accountId": "98432", "content": { "text": "Updated post content", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } } ``` | Field | Type | Required | Description | | --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `patch.scheduledTime` | `string` | No | New ISO 8601 timestamp. Must be in the future. | | `patch.draft` | `object` | No | Updated post payload. Same structure as the `post` object in [Publish Post](/api/publish-post). When provided, send the full object -- partial updates are not supported. | ### Response **Status Code:** `204 No Content` ### Errors | Status | Reason | | ------ | ----------------------------------------------------------- | | `404` | Schedule not found | | `422` | Empty patch, invalid date, or scheduled time is in the past | ### Examples #### Reschedule to a new time ```json PATCH https://backend.blotato.com/v2/schedules/sch_abc123 HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "patch": { "scheduledTime": "2026-04-05T10:00:00Z" } } ``` #### Update the post text ```json PATCH https://backend.blotato.com/v2/schedules/sch_abc123 HTTP/1.1 Content-Type: application/json blotato-api-key: YOUR_API_KEY { "patch": { "draft": { "accountId": "98432", "content": { "text": "New text for this scheduled post", "mediaUrls": [], "platform": "twitter" }, "target": { "targetType": "twitter" } } } } ``` #### Reschedule to the next available slot The update endpoint does not accept `useNextFreeSlot`. To move a post to the next available slot, first call [Find Next Available Slot](/api/schedule-slots#find-next-available-slot), then pass the returned time as `scheduledTime`: ``` 1. POST /v2/schedule/slots/next-available Body: { "platform": "twitter", "accountId": "98432" } Response: { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } } 2. PATCH /v2/schedules/sch_abc123 Body: { "patch": { "scheduledTime": "2026-04-02T09:00:00Z" } } ``` *** ## Delete Scheduled Post ### Endpoint **URL:** `/schedules/:id` **Method:** `DELETE` ### Description Delete a scheduled post and cancel its publishing job. This action cannot be undone. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | --------------------------------------------------- | | `id` | `string` | Yes | Schedule ID from the List Scheduled Posts endpoint. | ### Response **Status Code:** `204 No Content` ### Example ```http DELETE https://backend.blotato.com/v2/schedules/sch_abc123 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` # Schedule Slots Schedule slots define the recurring time windows in your content calendar. When you publish a post with `useNextFreeSlot: true`, Blotato picks the next open slot matching the target platform and queues the post at that time. To manage the posts queued in those slots, see [Schedules](/api/schedules). ## How Slots and Schedules Work Together 1. **Slots** define your posting cadence -- for example, "every Monday at 9:00 AM UTC for Twitter." 2. When you publish a post with `useNextFreeSlot: true` (see [Publish Post](/api/publish-post)), Blotato finds the next slot that matches the target platform and account, and schedules the post at that time. 3. A slot is "occupied" when a scheduled post is already queued at that time. The next call to `useNextFreeSlot` skips occupied slots and picks the next open one. 4. You manage what is queued (the **schedules**) and when things are queued (the **slots**) separately. *** ## List Slots ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/schedule/slots` **Method:** `GET` ### Description Returns all scheduling slots for the current user. ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "slot_1", "hour": 9, "minute": 0, "day": "monday", "selectedTargets": [ { "platform": "twitter", "accountId": "98432", "subaccountId": null } ] }, { "id": "slot_2", "hour": 14, "minute": 30, "day": "wednesday", "selectedTargets": [ { "platform": "instagram", "accountId": "98434", "subaccountId": null }, { "platform": "linkedin", "accountId": "98435", "subaccountId": null } ] } ] } ``` | Field | Type | Description | | ---------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- | | `items[].id` | `string` | Slot ID | | `items[].hour` | `integer` | Hour in UTC (0-23) | | `items[].minute` | `integer` | Minute (0-59) | | `items[].day` | `string` | Day of week: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` | | `items[].selectedTargets` | `array` | Platforms and accounts this slot applies to | | `items[].selectedTargets[].platform` | `string` | Platform name | | `items[].selectedTargets[].accountId` | `string or null` | Account ID. Null means the slot applies to all accounts on that platform. | | `items[].selectedTargets[].subaccountId` | `string or null` | Subaccount ID (for Facebook Pages / LinkedIn Company Pages). | *** ## Create Slots ### Endpoint **URL:** `/schedule/slots` **Method:** `POST` ### Description Create one or more scheduling slots. Each slot defines a day, time (in UTC), and which platforms/accounts it applies to. Returns an error if a slot at the same day and time already exists. ### Request Body ```json { "slots": [ { "hour": 9, "minute": 0, "day": "monday", "selectedTargets": [ { "platform": "twitter", "accountId": "98432", "subaccountId": null } ] } ] } ``` | Field | Type | Required | Description | | ------------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `slots` | `array` | Yes | Array of slots to create | | `slots[].hour` | `integer` | Yes | Hour in UTC (0-23) | | `slots[].minute` | `integer` | Yes | Minute (0-59) | | `slots[].day` | `string` | Yes | Day of week (e.g., `monday`) | | `slots[].selectedTargets` | `array` | Yes | Platforms and accounts. Set `accountId` to `null` for a slot that applies to all accounts on that platform. | ### Response **Status Code:** `201 Created` Returns the created slots with their generated IDs. *** ## Update Slot Targets ### Endpoint **URL:** `/schedule/slots/:id` **Method:** `PATCH` ### Description Replace the selected targets for a slot. Send the full list of targets -- this is a full replacement, not a partial update. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | ----------- | | `id` | `string` | Yes | Slot ID | ### Request Body ```json { "patch": { "selectedTargets": [ { "platform": "twitter", "accountId": "98432", "subaccountId": null }, { "platform": "instagram", "accountId": "98434", "subaccountId": null } ] } } ``` ### Response **Status Code:** `204 No Content` *** ## Delete Slot ### Endpoint **URL:** `/schedules/slots/:id` **Method:** `DELETE` ### Description Delete a scheduling slot. If posts are scheduled using this slot in the future, the delete fails. Delete the scheduled posts first (see [Schedules](/api/schedules)), then delete the slot. Past scheduled posts linked to this slot are cleaned up automatically. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | ----------- | | `id` | `string` | Yes | Slot ID | ### Response **Status Code:** `204 No Content` ### Errors | Status | Reason | | ------ | -------------------------------------------------------------------- | | `400` | Slot has future scheduled content. Delete the scheduled posts first. | *** ## Find Next Available Slot ### Endpoint **URL:** `/schedule/slots/next-available` **Method:** `POST` ### Description Find the next available (unoccupied) slot for a given platform and account. Returns the slot ID and the UTC time of the next open slot. Use this when you want to reschedule a post to the next free slot via the [Update Schedule](/api/schedules#update-scheduled-post) endpoint, since that endpoint accepts `scheduledTime` but not `useNextFreeSlot`. ### Request Body ```json { "platform": "twitter", "accountId": "98432", "subaccountId": null } ``` | Field | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------------------------------------- | | `platform` | `string` | Yes | Platform name | | `accountId` | `string` | No | Account ID. Omit to match slots for all accounts on the platform. | | `subaccountId` | `string` | No | Subaccount ID for Facebook Pages / LinkedIn Company Pages. | ### Response **Status Code:** `201 Created` ```json { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } } ``` | Field | Type | Description | | --------------- | -------- | ---------------------------------------------------------- | | `slot.slotId` | `string` | The slot that was matched | | `slot.slotTime` | `string` | ISO 8601 UTC time of the next open occurrence of this slot | Returns `400` if no slots are configured for the given platform/account. # Source Submit content for extraction and receive a source ID for polling. ## Endpoint ``` POST https://backend.blotato.com/v2/source-resolutions-v3 ``` **Rate Limit:** 30 requests / minute ## Authentication Include your Blotato API key in the request headers: ``` blotato-api-key: YOUR_API_KEY ``` ## Source Types | Value | Requires | Description | | ------------------ | -------- | -------------------------------------------------------- | | `youtube` | `url` | Extract YouTube transcript (English captions only) | | `tiktok` | `url` | Extract TikTok transcript (English captions only) | | `article` | `url` | Extract article text from a web page | | `pdf` | `url` | Extract text from a PDF | | `audio` | `url` | Transcribe audio (mp3, wav, m4a, ogg, flac, aac) | | `twitter` | `url` | Extract tweet content | | `text` | `text` | Transform raw text content with optional AI instructions | | `perplexity-query` | `text` | AI-powered web research query | ## Parameters | Parameter | Type | Required | Description | | -------------------- | ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------- | | `source.sourceType` | string | Yes | One of: `youtube`, `tiktok`, `article`, `pdf`, `audio`, `twitter`, `text`, `perplexity-query` | | `source.url` | string | Required for URL-based types | The URL to extract content from | | `source.text` | string | Required for `text` and `perplexity-query` | Raw text or search query | | `customInstructions` | string | No | AI instructions to transform extracted content | ## Examples ### Extract YouTube Transcript ```json { "source": { "sourceType": "youtube", "url": "https://www.youtube.com/watch?v=VIDEO_ID" } } ``` YouTube and TikTok transcript extraction reads **English captions only**. A non-English video, or a video with no captions, returns a `failed` status. For those videos, pass the transcript or a summary using `sourceType: "text"` instead. ### Extract Article with Custom Instructions ```json { "source": { "sourceType": "article", "url": "https://example.com/article" }, "customInstructions": "Summarize in 5 bullet points" } ``` ### AI Research Query ```json { "source": { "sourceType": "perplexity-query", "text": "latest AI trends in social media marketing" } } ``` ### Transform Raw Text ```json { "source": { "sourceType": "text", "text": "Your raw content here..." }, "customInstructions": "Rewrite as a Twitter thread" } ``` ## Response ```json { "id": "123e4567-e89b-12d3-a456-426614174000" } ``` Use this ID with the [Get Source](/api/create-source/get-source) endpoint to retrieve the extracted content. ## n8n and Make.com In the official Blotato nodes: 1. Add a Blotato node 2. Select "Source" > "Create" 3. Choose your source type 4. Pass the output source ID to a "Get Source" node to retrieve content # Get Source Retrieve extracted content by source ID. ## Endpoint ``` GET https://backend.blotato.com/v2/source-resolutions-v3/:id ``` ## Authentication Include your Blotato API key in the request headers: ``` blotato-api-key: YOUR_API_KEY ``` ## Parameters | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | -------------------------------------------------- | | `id` | string | Yes | The source resolution ID (UUID) from Create Source | | `cleanTranscript` | boolean | No | Remove timestamps from transcripts. Default: true | ## Clean Transcript Option When `cleanTranscript` is enabled (default), the response removes: * VTT/SRT timestamp lines * Sequence numbers * Markdown formatting * Extra whitespace This makes transcripts easier to use for content repurposing. ## Response ### Processing (poll again) ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "status": "processing" } ``` ### Completed ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "status": "completed", "title": "Video Title", "content": "Extracted text content...", "referenceUrl": "https://original-source-url.com" } ``` ### Failed ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "status": "failed", "message": "Error description" } ``` ## Status Values | Status | Description | | ------------ | ---------------------------------------- | | `queued` | Source submitted, waiting to process | | `processing` | Extraction in progress | | `completed` | Extraction successful, content available | | `failed` | Extraction failed, check message field | ## Polling Pattern Source extraction is asynchronous. After calling Create Source: 1. Wait 2-5 seconds 2. Call Get Source with the ID 3. If status is `queued` or `processing`, wait and retry 4. If status is `completed`, use the `content` field 5. If status is `failed`, check the `message` field ## n8n and Make.com In the official Blotato nodes: 1. Add a Blotato node 2. Select "Source" > "Get" 3. Pass in the source ID from "Create Source" 4. Add a Wait node (5-10 seconds) between Create and Get for longer content 5. The extracted content appears in the response # Automation Templates
TitleDescriptionCover image
11 Build Your First AI AutomationThe best starting point for anyone new to building automations. Learn how to extract content from YouTube, TikTok, articles, or PDFs using the Source nodes, then publish to social media./pages/V92yhead21w9sJMb1Zqf
1 Post EverywhereThis automation publishes to 9 social platforms daily! Manage your content in a simple Google Sheet. When you set a post's status to "Ready to Post" in your Google Sheet, this workflow grabs your image/video from your Google Drive, posts your content to 9 social platforms, then updates the Google Sheet post status to "Posted"./pages/gUqSC5IkZeuVZjo9ZFX1/files/tHVpGQJZTe2WglPwUhXy
2 Email to Long-Form ThreadSend an email to yourself with a rough idea you want to post about, then ChatGPT will clean it up, apply a viral thread template, and Blotato will post it on your socials as a long-form thread./pages/qmLOXpcNi91XgnGNR6XY/files/cEABD9HKmdQyY7rhTCXf
Hackernews to AI Clone VideosThis fully automated AI Avatar Social Media system that creates talking head AI clone videos, WITHOUT having to film or edit yourself. It combines n8n, AI agent, HeyGen, and Blotato to research, create, and distribute talking head AI clone videos to every social media platform every single day./pages/mUD927Nc6j70tTer6nEY/files/XSxCGBqKDQujck4avJZQ
4 Viral News to AI Avatar VideosThis fully automated AI Avatar Viral News system researches the latest trending news in your niche or industry, then generates talking head AI clone videos, WITHOUT having to film or edit yourself. It combines ChatGPT, Perplexity, HeyGen, and Blotato to research, create, and auto-post talking head AI avatar videos to every social media platform, every single day./pages/8t1mZoBaolJUFrUHAwA8/files/H3Ej0Ru3vE6RnAqOh6k4
5 Automate Instagram Carousels with AI ChatThis AI Agent Carousel Maker uses ChatGPT and Blotato to write, generate, and auto-post social media carousels to 5 social platforms: Instagram, Tiktok, Facebook, Twitter, and Pinterest. Simply chat with the AI agent, confirm which prebuilt viral carousel template you want to use, then the AI Agent populates the template with your personalized information and quotes, and posts to social media on autopilot./pages/LmfxmlWKorC64bUUG0ZR/files/J331MuOMaXxGh7RisedN
7 Clone Viral Reels with AI AvatarClone viral Instagram Reels into your own branded AI avatar video, WITHOUT having to film or edit yourself. It combines content analysis, script rewriting, and HeyGen AI avatars to download reels, write scripts tailored to your industry / use case, and captions into a short 30-second format, regenerate the video with your chosen avatar and voice, and automatically post across every major social media platform./pages/HoqZBZSsL9Op35fsziBX/files/WsxQk1Cp3AcdlJikPLSy
8 Repurpose Tiktoks On AutopilotThis automation detects when you post a Tiktok video, automatically downloads the video without watermark, stores it in Google Drive, and reposts your Tiktok video to other social media platforms. All on autopilot. So you can grow your presence on multiple platforms, without more work./pages/vD8XqxQRMx6jHl67HPsA/files/uksK1n4XBVvfKsViPavf
9 Repurpose Tiktoks into Carousels and ThreadsThis automation detects when you post a Tiktok video, automatically downloads the video without watermark, stores it in Google Drive, and reposts your Tiktok video to other social media platforms, including converting it into a carousel for Instagram and a long-form thread for X/Twitter, Bluesky, and Threads. There is also a human-in-the-loop email approval step before reposting to Linkedin../pages/Alclh3HHvPxN3SNdByYv/files/k7UYDZWghjZuKOzmM65f
10 Gamma TemplatesYou can now use Gamma to create presentations and social media carousels, using your own custom branded template, then post them automatically on social media!/pages/Alclh3HHvPxN3SNdByYv/files/MCCSgwNNSzeN4iZR39rh
# 11 Build Your First AI Automation This beginner-friendly template shows you how to extract content from any source (YouTube, TikTok, articles, PDFs) and publish it to social media. ## What You'll Learn * How to use the Create Source node to extract content * How to use the Get Source node to retrieve extracted content * How to transform content with custom instructions * How to create visuals and publish to multiple platforms ## Video Tutorial {% embed url="" %} ## Prerequisites 1. Blotato API key ([get one here](https://my.blotato.com/settings)) 2. n8n or Make.com account 3. Social accounts connected in Blotato ## Workflow Overview This automation: 1. Takes a YouTube URL as input 2. Extracts the transcript using Create Source 3. Waits for processing 4. Retrieves the content using Get Source 5. Creates visuals (videos, carousels) with Blotato 6. Publishes to your connected platforms ## Step-by-Step Setup ### Step 1: Add Create Source Node 1. Add a Blotato node to your workflow 2. Select "Source" > "Create" 3. Set Source Type to "URL" 4. Enter your YouTube URL ### Step 2: Add Wait Node 1. Add a Wait node after Create Source 2. Set wait time to 10 seconds (adjust for longer videos) ### Step 3: Add Get Source Node 1. Add another Blotato node 2. Select "Source" > "Get" 3. Pass the source ID from Step 1 4. Enable "Clean Transcript" to remove timestamps ### Step 4: Add Create Visual Node 1. Add a Blotato node 2. Select "Visual" > "Create" 3. Choose a template (carousel, slideshow, or video) 4. Pass the extracted content as the script or text input ### Step 5: Add Publish Node 1. Add a Blotato node 2. Select "Post" > "Publish" 3. Select your target platform 4. Pass the visual URL from Step 4 ## Tips * Start with short YouTube videos (under 5 minutes) for faster testing * Use custom instructions in Create Source to pre-process content * Increase wait time for longer videos or PDFs * Check your [API Dashboard](https://my.blotato.com/api-dashboard) if extraction fails ## Source Types You Can Use | Source Type | Examples | | ----------- | ----------------------------- | | YouTube | Video transcripts | | TikTok | Video transcripts | | Articles | Blog posts, news articles | | PDFs | Ebooks, research papers | | Audio | Podcasts, meeting recordings | | Text | Raw text you paste in | | AI Research | Perplexity-powered web search | ## Next Steps Once you're comfortable with this basic flow: * Explore the [1 Post Everywhere](/api/templates/1-post-everywhere) template for multi-platform posting * Try [AI Clone Videos](/api/templates/3-hackernews-to-ai-clone-videos) for automated avatar videos * Check [Faceless Videos](/api/n8n/n8n-faceless-videos) for AI-generated video content # 1 Post Everywhere ### Description This automation publishes to 9 social platforms daily! Manage your content in a simple Google Sheet. When you set a post's status to "Ready to Post" in your Google Sheet, this workflow grabs your image/video from Google Drive, posts to 9 social platforms, then updates the post status to "Posted". ### Platforms
n8nMakeZapier
truetruefalse
### Templates ### Tutorials {% embed url="" %} ### Overview Here’s how the automation works: **1. Trigger: Check Every 3 Hours** * Check Google Sheet for posts with Status "Ready to Post" * Return 1 post that is ready to go **2. Publish to Social Media via Blotato** * Pass your image/video URL directly to the Publish node - no upload step required Note: The original YouTube tutorial shows an UPLOAD node, but this step is no longer required. Pass your image/video URLs directly into the `mediaUrls` parameter in the Publish node. **3. Connect Your Social Accounts** * Connect your Blotato account * Choose your social accounts * Either post immediately or schedule for later * Includes support for images, videos, slideshows, carousels, and threads ### Setup * Sign up for Blotato.com * Generate Blotato API Key by going to Settings > API > Generate API Key (paid feature only) * [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) * Create credential for Blotato. * Connect your Google Drive to n8n: * Copy this sample Google Sheet. Do NOT change the column names, unless you know what you're doing: * Make your Google Drive folder containing images/videos PUBLIC (i.e. Anyone with the link) * Complete the 3 setup steps shown in BROWN sticky notes in this template The templates run every 3 hours, which you can customize. It checks Google Sheets for rows where Status is “Ready to Post”, and return only the first matching row. This avoids spamming too many posts at the same time. ### General Troubleshooting Checklist * your Google Drive is public * column names in your Google Sheet match the original example * file size < 60MB; for large files, Google Drive does not work, use Amazon S3 instead ### Tips & Tricks You can pair this workflow with another automation that populates your Google Sheet and drops media into your Google Drive folder, so that you have a human-in-the-loop quality review check allowing you to edit content before posting. This is the approach I always advise, especially for beginner creators, as you want to ensure you’re sharing high-quality content. Prepare a batch of rows with Status set to “In Progress” which means you’re still working on the content. Switch 1 row to “Ready to Post” when the ready to test posting. The workflow processes 1 row per run, then checks again on the next schedule. Scale by adjusting the schedule interval. Shorter intervals increase throughput. Longer intervals spread posts out. For issues, review the [Blotato API dashboard](https://my.blotato.com/api-dashboard) request log and payload because it contains all error messages. Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 2. If a template shows question marks instead of the Blotato logo, install the Blotato node first, then re-import the template. 3. Create a new Credential in n8n. Go to Blotato Settings > API > Copy API Key. Paste the API key in n8n, save, test, then select this credential on Blotato nodes. 4. Connect social accounts on each platform node. Open each Blotato Publish node, select the Blotato credential, then pick Tiktok, Linkedin, Facebook Page, Instagram, X, Youtube, Threads, Bluesky, or Pinterest. For Pinterest, add the Board ID. In Blotato, create a sample Pinterest post, click Schedule, choose a board, and copy the Board ID from the dropdown. 5. When testing, deactivate all social platform nodes. Activate just 1 to start with. Run the workflow, then Pin data at the Blotato Publish node. This locks inputs for repeat tests. Then, execute 1 platform node from pinned data to validate it works. Activate other social platforms to continue testing. 6. Use the [Blotato API dashboard](https://my.blotato.com/api-dashboard) to review each request, payload, and error message. ### Make Notes 1. Open the scenario and set the schedule at the bottom bar to run every 3 hours, or 180 minutes, as a safe starting point. 2. Connect to your Google Sheet and query rows where Status is “Ready to Post”. Limit to 1 row returned to avoid spamming. 3. Create a Blotato connection, choose each platform, then select your target social media account. Advanced parameters exist for slideshows, music, and other options, though your 1st run needs no changes. For Pinterest, remember to add your Board ID. 4. When testing, make sure to “Disable Route” to all social platform modules. Enable just 1 route to start with. If it’s successful, then activate other social platforms one at a time to continue testing. ### Zapier Notes n/a # 2 Email to Long Form Thread ### Description Send an email to yourself with a rough idea you want to post about, then ChatGPT will clean it up, apply a viral thread template, and Blotato will post it on your socials as a long-form thread. ### Platforms
n8nMakeZapier
truetruefalse
### Templates ### Tutorials {% embed url="" %} ### Overview Here’s how the automation works: **1. Trigger: Gmail** * Connect your Gmail account * This node will monitor emails sent from you and filter emails with subject containing the word “thread” **2. ChatGPT Writes Threads** * Connect your OpenAI account * This node prompts ChatGPT to write a long-form thread **3. Publish to Social Media via Blotato** * Connect your Blotato account * Choose your social accounts (Twitter, Threads, Bluesky) * Either schedule the thread later or post immediately * Includes support for optional image/video URLs ### Prerequisites 1. Sign up for [Blotato.com](https://www.blotato.com/) 2. Generate Blotato API Key by going to Settings > API > Generate API Key (paid feature only) 3. If you're using n8n, [install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 4. Make sure you have a Gmail account 5. Make sure you have an [OpenAI Platform](https://platform.openai.com/docs/overview) account to access ChatGPT. 6. Think of a topic you want to write about it and send an email yourself, making sure you use Gmail. It doesn’t need to be neatly formatted. I personally use Superwhispr to talk through my ideas, then AI cleans up the transcript automatically. Many folks find “talking” to be the fastest form of content creation vs. writing, so try it out! 1. Make sure your subject line contains the word: **“thread”** 2. Here’s an example… Subject: **thread** Body: > I'm obsessed with voice AI apps. Super Whisper is my current favorite because it runs locally and keeps my voice data private. I talk to it instead of typing. Way faster. ### Tips & Tricks I opted to use a Gmail trigger for this tutorial because it’s free, easy to setup, and ubiquitous. No fiddling around with bots, secrets, etc. But many of you will want to swap out Gmail for Whatsapp, Slack, or Telegram. There’s no issue doing so; everything still works the same. During testing, use “Scheduled Time” when posting via Blotato instead of immediate posting. That way you can preview before going live and spamming test posts. You can attach images or videos to individual tweets in the thread. The \`mediaUrls\` array takes a string of publicly accessible image/video URLs. This is more advanced, so I’ll showcase this in a future template. But if you know what you’re doing, insert your image/video URLs in to the \`mediaUrls\` array. To tweak the writing style further, provide examples of your favorite viral threads to help ChatGPT emulate structure and tone. There’s already a long prompt that shows 1 example viral thread; simply replace it with your preferred thread. If you need help troubleshooting your automation: * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to my.blotato.com and click the ORANGE BUTTON in the bottom right corner to send me a support message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 2. If a template shows question marks instead of the Blotato logo, install the Blotato node first, then re-import the template. 3. Create a new Credential in n8n. Go to Blotato Settings > API > Copy API Key. Paste the API key in n8n, save, test, then select this credential on Blotato nodes. 4. Connect social accounts on each platform node. Open each Blotato Publish node, select the Blotato credential, then pick your social account. 5. When testing, deactivate all social platform nodes. Activate just 1 to start with. Run the workflow, then Pin data at the Blotato Publish node. This locks inputs for repeat tests. Then, execute 1 platform node from pinned data to validate it works. Activate other social platforms to continue testing. 6. Use the [Blotato API dashboard](https://my.blotato.com/api-dashboard) to review each request, payload, and error message. ### Make Notes 1. Create a Blotato connection, choose each platform, then select your target social media account. 2. When testing, make sure to “Disable Route” to all social platform modules. Enable just 1 route to start with. If it’s successful, then activate other social platforms one at a time to continue testing. ### Zapier Notes n/a # 3 Hackernews to AI Clone Videos ### Description This fully automated AI Avatar Social Media system that creates talking head AI clone videos, WITHOUT having to film or edit yourself. It combines n8n, AI agent, HeyGen, and Blotato to research, create, and distribute talking head AI clone videos to every social media platform every single day. ### Platforms
n8nMakeZapier
truefalsefalse
### Templates ### Tutorials {% embed url="" %} ### Overview Here’s how the automation works: 1. **Trigger: Schedule** * Configured to run once daily at 10am 2. **AI News Research** * Research viral news from tech-focused forum, Hackernews * Fetch the selected news item, plus discussion comments 3. **AI Writer** * AI writes 30-second monologue script * AI writes short video caption 4. **Create Avatar Video** * Call Heygen API (requires paid API plan), specifying your avatar ID and voice ID * Create avatar video, optionally passing in an image/video background if you have a green screen avatar (matte: true) 5. **Get Video** * Wait awhile, then fetch completed avatar video 6. **Publish to Social Media via Blotato** * Pass the video URL directly to the Blotato Publish node - no upload step required * Connect your Blotato account * Choose your social accounts * Either post immediately or schedule for later ### Prerequisites 1. Sign up for [Blotato.com](https://www.blotato.com/) 2. Generate Blotato API Key by going to Settings > API > Generate API Key (paid feature only) 3. If you're using n8n, [install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 4. Sign up for Heygen * Paste your Heygen API key * Paste your Heygen avatar ID * Paste your Heygen voice ID * If you want to pass in an optional background video as a green screen effect, use the 2nd agnt `background_video_url` that is already filled out (change it later, after ensuring everything works) ### Tips & Tricks While testing: enable only 1 social platform, and deactivate the rest for testing purposes. Update the AI agent node’s prompt to return a 5-second script, rather than 30 seconds, to reduce the processing duration. Go to Heygen and check that your avatar video is being processed. After the workflow finishes, check your social media account for the final post. If successful, then enable another social media node, and continue testing. If you need help troubleshooting your automation: * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to my.blotato.com and click the ORANGE BUTTON in the bottom right corner to send me a support message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 2. If a template shows question marks instead of the Blotato logo, install the Blotato node first, then re-import the template. 3. Create a new Credential in n8n. Go to Blotato Settings > API > Copy API Key. Paste the API key in n8n, save, test, then select this credential on Blotato nodes. 4. Connect social accounts on each platform node. Open each Blotato Publish node, select the Blotato credential, then pick your social account. 5. When testing, deactivate all social platform nodes. Activate just 1 to start with. Run the workflow, then Pin data at the Blotato Publish node. This locks inputs for repeat tests. Then, execute 1 platform node from pinned data to validate it works. Activate other social platforms to continue testing. 6. Use the [Blotato API dashboard](https://my.blotato.com/api-dashboard) to review each request, payload, and error message. ### Make Notes 1. Create a Blotato connection, choose each platform, then select your target social media account. 2. When testing, make sure to “Disable Route” to all social platform modules. Enable just 1 route to start with. If it’s successful, then activate other social platforms one at a time to continue testing. ### Zapier Notes n/a ### FAQs #### How do I get captions on my Heygen avatar video? You'll need to change 2 steps: 1. In the CREATE HEYGEN VIDEO step, there is a setting to enable captions. Make sure it's turned on. 2. In the Blotato Publish step, pass the `video_url_caption` from the GET VIDEO step into the mediaUrls parameter. This will use the video version with captions. Remember to test your workflow after making this change to make sure everything works as expected. #### How do I make my HeyGen avatar videos look more stylized? Use Blotato's CREATE VISUAL node to enhance your HeyGen videos: 1. **Combine Existing Clips template**: Adds a stylized title and captions to your video 2. **Avatar video with b-roll template**: Generates relevant b-roll images based on your script In n8n or Make, add a Blotato node after you receive your HeyGen video, select "Visual" > "Create", then choose one of these templates. # 4 Viral News to AI Avatar Videos ### Description This fully automated AI Avatar Viral News system researches the latest trending news in your niche or industry, then generates talking head AI clone videos, WITHOUT having to film or edit yourself. It combines ChatGPT, Perplexity, HeyGen, and Blotato to research, create, and auto-post talking head AI avatar videos to every social media platform, every single day. ### Platforms
n8nMakeZapier
truefalsefalse
### Templates ### Tutorials {% embed url="" %} ### Overview Here’s how the automation works: **1. Trigger: Schedule** * Configured to run once daily at 10am **2. AI Researcher** * Call Perplexity to research the top 10 latest news in your industry * Select news story most likely to go viral * Compile detailed factual report on selected news story **3. AI Writer** * AI writes monologue script, video caption, and short title **4. Create Avatar Video** * Call Heygen API (requires paid API plan), specifying your avatar ID and voice ID * Create avatar video, optionally passing in an image/video background if you have a green screen avatar **5. Get Video** * Wait awhile, then fetch completed avatar video **6. Publish to Social Media via Blotato** * Pass the video URL directly to the Blotato Publish node - no upload step required * Connect your Blotato account * Choose your social accounts * Either post immediately or schedule for later ### Prerequisites 1. Sign up for Perplexity: * Setup your API Billing. * Generate your API Key: 2. Sign up for Heygen: * Create your avatar. * Paste your Heygen API key. * Paste your Heygen avatar ID. * Paste your Heygen voice ID. * If you want a background image/video behind your avatar: (1) ensure you have an avatar with background removed which requires a higher tier plan; (2) open SETUP HEYGEN node and set parameter 'has\_background\_video' to \`true\`; (3) open SETUP HEYGEN node and replace video URL in parameter 'background\_video\_url'. I only recommend doing this AFTER the full workflow is operational. 3. Sign up for [Blotato.com](https://www.blotato.com/) * Generate Blotato API Key by going to Settings > API > Generate API Key (paid feature only). * If you're using n8n, [install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) ### Tips & Tricks While testing: enable only 1 social platform, and deactivate the rest for testing purposes. Update the AI writer prompt to return a 5-second script, rather than 30 seconds, to reduce the processing duration. Go to Heygen and check that your avatar video is being processed. After the workflow finishes, check your social media account for the final post. If successful, then enable another social media node, and continue testing. If you need help troubleshooting your automation: * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to my.blotato.com and click the ORANGE BUTTON in the bottom right corner to send me a support message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 2. If a template shows question marks instead of the Blotato logo, install the Blotato node first, then re-import the template. 3. Create a new Credential in n8n. Go to Blotato Settings > API > Copy API Key. Paste the API key in n8n, save, test, then select this credential on Blotato nodes. 4. Connect social accounts on each platform node. Open each Blotato Publish node, select the Blotato credential, then pick your social account. 5. When testing, deactivate all social platform nodes. Activate just 1 to start with. Run the workflow, then Pin data at the Blotato Publish node. This locks inputs for repeat tests. Then, execute 1 platform node from pinned data to validate it works. Activate other social platforms to continue testing. 6. Use the [Blotato API dashboard](https://my.blotato.com/api-dashboard) to review each request, payload, and error message. ### Make Notes n/a ### Zapier Notes n/a ### FAQs #### How do I get captions on my Heygen avatar video? You'll need to change 2 steps: 1. In the CREATE HEYGEN VIDEO step, there is a setting to enable captions. Make sure it's turned on. 2. In the Blotato Publish step, pass the `video_url_caption` from the GET VIDEO step into the mediaUrls parameter. This will use the video version with captions. Remember to test your workflow after making this change to make sure everything works as expected. # 5 Automate Instagram Carousels with AI Chat ### Description This AI Agent Carousel Maker uses ChatGPT and Blotato to write, generate, and auto-post social media carousels to 5 social platforms: Instagram, Tiktok, Facebook, Twitter, and Pinterest. Simply chat with the AI agent, confirm which prebuilt viral carousel template you want to use, then the AI Agent populates the template with your personalized information and quotes, and posts to social media on autopilot. This is perfect for entrepreneurs, small businesses, content creators, digital marketing agencies, social media marketing agencies, and influencers. ### Platforms
n8nMakeZapier
truefalsefalse
### Templates ### Tutorials {% embed url="" %} ### Overview Here’s how the automation works: **1. Chat: AI Agent Carousel Maker** * Chat with AI agent about your desired carousel * Confirm quotes and carousel template to use **2. Carousel Generation** * AI agent calls corresponding Blotato tool to generate carousel * Wait and fetch completed carousel **3. Publish to Social Media via Blotato** * Choose your social accounts * Either post immediately or schedule for later ### Setup * Sign up for OpenAPI API access and create credential * Sign up for Blotato.com * Generate Blotato API Key by going to Settings > API > Generate API Key (paid feature only) * Create Blotato credential * If you're using n8n, [install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) * Click ""Open chat"" to test workflow * Complete SETUP sticky notes in BROWN in this template * AFTER your first successful run, open each carousel template tool call (i.e. pink nodes attached to AI Agent Carousel Maker) and tweak the parameters, but DO NOT change ""quotes"" parameter unless you're an n8n expert. ### Tips & Tricks * While testing: enable only 1 social platform, and deactivate the rest for testing purposes. Add optional parameter 'scheduledTime' so that you don't accidentally post to social media. Check your content calendar here: * Check how your carousels look in Blotato app: * You can browse all video/carousel templates and get a sense of how they work by making them in the Blotato web app first: * When adding a new template, DO NOT duplicate an existing node. Instead, click '+ Tool' > Blotato Tool > Video > Create > select new template. This ensures template parameters are correctly loaded. ### Troubleshooting * View all video/carousel templates available: * DO NOT edit the 'quotes' parameter unless you're an n8n expert * When adding a new template, DO NOT duplicate an existing node. Instead, click '+ Tool' > Blotato Tool > Video > Create > select new template. This ensures template parameters are correctly loaded. If you need help troubleshooting your automation: * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to my.blotato.com and click the ORANGE BUTTON in the bottom right corner to send me a support message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 2. If a template shows question marks instead of the Blotato logo, install the Blotato node first, then re-import the template. 3. Create a new Credential in n8n. Go to Blotato Settings > API > Copy API Key. Paste the API key in n8n, save, test, then select this credential on Blotato nodes. 4. Connect social accounts on each platform node. Open each Blotato Publish node, select the Blotato credential, then pick your social account. 5. When testing, deactivate all social platform nodes. Activate just 1 to start with. Run the workflow, then Pin data at the Blotato Publish node. This locks inputs for repeat tests. Then, execute 1 platform node from pinned data to validate it works. Activate other social platforms to continue testing. 6. Use the [Blotato API dashboard](https://my.blotato.com/api-dashboard) to review each request, payload, and error message. ### Make Notes n/a ### Zapier Notes n/a ### FAQs #### How do I request new carousel templates? Contact Sabrina via in-app chat in the bottom right corner with an example of your desired carousel template, desired inputs, and any other helpful information. # 7 Clone Viral Reels with AI Avatar ### Description This fully automated AI Avatar Reel Repurposing system lets you take any Instagram Reel and instantly transform it into your own branded AI avatar video, WITHOUT having to film or edit yourself. It combines content analysis, script rewriting, and HeyGen AI avatars to download reels, rewrite scripts and captions into a short 30-second format, regenerate the video with your chosen avatar and voice, and automatically post across every major social media platform including Instagram, TikTok, YouTube, Facebook, LinkedIn, Pinterest, Twitter/X, and Threads. Everything runs end-to-end in the background, so you only paste a link, and the system handles downloading, rewriting, recording, and publishing your content every single day. ### Platforms
n8nMakeZapier
truetruefalse
### Templates ### Tutorials #### n8n {% embed url="" %} #### Make {% embed url="" %} * Make template does not automatically check if your Airtable record has a background URL. Instead, it will create a Heygen avatar video WITHOUT a background. * If you want to create avatar videos with an image or video background, edit the CREATE VIDEO module as follows: * enable parameter `matting` to yes * scroll down and select `background type` * select image or video background * drop in `backgroundUrl` variable from Airtable ### Overview Here’s how the automation works: **1. Trigger: Airtable Input** \* Paste the Instagram Reel link into the \`ReelURL\` column (optional: add a \`BackgroundURL\`). **2. Reel Processing** \- Transcribe the Reel audio \- Rewrite into \~30 seconds of spoken text \- Generate SEO-optimized caption \- Create a viral overlay sentence for attention, that can be used as the title **3. Trigger 2: Human Approval** \- Edit or approve the Script, Caption, and Overlay in Airtable \- Check the \`Approved\` box to confirm content is ready **4. Create Avatar Video** \- Call Heygen API (requires paid API plan), specifying your avatar ID and voice ID \- Create avatar video, optionally passing in an image/video background if you have a green screen avatar **5. Get Video** \- Wait awhile, then fetch completed avatar video **6. Publish to Social Media** \- Pass the video URL directly to the Blotato Publish node - no upload step required \- Connect Blotato to your social accounts \- Choose your social accounts \- Either post immediately or schedule for later ### Setup * [Install the Blotato and Apify community nodes](https://help.blotato.com/api/n8n/n8n-blotato-node) * [**Airtable**](https://airtable.com/) Create a free account, then visit the [Personal Access Token Page](https://airtable.com/create/tokens) and create a new key (make sure to add `data.records:read`, `data.records:write`, `schema.bases:read` in Scopes and add your base in Access). Then create Airtable credential. Clone [this Airtable Database](https://airtable.com/appKGAkMPhWAhL9dF/shriczYSic1SRJzU2). Copy your newly made Airtable Database URL and paste it in both Airtable Triggers under `Base URL` and `Table URL`. * [**Blotato**](https://blotato.com) Sign up on Blotato, then go to [Dashboard → API Keys](https://my.blotato.com/settings/api) to create your key. Then create Blotato credential. * [**Apify**](https://apify.com) Create a free account, then visit [Account → Integrations → API Tokens](https://console.apify.com/settings/integrations) to generate your token. Then create Apify credential. * [**OpenAI**](https://platform.openai.com/) Create a free account, then go to the [API Keys page](https://platform.openai.com/api-keys) and create a new key. Then create OpenAI credential. * [**HeyGen\_API**](https://www.heygen.com) Sign up and visit the [API access page](https://app.heygen.com/settings?from=\&nav=Subscriptions%20%26%20API) to request an API key. Then paste the generated API Key under `HeyGen_API` in the Setup Node. * [**Avatar\_ID**](https://www.heygen.com) After creating/choosing an avatar in HeyGen, go to **Avatars** in the dashboard → copy the avatar ID from the developer panel. Then paste the Avatar ID under `Avatar_ID` in the Setup Node. * [**Voice\_ID**](https://www.heygen.com) In the HeyGen **Voices** section, select your desired voice and copy its ID from the developer panel or API docs. Then paste the Voice ID under `Voice_ID` in the Setup Node. * Follow the 3 setup instruction in BROWN sticky notes in this template. * If you want a background image/video behind your avatar, also add a publicly accessible link to the Background Video on Airtable Database in the field `BackgroundURL`. I only recommend doing this AFTER the full workflow is operational. ### Tips & Tricks * While testing: enable only 1 social platform, and deactivate the rest for testing purposes. Update the AI agent node’s prompt to return a 5-second script, rather than 30 seconds, to reduce the processing duration. * Go to Heygen and check that your avatar video is being processed. * After the workflow finishes, check your social media account for the final post. * If successful, then enable another social media node, and continue testing. * Update prompt to match your niche / industry ### Troubleshooting * Sometimes the Apify Scraper fails, let it loop to try again (usually works 2nd time) * OpenAI API account must have billing funded * make sure you copied your avatar ID correctly, not the group avatar ID * If your script is long, it takes more time for your video to finish If you need help troubleshooting your automation: * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to Blotato and click the ORANGE BUTTON in the bottom right corner to send me a message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) # 8 Repurpose Tiktoks On Autopilot ### Description This automation detects when you post a Tiktok video, automatically downloads the video without watermark, stores it in Google Drive, and reposts your Tiktok video to other social media platforms. All on autopilot. So you can grow your presence on multiple platforms, without more work. You can also easily add steps to customize captions per platform. ### Platforms
n8nMakeZapier
truefalsefalse
### Templates ### Tutorials {% embed url="" %} ### Overview Here’s how the automation works: **1. Trigger: RSS Feed** * RSS feed triggers when you post a new Tiktok video **2. Fetch Video** * Download the newly posted Tiktok video * Store video in Google Drive **3. Publish to Social Media** * Connect Blotato to your social accounts * Choose your social accounts * Either post immediately or schedule for later ### Setup * [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) * [**Blotato**](https://blotato.com) Sign up for Blotato, then go to [Dashboard → API Keys](https://my.blotato.com/settings/api) to create your key. Then create Blotato credential. Connect your social accounts, and select which accounts to post to. * [**RSS.app**](https://rss.app) Create an account, then visit [Feeds](https://rss.app/myfeeds), click "Add Feed", input your Tiktok profile URL, and generate the RSS feed. Copy paste RSS feed URL into the RSS Feed Trigger node. Within rss.app, configure your RSS feed setting "Number of Posts" to 1. ### Tips & Tricks * While testing: enable only 1 social platform, and deactivate the rest for testing purposes. You can also use the option "Scheduled Time" while testing, so that posts are scheduled in the future, not posted immediately. * After the workflow finishes, check your social media account for the final post. * If successful, then enable another social media node, and continue testing. ### Troubleshooting * Make sure your RSS feed is configured to output only 1 item at a time * If you post multiple Tiktok videos within an hour interval, you can set your refresh interval to 15 minutes in RSS.app but this requires a paid plan.\\ If you need help troubleshooting your automation: * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to Blotato and click the ORANGE BUTTON in the bottom right corner to send me a message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. [Install the Blotato community node](https://help.blotato.com/api/n8n/n8n-blotato-node) 2. If a template shows question marks instead of the Blotato logo, install the Blotato node first, then re-import the template. 3. Create a new Credential in n8n. Go to Blotato Settings > API > Copy API Key. Paste the API key in n8n, save, test, then select this credential on Blotato nodes. 4. Connect social accounts on each platform node. Open each Blotato Publish node, select the Blotato credential, then pick your social account. 5. When testing, deactivate all social platform nodes. Activate just 1 to start with. Run the workflow, then Pin data at the Blotato Publish node. This locks inputs for repeat tests. Then, execute 1 platform node from pinned data to validate it works. Activate other social platforms to continue testing. 6. Use the [Blotato API dashboard](https://my.blotato.com/api-dashboard) to review each request, payload, and error message. ### Make Notes n/a ### Zapier Notes n/a # 10 Gamma Templates ### Description You can now use [Gamma](https://gamma.app/) to create presentations and social media carousels, using your own custom branded template, then post them automatically on social media! ### Platforms
n8nMakeZapier
truetruefalse
### Templates ### Tutorials {% embed url="" %} ### Use Cases * Repurpose AI meeting notes into education carousels * Convert long and short-form videos into carousels * Convert Google testimonials into social posts * Daily industry news recap carousel ### Overview Here’s how the automation works: * Check Google Sheet daily * Create carousel using Gamma template * Convert carousel from PDF to PNG images using CloudConvert * Post carousel to social platforms using Blotato * Update item’s “Posted” status in Google sheet ### Setup Accounts * 1\. Sign up for: * Gamma.app * CloudConvert.com * Blotato.com 2\. Generate API Keys: * Gamma API Key: [https://gamma.app/settings/api-keys](https://my.blotato.com/settings/api) * CloudConvert API Key: [https://cloudconvert.com/dashboard/api/v2/keys](https://my.blotato.com/settings/api) * Blotato API Key: 3\. Ensure you have “Verified Community Nodes” enabled in your n8n Admin Panel 4\. Open n8n Settings and install nodes: * @blotato/n8n-nodes-blotato * @gammatech/n8n-nodes-gamma * @cloudconvert/n8n-nodes-cloudconvert 5\. Create CREDENTIALS for Blotato, Gamma, and CloudConvert 6\. Connect your [Google Drive to n8n](https://docs.n8n.io/integrations/builtin/credentials/google/oauth-single-service) ### Setup Workflow 1\. Copy this [sample Google Sheet](https://docs.google.com/spreadsheets/d/1UTskvZDjeLqwriXgo3KERlYR7s4iBCLT7L_B5Xepu9c/edit?usp=sharing) … and configure SETUP 1. Do NOT change columns, unless you know what you’re doing 2\. SETUP 2: Connect Gamma credential & input Gamma template ID 3\. SETUP 3: Connect CloudConvert credential 4\. SETUP 4: Connect Blotato credential and select social media account to post to 5\. Execute workflow and check to see your posts: * Blotato API Dashboard: * Blotato Calendar: ### Tips & Tricks * While testing: enable only 1 social platform, and deactivate the rest for testing purposes. You can also use the option "Scheduled Time" while testing, so that posts are scheduled in the future, not posted immediately. * After the workflow finishes, check your social media account for the final post. * If successful, then enable another social media node, and continue testing. ### Troubleshooting * the [API Dashboard](https://my.blotato.com/api-dashboard) is your best friend * go to Blotato and click the ORANGE BUTTON in the bottom right corner to send me a message Other helpful links: **👉** [**Blotato API Docs**](https://help.blotato.com/api) ✅ [**Troubleshoot Errors**](https://my.blotato.com/api-dashboard) 📷 [**Media Requirements**](https://help.blotato.com/api/media) ### n8n Notes 1. The Make and n8n templates are IDENTICAL IN LOGIC. However, n8n requires more setup installing verified community nodes. 2. Unfortunately, the n8n nodes for Gamma and CloudConvert are limited (e.g. Gamma node lacks PDF export), so I resort to raw HTTP calls. ### Make Notes n/a ### Zapier Notes n/a # n8n # 1 Post Everywhere ### How It Works This automation publishes to 9 social platforms daily! Manage your content in a simple Google Sheet. When you set a post's status to "Ready to Post" in your Google Sheet, this workflow grabs your image/video from Google Drive, posts to 9 social platforms, then updates the post status to "Posted". ### Tutorials * Youtube tutorial: * Newsletter tutorial: * Template: {% embed url="" %} # n8n AI Clone {% embed url="" %} Here’s the link to download the prebuilt n8n template: [n8n template link](https://drive.google.com/file/d/1IhELowUjDXEl-UsOKpnKnxn__twe3GpR/view?usp=sharing) Learn how to build a fully automated AI Avatar Social Media system that creates talking head AI clone videos, WITHOUT having to film or edit yourself. This tutorial combines n8n, AI tools agent, HeyGen, and Blotato to research, write, create, and distribute talking head AI clone videos to every social media platform every single day. 100% automated. * n8n - workflow automation that runs daily * AI agent - uses HackerNews and ChatGPT * Heygen - create realistic AI clone/avatar * Blotato - publish to all social platforms Here’s the Youtube version of this post: ## Prerequisites Before diving into the workflow, ensure you have the following accounts set up: * n8n: you can use the cloud-hosted version or host it yourself * API Accounts and Keys: * Heygen: generate AI avatar videos * Blotato: publish to social platforms * OpenAI: generate scripts and captions ## Step 1: Import Template into n8n Download Template: scroll to the bottom of this page to download the n8n template! 🛑 Scroll to the bottom of this newsletter to get the n8n template to import! Import into n8n: * Open n8n * Click “Create Workflow” * Click 3 dots * Click “Import from File” Review Workflow: Once imported, you will see a series of nodes visually connected. This template automates several tasks: scheduling, fetching news, generating scripts, creating the AI avatar video, and finally publishing to social media. ## Step 2. Understand the Workflow This JSON template is a complete pipeline that automates content creation and distribution. Here’s a breakdown of its primary components: ### 1. Schedule Trigger: * Purpose: Automatically trigger the workflow every day (or at the set hour). * How it Works: The node “Schedule Trigger” is configured to start the process at 10 AM daily. Adjust the schedule as needed. ### 2. News Fetching and Content Generation: * Fetching Trending News: * Tools Involved: “Fetch HN Front Page” and “Fetch HN Article.” * Function: These nodes use HackerNews data to pull the top 10 stories related to AI or LLMs from the last 24 hours. * Script Generation by AI Agent: * Node: “AI Agent” * Function: This node instructs the agent to pick the most viral story, fetch the article along with its comments, and then generate a 30-second script using a defined prompt. I tell ChatGPT to include detailed information, statistics, and a striking viral hook at the beginning. ### 3. Caption Creation: * Write Long Caption: * Write a summary paragraph, 3 bullet point questions, and hashtags. * Write Short Caption: * Write 2-sentence summary for Twitter, Threads, Bluesky. ![](https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/014301dd-0981-49db-9779-4d832ca36bd0/image.png?t=1744479925) ### 4. AI Avatar Video Creation: * Setup Heygen: * Prepares parameters for video creation, including background, avatar, and voice. * Create Avatar Video: * Calls the Heygen API to generate the video based on the AI-generated script and selected avatar settings. * Wait : * Ensures there’s enough time for the video to be made, before retrieving the video URL via the "Get Avatar Video" node. ![](https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/3d5d6f7e-a573-4a44-8963-429d64a8872b/image.png?t=1744479878) ### 5. Social Media Posting: * Publishing: * Pass the video URL directly to the Blotato Publish nodes - no upload step required. * Use Blotato API to post the video + captions to all social platforms. * The Blotato API currently doesn't support posting video to Bluesky or Pinterest, so those nodes are deactivated for now. This feature will be available soon, so I left these nodes in the template. Note: The original YouTube tutorial shows an UPLOAD node, but this step is no longer required. Pass your image/video URLs directly into the `mediaUrls` parameter in the Publish node. ![](https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/331186b1-574f-4128-98d7-b433b84ab135/image.png?t=1744479889) ## Step 3. Setup & Run Workflow 💡 IMPORTANT: the only 2 nodes where you need to edit the values are “Setup Heygen” and “Prepare for Publish”. Don’t tweak anything else, until the entire workflow is smoothly running and posting to your socials. Setup Heygen: * Paste your Heygen API key * Paste your Heygen avatar ID * Paste your Heygen voice ID * Use the `background_video_url` that is already filled out (change it later, after ensuring everything works) Prepare for Publish: * Paste your Blotato API key * Paste your Blotato account IDs * Paste your Facebook page ID If a social platform is not used, keep its node disabled. You don’t need to fill out the account ID for platforms you’re not publishing to. 1st Test Run: Enable only 1 social platform, and deactivate the rest for testing purposes. Update the AI agent node’s prompt to return a 5-second script, rather than 30 seconds, to reduce the processing duration. Update the “Wait” node to wait for 2 minutes, rather than 8 minutes, since you’re testing with a super short script. Now you’re ready to test the entire workflow! Go to Heygen and check that your avatar video is being processed. After the workflow finishes, check your social media account for the final post. If successful, then enable another social media node, and continue testing! # n8n Faceless Videos This is the EASIEST n8n/Make AI agent system that creates faceless AI videos and posts them to all social platforms, without having to sign up for multiple tools to generate AI images, videos, voice, and stitch everything together. Faceless AI videos are [blowing up on social media](https://www.tiktok.com/@dayli.pov), getting millions of views. Anyone can start making them today, without expertise in video editing. Here's the n8n template to import: [n8n template](https://drive.google.com/file/d/1ASkABU6tk9vOOGDMUWKISzOnGZ_PZj_o/view?usp=sharing) {% embed url="" %} Here’s a [sample video](https://database.blotato.io/storage/v1/object/public/public_media/4ddd33eb-e811-4ab5-93e1-2cd0b7e8fb3f/videogen2-render-65fdee14-f35b-46e7-9ee8-2e43e966a289.mp4) created by this automation — including the animated images, voiceover, and captions 😎 using image model “Recraft” and video model “Framepack”. *** ## Overview A single n8n/Make workflow that: 1. **Generates** a faceless video idea and script 2. **Turns** that script into a full AI video 3. **Posts** to 7 social platforms​ *** ## Prerequisites | Tool | Why you need it | Links | | --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **n8n or Make** | Runs the no-code workflow |

| | **Blotato** | Generates video & posts to social platforms | | | **ChatGPT** | Write script & caption | | *** ## Step 1. Import the template 1. **Download** the JSON file (top of this chat). 2. In n8n or Make, click **Import** 3. The full workflow should appear *** ## Step 2. Setup To get the workflow running for the first time, **you only need to configure 2 nodes:** 1. Prepare Video Here’s how the node looks. The only field you need to fill out is `blotato_api_key` which you can get [here](https://help.blotato.com/settings/api-keys). ```json { "blotato_api_key": "", "template": "empty", "voiceId": "elevenlabs/eleven_multilingual_v2/JBFqnCBsd6RMkjVDRZzb", "captionPosition": "bottom", "script": {{ $('AI Agent').item.json.output.toJsonString() }}, "style": "cinematic", "animate_first_image": true, "animate_all": false, "text_to_image_model": "replicate/recraft-ai/recraft-v3", "image_to_video_model": "fal-ai/framepack" } ``` 2. Prepare to Publish Here’s how the node looks. For your 1st test, the only fields you need to fill out are: * `blotato_api_key` * `instagram_id` OR `tiktok_id` After your first test succeeds, then you can test all your other social account IDs. ```json { "blotato_api_key": "", "instagram_id": "", "youtube_id": "", "tiktok_id": "", "facebook_id": "", "facebook_page_id": "", "threads_id": "", "twitter_id": "", "linkedin_id": "", "pinterest_id": "", "pinterest_board_id": "", "bluesky_id": "", "final_text_long": {{ $('Prepare Video').item.json.script.caption.toJsonString() }}, "final_text_short": {{ $('Prepare Video').item.json.script.caption.toJsonString() }} } ``` *** ## Step 3. Understand How AI Creates Your Video The heavy lifting happens in the **Create Video** node, which calls Blotato API to generate your faceless video. Here is the [API documentation](https://help.blotato.com/api/api-reference/create-video). ```json { "template": { "id": "{{ $json.template }}" "voiceId": "elevenlabs/eleven_multilingual_v2/JBFqnCBsd6RMkjVDRZzb", "captionPosition": "top", }, "script": {{ $json.script.script.toJsonString() }}, "style": "{{ $json.style }}", "animateFirstImage": {{ $json.animate_first_image }}, "animateAll": {{ $json.animate_all }}, "textToImageModel": "{{ $json.text_to_image_model }}", "imageToVideoModel": "{{ $json.image_to_video_model }}" } ``` The prebuilt template injects your variables automatically, as defined in the `Prepare Video` node, so you don’t have to touch anything right now. If you want Blotato to take your script and transform it into a **POV style video**, set `id` to `base/pov/wakeup` in the “Prepare Video” node. Viral POV videos typically don’t have an AI voiceover, so this template will disable the AI voiceover. If you want Blotato to **take your script as is**, without transforming it into POV style, set `id` to `empty` in the “Prepare Video” node. This will generate an AI voiceover reading your script. Here’s the full list of [AI voices](https://help.blotato.com/api/api-reference/voice-ids) available. Here are the parameters available for each video template: I plan to add many more templates, especially for business/professional videos! To animate the whole video, not just the first image, make sure to set `animate_all` to `true` in the “Prepare Video” node. *** ## Step 4. Test Run For your test run, make sure only 1 social platform is enabled. Disable the others. Don’t touch anything else besides the 2 “prepare” nodes as described above. Here are common issues and errors: | Symptom | Fix | | ------------------------------------ | ----------------------------------------------------------------------------- | | “401 Unauthorized” | Wrong or expired Blotato API key | | Getting video returns “script-ready” | The video isn’t done exporting, so you’ll need to increase wait time. | | Social post fails | Check that account ID is correct and that the account is connected in Blotato | Once everything is working, now you can go back and tweak the automation! For example, you probably want to change the AI agent node’s prompt, which I’ve copied below for reference: ```html # INSTRUCTIONS 1. Brainstorm 50 different viral faceless video ideas related to theme "Little known history facts about [famous person]". 2. Randomly select 1 of the ideas. Research relevant statistics, dates, and figures related to the specific idea. 3. Write a 15-second video script for a viral faceless video. Use 6th grade language, use active voice, and start with a hook that leaves viewers wanting to know the answer. Do NOT start with a greeting like "Hey there!". 4. Write a 2-sentence video caption, use 6th grade language, no emojis, and append 3 relevant hashtags to the end of the caption, including "#ai". # OUTPUT FORMAT In JSON format: 1. Output the script. 2. Output the caption. ``` *** ## AI Image and Video Models Note: This template uses the older `textToImageModel` / `imageToVideoModel` parameters. For new automations, use the CREATE VISUAL node instead, which supports pre-built templates for carousels, slideshows, and videos. See [Visual Templates](https://help.blotato.com/api/visuals) for details. You can also customize the AI image and video models. The template default AI image model is “recraft” which creates realistic-looking images. I also personally like the image model “flux-pro”. The template default AI video model is “framepack” which is the cheapest option, so that you don’t accidentally burn lots of credits. Go [here ](https://help.blotato.com/api/api-reference/create-video)to see the full list of AI models available. # n8n Slideshows & Carousels ## CREATE VISUAL Node (Recommended) Use the Blotato CREATE VISUAL node to generate carousels and slideshows from templates: 1. Add a Blotato node and select "Visual" > "Create" 2. Select a template from the dropdown list 3. Keep default inputs and click Execute to instantly make a carousel 4. Update inputs one-by-one to customize 5. Check the [API Dashboard](https://my.blotato.com/api-dashboard) to see the JSON payload for each template Tip: Browse all available templates at to see how they work before building your automation. *** ## Legacy Tutorial {% embed url="" %} {% embed url="" %} Here's the n8n template: [n8n template](https://drive.google.com/file/d/1bLUhrYM1wz3kaaw4S-Iifu1ZtlcKc3jp/view?usp=sharing\&utm_source=www.sabrina.dev\&utm_medium=referral\&utm_campaign=this-ai-agent-automates-slideshows-and-carousels) ### How do you create carousels and slideshows with your own images and videos? You don't need to use Blotato's AI generated images for your slideshow. You can use any images that have a publicly accessible URL. Open the PUBLISH TO INSTAGRAM/TIKTOK steps. Submit a `mediaUrls` array that contains your final images for the carousel. You can pass any publicly accessible image/video URL directly - no upload step required. I recommend switching to the n8n/Make official Blotato nodes. Much easier instead of fiddling with JSON. Check out this tutorial and template: # n8n Repost Tiktoks Everywhere n8n template: Repurposing your existing content is the EASIEST 10x growth multiplier for intermediate-level creators. I personally repost all my Tiktoks to Instagram, and I’ve grown from 0 to 350k Instagram followers in less than 1 year. 100% automated. If Tiktok gets banned in your country, you’ll be glad you started reposting, and this only takes 15 minutes to setup. This is a fully automated Tiktok Repost Engine that takes your latest Tiktok video and repurposes it to 8 social platforms, while also saving a copy to your Google Drive. The beauty is: ***No extra work!*** *Just post on Tiktok like you normally do.* *This automation takes care of everything else on autopilot.* {% embed url="" %} It reposts every new TikTok you publish to Instagram Reels, YouTube Shorts, Pinterest, Facebook, LinkedIn, Twitter, Threads, Bluesky, and Google Drive. You don’t need to write any code. You don’t need to change your content habits. Just post Tiktoks like normal, everything syncs behind the scenes. I use the following tools: * n8n - workflow automation * [RSS.app](http://rss.app/) - gets your latest tiktok video * [Blotato.com](http://blotato.com/) - repurpose tiktok to other social platforms *** If your automation fails: 1\. Go to Blotato > API Dashboard 2\. Click the failed request to view details 3\. Check the error message Common issues: \- Wrong API key \- Google Drive folder not public \- YouTube title exceeds 100 characters *** ### Recap To recap the 3 setup steps: 1. Input your RSS Feed from RSS.app 2. Setup Google Drive folder with public access 3. Setup Blotato account with API key and social account IDs Once the automation is configured, all you have to do: 1\. Post videos on TikTok like normal 2\. Let the automation trigger via RSS 3\. Your videos will be downloaded and reposted automatically! # n8n Blotato Node The official Blotato community node for n8n: *** ## Available Operations The Blotato node supports the following operations: | Resource | Operation | Description | | -------- | --------- | ----------------------------------------------------- | | Post | Publish | Publish a post to social platforms | | Media | Upload | Upload media files | | Visual | Create | Create visuals from templates (carousels, slideshows) | | Visual | Get | Get visual creation status | | Source | Create | Resolve content from URLs, text, PDFs, etc. | | Source | Get | Get source resolution status and content | *** ## Install the Blotato Node ### n8n Cloud Users 1. Go to your n8n Admin Panel > Settings 2. Enable Verified Community Nodes 3. Open any workflow 4. Click the "+" icon in the top right corner 5. Search for "Blotato" 6. Click Install ### Self-Hosted n8n Users For Railway, DigitalOcean, Docker, or other self-hosted setups, enable community nodes first: 1. Go to your hosting dashboard (Railway, DigitalOcean, etc.) 2. Open the Environment or Variables tab 3. Add a new variable: * Key: `N8N_ENABLE_COMMUNITY_NODES` * Value: `true` 4. Save and restart your n8n instance 5. Go to n8n Settings > Community Nodes 6. Search for "Blotato" and install You may need to restart your n8n docker container as well. *** ## Update the Blotato Node 1. Go to n8n Settings > Community Nodes 2. Find the Blotato node and click Options 3. Click Update *** ## Using Source Operations The Source operations allow you to resolve content from various sources programmatically. ### Supported Source Types | Source Type | Input | Description | | ---------------- | ------------ | ------------------------ | | text | Text content | Plain text | | article | URL | Web article or blog post | | youtube | URL | YouTube video | | twitter | URL | Twitter/X post | | tiktok | URL | TikTok video | | perplexity-query | Text query | Perplexity AI search | | audio | URL | Audio file | | pdf | URL | PDF document | ### Create Source 1. Add a Blotato node 2. Select Resource: "Source" 3. Select Operation: "Create" 4. Choose the source type 5. Provide the URL or text input 6. Execute to get a resolution ID ### Get Source 1. Add another Blotato node 2. Select Resource: "Source" 3. Select Operation: "Get" 4. Pass the resolution ID from the Create step 5. Execute to get the resolved content (title, content, referenceUrl) Add a Wait node between Create and Get if processing takes time (e.g., for long videos or PDFs). For full API details, see: [Source API Reference](https://github.com/Blotato-Inc/help.blotato.com/blob/main/api/api-reference/source.md) *** ## Troubleshooting ### Template shows question marks instead of the Blotato logo? 1. Enable Verified Community Nodes first 2. Install the Blotato node 3. Re-import the n8n template ### Need help? Contact support by clicking the orange button in the bottom right corner within the Blotato app. # FAQs ## How do I get started with the Blotato API in n8n? 1. Follow the [Blotato API Quickstart](https://help.blotato.com/api/start) to get your API key and install the official Blotato n8n node 2. Import one of the [Automation Templates](https://help.blotato.com/api/templates) to start with a working workflow 3. To create videos or carousels: add the Blotato CREATE VISUAL node, select a template from the dropdown, and click Execute. Start with a carousel template -- it renders near-instantly so you get a result right away 4. To publish: add the Blotato PUBLISH node. Pass your image/video URLs directly into the `mediaUrls` parameter -- no upload step required **Important:** If you're using an older template that includes a "Upload to Blotato" or "Media > Upload" node, you can disable or delete it. Media upload is now optional -- you can pass URLs directly to the Publish node's `mediaUrls` parameter. 5. To debug requests: open the [API Dashboard](https://my.blotato.com/api-dashboard) and click on any request to see the full payload and response Use the official Blotato n8n node. It handles API keys and account selection through dropdowns, so you do not need to copy/paste IDs or write raw JSON. *** ## What is the file size limit for binary data uploads? If you are using the n8n "Binary Data" upload option, the file size limit is 15MB. For larger files, switch to URL-based upload: 1. Use the [Presigned Upload](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) endpoint (`POST /media/uploads`) to upload directly to Blotato -- no Google Drive or S3 needed. Upload size depends on your plan (see [Plan Limits](/settings/billing-and-credits#plan-limits)). 2. Or upload your media to Google Drive, AWS S3, or another cloud storage service and pass the public URL into the Blotato node *** ## How do I post an Instagram story instead of a reel? Open the Instagram publish node in n8n, click "Add Option", select "Media Type", and set it to "Story". By default, Instagram posts with video publish as Reels. Setting Media Type to "Story" overrides this. **Not supported by Instagram API**: link stickers and interactive stickers must be added manually in the Instagram app after the Story publishes. See [Instagram Story link stickers](/platforms/instagram/limitations#story-link-stickers). *** ## How do I post to a LinkedIn page instead of personal LinkedIn? Open the LinkedIn publish node in n8n, click "Add Option", and select "LinkedIn Page" from the dropdown. This lets you pick which LinkedIn company page to post to. *** ## Having issues with the Blotato node in n8n? Make sure you follow these instructions to install the official Blotato n8n node: [Install Guide](https://help.blotato.com/api/start#n8n) You may need to re-import your workflow template after installing the official Blotato n8n node. *** ## How do I use the Source nodes in n8n? The Source nodes allow you to extract content from YouTube, TikTok, articles, PDFs, audio, or AI research queries. ### Create Source Node 1. Add a Blotato node 2. Select "Source" > "Create" 3. Choose your source type: * **URL**: YouTube, TikTok, Article, PDF, or Audio URL (auto-detected) * **Text**: Raw text content * **AI Research**: Perplexity-powered web search query 4. Optionally add Custom Instructions to transform the extracted content 5. Execute to get a source ID ### Get Source Node 1. Add a Blotato node after Create Source 2. Select "Source" > "Get" 3. Pass the source ID from Create Source 4. Enable "Clean Transcript" to remove timestamps (recommended) 5. Execute to retrieve the extracted content ### Workflow Pattern ``` [Create Source] --> [Wait 5-10s] --> [Get Source] --> [Use Content] ``` Add a Wait node between Create and Get because extraction is asynchronous. ### Example: YouTube to Visual Content 1. Create Source with YouTube URL 2. Wait 10 seconds 3. Get Source to retrieve transcript 4. Pass transcript to Blotato Create Visual to make carousels or videos 5. Publish to social platforms ### Source Node Not Showing? If you don't see the "Source" node in your Blotato n8n node, update to the latest version: 1. Click the "+" icon to add a new node 2. Search for "Blotato" 3. Look for the "UPDATE" button and click it After updating, the Source node will be available. Note: Make.com automatically receives updates. *** ## Troubleshooting Make.com and n8n Automations **The most common errors I see are related to:** * wrong API key or account IDs * invalid JSON (e.g. wrongly formatted) * invalid API request (e.g. wrong parameters) * invalid file format (e.g. wrong video dimensions) * you're on the free Creatomate plan and you need to upgrade to export correct video dimensions Tip: Use the official Blotato n8n node to avoid manually copying API keys and account IDs. [Install guide](https://help.blotato.com/api/n8n/n8n-blotato-node) ### First step: click "Fix My Automation" in the API Dashboard (n8n only) The fastest way to fix a failing n8n workflow is to let Blotato AI fix it for you automatically. 1. Go to your [API Dashboard](https://my.blotato.com/api-dashboard) 2. Click the failed request 3. Click the green **FIX MY AUTOMATION** button at the top 4. Blotato AI will attempt to fix your n8n workflow automatically This feature is **n8n only** — it does not work for Make.com, Claude, MCP, or direct REST API calls. For those, use the manual checklist below. ### Manual troubleshooting checklist * Check your Blotato API key, Account IDs, and Page IDs are correct * Check that the correct Account ID is connected and passed in every Publish API call * If you are publishing to a Facebook Page or Linkedin Company Page, you must also pass the Page ID, in addition to Account ID. * Check your [API Dashboard](https://my.blotato.com/api-dashboard) - click on any request to see the full payload, error response, and which account it was sent to * Verify that the JSON data in the HTTP Request contains the right parameters: 1. Ask ChatGPT to check if your **JSON is valid**. 2. Check it again with JSON Validator: [https://jsonlint.com](https://jsonlint.com/) 3. If your JSON is valid, ask ChatGPT to **compare your JSON to Blotato's API docs**. Use this prompt: ``` You are an expert in Blotato API: https://help.blotato.com/api/api-reference/publish-post Check the following JSON is valid and conforms to the Blotato API: PASTE_YOUR_JSON_REQUEST_HERE ``` *** ## Issues with JSON Request to Blotato API? I recommend using ChatGPT to troubleshoot your JSON payload: 1. Ask ChatGPT to check if your **JSON is valid**. 2. Check it again with JSON Validator: [https://jsonlint.com](https://jsonlint.com/) 3. If your JSON is valid, ask ChatGPT to **compare your JSON to Blotato's API docs**. Use this prompt: ``` You are an expert in Blotato API: https://help.blotato.com/api/api-reference/publish-post Check the following JSON is valid and conforms to the Blotato API: PASTE_YOUR_JSON_REQUEST_HERE ``` *** ## Submitting Wrong Video Dimensions to API? I see a lot of errors related to uploading invalid video dimensions. For example, if you're on the free Creatomate plan, you need to upgrade in order to export correct video dimensions. As a sanity check, try uploading this video instead: *** ## How to Preserve Newlines in Multi-Paragraph Posts? To preserve newlines in posts with multiple paragraphs, use the function toJsonString() in n8n like this: `"text": $("Prepare for Publish").item.json.final_text_long.toJsonString()` *** ## How do you customize text styles in the carousel/slideshow? It's on my roadmap to add more customization options and templates for carousels/slideshows! Right now, the only customization is the caption position (top, middle, bottom). *** ## How do I check if my post was published and get the live URL? Use the official Blotato **Get Post** node: 1. Add a Blotato node and select "Post" > "Get" 2. Pass in the `postSubmissionId` from your Publish node response 3. The node returns the post status and, once published, the live URL (e.g., the direct TikTok or Instagram link) TikTok and other platforms process posts asynchronously, so the published URL is not available immediately after the Publish step. Add a Wait node (10-30 seconds) between Publish and Get Post, or use a loop to poll until the status is `published`. API docs: [Get Post](/api/publish-post/get-post) *** ## How do you post a slideshow or carousel? Using the official Blotato node, it's now super easy to post a slideshow or carousel. In your publishing node, update the Media URLs parameter - give it a comma separated list of URLs to be posted as a slideshow/carousel. *** ## Don't see your Facebook or Linkedin Pages in the n8n node? As a workaround, switch from `From List` to `By ID`, then copy paste your pageId from Blotato Settings.
*** ## I'm using an older template with textToImageModel and imageToVideoModel parameters. Do these still work? Those parameters belong to an outdated template format. Switch to the new CREATE VISUAL system instead: 1. Browse all available templates at to see how they look 2. In n8n or Make, add the Blotato CREATE VISUAL node and select a template 3. Start with a carousel template -- carousels render near-instantly, so you get a fast test run 4. Click Execute to generate the carousel 5. Open your [API Dashboard](https://my.blotato.com/api-dashboard) to see the JSON payload for each template 6. Override your desired inputs one-by-one If you were making AI story videos, use the template called "AI Video with AI Voice." Full documentation for each template: [Visual Templates](https://help.blotato.com/api/visuals) *** ## My n8n workflow keeps generating the same content every run. How do I fix this? This usually happens when nodes have **pinned data** that prevents them from running fresh on each execution. ### Quick Fix 1. Open your n8n workflow 2. Click each node in your workflow (especially script/AI generation nodes and the Create Visual node) 3. Look for a small **pin icon** in the output panel of each node 4. If you see a pinned icon, click it to **Unpin data** 5. Run your workflow again ### Common Causes * **Pinned script/AI output**: If your script generation node is pinned, it will reuse the same script every run * **Pinned Create Visual inputs**: If inputs to Create Visual are pinned, the same content gets generated * **Pinned source data**: Any upstream nodes with pinned data will prevent fresh content ### Prevention Only pin data temporarily for testing. Always unpin before running production workflows. If your workflow still generates identical content after unpinning, verify that: * Your source data actually changes between runs * Random/variable elements are included in your prompts * You're not hardcoding static values *** **Didn't find your answer?** * [General FAQs](/support/faqs) * [API FAQs](https://github.com/Blotato-Inc/help.blotato.com/blob/main/api/faqs.md) * [Make.com FAQs](/api/make.com/faqs) # Make.com Blotato has an official Make.com integration with the following modules: | Resource | Operation | Description | | -------- | --------- | ----------------------------------------------------- | | Post | Publish | Publish a post to social platforms | | Media | Upload | Upload media files | | Visual | Create | Create visuals from templates (carousels, slideshows) | | Visual | Get | Get visual creation status | | Source | Create | Resolve content from URLs, text, PDFs, etc. | | Source | Get | Get source resolution status and content | ## Using Source Modules The Source modules allow you to resolve content from various sources programmatically. ### Supported Source Types | Source Type | Input | Description | | ---------------- | ------------ | ------------------------ | | text | Text content | Plain text | | article | URL | Web article or blog post | | youtube | URL | YouTube video | | twitter | URL | Twitter/X post | | tiktok | URL | TikTok video | | perplexity-query | Text query | Perplexity AI search | | audio | URL | Audio file | | pdf | URL | PDF document | ### Create Source 1. Add a Blotato module 2. Select "Create a Source Resolution" 3. Choose the source type 4. Provide the URL or text input 5. Run to get a resolution ID ### Get Source 1. Add another Blotato module 2. Select "Get a Source Resolution" 3. Pass the resolution ID from the Create step 4. Run to get the resolved content (title, content, referenceUrl) Add a Sleep module between Create and Get if processing takes time (e.g., for long videos or PDFs). For full API details, see: [Source API Reference](https://github.com/Blotato-Inc/help.blotato.com/blob/main/api/api-reference/source.md) ## Using Visual Modules Visual creation is asynchronous. The Create module starts rendering and returns an ID. The Get module checks the status and returns the finished result. ### Create Visual 1. Add a Blotato module 2. Select "Create a Visual" 3. Choose a template from the dropdown 4. Fill in the template inputs (prompt, scenes, etc.) 5. Run to get a visual creation ID ### Get Visual 1. Add a Sleep module after Create Visual: * For carousel/slideshow templates without AI image generation: 45 seconds * For templates with AI image generation: 2 minutes 2. Add another Blotato module 3. Select "Get a Visual" 4. Pass the visual creation ID from the Create step 5. Check the `status` field: * `done` = visual is ready, use `mediaUrl` or `imageUrls` * `creation-from-template-failed` = check inputs and retry * Any other status = still processing, add a longer Sleep and retry ### Scenario Pattern ``` [Create Visual] --> [Sleep 45s-2min] --> [Get Visual] --> [Publish Post] ``` The "Create Everything with AI Agent" option is web-app only and not available as a Make.com template. Use a specific template from the dropdown instead. For full API details, see: [Create Visual API Reference](/api/create-video) # Make AI Clone **How to Build a Fully Automated AI Clone Video System** In this guide, I’ll show you how to build a 100% AI-powered system that: * Automatically researches interesting topics * Writes a video script * Generates a video caption * Creates an AI avatar video * Publishes the video to multiple social platforms ## 1. Base Automation {% embed url="" %} ## 2. Improving AI Clone's Voice {% embed url="" %} ## 3. Combining AI Clones with Faceless Videos {% embed url="" %} This allows you to automate your short-form video creation for platforms like TikTok and Reels. #### Why Automate? Many platforms prioritize short-form video content. With this setup, you can create high-quality AI avatar videos efficiently and distribute them at scale. #### Overview of the Workflow The workflow uses [Make.com](https://make.com), but you can adapt it to other automation tools like Zapier or Pipedream. Here’s a high-level breakdown of the process: 1. Research the topic using Perplexity AI. 2. Write the video script and caption with OpenAI’s ChatGPT. 3. Generate an AI avatar video using Heygen. 4. Publish the video to all social platforms with Blotato. Let’s dive into the step-by-step guide. *** #### **Step 1: Set Up the Workflow in Make.com** 1. **Create a New Scenario** * In Make.com, click "Create a new scenario" and name it (e.g., "AI Clone Base"). * This base workflow can later be expanded for more complex automations. 2. **Add a Perplexity Module** * Search for Perplexity and select "Create a Chat Completion." * Connect your API key from Perplexity (available on their website). 3. **Input Your Prompt** *** #### **Step 2: Write the Video Caption** 1. **Add an OpenAI ChatGPT Module** * Select "Create a Chat Completion." * Use GPT-4o or 4o-mini (depending on task complexity). 2. **Craft the Prompt** * Provide an example of an SEO-optimized caption with: * A brief summary of the video. * Three questions viewers might ask to find this type of content. * Relevant hashtags. 3. **Map the Output** * Feed the video script from Perplexity into this step to generate the caption. *** #### **Step 3: Create the AI Avatar Video** 1. **Add Heygen Module** * Connect your Heygen account (get your API key from Heygen’s website). 2. **Create Your AI Avatar** * If you haven’t already, create an avatar by: * Filming 5 minutes of high-quality footage in natural lighting. * Speaking directly to the camera without pauses or stitched clips. * Upload your footage to Heygen and wait 10–15 minutes for processing. 3. **Configure the Avatar Video** * Input the script generated by Perplexity. * Select a voice and adjust parameters like pitch, speed, and emotion (e.g., set to "Excited" for a more engaging tone). * Use a resolution of 720x1280 for short-form vertical 9:16 videos. * To remove the Heygen watermark from your avatar video, follow these instructions: 4. **Add Delays** * Insert sleep modules (e.g., 5–10 minutes) to account for processing time. *** #### **Step 4: Publish the Video to Social Platforms** 1. **Connect to Blotato** * Get your Blotato API key: * In Blotato settings, link all your social media accounts: 2. **Set Up Publishing Modules** * Pass video URLs directly to the Blotato Publish modules - no upload step required. * For each platform: * Create a JSON object with fields for captions, video URLs, and platform-specific parameters (e.g., privacy settings for TikTok). * Add HTTP modules to handle API calls for posting content. Note: The original YouTube tutorial shows an UPLOAD module, but this step is no longer required. Pass your image/video URLs directly into the `mediaUrls` parameter in the Publish module. 3. **(Optional) Track in Google Sheets** * Log all published content in a Google Sheet for easy tracking. * Include fields for the date, script, caption, and video URL. * Blotato also tracks all your published content, so this step is optional. *** #### **Tips for Success** 1. **Optimize Captions for Search** * Use keywords and hashtags to improve discoverability. * Platforms like TikTok derive significant views from search results. 2. **Adjust Processing Times** * For videos under 30 seconds, a 5-minute delay is usually sufficient. * For longer videos, increase the wait time to 8–10 minutes. 3. **Test on Multiple Platforms** * Preview each post to ensure it appears correctly on all platforms. * Avoid deleting TikTok videos—set them to private instead to avoid penalties. *** #### **Misc** * **Daily Automation**: * Schedule the workflow to run daily at a specific time or multiple times per day for consistency. * **Future Enhancements**: * Add YouTube Shorts publishing with Make.com’s YouTube module. * Explore advanced audio processing with ElevenLabs for professional-quality voiceovers. *** #### **Recap** In this tutorial, we covered how to: 1. Automate research and scriptwriting with Perplexity and ChatGPT. 2. Create high-quality AI avatar videos using Heygen. 3. Distribute content to multiple platforms with Blotato and Make.com. 4. Track published content in Google Sheets. With this system, you can efficiently produce and publish short-form videos, freeing up time to focus on strategy and creativity. # Make Faceless Videos This is the EASIEST n8n/Make AI agent system that creates faceless AI videos and posts them to all social platforms, without having to sign up for multiple tools to generate AI images, videos, voice, and stitch everything together. Faceless AI videos are [blowing up on social media](https://www.tiktok.com/@dayli.pov), getting millions of views. Anyone can start making them today, without expertise in video editing. Here's the Make template to import: [Make template](https://drive.google.com/file/d/1StqYbpgOs-PIXcHYuarPvVGgp_DOZjPK/view?usp=sharing) {% embed url="" %} Here’s a [sample video](https://database.blotato.io/storage/v1/object/public/public_media/4ddd33eb-e811-4ab5-93e1-2cd0b7e8fb3f/videogen2-render-65fdee14-f35b-46e7-9ee8-2e43e966a289.mp4) created by this automation — including the animated images, voiceover, and captions 😎 using image model “Recraft” and video model “Framepack”. *** ## Overview A single n8n/Make workflow that: 1. **Generates** a faceless video idea and script 2. **Turns** that script into a full AI video 3. **Posts** to 7 social platforms​ *** ## Prerequisites | Tool | Why you need it | Links | | --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **n8n or Make** | Runs the no-code workflow |

| | **Blotato** | Generates video & posts to social platforms | | | **ChatGPT** | Write script & caption | | *** ## Step 1. Import the template 1. **Download** the JSON file (top of this chat). 2. In n8n or Make, click **Import** 3. The full workflow should appear *** ## Step 2. Setup To get the workflow running for the first time, **you only need to configure 2 nodes:** 1. Prepare Video Here’s how the node looks. The only field you need to fill out is `blotato_api_key` which you can get [here](https://help.blotato.com/settings/api-keys). ```json { "blotato_api_key": "", "template": "empty", "voiceId": "elevenlabs/eleven_multilingual_v2/JBFqnCBsd6RMkjVDRZzb", "captionPosition": "bottom", "script": {{ $('AI Agent').item.json.output.toJsonString() }}, "style": "cinematic", "animate_first_image": true, "animate_all": false, "text_to_image_model": "replicate/recraft-ai/recraft-v3", "image_to_video_model": "fal-ai/framepack" } ``` 2. Prepare to Publish Here’s how the node looks. For your 1st test, the only fields you need to fill out are: * `blotato_api_key` * `instagram_id` OR `tiktok_id` After your first test succeeds, then you can test all your other social account IDs. ```json { "blotato_api_key": "", "instagram_id": "", "youtube_id": "", "tiktok_id": "", "facebook_id": "", "facebook_page_id": "", "threads_id": "", "twitter_id": "", "linkedin_id": "", "pinterest_id": "", "pinterest_board_id": "", "bluesky_id": "", "final_text_long": {{ $('Prepare Video').item.json.script.caption.toJsonString() }}, "final_text_short": {{ $('Prepare Video').item.json.script.caption.toJsonString() }} } ``` *** ## Step 3. Understand How AI Creates Your Video The heavy lifting happens in the **Create Video** node, which calls Blotato API to generate your faceless video. Here is the [API documentation](https://help.blotato.com/api/api-reference/create-video). ```json { "template": { "id": "{{ $json.template }}" "voiceId": "elevenlabs/eleven_multilingual_v2/JBFqnCBsd6RMkjVDRZzb", "captionPosition": "top", }, "script": {{ $json.script.script.toJsonString() }}, "style": "{{ $json.style }}", "animateFirstImage": {{ $json.animate_first_image }}, "animateAll": {{ $json.animate_all }}, "textToImageModel": "{{ $json.text_to_image_model }}", "imageToVideoModel": "{{ $json.image_to_video_model }}" } ``` The prebuilt template injects your variables automatically, as defined in the `Prepare Video` node, so you don’t have to touch anything right now. If you want Blotato to take your script and transform it into a **POV style video**, set `id` to `base/pov/wakeup` in the “Prepare Video” node. Viral POV videos typically don’t have an AI voiceover, so this template will disable the AI voiceover. If you want Blotato to **take your script as is**, without transforming it into POV style, set `id` to `empty` in the “Prepare Video” node. This will generate an AI voiceover reading your script. Here’s the full list of [AI voices](https://help.blotato.com/api/api-reference/voice-ids) available. Here are the parameters available for each video template: I plan to add many more templates, especially for business/professional videos! To animate the whole video, not just the first image, make sure to set `animate_all` to `true` in the “Prepare Video” node. *** ## Step 4. Test Run For your test run, make sure only 1 social platform is enabled. Disable the others. Don’t touch anything else besides the 2 “prepare” nodes as described above. Here are common issues and errors: | Symptom | Fix | | ------------------------------------ | ----------------------------------------------------------------------------- | | “401 Unauthorized” | Wrong or expired Blotato API key | | Getting video returns “script-ready” | The video isn’t done exporting, so you’ll need to increase wait time. | | Social post fails | Check that account ID is correct and that the account is connected in Blotato | Once everything is working, now you can go back and tweak the automation! For example, you probably want to change the AI agent node’s prompt, which I’ve copied below for reference: ```html # INSTRUCTIONS 1. Brainstorm 50 different viral faceless video ideas related to theme "Little known history facts about [famous person]". 2. Randomly select 1 of the ideas. Research relevant statistics, dates, and figures related to the specific idea. 3. Write a 15-second video script for a viral faceless video. Use 6th grade language, use active voice, and start with a hook that leaves viewers wanting to know the answer. Do NOT start with a greeting like "Hey there!". 4. Write a 2-sentence video caption, use 6th grade language, no emojis, and append 3 relevant hashtags to the end of the caption, including "#ai". # OUTPUT FORMAT In JSON format: 1. Output the script. 2. Output the caption. ``` *** ## AI Image and Video Models Note: This template uses the older `textToImageModel` / `imageToVideoModel` parameters. For new automations, use the CREATE VISUAL node instead, which supports pre-built templates for carousels, slideshows, and videos. See [Visual Templates](https://help.blotato.com/api/visuals) for details. You can also customize the AI image and video models. The template default AI image model is “recraft” which creates realistic-looking images. I also personally like the image model “flux-pro”. The template default AI video model is “framepack” which is the cheapest option, so that you don’t accidentally burn lots of credits. Go [here ](https://help.blotato.com/api/api-reference/create-video)to see the full list of AI models available. # Make AI Social Media System To connect Make.com with Blotato, I recommend importing this sample [Make blueprint](https://drive.google.com/file/d/1ZefGr-5cWogaqjsbhozF7c_Riwz_sWfQ/view?usp=sharing\&utm_source=www.sabrina.dev\&utm_medium=referral\&utm_campaign=i-built-an-ai-social-media-system). This blueprint is an automated AI Social Media System that analyzes an article and creates text posts (Twitter, Threads), text and image posts (Linkedin, Facebook, Instagram), and AI avatar videos (Tiktok). If you just want to learn how the Make modules call Blotato, check these modules: * Setup Social Accounts * Upload to Blotato * Publish Here's the Youtube tutorial and detailed walkthrough of the AI Social Media System: {% embed url="" %} This system uses AI to automate content creation and posting across platforms: 🔥 Monitors Google Sheets for new articles 🔥 Writes AI social media posts 🔥 Generates AI images 🔥 Generates AI avatar clone videos 🔥 Publish to social media using Blotato API I included multiple different types of content generated (text, image, video), so that you can easily customize this AI system to fit your needs. ## Import Make Blueprint 1. Log into Make 2. Go to "Scenarios"‘ 3. Click on "Create a new scenario" 4. Click on "Import Blueprint" (top-right corner) 5. Upload my prebuilt Make Blueprint ## Workflow Overview Here’s how everything works: 1. Google Sheets - Watch Rows * Monitors a spreadsheet for new URLs. * Triggers the automation when new row is added. 2. HTTP Module - Fetch Content * Retrieves the article from the provided URL in the Google Sheet. 3. OpenAI - Extract Article * Extracts the text article from the raw HTML. This helps clean up the input for our AI writing prompts. 4. OpenAI - Create Content * Write posts for LinkedIn, Twitter, Threads, Facebook, Instagram. * Generate AI image prompt, then generate AI image with DALLE-3. * Write AI video script and caption for AI avatar video for Tiktok. 5. Blotato - Automated Posting * Publish content to social media platforms via Blotato API. ## Setup Google Sheets My Google Sheet is super simple. I just drop in an article URL, and the entire automation runs. You can easily switch this to Airtable, Notion, Slack, etc. depending on your flow. 1. Make a new Google Sheet 2. Create a column with header `URL` 3. Connect the Google Sheet to [Make](https://make.com/?utm_source=www.sabrina.dev\&utm_medium=referral\&utm_campaign=i-built-an-ai-social-media-system) * Select the correct spreadsheet ID and sheet name * Enable "Includes Headers" ## Setup Blotato Next, you’ll need to setup your Blotato API Key and Account IDs: * Login to [Blotato.com](http://blotato.com/?utm_source=www.sabrina.dev\&utm_medium=referral\&utm_campaign=i-built-an-ai-social-media-system) * Go to “Settings” * Copy your API key and account IDs * Paste them into the Make node “Setup Social Accounts” ## Setup Heygen Check out my previous in-depth tutorials on setting up your [AI Clone](https://www.sabrina.dev/p/your-100-automated-ai-clone-makes-talking-videos). You’ll need to sign up for Heygen’s API plan, which is separate from their web app. Within Make, select your Heygen avatar and voice. ## Test Everything After setting up your accounts and connecting them in Make, run the scenario with a real article URL, so that you have sample data flowing through the system. ⚡️ You don’t need to change anything else to get the system working! I also recommend testing one branch at a time. Simply UNLINK the other branches, while you isolate testing one branch. When done, link all branches back to the main router. ⚠️ Common troubleshooting issues: * If posts fail to publish, check your API key and Account IDs. * If your Make variables appear transparent with a colored border, run the scenario once so you have data flowing in the system. * If your avatar video is not generated, most likely you need to upgrade to a paid Heygen API plan OR increase the wait timeout. ## Make Blueprint Once configured, this AI Social Media System will: * Pull content from Google Sheets * Use AI to write social media posts * Use AI to generate images and avatar video * Post automatically to all major platforms # Make Slideshows & Carousels {% embed url="" %} {% embed url="" %} Here's the n8n template: [Make template](https://drive.google.com/file/d/1cYqrbOeR9T7k44R--nvnZj8bLwuGFn4s/view?usp=sharing\&utm_source=www.sabrina.dev\&utm_medium=referral\&utm_campaign=this-ai-agent-automates-slideshows-and-carousels) # FAQs ## How do I use the Source modules in Make.com? The Source modules allow you to extract content from YouTube, TikTok, articles, PDFs, audio, or AI research queries. ### Create Source Module 1. Add a Blotato module 2. Select "Create Source" 3. Choose your source type: * **URL**: YouTube, TikTok, Article, PDF, or Audio URL (auto-detected) * **Text**: Raw text content * **AI Research**: Perplexity-powered web search query 4. Optionally add Custom Instructions to transform the extracted content 5. Run to get a source ID ### Get Source Module 1. Add a Blotato module after Create Source 2. Select "Get Source" 3. Pass the source ID from Create Source 4. Enable "Clean Transcript" to remove timestamps (recommended) 5. Run to retrieve the extracted content ### Scenario Pattern ``` [Create Source] --> [Sleep 5-10s] --> [Get Source] --> [Use Content] ``` Add a Sleep module between Create and Get because extraction is asynchronous. ### Example: YouTube to Visual Content 1. Create Source with YouTube URL 2. Sleep 10 seconds 3. Get Source to retrieve transcript 4. Pass transcript to Blotato Create Visual to make carousels or videos 5. Publish to social platforms *** ## Troubleshooting Make.com and n8n Automations **The most common errors I see are related to:** * wrong API key or account IDs * invalid JSON (e.g. wrongly formatted) * invalid API request (e.g. wrong parameters) * invalid file format (e.g. wrong video dimensions) * you're on the free Creatomate plan and you need to upgrade to export correct video dimensions Tip: Use the official Blotato Make module to avoid manually copying API keys and account IDs. **Here's a step-by-step checklist to troubleshoot your Make.com automation:** * Check your Blotato API key, Account IDs, and Page IDs are correct * Check that the correct Account ID is connected and passed in every Publish API call * If you are publishing to a Facebook Page or Linkedin Company Page, you must also pass the Page ID, in addition to Account ID. * Check your "Failed" dashboard for additional context: * Verify that the JSON data in the HTTP Request contains the right parameters: 1. Ask ChatGPT to check if your **JSON is valid**. 2. Check it again with JSON Validator: [https://jsonlint.com](https://jsonlint.com/) 3. If your JSON is valid, ask ChatGPT to **compare your JSON to Blotato's API docs**. Use this prompt: ``` You are an expert in Blotato API: https://help.blotato.com/api/api-reference/publish-post Check the following JSON is valid and conforms to the Blotato API: PASTE_YOUR_JSON_REQUEST_HERE ``` *** ## Issues with JSON Request to Blotato API? I recommend using ChatGPT to troubleshoot your JSON payload: 1. Ask ChatGPT to check if your **JSON is valid**. 2. Check it again with JSON Validator: [https://jsonlint.com](https://jsonlint.com/) 3. If your JSON is valid, ask ChatGPT to **compare your JSON to Blotato's API docs**. Use this prompt: ``` You are an expert in Blotato API: https://help.blotato.com/api/api-reference/publish-post Check the following JSON is valid and conforms to the Blotato API: PASTE_YOUR_JSON_REQUEST_HERE ``` *** ## Submitting Wrong Video Dimensions to API? I see a lot of errors related to uploading invalid video dimensions. For example, if you're on the free Creatomate plan, you need to upgrade in order to export correct video dimensions. As a sanity check, try uploading this video instead: *** ## How to Preserve Newlines in Multi-Paragraph Posts? To preserve newlines in posts with multiple paragraphs, use the prebuilt Make module "Transform to JSON" and feed in your text. Then, update your HTTP request module: change `text` to use the resulting JSON string.
*** ## How do I get my Heygen avatar video with captions? You'll need to change 2 steps: 1. In the CREATE HEYGEN VIDEO step, there is a setting to enable captions. Make sure it's turned on. 2. In the Blotato Publish step, pass the `video_url_caption` from the GET VIDEO step into the mediaUrls parameter. This will use the video version with captions. Remember to test your workflow after making this change to make sure everything works as expected. *** ## How do you customize text styles in the carousel/slideshow? It's on my roadmap to add more customization options and templates for carousels/slideshows! Right now, the only customization is the caption position (top, middle, bottom). *** ## How do you post a slideshow or carousel? Using the official Blotato node, it's now super easy to post a slideshow or carousel. In your publishing node, update the Media URLs parameter - give it a comma separated list of URLs to be posted as a slideshow/carousel. *** ## I'm using an older template with textToImageModel and imageToVideoModel parameters. Do these still work? Those parameters belong to an outdated template format. If your Create Video module fails with a 400 error like `body.textToImageModel must be object, body.imageToVideoModel must NOT be valid`, this is the cause: the old `POST /v2/videos/creations` request format with `textToImageModel` and `imageToVideoModel` as string fields no longer works. If your scenario uses a raw HTTP module, point it at the current endpoint instead: * **URL:** `POST https://backend.blotato.com/v2/videos/from-templates` * **Body:** ```json { "templateId": "5903fe43-514d-40ee-a060-0d6628c5f8fd", "prompt": "YOUR SCRIPT OR TOPIC HERE", "inputs": {} } ``` That `templateId` is the "AI Video with AI Voice" template. Remove the old `textToImageModel` and `imageToVideoModel` fields entirely, then poll `GET /v2/videos/creations/{id}` for the result. See [Create Visual](/api/create-video) for the full migration guide. Or switch to the new CREATE VISUAL system instead: 1. Browse all available templates at to see how they look 2. In n8n or Make, add the Blotato CREATE VISUAL node and select a template 3. Start with a carousel template -- carousels render near-instantly, so you get a fast test run 4. Click Execute to generate the carousel 5. Open your [API Dashboard](https://my.blotato.com/api-dashboard) to see the JSON payload for each template 6. Override your desired inputs one-by-one If you were making AI story videos, use the template called "AI Video with AI Voice." Full documentation for each template: [Visual Templates](https://help.blotato.com/api/visuals) *** ## How do I schedule a post for a specific time? Set the Scheduled Time field in the Publish module using ISO-8601 format with timezone. Format: `YYYY-MM-DDTHH:MM:SSZ` (UTC) or `YYYY-MM-DDTHH:MM:SS+HH:MM` (with offset) Examples: * `2026-03-10T14:00:00Z` (2:00 PM UTC) * `2026-03-10T09:00:00-05:00` (9:00 AM Eastern) In Make.com expressions, use `formatDate()` to build the timestamp: ``` {{formatDate(now; "YYYY-MM-DDTHH:mm:ssZ")}} ``` Do not pass a date without timezone information. The API rejects timestamps without a timezone offset. *** **Didn't find your answer?** * [General FAQs](/support/faqs) * [API FAQs](https://github.com/Blotato-Inc/help.blotato.com/blob/main/api/faqs.md) * [n8n FAQs](/api/n8n/faqs) # Claude Code Use Claude Code with Blotato to build AI-powered social media workflows from your terminal. Looking for ready-made content skills? See [Free Claude Skills](/claude-skills/claude-skills) for a 5-skill pack covering brand brief, ideation, writing, grading, and scheduling. ## Tutorials ### Build Your AI Personal Assistant for Social Media Marketing Learn how to use Claude Code to build your own AI social media manager. Set up Claude Code and use prompts to write content in your brand voice, generate visuals, and post to social media. {% embed url="" %} ### The ULTIMATE Claude Code Tutorial A full course from first-time setup to building a personalized AI Marketing Officer with skills, quality gate hooks, brand voice, and subagents. {% embed url="" %} ### The ULTIMATE AI Coding Guide for Developers Step-by-step breakdown of AI coding with Claude Code, battle tested with an existing complex codebase. Includes CLAUDE.md rules file and a real feature implementation from scratch. {% embed url="" %} ## Install Claude Code first Claude Code is a terminal app from Anthropic. It is not the Claude chat at claude.ai, and it does not come pre-installed. Install it before connecting Blotato: 1. Install Claude Code from the [official Claude Code page](https://claude.com/claude-code) 2. On a Mac, open Terminal (press Cmd + Space, type "Terminal", press Enter). On Windows, open Command Prompt or PowerShell. 3. Type `claude` and press Enter to start a Claude Code session 4. If you see `command not found: claude`, Claude Code is not installed yet -- repeat step 1 The "no installation required" wording in the [MCP Server docs](/api/mcp) refers to the Blotato MCP server, which runs remotely. Claude Code itself still needs to be installed on your computer. ## Connect Blotato MCP Server to Claude Code To use Blotato tools directly in Claude Code, add the Blotato MCP server: 1. Go to [Settings > API](https://my.blotato.com/settings/api) in the Blotato app 2. Under "Claude Code (Terminal)", click **Copy Setup Command** 3. Paste the command into a Claude Code session and let it apply changes 4. Restart Claude Code Run the setup command inside the Claude Code session in Terminal -- not in a code editor like VS Code. Never paste your API key by itself as a Terminal command (Terminal returns `command not found` for it). The command adds the Blotato MCP server with your API key: ```bash claude mcp add blotato \ --url https://mcp.blotato.com/mcp \ --header "blotato-api-key: YOUR_API_KEY" ``` For the full setup guide, see [MCP Server Setup](/api/mcp/setup). # MCP Server The Blotato MCP Server lets you control your social media workflows directly from AI tools like ChatGPT, Claude.ai, Claude Desktop, Claude Code, Cursor, Antigravity, and Replit Agent. No installation or coding required for the MCP server itself -- it runs remotely. Connect via OAuth or add the server URL and your API key to your AI tool's config, and start giving natural language commands. Your AI tool still needs to be installed on your computer first (for example, the [Claude Code terminal app](/api/claude-code)). ## What You Get * Post to any connected social platform with a single prompt * Schedule posts to your content calendar * View, update, reschedule, and delete scheduled posts * Extract content from YouTube videos, articles, tweets, and more * Generate images, carousels, and videos from templates * Upload local files directly -- no Google Drive or S3 needed * Check the status of your posts and visuals * Compare top-performing posts and review engagement analytics * Read and post comments on your Instagram and Facebook posts * Read and send Instagram and Facebook DMs, with buttons or quick replies * Create DM automations that reply for you when someone comments on your post or messages you ## Tutorials * [Claude + Blotato Beginner Setup](https://www.youtube.com/watch?v=1dSNfnFL40c) * [Build Your AI Personal Assistant for Social Media Marketing](https://youtu.be/3HVH2Iuplqo) * [The ULTIMATE Claude Code Tutorial](https://youtu.be/fYX6hHC9FhQ) For Claude Code-specific tutorials, see [Claude Code](/api/claude-code). ## Quick Setup 1. Connect your social accounts in [Settings](https://my.blotato.com/settings) 2. Add the Blotato MCP server to your AI tool (see [Setup Guide](/api/mcp/setup)) **MCP Server URL**: `https://mcp.blotato.com/mcp` **REST API base URL** (for non-MCP HTTP clients): `https://backend.blotato.com/v2` `api.blotato.com` is **not a valid base URL**. If your AI tool reports a DNS error for `api.blotato.com`, it guessed wrong. Use the URLs above. **Auth**: OAuth (Claude.ai, Claude Desktop, Claude Cowork) or API key header (ChatGPT, Claude Code, Cursor, others) For step-by-step setup instructions, see the [Setup Guide](/api/mcp/setup). For all available tools and parameters, see the [Tools Reference](/api/mcp/tools). For example prompts and multi-step workflows, see [Example Prompts](/api/mcp/examples). Deciding between MCP and plain HTTP calls? See [Should I use the REST API or MCP?](https://github.com/Blotato-Inc/help.blotato.com/tree/main/api/faqs.md#should-i-use-the-rest-api-or-mcp). # Setup Guide Setting up Blotato with ChatGPT, Claude, Antigravity, or Cursor takes a few minutes. Generate your API key: [Settings > API](https://my.blotato.com/settings/api) ## Tutorials Using **Claude.ai Web**? Add Blotato directly here: Paste this URL: `https://mcp.blotato.com/mcp` Step-by-step video walkthrough for setting up Blotato with Claude Desktop and Cowork: * [Claude Cowork and Desktop + Blotato MCP](https://youtu.be/mh4Z9U-oaps) * [Claude + Blotato Beginner Setup](https://www.youtube.com/watch?v=1dSNfnFL40c) Step-by-step video walkthrough for setting up Blotato with Claude Code: * [Claude Code + Blotato MCP](https://youtu.be/3HVH2Iuplqo) * [The ULTIMATE Claude Code Tutorial](https://youtu.be/fYX6hHC9FhQ) (brand voice, quality gates, subagents) ## Prerequisites 1. A paid Blotato subscription 2. At least one connected social account in [Settings](https://my.blotato.com/settings) 3. For ChatGPT, Cursor, and other API-key-based clients: your Blotato API key from [Settings > API](https://my.blotato.com/settings/api) *** ## Claude.ai Web 1. In the left sidebar, click **Customize** > **Connectors**, then click the **+** button > **Add custom connector** 2. Name: `Blotato` 3. URL: `https://mcp.blotato.com/mcp` 4. Press **Connect** and approve access You must be logged into your Blotato account in the same browser to complete the OAuth connection. *** ## Claude Desktop / Claude Cowork 1. In the left sidebar, click **Customize** > **Connectors**, then click the **+** button > **Add custom connector** 2. Name: `Blotato` 3. URL: `https://mcp.blotato.com/mcp` 4. Press **Connect** and approve access You must be logged into your Blotato account in your default browser to complete the OAuth connection. On a Claude Team or Enterprise plan, only a workspace admin can add custom connectors -- if you don't see "Add custom connector," ask your Claude workspace admin to add the Blotato connector for your team. *** ## Claude Code (Terminal) 1. Start a Claude Code session 2. Copy and paste the following command into your session: ```bash claude mcp add \ --transport http \ Blotato https://mcp.blotato.com/mcp ``` 3. Let Claude apply changes 4. Once done, run `/mcp` inside the session 5. Select `Blotato > Authenticate` and approve access 6. Restart Claude Code You must be logged into your Blotato account in your default browser to complete the OAuth connection. *** ## ChatGPT 1. Open **Settings** > **Plugins** > **MCPs**. 2. Click **Add Server**. 3. Select **Streamable HTTP**. 4. Set **URL** to `https://mcp.blotato.com/mcp`. 5. Leave **Bearer token env var** blank. 6. Under **Headers**, set the key to `blotato-api-key`. 7. Paste your full API key from [Blotato Settings > API](https://my.blotato.com/settings/api) into the header value. Replace the `blt_` placeholder shown in the screenshot with your full key. 8. Click **Add**. ![Blotato MCP settings in ChatGPT](/files/U3c9nbU0yvGwCXjMEvld) *** ## Other MCP Clients (Cursor, Antigravity, Codex, Replit Agent, etc.) 1. Go to [Settings > API](https://my.blotato.com/settings/api) in the Blotato app 2. Under "Other MCP Clients", click **Copy MCP Config** 3. Paste the JSON config into your app's MCP settings 4. Restart your app The config adds the Blotato MCP server with your API key: ```json { "mcpServers": { "blotato": { "url": "https://mcp.blotato.com/mcp", "headers": { "blotato-api-key": "YOUR_API_KEY" } } } } ``` Keep the double quotes Blotato gives you and paste the full key inside them, including any trailing `=` characters. The `=` is part of your key. Do not delete it, and do not replace the double quotes with single quotes. Single quotes apply only to shells, `.env` files, and scripts, not to this JSON config. A dropped or deleted trailing `=` causes a 401 "invalid API key" error. ### Form-based setup (streamable HTTP) Some clients, including OpenAI Codex, ask you to fill out a form instead of pasting JSON. Choose the **streamable HTTP** server type, then fill out the fields like this: 1. Go to [Settings > API](https://my.blotato.com/settings/api) in the Blotato app. 2. Click **Copy API Key** (or click **Generate API Key** first if you don't have one yet). 3. Set **URL** to `https://mcp.blotato.com/mcp`. 4. Leave **Bearer token env var** blank. 5. Under **Headers**, set the key to `blotato-api-key` and paste your API key into the **Value** field. 6. Click **Save**. Paste the full key into the Value field, including any trailing `=` characters. A dropped `=` causes a 401 "invalid API key" error. *** ## Verify Your Connection After setup, test the connection by asking your AI tool: > "What social media accounts do I have connected?" The tool calls `blotato_list_accounts` and returns your connected platforms. If you see your accounts listed, the setup is complete. *** ## Upload your own local images or videos via MCP The Blotato MCP tools (`blotato_create_post`, `blotato_create_visual`) do not accept local file paths. Media must be a publicly accessible URL. Allowlisting egress to `database.blotato.io` is necessary but not enough on its own. You still upload the file first. To use a local file: 1. Call `blotato_create_presigned_upload_url` with your filename (include the extension). It returns a `presignedUrl` and a `publicUrl`. 2. Upload the raw file bytes to `presignedUrl` with an HTTP `PUT` (for example `curl -X PUT "" --data-binary "@"`). Send raw bytes, not JSON and not multipart form data. 3. Pass the returned `publicUrl` in the `mediaUrls` field of `blotato_create_post`. Do not pass the local file directly to `blotato_create_post`. If you allowlisted `database.blotato.io` but the upload still fails, the file was likely sent directly instead of being PUT to the presigned URL, or the PUT used the wrong body encoding. *** ## Troubleshooting If the MCP server connects but does not work as expected: 1. **OAuth clients (Claude.ai, Desktop, Cowork, Claude Code):** Make sure you are logged into your Blotato account in the browser. The OAuth approval requires an active Blotato session. 2. **API key clients (ChatGPT, Cursor, etc.):** Double check you copy/pasted the correct API key from [Settings > API](https://my.blotato.com/settings/api). Make sure there are no extra spaces or missing characters. If your key ends with one or more `=` characters, copy the full key including the trailing `=`, since dropping it causes a 401 "invalid API key" error. 3. Restart your AI tool after adding the MCP server. MCP servers load on startup. * **"Auth unsupported" or OAuth errors in API-key clients (Codex, Cursor, etc.):** This means the client cannot complete the OAuth browser flow. Do not use the `https://mcp.blotato.com/mcp` OAuth URL on its own. Use the API-key JSON config from the "Other MCP Clients" section above, which authenticates with the `blotato-api-key` header instead of OAuth. 4. Tell your AI tool the connection is correct and point it to the help docs. For example: "My Blotato MCP is connected. Reference this doc for instructions: " 5. If Blotato shows "Connected" in Claude Settings but Claude.ai returns an OAuth error when you ask it to list accounts or use any Blotato tool, your Blotato subscription is not active. Go to [Settings > API](https://my.blotato.com/settings/api) and click "Generate API Key" to activate your paid subscription. API access requires a paid plan. 6. Verify you have at least one social account connected in [Settings](https://my.blotato.com/settings). 7. If you get a JSON parsing error in your config file, validate it at [jsonlint.com](https://jsonlint.com). A common mistake is a missing comma between sections. 8. **Connector shows "Connected" but never authenticates (stale connector session).** If the Blotato connector in Claude Cowork or Claude Desktop shows Connected but every tool call fails with a credential error, and reconnecting does not help, the client is reusing a stale cached session. A simple reconnect reuses that same cached session, so remove it fully and add it fresh: 1. Go to **Customize > Connectors** and fully remove the Blotato connector 2. Click the **+** button, choose **Add custom connector**, and approve access again 3. To double-check the key itself, see [Settings > API](https://my.blotato.com/settings/api) 9. **"Access to this website is blocked by your network egress settings" during a presigned upload.** Claude Cowork and Claude Desktop block outbound network access by default, so the `PUT` to the presigned upload URL cannot reach `database.blotato.io`. To allow it: 1. Go to **Claude Cowork/Desktop > Settings > Capabilities > Allow network egress** 2. Set **"Package managers only"** 3. Under **Additional allowed domains**, add `database.blotato.io` and click **Add** 4. Fully quit and restart Claude Cowork/Desktop 5. If your settings look correct but the upload stays blocked, set **Allow network egress** to **"Allow all"** instead of **"Package managers only"**, then restart and retry Video walkthroughs: [Claude + Blotato Beginner Setup](https://www.youtube.com/watch?v=1dSNfnFL40c) and [Build Your AI Personal Assistant for Social Media Marketing](https://youtu.be/3HVH2Iuplqo) # Tools Reference The Blotato MCP Server exposes 35 tools. Your AI tool calls these automatically based on your prompts. ## Accounts ### blotato\_get\_user Get your account info and verify the connection is working. * **Input**: none * **Output**: user ID, email, subscription status ### blotato\_list\_accounts List all connected social media accounts with subaccounts (for Facebook Pages and LinkedIn Company Pages). * **Input**: `platform` (optional) - filter by platform name * **Output**: array of accounts with ID, platform, name, username, and subaccounts ### blotato\_list\_pinterest\_boards List boards owned by a connected Pinterest account. Use this to get the `boardId` required when publishing a Pinterest pin. * **Input**: `accountId` (required) - Pinterest account ID from blotato\_list\_accounts * **Output**: array of boards with `id` and `name`. Use `id` as `boardId` in blotato\_create\_post. *** ## Credits ### blotato\_get\_credits Get the account's remaining credits, the account email the API key belongs to, and current pricing (price per 1,000 credits and the min/max purchase quantity). * **Output**: `creditsRemaining`, `accountEmail`, `purchaseQuantityRange` (`min` and `max`), and `pricePer1000CreditsUsd`. ### blotato\_buy\_credits Create a Stripe Checkout link to buy credits. This does NOT charge anything by itself -- it returns a `checkoutUrl` the account owner opens in a browser to complete payment. Purchased credits land on this account. Confirm the account email with blotato\_get\_credits first, since credits are non-transferable between accounts. * **Input**: `quantity` (required) - credits to buy, between 1000 and 10000. * **Output**: `checkoutUrl` - the Stripe Checkout link to open in a browser. ## Publishing ### blotato\_create\_post Create and publish (or schedule) a post to a social media platform. * **Input**: * `accountId` (required) - from blotato\_list\_accounts * `platform` (required) - twitter, instagram, facebook, tiktok, linkedin, pinterest, bluesky, threads, or youtube * `text` (required) - post content * `mediaUrls` (optional) - array of public media URLs * `scheduledTime` (optional) - ISO 8601 datetime * `useNextFreeSlot` (optional) - use next available schedule slot * `pageId` (optional) - for Facebook/LinkedIn pages * `mediaType` (optional) - for Instagram/Facebook: reel or story. Facebook videos must be `"reel"` (regular feed videos no longer supported). * `trial` (optional) - for Instagram reels: object with `graduationStrategy` (`"MANUAL"` or `"SS_PERFORMANCE"`). Trial reels are shown to non-followers first. * `firstComment` (optional) - for Facebook/Instagram: text auto-posted as the first comment right after publishing. Not supported for stories. Useful for links. * `privacyLevel` (optional) - for TikTok * `additionalPosts` (optional) - array of additional posts for threads (Twitter, Bluesky, Threads). Each entry has `text` and `mediaUrls`. The first post uses the top-level `text` and `mediaUrls` fields. Blotato handles reply chaining. * `boardId` (optional) - for Pinterest (get from blotato\_list\_pinterest\_boards) * `title` (optional) - for Pinterest or YouTube * `privacyStatus` (optional) - for YouTube: public, private, or unlisted * `playlistIds` (optional) - for YouTube: array of playlist IDs from blotato\_list\_accounts to add the video to playlists * `thumbnailUrl` (optional) - for YouTube: publicly accessible image URL for a custom thumbnail. Requires a verified YouTube account in good standing * **Output**: postSubmissionId (poll with blotato\_get\_post\_status) ### blotato\_get\_post\_status Check the status of a submitted post. * **Input**: `postSubmissionId` (required) * **Output**: status, publicUrl (when published), errorMessage (when failed) * **Status values**: in-progress -> published | scheduled | failed ### blotato\_list\_posts 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. Each item includes a `state` field with a `type` of `scheduled`, `published` (includes `postUrl`), or `failed` (includes `errorMessage`). * **Input**: * `since` (optional) - ISO 8601 timestamp. Defaults to 7 days ago. * `until` (optional) - ISO 8601 timestamp. Defaults to 7 days from now. * `limit` (optional) - number of posts per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `status` (optional) - array of statuses to include: `scheduled`, `published`, `failed`. Omit to include all. * `platform` (optional) - array of platforms to include: twitter, instagram, linkedin, facebook, tiktok, pinterest, threads, bluesky, youtube. Omit to include all. * **Output**: array of posts with `id`, `postTime`, `platform`, `text`, `mediaUrls`, and a `state` object. Includes `cursor` for the next page when more pages are available. *** ## Analytics ### blotato\_list\_top\_posts List your top performing published posts, ranked by an 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. Metric values are returned as strings because counts can exceed normal number precision. * **Input**: * `since` (optional) - ISO 8601 timestamp. Only include posts published on or after this time. Defaults to 30 days ago. * `until` (optional) - ISO 8601 timestamp. Only include posts published on or before this time. Defaults to now. * `platform` (optional) - filter to a single platform: twitter, instagram, facebook, threads, or bluesky. Omit to include all. Analytics for other platforms are not collected yet. * `sortBy` (optional) - metric to rank by: `likes_count`, `comments_count`, `views_count`, or `reach_count`. Defaults to `views_count`. * `limit` (optional) - number of posts to return. Min: 1, Max: 100. Default: 20 * **Output**: array of `items`, each with `id`, `content`, `postUrl`, `platform`, `createdAt`, `mediaUrls`, `latestMetrics`, and `metricsHistory`. ### blotato\_get\_post\_analytics 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. * **Input**: `id` (required) - published post id from blotato\_list\_posts or blotato\_list\_top\_posts * **Output**: `publishedPostId`, `platform`, `lastFetchedAt`, `lastError`, `metrics` (latest, or null when not synced yet), and `history` (array of snapshots, each with `fetchedAt` and `metrics`). ## Comments Read and post comments on your published Instagram and Facebook posts, both audience replies and comments you post through Blotato. ### blotato\_list\_comments List comments on your published posts, ordered by creation time (most recent first). Supports cursor-based pagination and optional filters. Each comment includes an `isAuthor` flag: `true` for comments you posted, `false` for audience replies. * **Input**: * `limit` (optional) - number of comments per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `platform` (optional) - filter by platform: `instagram` or `facebook` * `accountId` (optional) - filter to a single connected account * `parentCommentId` (optional) - filter to direct replies to a single comment * `postId` (optional) - filter to comments on a single Blotato-published post (from blotato\_list\_posts) * `since` (optional) - only include comments created on or after this ISO 8601 timestamp * `until` (optional) - only include comments created on or before this ISO 8601 timestamp * **Output**: array of comments with `id`, `text`, `status`, `isAuthor`, `platform`, `postId`, `parentCommentId`, `createdAt`, and `errorMessage` (when failed). Includes `cursor` for the next page when present. ### blotato\_get\_comment Get a single comment by its Blotato ID. * **Input**: `commentId` (required) - comment ID from blotato\_list\_comments * **Output**: `id`, `text`, `status`, `isAuthor`, `platform`, `postId`, `createdAt`, and `errorMessage` (when failed) ### blotato\_post\_comment Post a comment on one of your published Instagram or Facebook posts, or a reply to an existing top-level comment when you pass `parentCommentId`. Blotato queues the comment and posts it in the background. To check the status of the comment, poll with blotato\_get\_comment. Replies to audience comments count toward your plan's monthly active-contacts limit. * **Input**: * `postId` (required) - Blotato ID of the published post (from blotato\_list\_posts) * `text` (required) - comment body. Instagram allows up to 2200 characters, Facebook up to 8000 * `parentCommentId` (optional) - Blotato ID of a top-level, posted comment on the same post to reply to. Replies to replies are not supported * **Output**: the queued comment (poll with blotato\_get\_comment) * **Status values**: queued -> processing -> posted | failed *** ## Messages Read and send direct messages on your Instagram account and Facebook Page. Reply to people who already have a conversation with you. ### blotato\_list\_conversations List your direct-message conversations, ordered by most recent activity. Supports cursor-based pagination and optional filters. * **Input**: * `limit` (optional) - number of conversations per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `platform` (optional) - filter by platform: `instagram` or `facebook` * `accountId` (optional) - filter to a single connected account * **Output**: array of conversations with `id`, `platform`, `participants`, `updatedAt`, and `createdAt`. Includes `cursor` for the next page when present. ### blotato\_get\_conversation Get a single conversation by its Blotato ID. * **Input**: `conversationId` (required) - conversation ID from blotato\_list\_conversations * **Output**: conversation object with `id`, `platform`, `participants`, and `updatedAt` ### blotato\_list\_messages List your messages, ordered by creation time (most recent first). Supports cursor-based pagination and optional filters. * **Input**: * `limit` (optional) - number of messages per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * `conversationId` (optional) - filter to a single conversation * `platform` (optional) - filter by platform: `instagram` or `facebook` * `accountId` (optional) - filter to a single connected account * **Output**: array of messages with `id`, `conversationId`, `direction`, `text`, `payload`, `status`, `senderId`, `recipientId`, and `createdAt`. `direction` is `incoming` for messages you receive and `outgoing` for messages you send. Includes `cursor` for the next page when present. ### blotato\_get\_message Get a single message by its Blotato ID. Poll this after blotato\_send\_message to check whether an outgoing message reached `sent` or `failed`. * **Input**: `messageId` (required) - message ID from blotato\_list\_messages * **Output**: message object with `id`, `conversationId`, `direction`, `text`, `payload`, `status`, `senderId`, `recipientId`, and `createdAt` ### blotato\_send\_message Send a direct message to one recipient, or a private reply to a comment. Blotato queues the message and sends it in the background. To check the status, poll with blotato\_get\_message. * **Input**: * `accountId` (required) - connected account to send from (from blotato\_list\_accounts) * `platform` (required) - `instagram` or `facebook` * `pageId` (required for Facebook) - the Facebook Page to send from (from the account's subaccounts via blotato\_list\_accounts) * `recipientId` (required) - the other party's id. Use an incoming message's `senderId` (from blotato\_list\_messages) * `text` (required) - message body. Instagram messages are limited to 1000 bytes, Facebook to 2000 characters. With `buttons` set, the limit drops to 640 characters * `commentId` (optional) - to send a private reply to a comment instead of a direct message, pass the comment's Blotato ID * `buttons` (optional) - Facebook and Instagram only. 1 to 3 call-to-action buttons pinned under the message. See [Buttons and Quick Replies](#buttons-and-quick-replies) * `quickReplies` (optional) - Facebook and Instagram only. 1 to 13 tappable reply chips. See [Buttons and Quick Replies](#buttons-and-quick-replies) * **Output**: the queued message (poll with blotato\_get\_message) * **Status values**: queued -> processing -> sent | failed ### Buttons and Quick Replies Facebook and Instagram messages may be sent with attached buttons or quick replies via `buttons` or `quickReplies`. They are mutually exclusive - pass one or the other, never both. **Buttons** sit under the message and stay there. Each has: * `type` - `web_url` opens a link, `postback` reports the tap back to you * `title` - button label, 1 to 20 characters * `url` - required for `web_url`, starts with `https://` * `payload` - required for `postback`, 1 to 1000 characters Blotato supports `web_url` and `postback` buttons. Phone buttons are not supported. **Instagram renders buttons in the mobile app only.** A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons. Pass `buttons` or a URL inside `text`, not both, since a message carrying both leaves the URL unclickable on desktop. For a desktop audience, drop `buttons` and put the URL in `text`. **Quick replies** are tappable chips offered as canned answers. They disappear once the person taps one or types their own message. Each has a `title` (1 to 20 characters) and a `payload` (1 to 1000 characters). **Reading a tap.** Both kinds of tap arrive as the next incoming message carrying `payload.selection`, readable with blotato\_list\_messages. A quick-reply tap sends a real text message, so `text` holds the chip label. A postback sends no text message: the tap is recorded as an incoming message with `text` set to the button label. Either way, branch on `selection.payload` rather than `text`, since two chips sharing a label are distinguishable only by payload. A `web_url` button produces no selection. **Reconnect for postback buttons.** Blotato subscribes your account to the postback webhook when you connect it. If you connected your account before buttons were launched, [reconnect](https://my.blotato.com/settings) to start receiving postback events. Quick-reply taps need no reconnect. See [Buttons and Quick Replies](/api/messages#buttons-and-quick-replies) for the REST equivalent. *** ## Automations Create and manage DM automations on Instagram and Facebook Pages. An automation sends one direct message when someone comments on your post or sends your account a message. See [DM Automations](/features/dm-automations). An automation sends one message by default. Three optional steps extend it, and Blotato runs them in a fixed order: a follow gate (Instagram only), an email gate, your message, then a webhook. Every DM an automation sends counts toward your plan's monthly active-contacts limit. Gate messages go to the same person, so one contact still counts once. See [Active Contacts](/settings/billing-and-credits#active-contacts). ### blotato\_create\_automation Create a DM automation. It starts as an inactive draft unless `isActive` is true. You can add an email gate, an Instagram follow gate, or a webhook. * **Input**: * `accountId` (required) - Instagram or Facebook account from blotato\_list\_accounts * `platform` (required) - `instagram` or `facebook` * `pageId` (required for Facebook) - the Facebook Page from the account's subaccounts * `name` (required) - automation label * `trigger` (required) - `type` (`comment-received` or `message-received`), `keywords` (omit or empty to match anything), `postId` (comment triggers only, the Blotato post ID to watch, omit for any post), `isActive` (default true) * `dmMessage` (required) - the message sent when the trigger fires, 1 to 640 characters * `buttons` (optional) - up to 3 link buttons, each with `type: "url"`, a `title` of 20 characters or fewer, and a `url` * `followGate` (optional, Instagram only) - `message` (1 to 640 characters) and `buttonTitle` (20 characters or fewer, default `I'm following`). Holds the DM back until the contact follows the account. Rejected on a Facebook automation * `emailGate` (optional) - `message` (1 to 640 characters). Holds the DM back until the contact replies with an email address * `webhook` (optional) - `method` (`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`), `url` (public `http(s)`, 2048 characters or fewer), and `headers` (optional). Called once the DM sends * `isActive` (optional) - true publishes it immediately. Default false * **Output**: the created automation **Follow gate.** Blotato sends the gate message with a confirm button, waits up to 1 hour for a reply, then reads follower status. A contact who does not follow gets the gate message again. An unknown status sends the DM anyway, since Instagram withholds follower status for a contact who never granted profile access. A confirmed follow is reused for 30 days. Any reply advances the follow gate, so the button tap is a shortcut rather than a requirement. Two setup points to pass on to the user. The Instagram account needs reconnecting if they connected it before DM automations and follow gating landed, since Blotato subscribes to button-tap events at connect time and an older connection does not reliably receive them, leaving runs to expire. Instagram also renders the confirm button in the mobile app only, so write the gate `message` to ask for a typed reply such as "Reply FOLLOWING once you have" in the message text. **Email gate.** Blotato sends the gate message, waits up to 1 hour, and reads the first email address out of the reply. A reply holding no address returns the gate message. A match saves to the contact, then the DM sends. A webhook is the only way to read a captured address, since blotato\_list\_conversations and blotato\_list\_messages do not return it. **Webhook.** Every method except `GET` carries a JSON body: `{"email": "them@example.com"}` with an email gate, `{}` without. `GET` carries no body. The host must resolve to a public address, redirects are not followed, and the timeout is 10 seconds. A non-2xx response gets logged and the run still completes. A blocked address, a DNS failure, or a timeout fails the run with error code 20304. ### blotato\_list\_automations List your DM automations, ordered by creation time (most recent first). Supports cursor-based pagination. * **Input**: * `limit` (optional) - number of automations per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * **Output**: array of automations with `id`, `name`, `platform`, `target`, `trigger`, `dmMessage`, `buttons`, `emailGate`, `followGate`, `webhook`, `isActive`, and `createdAt`. Includes `cursor` for the next page when present. ### blotato\_update\_automation Update a DM automation. Any of `name`, `trigger`, `dmMessage`, `buttons`, `followGate`, `emailGate`, or `webhook` you pass replaces that field. Omitted fields stay unchanged. Pass `null` to remove a trigger, a gate, or a webhook. Content changes to a live automation publish immediately. Changes to a draft stay saved until you pass `isActive` true. A live automation needs a trigger, so to clear the trigger pass `isActive` false in the same call. * **Input**: * `automationId` (required) - automation ID from blotato\_list\_automations * `name` (optional) - new automation label * `trigger` (optional) - replaces the trigger * `dmMessage` (optional) - replaces the message text * `buttons` (optional) - replaces the link buttons * `followGate` (optional, Instagram only) - replaces the follow gate. Pass null to remove it * `emailGate` (optional) - replaces the email gate. Pass null to remove it * `webhook` (optional) - replaces the webhook. Pass null to remove it * `isActive` (optional) - true publishes, false moves to draft. Omit to keep the current state * **Output**: the updated automation ### blotato\_delete\_automation Archive a DM automation. Its trigger stops listening and the automation stops firing. Runs already in flight finish. * **Input**: `automationId` (required) - automation ID from blotato\_list\_automations * **Output**: the archived automation ### blotato\_list\_automation\_runs List the execution runs of one automation, ordered by start time (most recent first). A run is one execution: one comment or message matched the trigger. Use it to check whether an automation fires and why a reply did not go out. * **Input**: * `automationId` (required) - automation ID from blotato\_list\_automations * `limit` (optional) - number of runs per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * **Output**: array of runs with `id`, `contactId`, `platform`, `status`, `error` (when failed), `createdAt`, and `updatedAt` * **Status values**: running, waiting, completed, expired, superseded, failed. A run expires when the contact never answers a gate inside the 1-hour window. A run is superseded when a newer run starts waiting on the same contact ### blotato\_list\_automation\_logs List the execution logs written as an automation's runs advance, ordered by creation time (most recent first). * **Input**: * `automationId` (required) - automation ID from blotato\_list\_automations * `flowRunId` (optional) - filter to a single run, from blotato\_list\_automation\_runs * `limit` (optional) - number of logs per page. Min: 1, Max: 250. Default: 50 * `cursor` (optional) - pagination cursor from a previous response * **Output**: array of logs with `id`, `flowRunId`, `nodeId`, `level` (`info`, `warning`, `error`), `message`, `context`, and `createdAt` ### blotato\_get\_automation\_analytics Get all-time run totals for one automation: how many times it was triggered, and how many of those runs completed or failed. Runs still in flight, and runs ending as expired or superseded, count toward `triggered` but not toward either outcome, so `completed` plus `failed` is sometimes lower than `triggered`. * **Input**: `automationId` (required) - automation ID from blotato\_list\_automations * **Output**: `triggered`, `completed`, `failed` *** ## Content Extraction ### blotato\_create\_source Extract content from a URL or text. Polls internally for up to 20 seconds and returns the result directly. If still processing (e.g., a long YouTube video), returns the source ID -- use blotato\_get\_source\_status to poll for completion. * **Input**: * `sourceType` (required) - youtube, article, twitter, tiktok, text, audio, pdf, or perplexity-query * `url` (optional) - required for URL-based source types * `text` (optional) - required for text and perplexity-query source types * `customInstructions` (optional) - guide extraction (e.g., "focus on key takeaways", "summarize in 5 bullet points") * **Output**: id, status, title, content (extracted text), and referenceUrl ### blotato\_get\_source\_status Check the status of a source extraction. Use this if blotato\_create\_source timed out and returned an in-progress status. * **Input**: `id` (required) - source ID from blotato\_create\_source * **Output**: status, title, content (when completed), errorMessage (when failed) * **Status values**: queued -> processing -> completed | failed *** ## Videos and Images ### blotato\_list\_visual\_templates List all available visual templates (videos, carousels, quote cards, infographics). * **Input**: `search` (optional) - filter templates by title or description * **Output**: array of templates with ID, name, and description ### blotato\_create\_visual Generate an image, carousel, or video from a template. * **Input**: * `templateId` (required) - from blotato\_list\_visual\_templates * `prompt` (optional) - describe what you want in natural language * `render` (optional, default: true) * **Output**: visual ID and status (poll with blotato\_get\_visual\_status) ### blotato\_get\_visual\_status Check the status of a visual generation request. * **Input**: `id` (required) * **Output**: status, mediaUrl (for videos), imageUrls (for images/carousels) * **Status values**: queueing -> generating-script -> script-ready -> generating-media -> media-ready -> exporting -> done | failed *** ## Content Calendar ### blotato\_list\_schedules List all future scheduled posts, ordered by scheduled time (ascending). Supports cursor-based pagination. Each schedule includes the draft content (same structure as the `post` object in blotato\_create\_post), the scheduled time in UTC, and the target account information. * **Input**: * `limit` (optional) - number of schedules per page. Min: 1, Max: 50. Default: 20 * `cursor` (optional) - pagination cursor from a previous response * **Output**: array of schedules with ID, scheduledAt, account info, and draft content. Includes `count` (total) and `cursor` (for next page, if present). ### blotato\_get\_schedule Get a single scheduled post by ID. Returns the full schedule details including draft content, scheduled time, and account info. * **Input**: `id` (required) - schedule ID from blotato\_list\_schedules * **Output**: schedule object with ID, scheduledAt, account, and draft ### blotato\_update\_schedule Update a scheduled post's content, scheduled time, or both. At least one field is required. The scheduled time must be a valid ISO 8601 date string in the future. When the time changes, the post is re-queued for publishing at the new time. To update the post content, provide the same fields as blotato\_create\_post (accountId, platform, text, mediaUrls, and platform-specific fields). Send the full post object -- partial updates are not supported. * **Input**: * `id` (required) - schedule ID from blotato\_list\_schedules * `scheduledTime` (optional) - new ISO 8601 timestamp, must be in the future * `post` (optional) - updated post object with accountId, platform, text, mediaUrls, and platform-specific fields * **Output**: confirmation message ### blotato\_delete\_schedule Delete a scheduled post and cancel its publishing job. This action cannot be undone. * **Input**: `id` (required) - schedule ID from blotato\_list\_schedules * **Output**: confirmation message *** ## Media ### blotato\_create\_presigned\_upload\_url Get a presigned URL to upload a local file directly to Blotato. No intermediate storage (Google Drive, S3) required. * **Input**: `filename` (required) - filename with extension, used to determine content type (e.g., "photo.jpg", "video.mp4") * **Output**: `presignedUrl` (URL to PUT the file to, expires after a short period) and `publicUrl` (the final public URL to use in blotato\_create\_post) * **Max file size**: depends on your plan (see [Plan Limits](/settings/billing-and-credits#plan-limits)) * **Rate limit**: 120 requests per minute **How to use:** 1. Call `blotato_create_presigned_upload_url` with your filename 2. PUT the file contents to the returned `presignedUrl` with the correct Content-Type header 3. Use the returned `publicUrl` in blotato\_create\_post's `mediaUrls` field If your media is already at a public URL, you don't need to upload it first -- pass the URL directly into blotato\_create\_post's `mediaUrls` field. The presigned upload tool is for local files that don't have a public URL yet. # Example Prompts The Blotato MCP Server translates your natural language prompts into the right sequence of API calls. Here are common prompts and how they work behind the scenes. ## Prompt-to-Tool Mapping | What You Say | Tools Called | How It Works | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Post 'Hello world' to my Twitter" | `blotato_list_accounts` -> `blotato_create_post` | 2 calls. Finds your Twitter account ID, creates and publishes the post. Returns the published URL. | | "Schedule a LinkedIn post for Friday at 3pm" | `blotato_list_accounts` -> `blotato_create_post` | 2 calls. Finds your LinkedIn account, creates the post with scheduledTime. Confirms the scheduled time. | | "Summarize this YouTube video and post it to Instagram" | `blotato_create_source` -> `blotato_list_accounts` -> `blotato_create_post` | 3 calls. Extracts the video transcript, rewrites it for Instagram, then publishes with the right media type. | | "What accounts do I have connected?" | `blotato_list_accounts` | 1 call. Returns all connected accounts with subaccounts and platform details. | | "How many credits do I have left?" | `blotato_get_credits` | 1 call. Returns your remaining credits, account email, and current pricing. | | "Buy 5,000 credits" | `blotato_get_credits` -> `blotato_buy_credits` | 2 calls. Confirms your account email, then returns a Stripe Checkout link to open and complete the purchase. Creating the link does not charge you. | | "Create an infographic about 5 AI trends" | `blotato_list_visual_templates` -> `blotato_create_visual` | 2 calls. Picks a suitable template, passes your prompt. AI fills in the content and layout. | | "Make a carousel of motivational quotes" | `blotato_list_visual_templates` -> `blotato_create_visual` -> `blotato_get_visual_status` | 2-3 calls. Picks a carousel template, generates the visual. Polls for completion if needed. | | "Generate a product showcase image for my new sneakers" | `blotato_list_visual_templates` -> `blotato_create_visual` | 2 calls. Picks a template, passes your prompt with product details. Template AI handles layout and styling. | | "Create a short video about my coffee brand and post it to TikTok" | `blotato_list_visual_templates` -> `blotato_create_visual` -> `blotato_get_visual_status` -> `blotato_list_accounts` -> `blotato_create_post` | 4-5 calls. Full pipeline: pick video template -> generate video -> poll until done -> find TikTok account -> publish with the video URL. | | "I want to make a quote card image" | `blotato_list_visual_templates` -> `blotato_create_visual` | 2 calls. Picks a quote card template, generates the image. Returns image URLs usable in a follow-up post. | | "Check on my visual I created earlier" | `blotato_get_visual_status` | 1 call. Checks the status of a previous visual generation using its ID. | | "Show me my scheduled posts" | `blotato_list_schedules` | 1 call. Returns all future scheduled posts with their content, times, and target accounts. | | "What did I publish on Instagram last week?" | `blotato_list_posts` | 1 call. Returns published Instagram posts in the time window with their public URLs. | | "Which of my Twitter posts failed this month?" | `blotato_list_posts` | 1 call. Filters by `status=failed` and `platform=twitter`; returns each failure's `errorMessage`. | | "Show me everything I posted or scheduled across all platforms recently" | `blotato_list_posts` | 1+ calls. Filters by `status=published,scheduled`; pages through results if there are many. | | "Show me recent comments on my Instagram posts" | `blotato_list_comments` | 1 call. Returns recent comments with their text, author, and status. | | "Comment 'Thanks everyone!' on my latest Instagram post" | `blotato_list_posts` -> `blotato_post_comment` | 2 calls. Finds your latest published Instagram post, then posts the comment on it. | | "Did my comment post yet?" | `blotato_get_comment` | 1 call. Looks up the comment by its ID and returns its current status (queued, posted, or failed). | | "What are my top posts this month?" | `blotato_list_top_posts` | 1 call. Returns your best published posts ranked by views (or another metric). | | "Get my top performing posts from last week and remix them into fresh viral ideas" | `blotato_list_top_posts` | 1 call. Returns last week's strongest posts, then uses their topics and formats to propose new ideas. | | "How is my latest Instagram post performing?" | `blotato_list_posts` -> `blotato_get_post_analytics` | 2 calls. Finds the published post, then returns its full metrics and history. | | "Fetch all the comments from my last 5 Instagram posts, summarize what people think, and recommend what I should post next" | `blotato_list_posts` -> `blotato_list_comments` | 6 calls. Finds the five posts, reads their comments, summarizes sentiment and themes, then recommends content ideas. | | "Find the positive-sentiment comments on my last 10 Facebook posts and draft a reply to each one saying, 'I'd love to chat!'" | `blotato_list_posts` -> `blotato_list_comments` | 11 calls. Finds the posts, reads their comments, classifies sentiment, and drafts replies for your review without sending them. | | "Show me my recent Instagram conversations" | `blotato_list_conversations` | 1 call. Returns your direct-message conversations, most recent first. | | "Reply 'Thanks!' to my latest message from @jamie" | `blotato_list_messages` -> `blotato_send_message` | 2 calls. Finds the conversation and the sender's id, then sends the reply. | | "Reschedule my LinkedIn post to Friday at 5pm" | `blotato_list_schedules` -> `blotato_update_schedule` | 2 calls. Lists schedules to find the LinkedIn post, then updates its scheduled time. | | "Delete my scheduled Twitter post" | `blotato_list_schedules` -> `blotato_delete_schedule` | 2 calls. Lists schedules to find the Twitter post, then deletes it and cancels the publishing job. | | "Change the text on my next scheduled Instagram post" | `blotato_list_schedules` -> `blotato_list_accounts` -> `blotato_update_schedule` | 3 calls. Lists schedules to find the post, fetches accounts for the required fields, then updates the draft content. | | "Analyze this article and turn it into a thread" | `blotato_create_source` -> `blotato_list_accounts` -> `blotato_create_post` | 3 calls. Extracts the article content, splits it into thread segments, publishes as one thread using additionalPosts\[]. | | "Remix this YouTube video into a fresh post" | `blotato_create_source` -> `blotato_list_accounts` -> `blotato_create_post` | 3 calls. Extracts the video transcript (YouTube or TikTok, English captions only), the AI tool adapts it into a new post, then publishes or schedules it. | | "Post this update to my Sunrise Bakery Facebook page" | `blotato_list_accounts` -> `blotato_create_post` | 2 calls. Lists all accounts and subaccounts, matches "Sunrise Bakery" Facebook page, publishes with the correct pageId. | | "Upload this photo from my desktop and post it to Instagram" | `blotato_create_presigned_upload_url` -> `blotato_list_accounts` -> `blotato_create_post` | 3 calls. Gets a presigned upload URL, uploads the local file, then publishes using the returned public URL. No Google Drive or S3 needed. | | "Walk me through how to set up a Blotato DM Automation" | `blotato_list_accounts` -> `blotato_create_automation` | The AI tool asks for the account, trigger, optional keywords, message, and links before creating the automation. | | "Set up a comment-based automation on my latest Instagram post. Ask for a follow and an email before sending my link, then post the email to my CRM" | `blotato_list_accounts` -> `blotato_list_posts` -> `blotato_create_automation` | Sets `followGate`, `emailGate`, and `webhook` on one automation. | *** ## Multi-Step Workflows ### Repurpose a YouTube Video to Multiple Platforms > "Take this YouTube video \[URL], summarize it, create a carousel, and post it to Instagram and LinkedIn" 1. `blotato_create_source` - extracts the video transcript 2. `blotato_list_visual_templates` - finds carousel templates 3. `blotato_create_visual` - generates the carousel from the summary 4. `blotato_get_visual_status` - waits for the carousel to finish 5. `blotato_list_accounts` - finds your Instagram and LinkedIn accounts 6. `blotato_create_post` (x2) - posts to both platforms ### Schedule a Week of Content > "Create 5 different quote cards and schedule them to my Twitter, one per day starting Monday" 1. `blotato_list_visual_templates` - finds quote card templates 2. `blotato_create_visual` (x5) - generates 5 quote cards with different prompts 3. `blotato_get_visual_status` (x5) - waits for each to finish 4. `blotato_list_accounts` - finds your Twitter account 5. `blotato_create_post` (x5) - schedules each with a different scheduledTime ### Review and Reschedule Content > "Show me everything I have scheduled for this week. Move anything on Monday to Tuesday instead." 1. `blotato_list_schedules` - fetches all future scheduled posts 2. AI filters for posts scheduled on Monday 3. `blotato_update_schedule` (xN) - updates each Monday post's scheduledTime to Tuesday at the same time ### Upload a Local File and Post It > "Post this video on my desktop to TikTok and Instagram" 1. `blotato_create_presigned_upload_url` - gets a presigned URL for the file 2. AI uploads the file to the presigned URL via HTTP PUT 3. `blotato_list_accounts` - finds your TikTok and Instagram accounts 4. `blotato_create_post` (x2) - posts to both platforms using the public URL from step 1 No need to upload the file to Google Drive or S3 first. The presigned URL lets you upload directly to Blotato. ### Research and Publish > "Research the latest AI trends and create a thread about it on Twitter" 1. `blotato_create_source` - uses perplexity-query to research the topic 2. `blotato_list_accounts` - finds your Twitter account 3. `blotato_create_post` - publishes as a thread using additionalPosts\[] for the additional tweets ### Triage new comments and DMs > "Show me every new comment and DM I have not answered since yesterday" 1. `blotato_list_comments` - lists recent comments filtered by `since`. Audience comments have `isAuthor: false`. 2. `blotato_list_conversations` - lists your recent DM threads. 3. `blotato_list_messages` - lists recent messages filtered by `since`. Incoming messages have `direction: incoming`. 4. AI groups the results into questions, positive replies, and action items, then drafts suggested responses. This recipe reads only and sends nothing. ### Reply to comments on a post > "Reply to every unanswered comment that expresses interest in my business on my latest Instagram post with a link to my website." 1. `blotato_list_posts` - finds your latest published post and its `postId`. 2. `blotato_list_comments` - lists the post's comments (`postId`, `isAuthor: false`). 3. `blotato_post_comment` - posts a reply to each comment with `parentCommentId` set to the comment ID. 4. `blotato_get_comment` - polls each reply until its status reaches `posted` or `failed`. Blotato posts top-level comments and one level of replies. You reply to a top-level comment (a comment without a `parentCommentId`), not to a reply. ### Turn a comment keyword into a private reply (comment-to-DM) > "When someone comments PRICE on my product post, send them the link in a private reply" Set up a DM automation once, and Blotato watches the post and answers every matching comment on its own. You do not run a workflow per comment. 1. `blotato_list_accounts` - finds the Instagram account (for Facebook, also grab the `pageId` from its subaccounts). 2. `blotato_create_automation` - creates the automation with a `comment-received` trigger, `keywords: ["PRICE"]`, the `dmMessage`, and one link button. Pass `isActive: true` to publish it. 3. `blotato_get_automation_analytics` - checks how many times it fired. 4. `blotato_list_automation_runs` - lists individual runs and the error on each failure. To watch one specific post instead of every post, pass its Blotato `postId` in the trigger. Get it from `blotato_list_posts`. To answer keyword DMs instead of comments, use a `message-received` trigger. ### Gate the link behind a follow and an email (lead capture) > "Ask people to follow me and share their email before I send the link, then push the email to my CRM" Pass the optional steps to `blotato_create_automation` in one call. Blotato runs them in a fixed order: follow gate, email gate, your message, webhook. 1. `blotato_list_accounts` - finds the Instagram account. 2. `blotato_create_automation` - creates the automation with the `comment-received` trigger plus: * `followGate: { message: "Follow me, then tap below.", buttonTitle: "I'm following" }` * `emailGate: { message: "Reply with your email and I'll send the link." }` * `webhook: { method: "POST", url: "https://example.com/hooks/leads", headers: { "X-Api-Key": "secret" } }` 3. `blotato_list_automation_runs` - checks the outcome of each run. Your endpoint receives `{"email": "them@example.com"}` after the DM sends. A webhook is the only way to read a captured address, since `blotato_list_conversations` and `blotato_list_messages` do not return it. Gate restrictions: * The follow gate runs on Instagram only. A Facebook automation rejects it. * Each gate waits up to 1 hour for a reply. A contact who never answers leaves the run as `expired`. * A contact who does not follow gets the follow-gate message again. A reply holding no email address gets the email-gate message again. * An unknown follower status sends your message anyway, since Instagram withholds follower status for a contact who never granted profile access. * The Instagram account needs reconnecting if it was connected before DM automations and follow gating landed. Blotato subscribes the account to button-tap events at connect time, so an older connection does not reliably receive taps and runs expire. * Instagram renders the confirm button in the mobile app only. Write the gate message to ask for a typed reply, for example "Reply FOLLOWING once you have", so a desktop audience advances. * The webhook URL needs a public address. Blotato rejects private and loopback addresses with error code 20304. Restrictions to keep in mind: * Instagram and Facebook allow one private reply per comment, within 7 days of the comment. If you've already privately replied to the comment (e.g. through another API or automation platform) your message will be rejected. * After the private reply, you reach the person again only after they message you and open a new 24-hour messaging window. * Automation buttons you author are link buttons only. For postback buttons or quick replies, send the message yourself with `blotato_send_message`. The follow-gate confirm button is a postback button Blotato manages, and you set its label only. * With a gate set, the gate message takes the one private reply and later messages in the run arrive as standard DMs. * Per-post targeting uses a Blotato post ID, so it works on posts published through Blotato. For a post published elsewhere, watch any post and rely on keywords. * Your own comments and the messages your account sends never trigger a run. * Each new person the automation reaches counts toward your plan's monthly active-contacts limit (Starter 1,000, Creator 6,000, Agency 15,000). See [Active Contacts](/settings/billing-and-credits#active-contacts). See [DM Automations](/features/dm-automations). ### Answer DMs from your inbox > "Draft replies to anyone asking about shipping in my Instagram DMs" 1. `blotato_list_conversations` - lists your DM threads. 2. `blotato_list_messages` - lists incoming messages (`direction: incoming`), filtered by conversation or account. 3. AI drafts a reply from your FAQ for each unanswered message. 4. `blotato_send_message` - sends each reply. Set `recipientId` to the incoming message's `senderId`. 5. `blotato_get_message` - poll each reply until its status reaches `sent` or `failed`. Restrictions to keep in mind: * You reply to a standard DM within 24 hours of the person's last message. Blotato does not support cold outreach to people who have not messaged you. * Each new person you message counts toward your plan's monthly active-contacts limit (Starter 1,000, Creator 6,000, Agency 15,000). See [Active Contacts](/settings/billing-and-credits#active-contacts). * To draft replies without sending, skip the `blotato_send_message` step. ### Offer buttons or quick replies in a DM > "Reply to this DM with three options: Small, Medium, Large" 1. `blotato_list_messages` - finds the incoming message and its `senderId`. 2. `blotato_send_message` - sends the reply with `quickReplies` set to the three chips, each with a `title` and a `payload`. 3. `blotato_list_messages` - reads the next incoming message and its `payload.selection.payload` to see the choice. Swap `quickReplies` for `buttons` to pin up to 3 call-to-action buttons under the message instead. Use `type: "web_url"` to open a link, or `type: "postback"` to capture the tap. Restrictions to keep in mind: * Buttons and quick replies are mutually exclusive. Sending both is rejected. * Instagram renders buttons in the Instagram mobile app only. A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons. Pass `buttons` or a URL inside `text`, not both, since a message carrying both leaves the URL unclickable on desktop. * Buttons cap the message text at 640 characters. Quick replies require non-empty text. * Button and chip labels are limited to 20 characters. * Blotato subscribes your account to the postback webhook when you connect it. If you connected your account before buttons were launched, [reconnect](https://my.blotato.com/settings) to start receiving postback events. See [Buttons and Quick Replies](/api/mcp/tools#buttons-and-quick-replies). *** ## Combining Canva and Blotato If you have both the [Canva](https://www.canva.com/help/mcp-agent-setup/) and Blotato MCP connectors enabled in your AI coding agent (Claude, Cursor, Codex, Cline, or another MCP-compatible client), use these prompts to bridge them. For a full walkthrough of combining Canva, Claude, and Blotato, watch this tutorial: [Canva + Claude + Blotato](https://youtu.be/MQjCyQBRZ_M). ### Post Canva designs to social media > "Export from Canva and then pass the Canva export domain URLs directly to Blotato to post." The AI agent exports your Canva design, captures the public Canva CDN URL, and passes it straight into `blotato_create_post` as a `mediaUrl`. No download or re-upload required. ### Use your own photos or videos inside a Canva design > "Use Blotato to upload the photos so Canva can use them." The AI agent calls `blotato_create_presigned_upload_url` to upload each local file to Blotato, then hands the resulting public URLs to Canva as image assets. From there, Canva imports the URLs into your design. ### Posts failing with "Could not fetch media" This error means Blotato was unable to download the image URL passed in `mediaUrls` at publish time. In n8n it usually surfaces as `Failed to fetch media URL: char '' is not expected.:1:1` together with `Deserialization error: to see the raw response, inspect the hidden field {error}.$response on this object.` -- the character in the error is the first character of whatever text the remote URL returned (e.g. `e` for "expired" or "error..."). Open `{error}.$response` in n8n to read the actual body. Common causes: * The URL is signed and expired before Blotato fetched it (Canva exports, S3 presigned URLs, Google Drive `/view` links) * The URL points to a preview page or folder, not a direct image file * The image is behind a login or CDN bot protection Different case -- the media was generated BY Blotato: if the failing URL points to Blotato's own hosting (for example a `...r2.dev/pipeline/...` or `database.blotato.io` link) and a plain retry sometimes publishes the same post with no changes, the cause is a Blotato-side media fetch timeout (most common with larger files), not your URL or your workflow. Retry the post from [Failed Posts](https://my.blotato.com/failed), and contact support in the in-app chat if the same post keeps failing after several retries. How to fix it: 1. If your AI agent generated images in Canva, send it the two prompts above so it passes the Canva export URL directly into `mediaUrls` instead of trying to download and re-upload. 2. If you used Google Drive, use a direct-download URL in this format: `https://drive.usercontent.google.com/download?id=FILE_ID&export=download&confirm=t` 3. If you have a local file, use Blotato's presigned upload flow to host the file on Blotato first, then publish using the returned `publicUrl`. See: [Upload Media](/api/publish-post/upload-media-v2-media#presigned-upload-local-files) 4. Test 1 post first before scheduling a batch. Platform-specific note: Pinterest is limited to 10 pins per day per account, so a large batch will hit the platform limit even with valid media. See: [Pinterest Limits](/settings/social-accounts) --- [Next Page](/llms-full.txt/1)