From Ayrshare - Unified Social Media API for AI Agents
Reads and sends direct messages on Facebook, Instagram, and Twitter/X, and manages DM auto-reply settings via the Ayrshare MCP server.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ayrshare:messagesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Four tools, split into two jobs — moving messages, and the account-level auto-responder:
Four tools, split into two jobs — moving messages, and the account-level auto-responder:
mcp__ayrshare__get_messages — read conversations and messages for one platform. Its conversation/message ids feed send_message.mcp__ayrshare__send_message — send a DM (text and/or media) to a recipient or into an existing conversation.mcp__ayrshare__get_auto_response — read the account's DM auto-reply settings.mcp__ayrshare__set_auto_response — change the account's DM auto-reply settings.DMs are ONLY on Facebook, Instagram, and Twitter/X. No other network (LinkedIn, TikTok, YouTube, etc.) has a messaging surface here. get_messages and send_message are platform-scoped and accept exactly one of facebook, instagram, twitter. The two auto-response tools take no platform: they govern the selected profile's DM auto-reply across FB/IG/X at once (network-agnostic, but still scoped to the profile the profileKey argument or Profile-Key header selects).
All four are profile-scoped: choose the profile with the profileKey argument or the Profile-Key header (see Auth; the argument wins when both are set).
| Tool | Purpose | Method + Endpoint | Required inputs | Optional inputs |
|---|---|---|---|---|
mcp__ayrshare__get_messages | Read conversations / messages for one platform | GET /messages/:platform | platform (facebook|instagram|twitter) | conversationsOnly (bool), conversationId, status (active|archived), limit (1-100, X/Twitter only), next (cursor, X only) |
mcp__ayrshare__send_message | Send a DM (text and/or media) | POST /messages/:platform | platform (facebook|instagram|twitter); message OR mediaUrls; recipientId OR conversationId | — (none beyond the above) |
mcp__ayrshare__get_auto_response | Read the account's DM auto-reply settings | GET /messages/autoresponse | — (no params) | — |
mcp__ayrshare__set_auto_response | Update the account's DM auto-reply settings | POST /messages/autoresponse | at least one of autoResponseActive (bool), autoResponseMessage (string), autoResponseWaitSeconds (int) | — (none beyond the above) |
Full input schemas and example payloads/responses are in references/schemas.md.
All four tools are profile-scoped: choose the profile with an optional profileKey tool argument or the Profile-Key connection header (the argument wins when both are set). Pass profileKey on the call to act as one client for that call, or set the Profile-Key header (.mcp.json headers) to default the whole connection to it; with neither, calls act on the account's primary/Business profile. Full model: ../getting-started/SKILL.md.
This applies to the auto-response tools too: they take no platform, but still act on whichever profile the profileKey argument or Profile-Key header selects. Different profiles → different DM auto-reply settings.
get_messages and send_message are :/platform calls; pass exactly one of facebook, instagram, twitter. There is no "all platforms" mode — to scan three networks, make three calls.get_messages to pull conversations/messages, find the right conversation, then reply with send_message. Use conversationsOnly: true for a lightweight list of threads (no message bodies) when you just need to pick a conversation; drop it (or pass a conversationId) to read the messages within one thread.send_message needs two things: content AND a target.
message (text), mediaUrls (an array of URLs), or both. At least one is required — an empty message with no media is rejected. On Twitter/X, message text is required even when you send mediaUrls — a media-only DM is rejected on X (FB/IG accept media-only). mediaUrls count also differs: Facebook and Instagram accept multiple URLs; X/Twitter accepts only one — sending more than one to X errors.recipientId (the person/page-scoped user id) or conversationId (an existing thread). At least one is required.recipientId. On FB/IG you must address the message to a recipientId; a bare conversationId is not enough. On Twitter/X you can reply into a conversationId or send to a recipientId. When in doubt, include recipientId — it's the universally accepted target.recipientId and conversationId come out of get_messages. Read first to obtain them; don't guess or hand-construct ids.mcp__ayrshare__explain_error and tell the user the window has closed (the customer must message first to reopen it). See the global retry rule in ../getting-started/SKILL.md.limit and next are Twitter/X-only. limit (1-100) caps results and next is the pagination cursor — both apply to X only on get_messages. Don't pass them for Facebook or Instagram.get_auto_response takes no params and returns autoResponseActive, autoResponseMessage, autoResponseWaitSeconds. set_auto_response accepts any subset of those three; send the field(s) you're changing (at least one of the three is required). Sending autoResponseMessage: "" (empty string) resets the message to the Ayrshare default, it does not blank it out.get_messages and send_message reject any other platform. Don't try LinkedIn/TikTok/YouTube/etc. DMs through these tools — there is no messaging surface for them.profileKey argument (per call; it wins) or the connection's Profile-Key header; with neither it's the primary profile. Confirm you're targeting the right profile before reading or sending.send_message needs content AND target. Missing either side fails: you must give message OR mediaUrls, and recipientId OR conversationId. FB/IG additionally require recipientId specifically — a conversationId alone won't do. On Twitter/X, message text is required even with mediaUrls — a media-only DM (the generic "mediaUrls alone is fine" case) is rejected on X; it works only on FB/IG.mediaUrls is an array of URLs. Media is referenced by reachable URL, same as posts — there is no upload step here. Validate a media URL with mcp__ayrshare__validate_media (see the Media skill) before sending if you're unsure it's reachable.autoResponseMessage: "" reverts to the Ayrshare default reply; it does not produce an empty auto-reply. To stop auto-replying entirely, set autoResponseActive: false.get_auto_response/set_auto_response hit /messages/autoresponse with no platform; they govern the whole account's (profile's) DM auto-reply across FB/IG/X at once. Don't expect a per-platform toggle here.mcp__ayrshare__explain_error, then surface it — don't loop. send_message is a write: never auto-retry it on a 4xx. A closed messaging window, a bad/expired recipientId, or an unsupported platform won't fix itself on retry, and a blind resend can double-send. Translate the error via mcp__ayrshare__explain_error and present it; 429 gets at most one retry. (Mirrors the global retry-safety rule.)npx claudepluginhub ayrshare/ayrshare-social-media-api-claude-plugin --plugin ayrshareSends personalized bulk DMs with templates, manages conversations, filters message requests, and exports DMs on X/Twitter via browser console JavaScript scripts.
Foundation skill for the Ayrshare MCP server: auth model, installation, client onboarding, and retry safety. Activate when configuring the plugin, resolving 401/403 errors, or onboarding new profiles.
Manages Instagram professional accounts via Hyper MCP: publish photos, Reels, Stories, carousels; moderate comments/mentions; send DMs; pull account and media insights.