messages

Ayrshare MCP — Messages (DMs)

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

Functions

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.

Auth

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.

Usage guidance

• Pick the platform first. 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.
• Read before you reply. Call 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.
  • Content: supply 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.
  • Target: supply recipientId (the person/page-scoped user id) or conversationId (an existing thread). At least one is required.
• Facebook and Instagram REQUIRE 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.
• Where ids come from. recipientId and conversationId come out of get_messages. Read first to obtain them; don't guess or hand-construct ids.
• Messaging windows are real. Each platform enforces a window in which you may DM a user; on Facebook/Instagram this follows Meta's standard messaging-window policy (tied to the user's last message to you). Outside the window the API returns a clear error. Don't retry it — translate it via 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.
• Auto-responder is account-level. 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.

Gotchas

• DMs are only FB / IG / X. 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.
• Be deliberate about scope. Whose DMs you read/send, and whose auto-responder you read/set, is set by the 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.
• Auto-response empty string resets, not clears. autoResponseMessage: "" reverts to the Ayrshare default reply; it does not produce an empty auto-reply. To stop auto-replying entirely, set autoResponseActive: false.
• Auto-response is not platform-scoped. 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.
• On failure, call 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.)