@omnisocials/mcp-server 1.46.0 → 1.48.0

package/README.md

@@ -212,12 +212,12 @@ Requires an API key with the opt-in `inbox:read` / `inbox:write` scopes — enab
 
 | Tool | Description |
 |------|-------------|
-| `list_automations` | List the comment-to-DM automations of the workspace (Instagram and Facebook Page), optionally by `status`, `post_id` or `platform` |
+| `list_automations` | List the comment-to-DM automations of the workspace (Instagram, Facebook Page and X), optionally by `status`, `post_id` or `platform` |
 | `get_automation` | Get one automation: trigger, keywords, DM text, public reply, limits and stats |
-| `create_automation` | Create a comment-to-DM automation: a keyword in a comment (or a DM) gets a DM back, once per person, with an optional public reply |
+| `create_automation` | Create a comment-to-DM automation: a keyword in a comment (or a DM) gets a DM back, once per person, with an optional public reply. On X (`platform: "x"`) it answers DMs only, needs X DMs on for the workspace and ends every answer with "Reply STOP to stop automatic messages." |
 | `update_automation` | Pause, resume or change the keywords, DM text, public reply, limits or post of an automation |
 | `delete_automation` | Delete an automation |
-| `get_automation_activity` | One row per comment or message the automation acted on: the DM sent, a skip with its reason, or the platform's error |
+| `get_automation_activity` | One row per comment or message the automation acted on: the DM sent, an answer waiting in the queue, a skip with its reason, a person who replied STOP on X, or the platform's error |
 
 Requires an API key with the opt-in `automations:read` / `automations:write` scopes (Settings > API, "Automations" on the key).
 
@@ -244,6 +244,18 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ## Changelog
 
+### 1.48.0 (2026-10-26)
+
+- **Added: video retention in `get_post_analytics`:** a `3-second hold (%)` row (`hold_rate_3s`: TikTok videos with TikTok comments enabled, Facebook Reels, Instagram Reels as 100 minus `skip_rate`) and a `Still watching` row that sums up the retention curve of TikTok videos and Facebook Reels and videos (1, 3, 5, 10, 15, 30 seconds and each quarter). Instagram and YouTube give no curve through their APIs.
+- **Fixed:** Instagram Reels carry `skip_rate` again, and totals across platforms add up counters only (rates and averages show per platform).
+
+### 1.47.0 (2026-10-25)
+
+- **Added: automations on X.** The automation tools take `platform: "x"`: the connected X account answers a DM that contains a keyword (or any first message, with `match: "any"`) with `dm_text`, once per person. On X only `triggers: ["dm"]` exists (the default when `platform` is `x`), with no post fields and no public replies. An active X automation needs X DMs turned on for the workspace in OmniSocials (else `409 x_dms_off`; `status: "paused"` always saves). Every X answer ends with "Reply STOP to stop automatic messages.", and a person who replies with only STOP gets no automatic DM from that X account again (in every workspace, also after the automation is deleted). X sends at most 15 answers per 15 minutes and 450 a day per account, and each answer uses 2 X DM credits. Encrypted X Chat conversations get no answer: X does not give apps their messages.
+- **Added: `status` on `create_automation`** (`paused` creates it without turning it on).
+- **Changed: answers over the send cap wait in a queue** (`queued`, out within the hour; also when X answers 429) instead of being skipped at once. `get_automation_activity` filters on `queued` and `opted_out`; new skip reasons `dms_closed`, `no_credits`, `opted_out` and `automation_off`.
+- Also in 1.47.0: the Ads tools listed above (see CHANGELOG.md; that text is a draft until Ads launches).
+
 ### 1.46.0 (2026-10-23)
 
 - **Added: comment-to-DM on a Facebook Page.** The automation tools now run on the connected Facebook Page as well as on Instagram. `create_automation` takes `platform` (`instagram`, the default, or `facebook`) and `facebook_post_id` (a Page post published outside OmniSocials, `{page-id}_{post-id}` or the post id alone; it implies `facebook`). On Facebook the DM lands in Messenger, `triggers` takes `comment` and `dm` (a keyword in a Messenger message to the Page), and `story_reply` is refused (Facebook has no story replies). Meta's rules are the same on both: one private reply per comment within 7 days, a follow-up only after the person answers. `list_automations` takes a `platform` filter and shows a Platform column; `get_automation` and `create_automation` print the platform. `update_automation` takes `facebook_post_id` to move a Facebook automation to another Page post; the platform itself cannot change (`platform_immutable`). `get_automation_activity` shows a Facebook person by name, without an @. Same on the companion server (`mcp.omnisocials.com`).

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, ApiVideoCover, AudioSearchResult, Automation, AutomationEvent, AutomationEventsResult, AutomationInput, BestTimesResult, CommentDmAutomationInput, HashtagSet, LocationSearchResult, PinterestProductCheck, PinterestProductsResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, ApprovePostResult, RejectPostResult, PostApproval, InboxConversation, InboxDeleteResult, InboxMessage, InboxNextUnanswered, Webhook } from "./types.js";
+import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, ApiVideoCover, AudioSearchResult, Automation, AutomationEvent, AutomationEventOutcome, AutomationEventsResult, AutomationInput, AutomationPlatform, BestTimesResult, CommentDmAutomationInput, HashtagSet, LocationSearchResult, PinterestProductCheck, PinterestProductsResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, ApprovePostResult, RejectPostResult, PostApproval, InboxConversation, InboxDeleteResult, InboxMessage, InboxNextUnanswered, Webhook } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -9,17 +9,34 @@ export declare function formatDate(iso: string | null): string;
 export declare function formatDateTime(iso: string | null): string;
 export declare function truncate(value: unknown, len: number): string;
 export declare function capitalize(str: string): string;
+/** Rates, averages and lengths: shown per platform, never added up across
+ * platforms (two 60% hold rates are not 120%). Mirrors
+ * NON_ADDITIVE_METRIC_KEYS in the backend's analyticsAggregate.js. */
+export declare const NON_ADDITIVE_METRIC_KEYS: Set<string>;
+/** `retention_curve` as the API returns it (TikTok, Facebook Reels and
+ * videos): the % of viewers still watching at each point of the video. */
+export interface RetentionCurve {
+    x: "seconds" | "percent";
+    base?: "views" | "plays" | "views_3s";
+    duration?: number;
+    points: Array<[number, number]>;
+}
+/** One line for a retention curve: the opening seconds, then the quarters
+ * ("1s 92% · 3s 71% · 10s 48% · 50% 40% · end 22%"). Mirrors
+ * retentionSummary in the backend's utils/analytics/retentionCurve.js. */
+export declare function retentionSummary(curve: unknown): string;
 /** Breakdown objects (reactions by type, traffic sources, ...) rendered as
  * "Label: a 12, b 3" lines under the metric table. */
 export declare function metricBreakdownRows(m: Record<string, unknown> | null | undefined): Array<[string, string]>;
 export declare function sortMetricLabels(labels: string[]): string[];
 /**
- * Flatten a raw per-platform metrics object into ordered [label, value] rows,
- * keeping every numeric counter the platform reported. Strings (note, title,
- * cover_image_url, …) are skipped; `plays` is a legacy always-0 Instagram
- * back-compat key so a zero there is noise, not data.
+ * Flatten a raw per-platform metrics object into ordered [label, value, key]
+ * rows, keeping every numeric counter the platform reported. Strings (note,
+ * title, cover_image_url, …) and objects (breakdowns, the retention curve) are
+ * skipped; `plays` is a legacy always-0 Instagram back-compat key so a zero
+ * there is noise, not data.
  */
-export declare function metricRows(m: Record<string, unknown> | null | undefined): Array<[string, number]>;
+export declare function metricRows(m: Record<string, unknown> | null | undefined): Array<[string, number, string]>;
 /** A `media_urls` entry — a plain external URL, or `{ url, alt }` to attach
  * an accessibility description (alt text, max 1500 chars) to that file. */
 export type MediaUrlEntry = string | {
@@ -467,14 +484,14 @@ export declare class OmniSocialsClient {
     listAutomations(params?: {
         status?: string;
         post_id?: string;
-        platform?: string;
+        platform?: AutomationPlatform;
     }): Promise<ApiResponse<Automation[]>>;
     getAutomation(id: string): Promise<ApiResponse<Automation>>;
     createAutomation(data: AutomationInput): Promise<ApiResponse<Automation>>;
     updateAutomation(id: string, data: AutomationInput): Promise<ApiResponse<Automation>>;
     deleteAutomation(id: string): Promise<ApiResponse<unknown>>;
     listAutomationEvents(id: string, params?: {
-        outcome?: string;
+        outcome?: AutomationEventOutcome;
         limit?: number;
         offset?: number;
     }): Promise<ApiResponse<AutomationEvent[]> & Partial<Omit<AutomationEventsResult, "data">>>;

package/build/client.js

@@ -123,11 +123,87 @@ const METRIC_LABELS = [
     ["watch_time_percentage", "Watched (%)"],
     ["completion_rate", "Completion rate (%)"],
     ["skip_rate", "Skip rate (%)"],
+    ["hold_rate_3s", "3-second hold (%)"],
     ["replays", "Replays"],
     ["subscribers_gained", "Subscribers gained"],
     ["subscribers_lost", "Subscribers lost"],
     ["duration", "Duration (s)"],
 ];
+/** Rates, averages and lengths: shown per platform, never added up across
+ * platforms (two 60% hold rates are not 120%). Mirrors
+ * NON_ADDITIVE_METRIC_KEYS in the backend's analyticsAggregate.js. */
+export const NON_ADDITIVE_METRIC_KEYS = new Set([
+    "engagement_rate",
+    "save_rate",
+    "pin_click_rate",
+    "outbound_click_rate",
+    "avg_watch_time",
+    "average_time_watched",
+    "average_view_duration",
+    "average_view_percentage",
+    "watch_time_percentage",
+    "completion_rate",
+    "full_video_watched_rate",
+    "skip_rate",
+    "hold_rate_3s",
+    "duration",
+    "upvote_ratio",
+    "story_slide_index",
+]);
+function interpolate(points, at) {
+    if (points.length === 0 || at < points[0][0] || at > points[points.length - 1][0])
+        return undefined;
+    for (let i = 0; i < points.length; i++) {
+        const [x1, y1] = points[i];
+        if (x1 === at)
+            return y1;
+        if (x1 > at) {
+            const [x0, y0] = points[i - 1];
+            return y0 + ((y1 - y0) * (at - x0)) / (x1 - x0);
+        }
+    }
+    return undefined;
+}
+function curveValueAtSecond(curve, second) {
+    if (curve.x === "seconds")
+        return interpolate(curve.points, second);
+    if (curve.x === "percent" && curve.duration && curve.duration > 0) {
+        return interpolate(curve.points, (second / curve.duration) * 100);
+    }
+    return undefined;
+}
+function curveValueAtShare(curve, percent) {
+    if (curve.x === "percent")
+        return interpolate(curve.points, percent);
+    if (curve.duration && curve.duration > 0)
+        return interpolate(curve.points, (percent / 100) * curve.duration);
+    return undefined;
+}
+/** One line for a retention curve: the opening seconds, then the quarters
+ * ("1s 92% · 3s 71% · 10s 48% · 50% 40% · end 22%"). Mirrors
+ * retentionSummary in the backend's utils/analytics/retentionCurve.js. */
+export function retentionSummary(curve) {
+    const c = curve;
+    if (!c || typeof c !== "object" || !Array.isArray(c.points) || c.points.length < 2)
+        return "";
+    const parts = [];
+    const of3sViews = c.base === "views_3s";
+    if (!of3sViews) {
+        for (const s of [1, 3, 5, 10, 15, 30]) {
+            const v = curveValueAtSecond(c, s);
+            if (v !== undefined)
+                parts.push(`${s}s ${Math.round(v)}%`);
+        }
+    }
+    for (const share of [25, 50, 75, 100]) {
+        const v = curveValueAtShare(c, share);
+        if (v !== undefined)
+            parts.push(`${share === 100 ? "end" : `${share}%`} ${Math.round(v)}%`);
+    }
+    if (parts.length === 0)
+        return "";
+    return of3sViews ? `${parts.join(" · ")} (of 3-second views)` : parts.join(" · ");
+}
 // Context keys that ride along in stored metrics, not counters.
 const NON_COUNTER_KEYS = new Set(["create_time", "story_slide_index"]);
 /** Breakdown objects (reactions by type, traffic sources, ...) rendered as
@@ -159,6 +235,9 @@ export function metricBreakdownRows(m) {
         if (parts.length)
             rows.push([label, parts.join(", ")]);
     }
+    const retention = retentionSummary(m?.retention_curve);
+    if (retention)
+        rows.push(["Still watching", retention]);
     return rows;
 }
 /** Canonical position of a metric label — for sorting totals rows collected
@@ -168,10 +247,11 @@ export function sortMetricLabels(labels) {
     return [...labels].sort((a, b) => (LABEL_ORDER.get(a) ?? 999) - (LABEL_ORDER.get(b) ?? 999));
 }
 /**
- * Flatten a raw per-platform metrics object into ordered [label, value] rows,
- * keeping every numeric counter the platform reported. Strings (note, title,
- * cover_image_url, …) are skipped; `plays` is a legacy always-0 Instagram
- * back-compat key so a zero there is noise, not data.
+ * Flatten a raw per-platform metrics object into ordered [label, value, key]
+ * rows, keeping every numeric counter the platform reported. Strings (note,
+ * title, cover_image_url, …) and objects (breakdowns, the retention curve) are
+ * skipped; `plays` is a legacy always-0 Instagram back-compat key so a zero
+ * there is noise, not data.
  */
 export function metricRows(m) {
     const rows = [];
@@ -186,7 +266,7 @@ export function metricRows(m) {
         seen.add(key);
         if (key === "plays" && n === 0)
             continue;
-        rows.push([label, n]);
+        rows.push([label, n, key]);
     }
     for (const [key, v] of Object.entries(m || {})) {
         if (seen.has(key) || NON_COUNTER_KEYS.has(key))
@@ -194,7 +274,7 @@ export function metricRows(m) {
         const n = Number(v);
         if (!Number.isFinite(n))
             continue;
-        rows.push([capitalize(key.replace(/_/g, " ")), n]);
+        rows.push([capitalize(key.replace(/_/g, " ")), n, key]);
     }
     return rows;
 }

package/build/index.js

@@ -30,7 +30,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.46.0",
+    version: "1.48.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/tools/analytics.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { formatNumber, capitalize, metricRows, metricBreakdownRows, sortMetricLabels } from "../client.js";
+import { formatNumber, capitalize, metricRows, metricBreakdownRows, sortMetricLabels, NON_ADDITIVE_METRIC_KEYS } 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, 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.", {
+    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). Video retention: hold_rate_3s (% of viewers still watching at second 3) on TikTok videos (with TikTok comments enabled), Facebook Reels, and Instagram Reels (there 100 minus skip_rate, Meta's 3-second skip rate); a 'Still watching' row sums up the retention curve (TikTok videos, Facebook Reels and videos) at 1, 3, 5, 10, 15 and 30 seconds and at each quarter of the video. Instagram and YouTube give no curve through their APIs. Rates and averages show per platform, never added up across platforms. 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);
@@ -47,7 +47,11 @@ export function registerAnalyticsTools(server, getClient) {
             const denom = getImpressions(platform, m);
             totalEngagements += engagements;
             totalDenom += denom;
-            for (const [label, n] of rows) {
+            for (const [label, n, key] of rows) {
+                // Rates, averages and lengths do not add up across platforms (two
+                // 60% hold rates are not 120%); they show per platform only.
+                if (NON_ADDITIVE_METRIC_KEYS.has(key))
+                    continue;
                 if (!totalsByLabel.has(label))
                     totalOrder.push(label);
                 totalsByLabel.set(label, (totalsByLabel.get(label) || 0) + n);

package/build/tools/automations.d.ts

@@ -1,9 +1,9 @@
 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";
+import type { Automation, AutomationInput, AutomationPlatform } from "../types.js";
+export declare const automationChannelLabel: (platform: string | null | undefined) => "Facebook Page" | "Instagram" | "X";
 type Fields = {
-    platform?: "instagram" | "facebook";
+    platform?: AutomationPlatform;
     name?: string;
     keywords?: string[];
     match?: "word" | "contains" | "any";

package/build/tools/automations.js

@@ -2,31 +2,34 @@ 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 PLATFORM = z.enum(["instagram", "facebook", "x"]);
 const KINDS = z.enum(["comment", "dm", "story_reply"]);
+const OUTCOME = z.enum(["sent", "skipped", "failed", "pending", "queued", "opted_out"]);
 // How the channel reads in a table or a sentence.
-export const automationChannelLabel = (platform) => platform === "facebook" ? "Facebook Page" : "Instagram";
+export const automationChannelLabel = (platform) => platform === "facebook" ? "Facebook Page" : platform === "x" ? "X" : "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."),
+    platform: PLATFORM.optional().describe("Where the automation runs: 'instagram' (default) = the connected Instagram account, 'facebook' = the connected Facebook Page (the DM lands in Messenger), 'x' = the connected X account (it answers DMs only; see create_automation). 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."),
+    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. On X, OmniSocials adds the line 'Reply STOP to stop automatic messages.' under it. 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 (Instagram and Facebook; X has none). An empty array turns the public reply off."),
+    triggers: z.array(KINDS).min(1).optional().describe("What starts the automation. 'comment' (default on Instagram and Facebook) = a comment on an Instagram post or reel, or on a Facebook Page post; 'dm' = a keyword in a DM to the Instagram account, in a Messenger message to the Facebook Page, or in a DM to the X account; 'story_reply' = a keyword in a reply to an Instagram story (Instagram only: Facebook has no story replies). On X only 'dm' exists, and it is the default there. One automation can listen to several."),
+    scope: SCOPE.optional().describe("For the comment trigger (Instagram and Facebook; an X automation has no post): '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' (Instagram and Facebook): 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.
+// given are sent, so update_automation leaves the rest untouched. The API's
+// default trigger is a comment, which X does not have: an X create without
+// triggers sends ["dm"].
 export function buildAutomationBody(f, { create }) {
     const body = {};
     if (f.name !== undefined)
@@ -43,6 +46,8 @@ export function buildAutomationBody(f, { create }) {
         body.trigger = {};
         if (f.triggers !== undefined)
             body.trigger.kinds = f.triggers;
+        else if (create && f.platform === "x")
+            body.trigger.kinds = ["dm"];
         if (f.scope !== undefined)
             body.trigger.scope = f.scope;
         if (f.keywords !== undefined)
@@ -94,7 +99,7 @@ export function describeAutomation(a) {
     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.", {
+    server.tool("list_automations", "List the comment-to-DM automations of this workspace, on Instagram, on the Facebook Page and on X. 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; on X it answers DMs only. 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."),
@@ -116,7 +121,7 @@ export function registerAutomationTools(server, getClient) {
         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 }) => {
+    server.tool("get_automation", "Get one comment-to-DM automation: its platform (Instagram, the Facebook Page or X), 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) }] };
@@ -124,10 +129,16 @@ export function registerAutomationTools(server, getClient) {
             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) => {
+    server.tool("create_automation", "Create a comment-to-DM automation on the connected Instagram account (default), on the connected Facebook Page (platform 'facebook') or on the connected X account (platform 'x'): 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 Instagram and Facebook: 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, and an answer over the cap waits in a queue and goes out within the hour. 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). On X the automation answers DMs only: triggers ['dm'] (the default there; X allows an automated DM only after the person wrote first), so a DM to the X account with a keyword, or any first message with match 'any', gets dm_text once per person; no post fields and no public replies. An X automation runs only while X DMs are turned on for the workspace in OmniSocials (Social Inbox, X DMs card, or the automation editor): an active create without them answers 409 x_dms_off, so tell the user where to turn them on, or create it with status 'paused'. 409 x_not_connected means the workspace has no X account. Every X answer ends with the line 'Reply STOP to stop automatic messages.', and a person who replies STOP gets no automatic DM from that X account again (the stop list belongs to the account: it holds after the automation is deleted, for later automations and in every workspace with that account). X takes at most 15 answers per 15 minutes and 450 a day per account; more wait in the queue for up to an hour. Each X answer uses X DM credits like an inbox reply (2 credits); when the credits ran out the answer is skipped (no_credits): top up, then answer in the Social Inbox. X does not give apps the messages of an encrypted X Chat conversation, so those get no answer. To attach automations to a NEW post, pass comment_dm_automation on create_post instead (Instagram and Facebook).", {
+        ...AUTOMATION_FIELDS,
+        status: z.enum(["active", "paused"]).optional().describe("'paused' creates it without turning it on (default 'active'). A paused X automation saves even while X DMs are off; turn it on later with update_automation."),
+    }, { title: "Create Automation", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ status, ...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 }));
+        const body = buildAutomationBody(params, { create: true });
+        if (status)
+            body.status = status;
+        const result = await getClient().createAutomation(body);
         if (result.error)
             return { content: [{ type: "text", text: errorText(result.error) }] };
         if (!result.data)
@@ -136,11 +147,13 @@ export function registerAutomationTools(server, getClient) {
         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._`;
+        if (a.platform === "x" && a.status === "paused")
+            md += `\n_Paused: it answers nothing until it is turned on (update_automation with status 'active'), which needs X DMs on for the workspace._`;
         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.", {
+    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 to another channel (Instagram, the Facebook Page or X), create a new automation. Turning an X automation on (status 'active') needs X DMs on for the workspace, else 409 x_dms_off. 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."),
+        status: z.enum(["active", "paused"]).optional().describe("'paused' stops it without deleting it; 'active' resumes it (on X only while X DMs are on for the workspace)."),
         ...AUTOMATION_FIELDS,
     }, { title: "Update Automation", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ automation_id, status, ...fields }) => {
         const body = buildAutomationBody(fields, { create: false });
@@ -155,15 +168,15 @@ export function registerAutomationTools(server, getClient) {
             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 }) => {
+    server.tool("delete_automation", "Delete a comment-to-DM automation (Instagram, Facebook Page or X) 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'.", {
+    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, an answer that waits in the queue (queued: the send cap is full or X asked to wait; it goes out within the hour), a skip and its reason (already got the DM, limit reached, comment older than 7 days, the send cap stayed full for an hour, the person does not accept DMs from the X account, credits ran out before the answer, the person replied STOP earlier, the automation was paused while the answer waited), a person who replied STOP on X (opted_out: no automatic DMs to them from that X account again, in any workspace or automation), 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."),
+        outcome: OUTCOME.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 }) => {
@@ -187,7 +200,11 @@ export function registerAutomationTools(server, getClient) {
         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 outcome = e.outcome === "skipped" ? `skipped: ${e.reason_label || e.reason || ""}`
+                : e.outcome === "failed" ? `failed: ${truncate(e.reason || "", 60)}`
+                    : e.outcome === "queued" ? `queued: ${e.reason_label || "waits for room under the send limit"}`
+                        : e.outcome === "opted_out" ? `opted out: ${e.reason_label || "replied STOP"}`
+                            : 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`;
         }

package/build/types.d.ts

@@ -631,10 +631,20 @@ export interface HashtagSet {
     created_at: string;
     updated_at: string;
 }
-/** The channel an automation runs on: the Instagram account or the Facebook Page. */
-export type AutomationPlatform = "instagram" | "facebook";
-/** `story_reply` is Instagram only: Facebook has no story replies. */
+/** The channel an automation runs on: the Instagram account, the Facebook Page or the X account. */
+export type AutomationPlatform = "instagram" | "facebook" | "x";
+/** The channels a post-bound automation (`comment_dm_automation`) can run on: X has no comment trigger. */
+export type CommentDmPlatform = "instagram" | "facebook";
+/** `story_reply` is Instagram only: Facebook has no story replies. X has `dm` only. */
 export type AutomationTriggerKind = "comment" | "dm" | "story_reply";
+/**
+ * `queued` = the answer waits for a free slot under the send cap (X 15 per 15
+ * minutes and 450 a day, Instagram and Facebook 180 an hour), or for X's
+ * reset time after X answered 429, and goes out within the hour, else it
+ * becomes `skipped` with `rate_limited`. `opted_out` = the person replied
+ * STOP on X (the stop list of that X account).
+ */
+export type AutomationEventOutcome = "sent" | "skipped" | "failed" | "pending" | "queued" | "opted_out";
 export type AutomationScope = "post" | "next_post" | "any";
 export type AutomationMatch = "word" | "contains" | "any";
 export interface AutomationPost {
@@ -696,7 +706,11 @@ export interface Automation {
 /** The body of POST /automations; every section is optional on PATCH. */
 export interface AutomationInput {
     name?: string | null;
-    /** Default instagram; cannot change on PATCH (400 platform_immutable) */
+    /**
+     * Default instagram; cannot change on PATCH (400 platform_immutable). `x`
+     * takes trigger.kinds ["dm"] only, needs X DMs on for an active automation
+     * (409 x_dms_off; `status: "paused"` always saves) and has no post fields.
+     */
     platform?: AutomationPlatform;
     post_id?: string;
     instagram_media_id?: string;
@@ -726,7 +740,7 @@ export interface AutomationInput {
 /** `comment_dm_automation` on a post: the automations bound to that post. */
 export interface CommentDmAutomationInput {
     /** One automation per listed channel; default Instagram when the post goes there, else Facebook */
-    platforms?: AutomationPlatform[];
+    platforms?: CommentDmPlatform[];
     trigger?: {
         keywords?: string[];
         match?: AutomationMatch;
@@ -748,10 +762,10 @@ export interface CommentDmAutomationInput {
 /** `comment_dm_automation` on a post: the first automation's fields (Instagram
  * first), plus the channels and the id of each automation. */
 export interface PostCommentDmAutomation extends Automation {
-    platforms?: AutomationPlatform[];
+    platforms?: CommentDmPlatform[];
     automations?: Array<{
         id: string;
-        platform: AutomationPlatform;
+        platform: CommentDmPlatform;
         status: Automation["status"];
     }>;
 }
@@ -759,10 +773,20 @@ export interface AutomationEvent {
     id: string;
     automation_id: string;
     kind: AutomationTriggerKind;
-    outcome: "sent" | "skipped" | "failed" | "pending";
+    outcome: AutomationEventOutcome;
+    /**
+     * `skipped`: already_sent, limit_reached, stopped, window_passed,
+     * rate_limited (the send cap stayed full for an hour), cannot_message,
+     * already_replied, dm_window_passed, dms_closed (X: the person does not
+     * accept DMs from the account), no_credits (credits ran out before the
+     * answer), opted_out (the person replied STOP before, also while the
+     * answer waited), automation_off (paused or finished while the answer
+     * waited). `failed`: the platform's error text. A `queued` row carries
+     * the reason it waits, an `opted_out` row the reason `opted_out`.
+     */
     reason: string | null;
     reason_label: string | null;
-    /** `username` = the Instagram @handle, or the person's name on Facebook */
+    /** `username` = the Instagram or X @handle, or the person's name on Facebook */
     person: {
         id: string;
         username: string | null;
@@ -933,6 +957,11 @@ export interface PostAnalyticsStorySlide {
 export interface PostAnalyticsPlatformEntry {
     platform: string;
     platform_post_id: string;
+    /** Numbers and strings, plus objects this type leaves out: breakdowns
+     * (`reactions`, `impression_sources`, ...) and, on TikTok and Facebook
+     * videos, `retention_curve` (RetentionCurve in client.ts). `hold_rate_3s`
+     * is the % of viewers still watching at second 3 (TikTok, Facebook Reels,
+     * Instagram Reels as 100 - skip_rate). */
     metrics: Record<string, number | string>;
     thread_parts: number;
     collected_at: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "mcpName": "io.github.omnisocials/mcp-server",
   "description": "MCP server for OmniSocials API - manage social media posts, media, accounts, analytics, and webhooks",
   "type": "module",
@@ -52,7 +52,7 @@
     "typescript": "^5.8.2"
   },
   "overrides": {
-    "zod": "4.4.0",
+    "zod": "4.6.7",
     "fast-uri": "^3.1.8",
     "hono": "^4.13.7",
     "qs": "^6.16.0"