@omnisocials/mcp-server 1.35.0 → 1.46.0

package/build/metrics.js

@@ -57,6 +57,14 @@ export function getEngagement(platform, metrics) {
             return sum("likes", "comments", "reposts", "quotes", "bookmarks");
         case "mastodon":
             return sum("likes", "comments", "reposts", "quotes");
+        case "telegram":
+            // Reactions are the only post number a bot gets (message_reaction_count),
+            // stored as `likes` (total) next to `reactions` (per emoji).
+            return sum("likes");
+        case "discord":
+            // A webhook reads back its own message: reactions only (2026-10-22),
+            // stored the Telegram way, `likes` (total) next to `reactions` (per emoji).
+            return sum("likes");
         case "reddit":
             // likes == upvote score; shares == crossposts.
             return sum("likes", "comments", "shares");
@@ -129,6 +137,7 @@ export const UNSUPPORTED_POST_METRICS = {
         reach: "X does not report reach, only impressions.",
     },
     facebook: {
+        reach: "Facebook stopped reporting post reach in June 2026: Meta retired the metric and its replacement returns no data.",
         saves: "Facebook does not report saves.",
     },
     instagram: {
@@ -176,6 +185,28 @@ export const UNSUPPORTED_POST_METRICS = {
         video_views: "Mastodon does not report video views.",
         engagement_rate: "Engagement rate needs impressions, which Mastodon does not report.",
     },
+    telegram: {
+        impressions: "Telegram does not give view counts to bots. Open the post in Telegram to see its views.",
+        reach: "Telegram does not report reach to bots.",
+        comments: "Telegram does not report comment counts to bots.",
+        shares: "Telegram does not report forwards to bots.",
+        saves: "Telegram does not report saves.",
+        clicks: "Telegram does not report clicks.",
+        link_clicks: "Telegram does not report clicks.",
+        video_views: "Telegram does not give view counts to bots.",
+        engagement_rate: "Engagement rate needs views, which Telegram does not give to bots.",
+    },
+    discord: {
+        impressions: "Discord does not report views. Open the message in Discord to see who reacted.",
+        reach: "Discord does not report reach.",
+        comments: "Discord does not report replies to a webhook message.",
+        shares: "Discord does not report shares.",
+        saves: "Discord does not report saves.",
+        clicks: "Discord does not report clicks.",
+        link_clicks: "Discord does not report clicks.",
+        video_views: "Discord does not report video views.",
+        engagement_rate: "Engagement rate needs views, which Discord does not report.",
+    },
     google_business: {
         impressions: "Google discontinued per-post metrics for Business Profiles in 2023.",
         reach: "Google discontinued per-post metrics for Business Profiles in 2023.",
@@ -190,13 +221,19 @@ export const UNSUPPORTED_POST_METRICS = {
         engagement_rate: "Google discontinued per-post metrics for Business Profiles in 2023.",
     },
 };
-/** Reason `metricKey` is unavailable on `platform`, or null when it is available. */
-export function unsupportedMetricReason(platform, metricKey) {
+/** Metrics unavailable for some post types only: platform -> content_type -> metric key -> reason. Empty since Facebook reach moved to the platform-wide map. */
+export const UNSUPPORTED_POST_METRICS_BY_CONTENT_TYPE = {};
+/** Reason `metricKey` is unavailable on `platform` (refined by `contentType`), or null when it is available. */
+export function unsupportedMetricReason(platform, metricKey, contentType) {
+    const typed = contentType ? UNSUPPORTED_POST_METRICS_BY_CONTENT_TYPE[platform]?.[contentType]?.[metricKey] : undefined;
+    if (typed)
+        return typed;
     return UNSUPPORTED_POST_METRICS[platform]?.[metricKey] ?? null;
 }
-/** True when the platform can never report `metricKey`; a finite stored value overrides the map. */
+/** True when the platform can never report `metricKey` for this post; a finite stored value overrides the map. */
 export function isMetricUnsupported(platform, metricKey, metrics) {
-    if (!unsupportedMetricReason(platform, metricKey))
+    const contentType = typeof metrics?.content_type === "string" ? metrics.content_type : undefined;
+    if (!unsupportedMetricReason(platform, metricKey, contentType))
         return false;
     if (metrics && finiteOrNull(metrics[metricKey]) !== null)
         return false;

package/build/tools/accounts.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { fetchImageAsBase64, capitalize } from "../client.js";
 export function registerAccountTools(server, getClient) {
-    server.tool("list_accounts", "List all connected social media accounts in the workspace. Each account includes its platform, display name, channel ID (used for create_post), supported content_types (post, story, reel), and `needs_reconnect` (true when the OAuth token has been revoked/expired and the user must reconnect before posts can succeed; also reflected in `status` as `needs_reconnect` instead of `active`). Pinterest accounts include a `boards` array with `{id, name}` — use the board `id` as `board_id` when creating Pinterest posts. X accounts with Premium include `platform_details` with `subscription_type` (e.g. \"Premium\", \"PremiumPlus\"). LinkedIn appears as two independent platforms: `linkedin` for a personal profile and `linkedin_page` for a company page. A workspace can have both connected at the same time and post to each separately. Call this to help users pick which platforms to post to.", {}, { title: "List Connected Accounts", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async () => {
+    server.tool("list_accounts", "List all connected social media accounts in the workspace. Each account includes its platform, display name, channel ID (used for create_post), supported content_types (post, story, reel), and `needs_reconnect` (true when the OAuth token has been revoked/expired and the user must reconnect before posts can succeed; also reflected in `status` as `needs_reconnect` instead of `active`). Pinterest accounts include a `boards` array with `{id, name}` — use the board `id` as `board_id` when creating Pinterest posts. X accounts with Premium include `platform_details` with `subscription_type` (e.g. \"Premium\", \"PremiumPlus\"). Telegram accounts are a channel or group the OmniSocials bot posts to; `platform_details` carries `chat_type` (channel, supergroup or group), `subscribers` and `url`. Discord accounts are one Discord channel the workspace posts to through its webhook (posts show the webhook's name and picture); `platform_details` carries `guild_id`, `guild_name` (the server, when connected with Continue with Discord), `channel_id`, `channel_name` (read by the OmniSocials bot or given by the person, else null), `channel_type` (text, voice, announcement, stage, forum or media; a forum or media channel needs `discord.thread_name` on every post), `webhook_name`, `connect_method` (oauth or url) and `url`. LinkedIn appears as two independent platforms: `linkedin` for a personal profile and `linkedin_page` for a company page. A workspace can have both connected at the same time and post to each separately. Call this to help users pick which platforms to post to.", {}, { title: "List Connected Accounts", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async () => {
         const result = await getClient().listAccounts();
         if (result.error) {
             return {
@@ -20,13 +20,21 @@ export function registerAccountTools(server, getClient) {
         md += `|---|----------|---------|---------------|------------|--------|\n`;
         for (let i = 0; i < accounts.length; i++) {
             const a = accounts[i];
-            const name = a.username ? `@${a.username}` : a.display_name || "—";
+            // Discord: the server, then the channel the bot read or the person gave.
+            const channel = a.platform === "discord" && a.platform_details?.channel_name ? ` · #${a.platform_details.channel_name}` : "";
+            const name = `${a.username ? `@${a.username}` : a.display_name || "—"}${channel}`;
             const types = (a.content_types || []).join(", ");
             const platform = capitalize(a.platform);
             const subType = a.platform_details?.subscription_type;
+            const chatType = a.platform === "telegram" ? a.platform_details?.chat_type : null;
+            const guildName = a.platform === "discord" ? a.platform_details?.guild_name : null;
             const sub = subType === "Premium" || subType === "PremiumPlus"
                 ? ` (${subType})`
-                : "";
+                : chatType
+                    ? ` (${chatType === "channel" ? "channel" : "group"})`
+                    : guildName && guildName !== a.display_name
+                        ? ` (${guildName})`
+                        : "";
             const statusCell = a.needs_reconnect
                 ? `⚠️ needs_reconnect`
                 : "active";
@@ -93,6 +101,30 @@ export function registerAccountTools(server, getClient) {
         if (getSubType === "Premium" || getSubType === "PremiumPlus") {
             md += `| **Subscription** | ${getSubType} |\n`;
         }
+        if (a.platform === "telegram" && a.platform_details) {
+            const d = a.platform_details;
+            if (d.chat_type)
+                md += `| **Chat type** | ${d.chat_type} |\n`;
+            if (typeof d.subscribers === "number")
+                md += `| **Subscribers** | ${d.subscribers.toLocaleString("en-US")} |\n`;
+            if (d.url)
+                md += `| **Link** | ${d.url} |\n`;
+        }
+        if (a.platform === "discord" && a.platform_details) {
+            const d = a.platform_details;
+            if (d.guild_name)
+                md += `| **Server** | ${d.guild_name} |\n`;
+            if (d.channel_name)
+                md += `| **Channel** | #${d.channel_name}${d.channel_type ? ` (${d.channel_type})` : ""} |\n`;
+            if (d.webhook_name)
+                md += `| **Posts as** | ${d.webhook_name} (the webhook's name) |\n`;
+            if (d.channel_id)
+                md += `| **Channel ID** | ${d.channel_id} |\n`;
+            if (d.connect_method)
+                md += `| **Connected with** | ${d.connect_method === "oauth" ? "Continue with Discord" : "a webhook URL"} |\n`;
+            if (d.url)
+                md += `| **Link** | ${d.url} |\n`;
+        }
         if (a.boards?.length) {
             md += `\n### Pinterest Boards\n\n`;
             md += `| Board Name | Board ID |\n`;

package/build/tools/analytics.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { formatNumber, capitalize, metricRows, metricBreakdownRows, sortMetricLabels } from "../client.js";
 import { getEngagement, getImpressions, getEngagementRate, MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE, } from "../metrics.js";
 export function registerAnalyticsTools(server, getClient) {
-    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported per platform: impressions, reach, views, saves, likes, comments, shares, clicks, link_clicks, engagements, and more. A missing key means the platform does not report it: reach is absent (not 0) on X, Pinterest, YouTube, Threads, Bluesky and Mastodon; link_clicks (clicks on links in the post) exists for X posts under 30 days, LinkedIn profile, Facebook feed posts, Pinterest and Instagram stories, while clicks is the platform's broadest click count. TikTok videos also carry average_time_watched, full_video_watched_rate, total_time_watched, favorites and reach when the workspace enabled TikTok comments (Business API authorization).", {
+    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported per platform: impressions, reach, views, saves, likes, comments, shares, clicks, link_clicks, engagements, and more. A missing key means the platform does not report it: reach is absent (not 0) on X, Pinterest, YouTube, Threads, Bluesky, Mastodon, Telegram, Discord and Facebook (Meta retired Facebook post reach in June 2026 and its replacement metric returns no data; a Facebook row collected before 2026-09-27 may still carry reach: 0, treat it as absent); link_clicks (clicks on links in the post) exists for X posts under 30 days, LinkedIn profile, Facebook feed posts, Pinterest and Instagram stories, while clicks is the platform's broadest click count. TikTok videos also carry average_time_watched, full_video_watched_rate, total_time_watched, favorites and reach when the workspace enabled TikTok comments (Business API authorization). Telegram gives bots no view counts: a Telegram post carries likes (all reactions), reactions (per emoji) and, for a poll, the votes. Discord reports the same for a webhook message: likes (all reactions), reactions (per emoji) and the poll votes, no views.", {
         post_id: z.string().describe("The numeric OmniSocials post id (the `id` field from list_posts). NOT a platform post id such as a YouTube video id or tweet id."),
     }, { title: "Get Post Analytics", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ post_id }) => {
         const result = await getClient().getPostAnalytics(post_id);
@@ -310,7 +310,7 @@ export function registerAnalyticsTools(server, getClient) {
         };
     });
     server.tool("get_best_times", "Get recommended posting times (day + hour) for one platform, computed from the workspace's own posting history: publish time × engagement of every post published there, recency-weighted and outlier-damped, bucketed in the user's timezone, and blended with when the account's followers are online when the platform provides that (Instagram, TikTok Business; `basis: own_data_and_audience`, response carries `audience_online`). Returns the top 3 recommended slots plus a per-day breakdown. When the workspace has fewer than 15 analyzed posts on the platform, the audience-online profile alone is used (`basis: audience`) or industry-average defaults are returned (`basis: defaults`) with how many more posts unlock personalized recommendations — tell the user that so the numbers aren't mistaken for their own audience data. Use this before scheduling when the user asks 'when should I post?' or hasn't specified a time. Requires the analytics:read scope.", {
-        platform: z.string().describe("Platform identifier, e.g. instagram, tiktok, linkedin, linkedin_page, x, facebook, youtube, pinterest, threads, bluesky, mastodon, google_business"),
+        platform: z.string().describe("Platform identifier, e.g. instagram, tiktok, linkedin, linkedin_page, x, facebook, youtube, pinterest, threads, bluesky, mastodon, google_business, telegram, discord"),
         timezone: z.string().optional().describe("IANA timezone for the buckets (e.g. Europe/Amsterdam). Defaults to the account's timezone."),
     }, { title: "Get Best Times to Post", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (params) => {
         const result = await getClient().getBestTimes(params);

package/build/tools/automations.d.ts

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OmniSocialsClient } from "../client.js";
+import type { Automation, AutomationInput } from "../types.js";
+export declare const automationChannelLabel: (platform: string | null | undefined) => "Facebook Page" | "Instagram";
+type Fields = {
+    platform?: "instagram" | "facebook";
+    name?: string;
+    keywords?: string[];
+    match?: "word" | "contains" | "any";
+    dm_text?: string;
+    public_replies?: string[];
+    triggers?: Array<"comment" | "dm" | "story_reply">;
+    scope?: "post" | "next_post" | "any";
+    post_id?: string;
+    instagram_media_id?: string;
+    facebook_post_id?: string;
+    max_sends?: number | null;
+    stop_at?: string | null;
+};
+export declare function buildAutomationBody(f: Fields, { create }: {
+    create: boolean;
+}): AutomationInput;
+export declare function describeAutomation(a: Automation): string;
+export declare function registerAutomationTools(server: McpServer, getClient: () => OmniSocialsClient): void;
+export {};

package/build/tools/automations.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { formatDateTime, truncate } from "../client.js";
+const SCOPE_HINT = "The API key needs the opt-in Automations scopes (OmniSocials Settings > API > create a key with Automations on: automations:read and automations:write).";
+const errorText = (error) => `Error (${error.code}): ${error.message}${error.code === "insufficient_scope" ? `\n\n${SCOPE_HINT}` : ""}`;
+const PLATFORM = z.enum(["instagram", "facebook"]);
+const KINDS = z.enum(["comment", "dm", "story_reply"]);
+// How the channel reads in a table or a sentence.
+export const automationChannelLabel = (platform) => platform === "facebook" ? "Facebook Page" : "Instagram";
+const MATCH = z.enum(["word", "contains", "any"]);
+const SCOPE = z.enum(["post", "next_post", "any"]);
+// The shared fields of create_automation and update_automation, flat so an
+// assistant fills them from one sentence ("DM everyone who comments guide").
+const AUTOMATION_FIELDS = {
+    platform: PLATFORM.optional().describe("Where the automation runs: 'instagram' (default) = the connected Instagram account, 'facebook' = the connected Facebook Page (the DM lands in Messenger). instagram_media_id implies 'instagram', facebook_post_id implies 'facebook'. It cannot change after create."),
+    name: z.string().max(120).optional().describe("A label for the automations list, e.g. 'Free guide'."),
+    keywords: z.array(z.string()).max(20).optional().describe("Keywords that start the automation (up to 20, matched case-insensitively), e.g. [\"guide\", \"link\"]. Required unless match is 'any'."),
+    match: MATCH.optional().describe("word (default): the keyword stands on its own ('guide', 'Guide!' match; 'linkedin' does not match 'link'). contains: the keyword appears anywhere. any: every comment or message with text (ask the user before using it)."),
+    dm_text: z.string().max(1000).optional().describe("The DM sent to the person (max 1000 characters), once per person. On Facebook it lands in Messenger. Required on create. Confirm the text with the user before creating the automation: it goes out in the account's name."),
+    public_replies: z.array(z.string().max(300)).max(10).optional().describe("Optional public replies posted under the comment (one is picked at random per comment), e.g. [\"Sent you a DM!\", \"Check your inbox\"]. Comment trigger only. An empty array turns the public reply off."),
+    triggers: z.array(KINDS).min(1).optional().describe("What starts the automation. 'comment' (default) = a comment on an Instagram post or reel, or on a Facebook Page post; 'dm' = a keyword in a DM to the Instagram account, or in a Messenger message to the Facebook Page; 'story_reply' = a keyword in a reply to an Instagram story (Instagram only: Facebook has no story replies). One automation can listen to several."),
+    scope: SCOPE.optional().describe("For the comment trigger: 'post' (default) = one post (pass post_id, instagram_media_id or facebook_post_id), 'next_post' = the next post the workspace publishes on this platform, 'any' = every post of the account or Page."),
+    post_id: z.string().optional().describe("For scope 'post': the OmniSocials post id (from list_posts) that goes to the automation's platform. A scheduled post starts listening once it is live. One automation per post and platform: a post that goes to Instagram and Facebook can have one of each."),
+    instagram_media_id: z.string().optional().describe("For scope 'post' on Instagram: the numeric Instagram media id of a post or reel that was NOT published through OmniSocials. OmniSocials reads it from Instagram to check it belongs to the connected account. Pass only one of post_id, instagram_media_id or facebook_post_id."),
+    facebook_post_id: z.string().optional().describe("For scope 'post' on Facebook: the id of a Facebook Page post that was NOT published through OmniSocials ({page-id}_{post-id}, or the post id alone). OmniSocials reads it from Facebook to check it belongs to the connected Page. Implies platform 'facebook'. Pass only one of post_id, instagram_media_id or facebook_post_id."),
+    max_sends: z.number().int().positive().nullable().optional().describe("Stop after this many DMs (the automation becomes 'completed'). null = no limit."),
+    stop_at: z.string().nullable().optional().describe("Stop at this time (ISO 8601). null = no end."),
+};
+// Turn the flat tool fields into the API body. Only the sections that were
+// given are sent, so update_automation leaves the rest untouched.
+export function buildAutomationBody(f, { create }) {
+    const body = {};
+    if (f.name !== undefined)
+        body.name = f.name;
+    if (f.post_id !== undefined)
+        body.post_id = f.post_id;
+    if (f.platform !== undefined)
+        body.platform = f.platform;
+    if (f.instagram_media_id !== undefined)
+        body.instagram_media_id = f.instagram_media_id;
+    if (f.facebook_post_id !== undefined)
+        body.facebook_post_id = f.facebook_post_id;
+    if (create || f.keywords !== undefined || f.match !== undefined || f.triggers !== undefined || f.scope !== undefined) {
+        body.trigger = {};
+        if (f.triggers !== undefined)
+            body.trigger.kinds = f.triggers;
+        if (f.scope !== undefined)
+            body.trigger.scope = f.scope;
+        if (f.keywords !== undefined)
+            body.trigger.keywords = f.keywords;
+        if (f.match !== undefined)
+            body.trigger.match = f.match;
+    }
+    if (create || f.dm_text !== undefined || f.public_replies !== undefined) {
+        body.actions = {
+            dm: { text: f.dm_text ?? "" },
+            ...(f.public_replies !== undefined
+                ? { public_reply: { enabled: f.public_replies.length > 0, variations: f.public_replies } }
+                : {}),
+        };
+    }
+    if (f.max_sends !== undefined || f.stop_at !== undefined) {
+        body.limits = {};
+        if (f.max_sends !== undefined)
+            body.limits.max_sends = f.max_sends;
+        if (f.stop_at !== undefined)
+            body.limits.stop_at = f.stop_at;
+    }
+    return body;
+}
+export function describeAutomation(a) {
+    const kinds = a.trigger.kinds.join(", ");
+    const scope = a.trigger.scope ? ` on ${a.trigger.scope === "post" ? "one post" : a.trigger.scope === "next_post" ? "the next post" : "every post"}` : "";
+    const keywords = a.trigger.match === "any" ? "any text" : a.trigger.keywords.map((k) => `"${k}"`).join(", ");
+    let md = `## Automation \`${a.id}\`${a.name ? ` "${a.name}"` : ""}\n\n`;
+    md += `| Field | Value |\n|-------|-------|\n`;
+    md += `| **Platform** | ${automationChannelLabel(a.platform)} |\n`;
+    md += `| **Status** | ${a.status} |\n`;
+    md += `| **Trigger** | ${kinds}${scope}, keywords ${keywords} (${a.trigger.match}) |\n`;
+    if (a.post) {
+        const label = a.post.caption ? truncate(a.post.caption, 60) : a.post.permalink || a.post.id;
+        md += `| **Post** | ${label}${a.post.permalink ? ` (${a.post.permalink})` : ""}${a.post.live === false ? " (not live yet)" : ""} |\n`;
+    }
+    else if (a.post_id) {
+        md += `| **Post** | OmniSocials post \`${a.post_id}\` |\n`;
+    }
+    md += `| **DM** | ${truncate(a.actions.dm.text, 120)} |\n`;
+    if (a.actions.public_reply.enabled && a.actions.public_reply.variations.length) {
+        md += `| **Public reply** | ${a.actions.public_reply.variations.map((v) => `"${truncate(v, 40)}"`).join(", ")} |\n`;
+    }
+    const limits = [a.limits.max_sends ? `max ${a.limits.max_sends} DMs` : null, a.limits.stop_at ? `until ${formatDateTime(a.limits.stop_at)}` : null].filter(Boolean);
+    if (limits.length)
+        md += `| **Limits** | ${limits.join(", ")} |\n`;
+    md += `| **Sent** | ${a.stats.sent} DMs (${a.stats.matched} matched, ${a.stats.skipped} skipped, ${a.stats.failed} failed) |\n`;
+    return md;
+}
+export function registerAutomationTools(server, getClient) {
+    server.tool("list_automations", "List the comment-to-DM automations of this workspace, on Instagram and on the Facebook Page. An automation DMs a person once when they comment a keyword on a post (or send it in a DM, or in an Instagram story reply), with an optional public reply under the comment. Use it to answer 'which automations run', before creating one on a post that may have one already, or to find the id for update_automation / get_automation_activity.", {
+        status: z.enum(["active", "paused", "completed"]).optional().describe("Only automations with this status."),
+        post_id: z.string().optional().describe("Only the automations bound to this OmniSocials post (one per platform at most)."),
+        platform: PLATFORM.optional().describe("Only the automations of this platform."),
+    }, { title: "List Automations", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (params) => {
+        const result = await getClient().listAutomations(params);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        const items = Array.isArray(result.data) ? result.data : [];
+        if (!items.length) {
+            return { content: [{ type: "text", text: "No comment-to-DM automations yet. Create one with create_automation, or pass comment_dm_automation on create_post." }] };
+        }
+        let md = `## Automations (${items.length})\n\n`;
+        md += `| ID | Platform | Status | Trigger | Keywords | Post | Sent |\n|----|----------|--------|---------|----------|------|------|\n`;
+        for (const a of items) {
+            const post = a.post ? truncate(a.post.caption || a.post.permalink || a.post.id, 40) : a.post_id ? `post ${a.post_id}` : a.trigger.scope === "next_post" ? "next post" : a.trigger.scope === "any" ? "every post" : "";
+            const keywords = a.trigger.match === "any" ? "any text" : a.trigger.keywords.join(", ");
+            md += `| \`${a.id}\`${a.name ? ` ${a.name}` : ""} | ${automationChannelLabel(a.platform)} | ${a.status} | ${a.trigger.kinds.join(", ")} | ${keywords} | ${post} | ${a.stats.sent} |\n`;
+        }
+        md += `\nDetails with get_automation, activity with get_automation_activity, pause or edit with update_automation.`;
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("get_automation", "Get one comment-to-DM automation: its platform (Instagram or the Facebook Page), its trigger, the DM text, the public replies, the limits and the counts.", { automation_id: z.string().describe("The automation id (from list_automations).") }, { title: "Get Automation", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ automation_id }) => {
+        const result = await getClient().getAutomation(automation_id);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        if (!result.data)
+            return { content: [{ type: "text", text: "The API returned no automation." }] };
+        return { content: [{ type: "text", text: describeAutomation(result.data) }] };
+    });
+    server.tool("create_automation", "Create a comment-to-DM automation on the connected Instagram account (default) or on the connected Facebook Page (platform 'facebook'): when somebody comments one of the keywords on the post (or sends it in a DM, or in an Instagram story reply, see triggers), the account DMs them dm_text once, and optionally posts one of public_replies under the comment. On Facebook the DM lands in Messenger. Before creating one, show the user the keyword(s) and the exact DM text and get a yes: the DM goes out in their name. Meta rules, the same on both: one private reply per comment, within 7 days of the comment; a follow-up only after the person answers (24-hour window); OmniSocials caps sends at 180 DMs an hour per account and platform. For scope 'post' pass one of post_id (an OmniSocials post, scheduled or live), instagram_media_id (an Instagram post published outside OmniSocials) or facebook_post_id (a Page post published outside OmniSocials). To attach automations to a NEW post, pass comment_dm_automation on create_post instead.", AUTOMATION_FIELDS, { title: "Create Automation", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async (params) => {
+        if (!params.dm_text)
+            return { content: [{ type: "text", text: "dm_text is required: the DM the person receives." }] };
+        const result = await getClient().createAutomation(buildAutomationBody(params, { create: true }));
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        if (!result.data)
+            return { content: [{ type: "text", text: "Automation created, but the API returned no details. List it with list_automations." }] };
+        const a = result.data;
+        let md = `Created automation \`${a.id}\` (${a.status}).\n\n${describeAutomation(a)}`;
+        if (a.post && a.post.live === false)
+            md += `\n_The post is not live on ${a.platform === "facebook" ? "the Facebook Page" : "Instagram"} yet; the automation starts listening at publish._`;
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("update_automation", "Change a comment-to-DM automation: pause or resume it (status), new keywords or match, a new DM text or public replies, new limits, or move it to another post (post_id, instagram_media_id or facebook_post_id). Only the fields you pass change. The platform cannot change: to move from Instagram to the Facebook Page, create a new automation. A 'completed' automation starts again when its limits or trigger change.", {
+        automation_id: z.string().describe("The automation id (from list_automations)."),
+        status: z.enum(["active", "paused"]).optional().describe("'paused' stops it without deleting it; 'active' resumes it."),
+        ...AUTOMATION_FIELDS,
+    }, { title: "Update Automation", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ automation_id, status, ...fields }) => {
+        const body = buildAutomationBody(fields, { create: false });
+        if (status)
+            body.status = status;
+        if (Object.keys(body).length === 0)
+            return { content: [{ type: "text", text: "Nothing to change: pass status, keywords, dm_text, public_replies, limits or a post." }] };
+        const result = await getClient().updateAutomation(automation_id, body);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        if (!result.data)
+            return { content: [{ type: "text", text: "Automation updated, but the API returned no details. Read it with get_automation." }] };
+        return { content: [{ type: "text", text: `Updated automation \`${automation_id}\`.\n\n${describeAutomation(result.data)}` }] };
+    });
+    server.tool("delete_automation", "Delete a comment-to-DM automation (Instagram or Facebook Page) and its activity log. DMs that were already sent stay sent. To stop it for a while, use update_automation with status 'paused' instead. Confirm with the user first.", { automation_id: z.string().describe("The automation id (from list_automations).") }, { title: "Delete Automation", readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ automation_id }) => {
+        const result = await getClient().deleteAutomation(automation_id);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        return { content: [{ type: "text", text: `Deleted automation \`${automation_id}\`.` }] };
+    });
+    server.tool("get_automation_activity", "The activity of a comment-to-DM automation, newest first: one row per comment or message it acted on, with the DM sent, a skip and its reason (already got the DM, limit reached, comment older than 7 days, hourly cap), or a failure with the platform's error. On the Facebook Page the person shows by name (Facebook has no @handle). Use it to answer 'how many people got the DM' or 'why did this person not get it'.", {
+        automation_id: z.string().describe("The automation id (from list_automations)."),
+        outcome: z.enum(["sent", "skipped", "failed", "pending"]).optional().describe("Only rows with this outcome."),
+        limit: z.number().int().min(1).max(100).optional().describe("Rows per page (default 25, max 100)."),
+        offset: z.number().int().min(0).optional().describe("Rows to skip (for the next page)."),
+    }, { title: "Get Automation Activity", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ automation_id, ...params }) => {
+        // The automation's platform decides how a person shows: an Instagram
+        // @handle, or a Facebook name.
+        const [result, automation] = await Promise.all([
+            getClient().listAutomationEvents(automation_id, params),
+            getClient().getAutomation(automation_id).catch(() => null),
+        ]);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        const onFacebook = automation?.data?.platform === "facebook";
+        const rows = Array.isArray(result.data) ? result.data : [];
+        const counts = result.counts || {};
+        const countLine = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ") || "nothing yet";
+        if (!rows.length) {
+            return { content: [{ type: "text", text: `## Activity of automation \`${automation_id}\`\n\nTotals: ${countLine}.\n\nNo rows${params.outcome ? ` with outcome ${params.outcome}` : ""}.` }] };
+        }
+        let md = `## Activity of automation \`${automation_id}\`\n\nTotals: ${countLine}.\n\n`;
+        md += `| When | Who | Did | Outcome | Text |\n|------|-----|-----|---------|------|\n`;
+        for (const e of rows) {
+            const who = e.person.username ? (onFacebook ? e.person.username : `@${e.person.username}`) : e.person.id;
+            const did = e.kind === "comment" ? "commented" : e.kind === "dm" ? (onFacebook ? "sent a Messenger message" : "sent a DM") : "replied to a story";
+            const outcome = e.outcome === "skipped" ? `skipped: ${e.reason_label || e.reason || ""}` : e.outcome === "failed" ? `failed: ${truncate(e.reason || "", 60)}` : e.outcome;
+            const text = e.trigger_text ? `"${truncate(e.trigger_text, 50)}"` : "";
+            md += `| ${formatDateTime(e.sent_at || e.created_at)} | ${who} | ${did} | ${outcome} | ${text} |\n`;
+        }
+        const p = result.pagination;
+        if (p?.has_more)
+            md += `\n_${p.total} rows in total; pass offset ${p.offset + p.limit} for the next page._`;
+        return { content: [{ type: "text", text: md }] };
+    });
+}

package/build/tools/inbox.js

@@ -80,11 +80,15 @@ function renderNextUnanswered(result) {
     const c = item.conversation;
     const who = c.participant?.name || c.participant?.username || "Unknown";
     let md = `## Next: ${PLATFORM_EMOJI[c.platform] || ""} ${c.platform} ${c.type} from ${who}\n\n`;
-    md += `Conversation ID: \`${c.conversation_id}\`\nMessage to answer: \`#${item.message.id}\`\n\n`;
+    md += `Conversation ID: \`${c.conversation_id}\`\nMessage to answer: \`#${item.message.id}\` (pass it as message_id when replying)\n\n`;
+    if (item.reply_window?.open === false) {
+        const app = c.platform === "instagram" ? "Instagram" : "Facebook";
+        md += `⚠️ **Meta's 24-hour reply window for this DM closed ${formatDateTime(item.reply_window.closes_at)}.** OmniSocials cannot send a reply here (reply_to_inbox answers 422 outside_messaging_window). Tell the user to answer it from the ${app} app; that reply is mirrored into the inbox and clears this item. Or mark_inbox_read to skip it.\n\n`;
+    }
     md += renderInboxPost(item.message.post || c.post);
     md += renderInboxMessages(item.messages, item.message.id);
     md += `_${result.remaining || 0} more waiting._\n\n`;
-    md += `_Reply: reply_to_inbox with the conversation ID (add include_next: true to get the next one in the same call). Skip for good: mark_inbox_read. Comments: hide_inbox_comment / delete_inbox_comment with the message id._`;
+    md += `_Reply: reply_to_inbox with the conversation ID and message_id: "${item.message.id}" (add include_next: true to get the next one in the same call). Skip for good: mark_inbox_read. Comments: hide_inbox_comment / delete_inbox_comment with the message id._`;
     return md;
 }
 export function registerInboxTools(server, getClient) {
@@ -104,7 +108,7 @@ export function registerInboxTools(server, getClient) {
         unanswered: z
             .boolean()
             .optional()
-            .describe("Only conversations that still need an answer: the customer's latest DM has no reply after it (Instagram/Facebook DMs within the 24-hour reply window), or a comment/mention nobody replied to and that is not hidden. Replies typed in the native apps count as answers."),
+            .describe("Only conversations that still need an answer: the customer's latest DM has no reply after it (Instagram/Facebook DMs past the 24-hour reply window included; they cannot be answered through the API but the customer is still waiting), or a comment/mention nobody replied to and that is not hidden. Replies typed in the native apps count as answers."),
         limit: z
             .number()
             .optional()
@@ -201,8 +205,12 @@ export function registerInboxTools(server, getClient) {
             ],
         };
     });
-    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, TikTok, YouTube, X, or Threads. You can only reply to conversations that already exist. Meta direct-message replies must be within the platform's 24-hour messaging window. TikTok replies are comments only, text-only, and capped at 150 characters; they can take a few minutes to appear on TikTok while they pass spam review. YouTube replies are comments only. Threads replies are on the workspace's posts and mentions; a 401 reauth_required means the Threads connection must be reconnected to grant the reply permission. X replies are DM-only and use 2 prepaid credits per send (X's API fee passed through at cost); a 402 insufficient_credits error means the organisation needs to top up at https://app.omnisocials.com/credits; relay that link to the user rather than retrying. Each workspace can send up to 1,000 replies per day. attachment_url/attachment_type let you send media on a Facebook or Instagram DM (text is optional when an attachment is set); other platforms are text-only. Set include_next: true to get the next conversation that needs an answer back in the same call (same as get_next_unanswered), so the inbox can be worked through as: get_next_unanswered → draft → reply_to_inbox(include_next) → draft → repeat.", {
+    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, TikTok, YouTube, X, or Threads. You can only reply to conversations that already exist. For a comment or mention, pass message_id (the #id of the comment being answered): comments on one post share a conversation and without it the reply goes under the newest comment on the post. Meta direct-message replies must be within the platform's 24-hour messaging window: a 422 outside_messaging_window means the window has closed, nothing was sent, and the user must answer that DM from the Instagram or Facebook app (mirrored into the inbox) or skip it with mark_inbox_read; do not retry. TikTok replies are comments only, text-only, and capped at 150 characters; they can take a few minutes to appear on TikTok while they pass spam review. YouTube replies are comments only. Threads replies are on the workspace's posts and mentions; a 401 reauth_required means the Threads connection must be reconnected to grant the reply permission. X replies are DM-only and use 2 prepaid credits per send (X's API fee passed through at cost); a 402 insufficient_credits error means the organisation needs to top up at https://app.omnisocials.com/credits; relay that link to the user rather than retrying. Each workspace can send up to 1,000 replies per day. attachment_url/attachment_type let you send media on a Facebook or Instagram DM (text is optional when an attachment is set); other platforms are text-only. Set include_next: true to get the next conversation that needs an answer back in the same call (same as get_next_unanswered), so the inbox can be worked through as: get_next_unanswered → draft → reply_to_inbox(include_next) → draft → repeat. A 409 duplicate_reply means this exact reply already went out to this conversation in the last 10 minutes (an earlier call that looked slow or failed did succeed) or is being sent right now: nothing was sent again, do NOT retry it — continue with get_next_unanswered. A 422 reply_not_allowed means the platform refuses replies to this item for good (Facebook #1705: the comment sits on a share or boosted copy of the post, or the commenter restricts replies; YouTube: the thread's canReply is false because comments are off on the video or the comment was removed or held for review): the item is dropped from get_next_unanswered automatically, tell the user, and do NOT retry.", {
         conversation_id: z.string().describe("The conversation ID to reply to"),
+        message_id: z
+            .string()
+            .optional()
+            .describe("For comment/mention threads: the inbox id of the comment you are answering (the 'Message to answer' #id from get_next_unanswered, or a #id from get_inbox_conversation). Every comment on a post shares one conversation, so without it the reply is posted under the newest comment on the post, which can be a different person than the one you drafted for. Always pass it for comments. Ignored for DMs."),
         text: z
             .string()
             .optional()
@@ -219,9 +227,10 @@ export function registerInboxTools(server, getClient) {
             .boolean()
             .optional()
             .describe("After sending, also return the next conversation that needs an answer (full thread + post context), or 'nothing waiting'"),
-    }, { title: "Reply to Inbox Message", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ conversation_id, text, attachment_url, attachment_type, include_next }) => {
+    }, { title: "Reply to Inbox Message", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ conversation_id, message_id, text, attachment_url, attachment_type, include_next }) => {
         const result = await getClient().replyToInboxConversation(conversation_id, {
             text: text ?? "",
+            ...(message_id ? { message_id } : {}),
             attachment_url,
             attachment_type,
             ...(include_next ? { include_next: true } : {}),
@@ -240,7 +249,7 @@ export function registerInboxTools(server, getClient) {
         }
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("get_next_unanswered", "Get the next inbox item that needs an answer, with the whole conversation and the post it is on, in one call. Serves the longest-waiting item first: the customer's latest DM with no reply after it (Instagram/Facebook DMs within the 24-hour reply window only, since Meta refuses later replies), or a comment/mention nobody replied to and that is not hidden. Replies typed in the native apps count as answered (they are mirrored into the inbox), so a thread a colleague answered on their phone is not served again. Instagram mentions are skipped (no reply path). Only unread items are served by default: to skip one for good, mark_inbox_read it; pass include_read to also see read-but-unanswered items. Looks back 30 days. Loop: get_next_unanswered → draft a reply → reply_to_inbox with include_next: true → repeat until nothing is waiting.", {
+    server.tool("get_next_unanswered", "Get the next inbox item that needs an answer, with the whole conversation and the post it is on, in one call. An item needs an answer when it is the customer's latest DM with no reply after it, or a comment/mention nobody replied to and that is not hidden. Order: DMs that can still be answered first (Instagram/Facebook DMs inside Meta's 24-hour window, the one closing soonest first, plus X DMs), then Instagram/Facebook DMs whose window has closed (reply_window.open = false: OmniSocials cannot reply, tell the user to answer from the native app or skip with mark_inbox_read), then comments and mentions, oldest first. Replies typed in the native apps count as answered (they are mirrored into the inbox), so a thread a colleague answered on their phone is not served again. Instagram mentions are skipped (no reply path). Only unread items are served by default: to skip one for good, mark_inbox_read it; pass include_read to also see read-but-unanswered items. Looks back 30 days. Loop: get_next_unanswered → draft a reply → reply_to_inbox with the conversation id, message_id = the served message's #id, and include_next: true → repeat until nothing is waiting.", {
         platform: z
             .enum(INBOX_PLATFORMS)
             .optional()
@@ -252,7 +261,7 @@ export function registerInboxTools(server, getClient) {
         order: z
             .enum(["oldest", "newest"])
             .optional()
-            .describe("oldest (default): the item that has waited longest first; newest: the most recent first"),
+            .describe("oldest (default): the item that has waited longest first; newest: the most recent first. Applies within each group (answerable DMs, then expired Instagram/Facebook DMs, then comments); the groups keep their order"),
         include_read: z
             .boolean()
             .optional()
@@ -307,7 +316,7 @@ export function registerInboxTools(server, getClient) {
             ],
         };
     };
-    server.tool("hide_inbox_comment", "Hide (or unhide) a comment someone left on one of the workspace's posts, on the platform, as the post owner. Facebook, Instagram, TikTok, YouTube and Threads comments. On YouTube, hide sets the comment to 'rejected' (removed from public view together with its replies) and unhide publishes it again. Takes the message id (the #id shown by get_inbox_conversation and get_next_unanswered), not the conversation id. A hidden comment no longer counts as unanswered. If the comment was already deleted on the platform (its author removed it, etc.), this still succeeds — the response says so — and the item is marked handled; do not retry it. A 403 reconnect_required means the account was connected without the comment-moderation permission and must be reconnected in the dashboard; relay that to the user rather than retrying.", hideCommentSchema, { title: "Hide Inbox Comment", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, hideComment);
+    server.tool("hide_inbox_comment", "Hide (or unhide) a comment someone left on one of the workspace's posts, on the platform, as the post owner. Facebook, Instagram, TikTok, YouTube and Threads comments. On YouTube, hide sets the comment to 'rejected' (removed from public view together with its replies) and unhide publishes it again. Takes the message id (the #id shown by get_inbox_conversation and get_next_unanswered), not the conversation id. A hidden comment no longer counts as unanswered. If the comment was already deleted on the platform (its author removed it, etc.), this still succeeds — the response says so — and the item is marked handled; do not retry it. A 403 reconnect_required means the account was connected without the comment-moderation permission and must be reconnected in the dashboard; relay that to the user rather than retrying. A 422 cannot_hide means Facebook does not let the Page hide this particular comment (the commenter blocked the Page, their account is deactivated or restricted, or the comment sits on a shared copy of the post): retrying never changes it — tell the user, and use mark_inbox_read on the conversation if it should stop coming up. A 502 hide_not_applied means Instagram accepted the call but still reports the comment as visible (this happens with comments shown under 'Comments from Facebook' on a reel shared to Facebook; they live on Facebook and Instagram's hide does not reach them): nothing changed in the inbox, tell the user to hide it in the Instagram or Facebook app, do not retry.", hideCommentSchema, { title: "Hide Inbox Comment", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, hideComment);
     // Older name from 1.28.0 (when hiding was Threads-only). Kept so existing
     // setups keep working; same call, same platforms as hide_inbox_comment.
     server.tool("hide_inbox_reply", "Older name for hide_inbox_comment, kept so existing setups keep working; prefer hide_inbox_comment. Same behaviour: hide (or unhide with hide: false) a comment someone left on one of the workspace's posts, as the post owner, on Facebook, Instagram, TikTok, YouTube or Threads. Takes the message id (the #id in the thread), not the conversation id. A 403 reconnect_required means the account must be reconnected in the dashboard to grant the comment-moderation permission.", hideCommentSchema, { title: "Hide Inbox Comment (older name)", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, hideComment);