@omnisocials/mcp-server 1.39.0 → 1.48.0

package/README.md

@@ -112,6 +112,8 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `threads` | Threads | Posts, chained threads via `threads.thread_parts`, location tagging via `threads.location_id` (rolling out) |
 | `bluesky` | Bluesky | Posts, chained threads via `bluesky.thread_parts` |
 | `mastodon` | Mastodon | Posts, chained threads via `mastodon.thread_parts` |
+| `telegram` | Telegram | A channel or group the OmniSocials bot posts to: text, photos, videos, GIFs, albums of up to 10, native polls and link buttons via `telegram` |
+| `discord` | Discord | One Discord channel, posted through its webhook: text, up to 10 images, GIFs and videos, native polls, link buttons and forum post titles via `discord` |
 
 ## Available Tools
 
@@ -206,11 +208,24 @@ Apply a set when creating a post: `create_post` / `create_and_publish_post` acce
 
 Requires an API key with the opt-in `inbox:read` / `inbox:write` scopes — enable "Social Inbox access" when you create the key.
 
+### Automations (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `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. 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, 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).
+
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `OMNISOCIALS_API_KEY` | Yes | Your API key (`omsk_live_*` or `omsk_test_*`). Comma-separated for multiple workspaces. |
+| `OMNISOCIALS_API_KEY` | Yes | Your API key (`omsk_live_*`; there are no test keys). Comma-separated for multiple workspaces. |
 | `OMNISOCIALS_BASE_URL` | No | Custom API base URL (defaults to production) |
 
 ## Alternative: Agent Skills
@@ -229,6 +244,56 @@ 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`).
+- **Added: `platforms` on `comment_dm_automation`.** `create_post`, `create_and_publish_post` and `update_post` take `comment_dm_automation.platforms`: `["instagram"]`, `["facebook"]` or both, one automation per channel with the same keywords, DM, public reply and limits. Each listed channel must be a channel of the post. Without it, the post gets one automation: Instagram when the post goes there, else Facebook. On `update_post` a channel no longer listed loses its automation, and `null` removes them all. The post shows every automation id with its channel; `get_post` shows them for a post that goes to Instagram or Facebook.
+- **Added: Discord.** `discord` is a new channel ID: one Discord channel the user connected in OmniSocials (with Continue with Discord, or by pasting a webhook URL). The post is sent through the channel's webhook, so it shows the webhook's name and picture. `create_post`, `create_and_publish_post` and `update_post` take a `discord` object: `silent` (no notification), `link_preview` (`false` hides the link previews), `allow_mentions` (off by default: @everyone, @here and role mentions in the text ping nobody until it is `true`), `spoiler`, `thread_name` (the post title in a forum or media channel, where Discord requires one; max 100 chars), up to 5 `buttons` (`{ text, url }`, labels up to 80 chars, not with a poll) and a native `poll` (`{ options: 2-10 of up to 55 chars, duration_hours: 1-768 (default 24), multiple }`; the post text is the question, max 300 chars; no media). Text up to 2,000 characters; up to 10 images, GIFs and videos per message, which may mix; a video or GIF over Discord's 20 MB file limit is sent as a link in the message (listed in `result.video_links`); no Stories; a Reel is sent as one video message. On `update_post` every key merges into the stored options and `null` removes it. `get_post` prints the options and, once sent, the link to the message. `list_accounts` and `get_account` show the server, the channel name and type (`platform_details.channel_name` and `channel_type`: read by the OmniSocials bot, which Continue with Discord adds with no permissions, or given by the person when connecting), the webhook name, the channel id, how it was connected and the channel link; with the bot in the server, `get_account_analytics` shows the member count as followers. Discord gives webhooks no view counts: `get_post_analytics` shows the reactions (total and per emoji) and the poll votes. Same on the companion server (`mcp.omnisocials.com`), whose version is 1.46.0 too.
+
+### 1.45.0 (not published; included in 1.46.0)
+
+- **Added: a link to the post on every post tool.** `publish_post`, `retry_post`, `approve_post` and `reject_post` now end with the "Open in OmniSocials" row that `create_post`, `create_and_publish_post`, `get_post` and `update_post` already had, and `publish_post` says that `get_post` lists the live links once each platform has posted. Every app link carries `?ref=mcp`, so OmniSocials can count the visits from an agent's answer (the app ignores the parameter).
+- **Added on the companion server (`mcp.omnisocials.com`): the post card.** In apps that show MCP Apps (Claude, ChatGPT, Cursor, VS Code), the results of `get_post`, `create_post`, `create_and_publish_post`, `update_post`, `publish_post`, `retry_post`, `approve_post` and `reject_post` appear as a card: the post the way each platform will show it, a channel list with each channel's state (the planned time, Posting, Posted with its live link, or Failed with the reason), and a link into OmniSocials. While a post publishes, the card follows it until every channel is done. Other clients (terminal agents, automations) get the same text answer as before. The card is built as an MCP App resource, `ui://omnisocials/post-card.html`; a new tool, `get_post_status`, is only for the card (hidden from the model in apps that support MCP Apps).
+
+### 1.44.0 (2026-10-17, not published; included in 1.46.0)
+
+- **Added: Telegram.** `telegram` is a new channel ID: a Telegram channel or group the user connected in OmniSocials, where the OmniSocials bot is an admin that can post. `create_post`, `create_and_publish_post` and `update_post` take a `telegram` object: `silent`, `link_preview`, `pin`, `protect_content`, `spoiler`, `caption_above_media`, up to 3 `buttons` (`{ text, url }`, one per row, not on an album or a poll), a native `poll` (`{ options: 2-12 of up to 100 chars, open_period: 5-2628000 seconds, multiple }`; the post text is the question, max 300 chars; no media) and `first_comment` (a reply under the post). Text up to 4,096 characters; with media, text over 1,024 characters is sent as a reply under the media. Albums hold up to 10 photos and videos; a GIF goes on its own; files up to 50 MB; no Stories; a Reel is sent as a video message. On `update_post` every key merges into the stored options and `null` removes it. `get_post` prints the options and, once sent, the message count, the pin and the link. `list_accounts` and `get_account` show the chat type, the subscribers and the link. Telegram gives bots no view counts: `get_post_analytics` shows the reactions (total and per emoji) and the poll votes. Same on the companion server (`mcp.omnisocials.com`).
+- **Changed: the three version strings match again.** `package.json`, the stdio server and the companion server all say 1.44.0 (the stdio server said 1.42.0 and the companion server 1.41.0 after the last releases).
+
+### 1.43.0 (2026-10-12, not published; included in 1.46.0)
+
+- **Polls on X, Threads and Mastodon.** `create_post`, `create_and_publish_post` and `update_post` take `poll` under `x`, `threads` and `mastodon` (the post text is the question): X `{ options: 2-4 of up to 25 chars, duration_minutes: 5-10080 }`, Threads `{ options: 2-4 of 1-25 chars }` (closed by Threads after 24 hours), Mastodon `{ options, expires_in, multiple, hide_totals }` within the instance's limits. The API refuses a channel with a poll and media; on a thread the poll goes on the first part. `null` on `update_post` removes it. `get_post` prints the poll per channel.
+
+### 1.42.0 (not published; included in 1.46.0)
+
+- **Added: comment-to-DM automations.** Six new tools manage the Instagram comment-to-DM automations of the workspace: `list_automations`, `get_automation`, `create_automation`, `update_automation` (pause, resume, new keywords, new DM text, new limits, another post), `delete_automation` and `get_automation_activity` (one row per comment or message the automation acted on: the DM sent, a skip with its reason, or Instagram's error). An automation DMs a person once when they comment a keyword on a post, and can post a public reply under the comment; `triggers` also takes `dm` (a keyword in a DM to the account) and `story_reply` (a keyword in a reply to a story). `scope` is one post (`post_id` = an OmniSocials post, scheduled or live; `instagram_media_id` = a post published outside OmniSocials, read from Instagram to check it belongs to the account), `next_post` (the next Instagram post the workspace publishes) or `any` (every post). Backed by the new `/automations` endpoints, which need the opt-in API key scopes `automations:read` and `automations:write` (Settings > API, "Automations" on the key); the tools say so on a 403. Same on the companion server (`mcp.omnisocials.com`), where the OAuth session needs the `create_schedule_post` permission for the writes.
+- **Added: `comment_dm_automation` on `create_post`, `create_and_publish_post` and `update_post`.** A comment-to-DM automation bound to the new post (Instagram must be a channel): `{ trigger: { keywords, match }, actions: { dm: { text }, public_reply: { enabled, variations } }, limits: { max_sends, stop_at } }`. The automation starts listening once the post is live on Instagram. On `update_post` the object replaces the post's automation and `null` removes it. The created automation comes back as `comment_dm_automation` on the post, and `get_post` shows it for a post that goes to Instagram. Same on the companion server.
+
+### 1.41.0 (not published; included in 1.46.0)
+
+- **Added: image fit per channel (`media_fit`).** A feed image whose ratio is outside what a channel shows uncropped is handled per channel at create time. Instagram shows feed images between 4:5 and 1.91:1: a 9:16 (story-style) or very wide image posted to the Instagram feed is now cropped to 4:5 / 1.91:1 around the subject by default, because Instagram cut it to that window anyway (a blind centre crop) and Meta cannot boost a feed post outside it. Pinterest keeps a Pin taller than 2:3 and reports it. `create_post`, `create_and_publish_post` and `update_post` take `media_fit: { instagram: "auto" | "crop" | "keep", pinterest: ... }`; every decision comes back as a `warnings` entry with code `image_fit` (`action` cropped / kept / crop_failed, the crop's url, and how to undo it). The crop is a separate file for that channel only; `default` and the other channels keep the original; stories, reels and videos are never cropped. On `update_post`, `media_fit` alone re-decides the stored images (`keep` gives the original back). Same on the companion server (`mcp.omnisocials.com`).
+- **Changed: `check_media_compatibility` reports image fit.** For an image whose size is known (a library file of the workspace) the answer lists, per connected channel with a rule, whether its feed shows the image uncropped and what a post does by default, so an assistant can ask "crop to 4:5 or keep the original?" before it posts. Media items (`list_media`, `get_media`, uploads) now carry `width` and `height`.
+
+### 1.40.0 (not published; included in 1.46.0)
+
+- **Changed: the MCP SDK dependency moves to 1.32.1.** GHSA-6qxp-vccf-f47h (CVE-2026-104850) is in the SDK's OAuth client, which let an MCP server name the authorization server that received the client's credentials. This package is a server and talks to OmniSocials with an API key, so it was not affected; the move clears the advisory for everyone who installs it.
+
+### 1.39.1 (2026-10-06, not published; included in 1.46.0)
+
+- **Changed: `list_pinterest_products` names an account without a catalog.** Pinterest answers HTTP 409 ("Can't access this feature without an existing catalog") when the connection has catalog access but the account has no catalog yet. The API now returns `no_catalog: true` with empty `products` and `product_groups` instead of a `platform_error`, and the tool says where the user adds products (https://www.pinterest.com/business/catalogs/). Seen live on 2026-10-06, the first day of the feature.
+
 ### 1.39.0 (2026-10-05)
 
 - **Added: tag products on a Pinterest Pin.** `pinterest.product_tags` on `create_post`, `create_and_publish_post` and `update_post` takes up to 24 product Pins of the connected Pinterest account (Pin IDs or Pin links), so people can shop the items in the image. Pinterest accepts a product only when its Pin is public, belongs to the same account and links to a website that account claimed; products of other merchants cannot be tagged. The tags are added right after the Pin is published. A product that Pinterest refuses never fails the post: the other products are still tagged, and `get_post` shows the outcome (`product_tags_result`, with Pinterest's reason for each product that was not tagged).
@@ -365,7 +430,7 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 ### 1.16.0
 
 - **Hashtag sets:** save reusable, named groups of hashtags per workspace and apply one to a new post in a single call. Four new tools: `list_hashtag_sets`, `create_hashtag_set`, `update_hashtag_set`, `delete_hashtag_set`.
-- `create_post` / `create_and_publish_post` accept `hashtag_set`, `hashtag_placement` (`caption_append` default, or `first_comment`), and `hashtag_platforms`. The set expands server-side once at create time — editing a set later never changes existing posts; duplicate tags are skipped; Instagram's 30-hashtag cap fails fast with `hashtag_limit_exceeded`.
+- `create_post` / `create_and_publish_post` accept `hashtag_set`, `hashtag_placement` (`caption_append` default, or `first_comment`), and `hashtag_platforms`. The set expands server-side once at create time — editing a set later never changes existing posts; duplicate tags are skipped; Instagram's 5-hashtag cap fails fast with `hashtag_limit_exceeded`.
 - Same tools on the companion server (`mcp.omnisocials.com`).
 
 ### 1.15.0

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, ApiVideoCover, AudioSearchResult, BestTimesResult, 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 | {
@@ -44,10 +61,27 @@ export interface XThreadPartInput {
      * Entries may be `{ url, alt }` to attach alt text (photos/GIFs only). */
     media_urls?: MediaUrlEntry[];
 }
+/**
+ * A poll on an X, Threads or Mastodon post (the post text is the question).
+ * X: 2 to 4 options of up to 25 characters, duration_minutes 5 to 10080
+ * (default 1440). Threads: 2 to 4 options of 1 to 25 characters, closed by
+ * Threads after 24 hours. Mastodon: options and expires_in (seconds) within
+ * the instance's limits, plus multiple and hide_totals. No media together
+ * with a poll; on a thread the poll goes on the first part. On update,
+ * `null` removes the poll.
+ */
+export interface ChannelPollInput {
+    options: string[];
+    duration_minutes?: number;
+    expires_in?: number;
+    multiple?: boolean;
+    hide_totals?: boolean;
+}
 export interface XPostOptions {
     reply_settings?: "" | "following" | "mentionedUsers";
     paid_partnership?: boolean;
     made_with_ai?: boolean;
+    poll?: ChannelPollInput | null;
     /** Provide 2–25 parts to publish as a thread. Omit for a single tweet. */
     thread_parts?: XThreadPartInput[];
 }
@@ -93,6 +127,7 @@ export interface MastodonThreadPartInput {
     media_urls?: MediaUrlEntry[];
 }
 export interface MastodonPostOptions {
+    poll?: ChannelPollInput | null;
     /** Provide 2–25 parts to publish as a thread. Omit for a single status. */
     thread_parts?: MastodonThreadPartInput[];
 }
@@ -101,8 +136,96 @@ export interface MastodonPostOptions {
  * single status); `undefined` leaves the existing thread untouched.
  */
 export interface MastodonPostOptionsUpdate {
+    poll?: ChannelPollInput | null;
     thread_parts?: MastodonThreadPartInput[] | null;
 }
+export interface TelegramButtonInput {
+    /** Button label, 1 to 64 characters. */
+    text: string;
+    /** https://, http:// or tg:// link. */
+    url: string;
+}
+export interface TelegramPollInput {
+    /** 2 to 12 answer options of up to 100 characters, all different. */
+    options: string[];
+    /** Seconds the poll stays open (5 to 2628000). Omit to keep it open. */
+    open_period?: number;
+    /** Allow several answers per person. */
+    multiple?: boolean;
+}
+export interface TelegramPostOptions {
+    silent?: boolean | null;
+    link_preview?: boolean | null;
+    pin?: boolean | null;
+    protect_content?: boolean | null;
+    spoiler?: boolean | null;
+    caption_above_media?: boolean | null;
+    /** Up to 3 link buttons, one per row. Not on an album or a poll. */
+    buttons?: TelegramButtonInput[] | null;
+    /** A native poll; the post text is the question (max 300 characters). */
+    poll?: TelegramPollInput | null;
+    /** A reply under the post, sent right after it is published. */
+    first_comment?: string;
+}
+/** What GET /posts/{id} returns under `telegram` once the post went out. */
+export interface TelegramPostResult {
+    chat_id: string | null;
+    message_ids: string[];
+    pinned: boolean;
+    pin_error?: string;
+    text_message_id?: string;
+    link_public: string | null;
+    link_private: string | null;
+    sent_at: string | null;
+}
+export interface DiscordButtonInput {
+    /** Button label, 1 to 80 characters. */
+    text: string;
+    /** https:// or http:// link. */
+    url: string;
+}
+export interface DiscordPollInput {
+    /** 2 to 10 answer options of up to 55 characters, all different. */
+    options: string[];
+    /** Hours the poll stays open (1 to 768). Default 24. */
+    duration_hours?: number;
+    /** Allow several answers per person. */
+    multiple?: boolean;
+}
+export interface DiscordPostOptions {
+    /** Send without a push or desktop notification (@silent). */
+    silent?: boolean | null;
+    /** false hides the previews of the links in the text. */
+    link_preview?: boolean | null;
+    /** true lets @everyone, @here, role and user mentions ping. Off by default. */
+    allow_mentions?: boolean | null;
+    /** Blur every image and video until someone clicks it. */
+    spoiler?: boolean | null;
+    /** Post title in a forum or media channel (required there), max 100 characters. */
+    thread_name?: string | null;
+    /** Up to 5 link buttons in one row. Not with a poll. */
+    buttons?: DiscordButtonInput[] | null;
+    /** A native poll; the post text is the question (max 300 characters). */
+    poll?: DiscordPollInput | null;
+}
+/** What GET /posts/{id} returns under `discord` once the message went out. */
+export interface DiscordPostResult {
+    webhook_id: string | null;
+    guild_id: string | null;
+    channel_id: string | null;
+    /** The forum post the message opened, in a forum or media channel. */
+    thread_id: string | null;
+    message_id: string | null;
+    /** discord.com/channels/<server>/<channel or thread>/<message>. */
+    url: string | null;
+    sent_at: string | null;
+    /** Media sent as a link in the text (videos and GIFs over 20 MB). */
+    video_links: string[];
+    /** A second message with the media links, when they did not fit in the text. */
+    link_message_id: string | null;
+    /** Codes such as "media_sent_as_links" or "links_sent_as_follow_up". */
+    warnings: string[];
+}
 export interface ThreadsThreadPartInput {
     /** Part text, 1 to 500 characters. */
     text: string;
@@ -114,6 +237,7 @@ export interface ThreadsThreadPartInput {
     media_urls?: MediaUrlEntry[];
 }
 export interface ThreadsPostOptions {
+    poll?: ChannelPollInput | null;
     /** Provide 2 to 25 parts to publish as a thread. Omit for a single post.
      * When set, the Threads caption is taken from part 1. */
     thread_parts?: ThreadsThreadPartInput[];
@@ -128,6 +252,7 @@ export interface ThreadsPostOptions {
  * single post); `undefined` leaves the existing thread untouched.
  */
 export interface ThreadsPostOptionsUpdate {
+    poll?: ChannelPollInput | null;
     thread_parts?: ThreadsThreadPartInput[] | null;
     /** New Threads location id, or null to remove the tag. Omit to leave the
      * existing tag untouched. */
@@ -152,6 +277,10 @@ export interface CreatePostInput {
     content: string | Record<string, string>;
     channels?: string[];
     scheduled_at?: string;
+    /** With scheduled_at: keep the time but store the post as a draft (planned draft). */
+    draft?: boolean;
+    /** Image fit per channel: { instagram: "auto" | "crop" | "keep" }. */
+    media_fit?: Record<string, "auto" | "crop" | "keep">;
     media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
     media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
     type?: string;
@@ -183,11 +312,15 @@ export interface CreatePostInput {
     mastodon?: MastodonPostOptions;
     threads?: ThreadsPostOptions;
     google_business?: Record<string, unknown>;
+    telegram?: TelegramPostOptions | null;
+    discord?: DiscordPostOptions | null;
     hashtag_set?: string;
     hashtag_placement?: "caption_append" | "first_comment";
     hashtag_platforms?: string[];
     /** Route the post through a saved approval workflow (GET /approval-workflows). */
     approval_workflow_id?: string;
+    /** Comment-to-DM automations bound to this post (Instagram or Facebook must be a channel). `null` removes them on update. */
+    comment_dm_automation?: CommentDmAutomationInput | null;
 }
 export interface ApprovalWorkflowApprover {
     id: string;
@@ -234,6 +367,8 @@ export declare class OmniSocialsClient {
     updatePost(id: string, data: {
         content?: string | Record<string, string>;
         scheduled_at?: string;
+        /** false = schedule a planned draft at its stored time; true = unschedule, keep the time. */
+        draft?: boolean;
         channels?: string[];
         media_ids?: MediaIdEntry[] | Record<string, MediaIdEntry[]>;
         media_urls?: MediaUrlEntry[] | Record<string, MediaUrlEntry[]>;
@@ -258,12 +393,15 @@ export declare class OmniSocialsClient {
         linkedin?: Record<string, unknown>;
         linkedin_page?: Record<string, unknown>;
         linkedin_poll?: LinkedInPollInput | null;
+        comment_dm_automation?: CommentDmAutomationInput | null;
         tiktok?: Record<string, unknown>;
         x?: XPostOptionsUpdate;
         bluesky?: BlueskyPostOptionsUpdate;
         mastodon?: MastodonPostOptionsUpdate;
         threads?: ThreadsPostOptionsUpdate;
         google_business?: Record<string, unknown>;
+        telegram?: TelegramPostOptions | null;
+        discord?: DiscordPostOptions | null;
     }): Promise<ApiResponse<ApiPost>>;
     deletePost(id: string): Promise<ApiResponse<unknown>>;
     publishPost(id: string): Promise<ApiResponse<PublishPostResult>>;
@@ -343,6 +481,20 @@ export declare class OmniSocialsClient {
         hashtags?: string[];
     }): Promise<ApiResponse<HashtagSet>>;
     deleteHashtagSet(id: string): Promise<ApiResponse<unknown>>;
+    listAutomations(params?: {
+        status?: string;
+        post_id?: 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?: AutomationEventOutcome;
+        limit?: number;
+        offset?: number;
+    }): Promise<ApiResponse<AutomationEvent[]> & Partial<Omit<AutomationEventsResult, "data">>>;
     listAccounts(): Promise<ApiResponse<Account[]> & {
         workspace_id?: number | string | null;
         workspace_name?: string | null;

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,10 +274,17 @@ 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;
 }
+// Query params as strings, without the undefined ones (request() takes
+// Record<string, string>).
+const queryString = (params) => params
+    ? Object.fromEntries(Object.entries(params)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => [k, String(v)]))
+    : undefined;
 export class OmniSocialsClient {
     baseUrl;
     apiKey;
@@ -391,6 +478,26 @@ export class OmniSocialsClient {
     async deleteHashtagSet(id) {
         return this.request("DELETE", `/hashtag-sets/${id}`);
     }
+    // Comment-to-DM automations (opt-in scopes automations:read / automations:write)
+    async listAutomations(params) {
+        return this.request("GET", "/automations", undefined, queryString(params));
+    }
+    async getAutomation(id) {
+        return this.request("GET", `/automations/${id}`);
+    }
+    async createAutomation(data) {
+        return this.request("POST", "/automations", data);
+    }
+    async updateAutomation(id, data) {
+        return this.request("PATCH", `/automations/${id}`, data);
+    }
+    async deleteAutomation(id) {
+        return this.request("DELETE", `/automations/${id}`);
+    }
+    // The events response is not the plain list envelope: { data, counts, pagination }.
+    async listAutomationEvents(id, params) {
+        return this.request("GET", `/automations/${id}/events`, undefined, queryString(params));
+    }
     // Accounts. Alongside `data`, the list response carries the workspace's
     // identity top-level (backend/routes/api/v1/accounts.js) — the workspaces
     // tool reads it to label multi-workspace setups.

package/build/index.js

@@ -9,6 +9,7 @@ import { registerAccountTools } from "./tools/accounts.js";
 import { registerAnalyticsTools } from "./tools/analytics.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
 import { registerHashtagSetTools } from "./tools/hashtag-sets.js";
+import { registerAutomationTools } from "./tools/automations.js";
 import { registerInboxTools } from "./tools/inbox.js";
 import { registerWorkspaceTools } from "./tools/workspaces.js";
 const apiKeyEnv = process.env.OMNISOCIALS_API_KEY;
@@ -29,7 +30,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.39.0",
+    version: "1.48.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);
@@ -38,6 +39,7 @@ registerAccountTools(server, getActiveClient);
 registerAnalyticsTools(server, getActiveClient);
 registerWebhookTools(server, getActiveClient);
 registerHashtagSetTools(server, getActiveClient);
+registerAutomationTools(server, getActiveClient);
 registerInboxTools(server, getActiveClient);
 registerWorkspaceTools(server, workspaceClients, sessionState);
 // Register prompts

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");
@@ -177,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.",