> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/start-with-an-ai-agent/mcp/examples.md). # Example prompts Map customer prompts to MCP workflows while preserving draft-only intent, destination approval, upload bytes, and completion checks. Use these prompts with your connected assistant. The assistant selects Blotato tools and follows the task's completion rules. For step-by-step instructions, start with [Agent workflows](/agent-workflows/agent-workflows.md). Tool-call counts vary with pagination, processing time, and the selected platform. A create response alone does not confirm publication. Follow [Async jobs and polling](/api-and-mcp-concepts/async-jobs-and-polling.md). Draft, summarize, research, preview, and explain requests do not authorize publishing or sending messages. Stop at the requested artifact. Submit a write only when the user's request authorizes its content and destination. ## Prompt-to-Tool Mapping | What You Say | Tools Called | How It Works | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | "Post 'Hello world' to my Twitter" | `blotato_list_accounts` -> `blotato_create_post` | 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` | 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` -> source status if needed -> `blotato_list_accounts` -> `blotato_create_post` -> post status if needed | Extracts the content and writes the caption. Instagram also requires an image or video, so include a media URL in your prompt. Visual generation through MCP is not supported at this time. | | "What accounts do I have connected?" | `blotato_list_accounts` | Returns all connected accounts with subaccounts and platform details. | | "How many credits do I have left?" | `blotato_get_credits` | Returns your remaining credits, account email, and current pricing. | | "Show me my scheduled posts" | `blotato_list_schedules` | Returns all future scheduled posts with their content, times, and target accounts. | | "What did I publish on Instagram last week?" | `blotato_list_posts` | Returns published Instagram posts in the time window with their public URLs. | | "Which of my Twitter posts failed this month?" | `blotato_list_posts` | 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` | Filters by `status=published,scheduled`; pages through results if there are many. | | "Show me recent comments on my Instagram posts" | `blotato_list_comments` | Returns recent comments with their text, author, and status. | | "Comment 'Thanks everyone!' on my latest Instagram post" | `blotato_list_posts` -> `blotato_post_comment` -> `blotato_get_comment` | Finds your latest published Instagram post, then posts the comment on it. | | "Did my comment post yet?" | `blotato_get_comment` | 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` | 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` | 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` | 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` | 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` | 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` | Returns your direct-message conversations, most recent first. | | "Reply 'Thanks!' to my latest message from @jamie" | `blotato_list_messages` -> `blotato_send_message` -> `blotato_get_message` | 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` | Lists schedules to find the LinkedIn post, then updates its scheduled time. | | "Delete my scheduled Twitter post" | `blotato_list_schedules` -> `blotato_delete_schedule` | 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` | 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` -> source status if needed | Extracts the article and drafts thread segments. Do not call create-post unless the user also authorizes publishing. | | "Remix this YouTube video into a fresh post" | `blotato_create_source` -> source status if needed | Extracts supported source content, then the assistant drafts the post. Publishing or scheduling requires a separate authorized action. See [source extraction](/agent-workflows/agent-workflows/sources.md). | | "Post this update to my Sunrise Bakery Facebook page" | `blotato_list_accounts` -> `blotato_create_post` | 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` | 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" | Read the [automation workflow](/agent-workflows/agent-workflows/automations.md), then account lookup if needed | Explains prerequisites and prepares the account, trigger, message, and link choices. A walkthrough alone does not authorize creating or activating an 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, and post it to Instagram and LinkedIn with this image: \[image URL]" 1. `blotato_create_source` - starts source extraction. Check its result and use `blotato_get_source_status` with the returned ID if unfinished. 2. `blotato_list_accounts` - finds your Instagram and LinkedIn accounts 3. `blotato_create_post` (x2) - submits the approved content for each destination, with the image URL in `mediaUrls`. 4. Check each result with `blotato_get_post_status` if needed. Report each destination's actual outcome, not success for the whole batch after 1 successful post. ### Schedule a Week of Content > "Write 5 different motivational posts and schedule them to my Twitter, one per day starting Monday" 1. The AI tool writes 5 posts 2. `blotato_list_accounts` - finds your Twitter account 3. `blotato_create_post` (x5) - schedules each with a different scheduledTime Resolve the dates and timezone before submitting. Verify each returned scheduled time and retain each submission ID. Scheduled is not published. See [scheduling completion rules](/agent-workflows/agent-workflows/schedule.md). ### 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 The assistant needs access to the local file and an HTTP upload tool. Confirm the PUT completed before submitting, then check each publishing result. The presigned-URL tool does not transfer the file bytes. 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 the supported research source format described in [source extraction](/agent-workflows/agent-workflows/sources.md). 2. Check the source result, including status and any truncated content. 3. Draft the thread from the retrieved material and preserve source attribution. 4. Stop at the draft. Publish through the [publishing workflow](/agent-workflows/agent-workflows/publish.md) only when the user requests publication to a specified destination. ### 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. Inspect the existing reply history before choosing unanswered comments. `isAuthor: false` identifies audience comments, not unanswered comments. 4. `blotato_post_comment` - posts each authorized reply with `parentCommentId` set to its top-level comment ID. 5. `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 comment trigger. Get it from `blotato_list_posts`. To answer keyword DMs as well, add a `message-received` trigger to `triggers`. An automation holds one comment trigger and one message trigger at most, and either one starts a run. To pause one trigger while the other keeps running, call `blotato_update_automation_trigger` with the trigger's `id` and `isActive: false`. ### 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", "isFollower": true}` after the DM sends. `email` is `null` when Blotato holds no address, and `isFollower` is `null` when no follow gate checked the person. Use a webhook to export the stored contact email. Conversation and message responses have no dedicated captured-email field, although the original reply remains available as message text. Gate restrictions: * The follow gate runs on Instagram only. A Facebook automation rejects it. * The follow gate waits up to 30 days for a reply, and the email gate up to 72 hours. 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. * On automations published after September 14, 2026, a contact with an email already on file skips the email gate. * 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 tracked Blotato post ID. For an externally published Instagram post already tracked through an incoming comment, use the comment's non-null `postId` after verifying its account and `platformPostId`. If the required ID is unavailable, stop. An any-post keyword automation requires approval for the broader scope. See [post targeting](/rest-api-reference/dm-automations.md#trigger-object). * Your own comments and the messages your account sends never trigger a run. * Each new person the automation reaches counts toward your monthly active-contacts limit. Standard plan limits are Starter 1,000, Creator 6,000, and Agency 15,000. Some accounts have a custom limit. See [Active Contacts](/settings/billing-and-credits.md#active-contacts). See [DM Automations](/web-app-features/dm-automations.md). ### 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. Read enough conversation history to determine which messages still need a reply. 4. Draft replies from the user's FAQ and present them for review. Do not call `blotato_send_message` for this draft-only request. If the user later authorizes sending, follow [Read and send messages](/agent-workflows/agent-workflows/messages.md). Set `recipientId` from the incoming message's `senderId`, then verify the returned message's final status. Do not send a 2nd reply to check the first reply's status. 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 monthly active-contacts limit. Standard plan limits are Starter 1,000, Creator 6,000, and Agency 15,000. Some accounts have a custom limit. See [Active Contacts](/settings/billing-and-credits.md#active-contacts). * Draft-only requests stop before sending, even when the tool is available. ### Offer buttons or quick replies in a DM > "Reply to this DM with 3 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/accounts) to start receiving postback events. See [Buttons and Quick Replies](/start-with-an-ai-agent/mcp/tools.md#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." If the connected Canva tool provides a direct media export URL accessible to Blotato, pass that URL in the `mediaUrls` array of `blotato_create_post`. Verify the export finished and the URL remains valid through publishing. Blotato does not provide Canva export tools. Do not promise a Canva capability absent from the user's connected tool schema. ### Use your own photos or videos inside a Canva design > "Use Blotato to upload the photos so Canva can use them." With the user's authorization to host those files, the assistant requests a presigned URL, uploads the bytes by HTTP PUT, and verifies completion. It then uses `publicUrl` only if the connected Canva tool supports importing that media type by URL. Requesting the presigned URL alone does not upload a file. Follow [Upload local media](/agent-workflows/agent-workflows/upload.md). ### Posts failing with "Could not fetch media" The error reports a failed media retrieval. It does not establish whether the cause is an expired URL, access restrictions, an empty response, a network failure, or another service error. 1. Preserve the exact error, HTTP status when available, and submission ID. 2. Confirm the submitted `mediaUrls` value points to the intended image or video rather than a preview page, folder, or login page. 3. Check whether the URL is accessible without the user's browser session and remains valid through the scheduled publishing time. Browser access alone does not prove access from Blotato's servers. 4. For a local file, finish the [presigned upload](/rest-api-reference/publish-post/upload-media-v2-media.md#presigned-upload-local-files) before using `publicUrl`. 5. For media generated in the web app or with the REST API, reuse the finished visual's URL instead of regenerating it. 6. Check the [original publishing outcome](/start-with-an-ai-agent/publishing-status.md) before submitting again. Blotato-hosted media is not exempt from diagnosis. Its hostname or a later successful retry does not prove a timeout. Send support the request/reference ID if a valid hosted result repeatedly fails. If a client reports a deserialization error, inspect its available response details without disclosing secrets. Do not infer the full response body from the first unexpected character. See [media upload and conversion diagnosis](/api-and-mcp-concepts/media-uploads-and-conversion.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.blotato.com/start-with-an-ai-agent/mcp/examples.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.