@jclvsh/iris 0.20.0 → 0.22.1

package/README.md

@@ -74,6 +74,7 @@ iris campaigns --help
 | billing       | `b`    | plans                                                         | 1     |
 | channels      | `ch`   | accounts, availability, send                                  | 3     |
 | credits       | `cr`   | balance, buy                                                  | 2     |
+| responder     | `r`    | status, configure, activity, show, pause, resume, triggers list, triggers add, triggers update, triggers remove, triggers posts | 11 |
 
 ## MCP Server Configuration
 
@@ -351,6 +352,36 @@ Add to `.cursor/mcp.json`:
 | `get_credit_balance`   | Check the agent credit balance            |
 | `purchase_credit_pack` | Purchase a 5-credit pack via MPP ($12.00) |
 
+### Responder
+
+| Tool                               | Description                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| `get_responder`                    | Get the config, whether iris is replying right now, and last-30-days counts     |
+| `configure_responder`              | Create or update the responder config                                           |
+| `list_responder_activity`          | List what the responder did (replies sent, handoffs, skips, failures)           |
+| `get_conversation_responder`       | Get the responder's state for a single conversation                             |
+| `set_conversation_responder`       | Pause or resume the responder for a single conversation                         |
+| `list_responder_comment_triggers`  | List comment triggers                                                           |
+| `create_responder_comment_trigger` | Create a comment trigger                                                        |
+| `update_responder_comment_trigger` | Update a comment trigger's keyword, message, post, or enabled state             |
+| `delete_responder_comment_trigger` | Delete a comment trigger                                                        |
+| `list_responder_posts`             | List the newest Instagram posts and their media ids, for a trigger's `media_id` |
+
+The responder answers inbound Instagram DMs for the account owner. It is off by default. It needs an API key and a connected Instagram account, so agents paying by x402 or MPP cannot use it.
+
+- Replies go only to someone who wrote first.
+- A reply goes out only within 24 hours of their last message.
+- It cannot read photos, videos, or story replies.
+- It cannot see whether someone booked.
+
+A comment trigger watches for a keyword in the comments on the account's Instagram posts. When someone comments it, iris sends that person one direct message: the owner's message as written, followed by the notice that it is automated. Instagram allows one such message per comment, within 7 days of the comment, and nothing more unless the person replies.
+
+- It sends only while the responder is enabled and not paused, the subscription is active, and `status.comment_triggers` on `get_responder` is `ready`.
+- `needs_permission` means the owner has to allow comments on the Instagram connection, from the responder settings page in the iris web app. `unavailable` means comment triggers are not offered on the account yet, and their tools return a 403.
+- A trigger applies to every post, or to one post named by `media_id`. `list_responder_posts` lists the newest posts with their ids.
+- Each message sent counts as a message against the plan and shares the account's send pacing. A comment gets no message when it arrives while that pace or the plan's message allowance is reached, or when Instagram refuses or fails the send. iris does not try the same comment again.
+- An account holds up to 20 triggers.
+
 ## API Key & Scopes
 
 Generate an API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
@@ -401,6 +432,8 @@ API keys support fine-grained scopes per resource:
 | `message.rejected`            | Message rejected in the queue       |
 | `discovery.completed`         | Discovery job finished successfully |
 | `discovery.failed`            | Discovery job failed                |
+| `responder.reply_sent`        | Responder sent an automatic reply   |
+| `responder.handoff`           | Responder handed a conversation off |
 
 Webhook deliveries are signed with HMAC-SHA256 using the secret returned from `create_webhook` / `rotate_webhook_secret`. Verify the signature in the `X-Iris-Signature` header before trusting the payload.
 

package/dist/cli.js

@@ -17,6 +17,7 @@ import { registerAnalyticsCommands } from "./commands/analytics.js";
 import { registerBillingCommands } from "./commands/billing.js";
 import { registerChannelCommands } from "./commands/channels.js";
 import { registerCreditCommands } from "./commands/credits.js";
+import { registerResponderCommands } from "./commands/responder.js";
 const program = new Command()
     .name("iris")
     .description("iris CLI - manage campaigns, contacts, messages, and outreach")
@@ -50,6 +51,7 @@ try {
     registerBillingCommands(program, client);
     registerChannelCommands(program, client);
     registerCreditCommands(program, client);
+    registerResponderCommands(program, client);
     await program.parseAsync(process.argv);
 }
 catch (error) {

package/dist/commands/campaigns.js

@@ -110,7 +110,7 @@ export function registerCampaignCommands(program, client) {
     });
     campaigns
         .command("analyze <id>")
-        .description("run AI analysis on a campaign to generate target profiles")
+        .description("queue AI analysis of a campaign to generate target profiles (from its product, or from its goal)")
         .action(async (id) => {
         try {
             const result = await client.post(`/campaigns/${id}/analyze`);

package/dist/commands/responder.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerResponderCommands(program: Command, client: IrisClient): void;

package/dist/commands/responder.js

@@ -0,0 +1,261 @@
+import { formatOutput, handleError, getFormat, parseList } from "../cli-utils.js";
+const CLEARABLE_FIELDS = ["instructions", "booking-url", "disclosure"];
+function parseStrictBoolean(value, flag) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`invalid value for ${flag}: "${value}" (expected "true" or "false")`);
+}
+function collectQuestion(value, previous) {
+    if (previous) {
+        previous.push(value);
+        return previous;
+    }
+    return [value];
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The id goes into the request path, so it has to be an id and nothing else. */
+function requireTriggerId(id) {
+    if (UUID.test(id))
+        return;
+    console.error("error: the comment trigger id must be a uuid (see `responder triggers list`)");
+    process.exit(1);
+}
+export function registerResponderCommands(program, client) {
+    const responder = program.command("responder").alias("r").description("manage the Instagram DM auto-responder");
+    responder
+        .command("status")
+        .description("get responder status: configured, current config, connection/pause status, and last-30-days activity")
+        .action(async () => {
+        try {
+            const result = await client.get("/responder");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    responder
+        .command("configure")
+        .description("create or update the responder config (merge: only the options you pass change)")
+        .option("--enabled <bool>", '"true" or "false" - thread Instagram DMs into the inbox')
+        .option("--auto-reply <bool>", '"true" or "false" - let iris send replies without review')
+        .option("--instructions <text>", "what you offer, prices, answers to common questions, tone")
+        .option("--booking-url <url>", "https url shared when someone asks to talk or book")
+        .option("--question <text>", "a qualifying question, asked in order before the booking link (repeatable)", collectQuestion)
+        .option("--clear-questions", "clear all qualifying questions (sends an empty array)")
+        .option("--disclosure <text>", "the automated-reply disclosure line (10-200 chars)")
+        .option("--max-replies <n>", "automatic replies per conversation before handoff (1-30, default 8)")
+        .option("--clear <fields>", `comma-separated fields to unset: ${CLEARABLE_FIELDS.join(", ")}`, parseList)
+        .action(async (opts) => {
+        try {
+            const body = {};
+            if (opts.clear) {
+                for (const field of opts.clear) {
+                    if (!CLEARABLE_FIELDS.includes(field)) {
+                        console.error(`error: unknown --clear field "${field}" (expected one of: ${CLEARABLE_FIELDS.join(", ")})`);
+                        process.exit(1);
+                    }
+                }
+                if (opts.clear.includes("instructions"))
+                    body.instructions = null;
+                if (opts.clear.includes("booking-url"))
+                    body.booking_url = null;
+                if (opts.clear.includes("disclosure"))
+                    body.disclosure = null;
+            }
+            if (opts.enabled !== undefined)
+                body.enabled = parseStrictBoolean(opts.enabled, "--enabled");
+            if (opts.autoReply !== undefined)
+                body.auto_reply = parseStrictBoolean(opts.autoReply, "--auto-reply");
+            if (opts.instructions !== undefined)
+                body.instructions = opts.instructions;
+            if (opts.bookingUrl !== undefined)
+                body.booking_url = opts.bookingUrl;
+            if (opts.clearQuestions)
+                body.qualifying_questions = [];
+            else if (opts.question !== undefined)
+                body.qualifying_questions = opts.question;
+            if (opts.disclosure !== undefined)
+                body.disclosure = opts.disclosure;
+            if (opts.maxReplies !== undefined) {
+                const maxReplies = Number(opts.maxReplies);
+                if (!Number.isInteger(maxReplies) || maxReplies < 1 || maxReplies > 30) {
+                    throw new Error(`invalid value for --max-replies: "${opts.maxReplies}" (expected a whole number from 1 to 30)`);
+                }
+                body.max_replies_per_conversation = maxReplies;
+            }
+            if (Object.keys(body).length === 0) {
+                console.error("error: at least one option is required");
+                process.exit(1);
+            }
+            const result = await client.patch("/responder", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    responder
+        .command("activity")
+        .description("list the responder's activity log (replies sent, handoffs, skips, failures)")
+        .option("-p, --page <n>", "page number", "1")
+        .option("-s, --page-size <n>", "items per page (max 100)", "50")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.page)
+                params.page = opts.page;
+            if (opts.pageSize)
+                params.page_size = opts.pageSize;
+            const result = await client.get("/responder/activity", params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    responder
+        .command("show <conversation-id>")
+        .description("get the responder's status for a single conversation")
+        .action(async (conversationId) => {
+        try {
+            const result = await client.get(`/conversations/${conversationId}/responder`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    responder
+        .command("pause <conversation-id>")
+        .description("pause the responder for a single conversation")
+        .action(async (conversationId) => {
+        try {
+            const result = await client.patch(`/conversations/${conversationId}/responder`, { status: "paused" });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    responder
+        .command("resume <conversation-id>")
+        .description("resume the responder for a single conversation (refused if the person asked iris to stop)")
+        .action(async (conversationId) => {
+        try {
+            const result = await client.patch(`/conversations/${conversationId}/responder`, { status: "active" });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    const triggers = responder
+        .command("triggers")
+        .alias("tr")
+        .description("manage comment triggers: a keyword in an instagram comment that sends the commenter one automatic DM");
+    triggers
+        .command("list")
+        .description("list comment triggers")
+        .action(async () => {
+        try {
+            const result = await client.get("/responder/comment-triggers");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    triggers
+        .command("add")
+        .description("create a comment trigger")
+        .requiredOption("-k, --keyword <text>", "matched as a whole word or phrase in the comment, case-insensitive (1-50 characters)")
+        .requiredOption("-m, --message <text>", "the DM sent to the commenter, before the automated notice (1-900 characters, at most 700 bytes)")
+        .option("--media-id <id>", "the numeric instagram media id to limit the trigger to one post (5-40 digits, from `responder triggers posts`); omit to match every post")
+        .option("--disabled", "create the trigger turned off (default enabled)")
+        .action(async (opts) => {
+        try {
+            const body = { keyword: opts.keyword, message: opts.message };
+            if (opts.mediaId)
+                body.media_id = opts.mediaId;
+            if (opts.disabled)
+                body.enabled = false;
+            const result = await client.post("/responder/comment-triggers", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    triggers
+        .command("update <id>")
+        .description("update a comment trigger")
+        .option("-k, --keyword <text>", "new keyword, matched case-insensitively (1-50 characters)")
+        .option("-m, --message <text>", "new DM text (1-900 characters, at most 700 bytes)")
+        .option("--media-id <id>", "limit the trigger to one post (5-40 digits, from `responder triggers posts`)")
+        .option("--all-posts", "match every post (clears media_id)")
+        .option("--enable", "turn the trigger on")
+        .option("--disable", "turn the trigger off")
+        .action(async (id, opts) => {
+        try {
+            requireTriggerId(id);
+            if (opts.mediaId && opts.allPosts) {
+                console.error("error: --media-id and --all-posts cannot both be given");
+                process.exit(1);
+            }
+            if (opts.enable && opts.disable) {
+                console.error("error: --enable and --disable cannot both be given");
+                process.exit(1);
+            }
+            const body = {};
+            if (opts.keyword !== undefined)
+                body.keyword = opts.keyword;
+            if (opts.message !== undefined)
+                body.message = opts.message;
+            if (opts.mediaId !== undefined)
+                body.media_id = opts.mediaId;
+            if (opts.allPosts)
+                body.media_id = null;
+            if (opts.enable)
+                body.enabled = true;
+            if (opts.disable)
+                body.enabled = false;
+            if (Object.keys(body).length === 0) {
+                console.error("error: at least one option is required");
+                process.exit(1);
+            }
+            const result = await client.patch(`/responder/comment-triggers/${id}`, body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    triggers
+        .command("remove <id>")
+        .description("delete a comment trigger")
+        .action(async (id) => {
+        try {
+            requireTriggerId(id);
+            await client.delete(`/responder/comment-triggers/${id}`);
+            console.log("comment trigger deleted");
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    triggers
+        .command("posts")
+        .description("list the account's recent instagram posts with their media ids, to find one for --media-id")
+        .action(async () => {
+        try {
+            const result = await client.get("/responder/posts");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/webhooks.js

@@ -24,7 +24,7 @@ export function registerWebhookCommands(program, client) {
         .command("create")
         .description("create a webhook endpoint")
         .requiredOption("-u, --url <url>", "HTTPS webhook URL")
-        .requiredOption("-e, --events <list>", "comma-separated events: campaign.created, campaign.updated, campaign.deleted, contact.created, contact.updated, contact.deleted, conversation.created, conversation.reply_received, message.sent, message.delivered, message.opened, message.bounced, message.approved, message.rejected, discovery.completed, discovery.failed (or '*' for all)", parseList)
+        .requiredOption("-e, --events <list>", "comma-separated events: campaign.created, campaign.updated, campaign.deleted, contact.created, contact.updated, contact.deleted, conversation.created, conversation.reply_received, message.sent, message.delivered, message.opened, message.bounced, message.approved, message.rejected, discovery.completed, discovery.failed, responder.reply_sent, responder.handoff (or '*' for all)", parseList)
         .option("-d, --description <text>", "optional description")
         .action(async (opts) => {
         try {

package/dist/index.js

@@ -18,6 +18,7 @@ import { registerWebhookTools } from "./tools/webhooks.js";
 import { registerAgentCreditTools } from "./tools/agent-credits.js";
 import { registerUsageTools } from "./tools/usage.js";
 import { registerAutopilotTools } from "./tools/autopilot.js";
+import { registerResponderTools } from "./tools/responder.js";
 import { registerAudienceTools } from "./tools/audiences.js";
 const requireFromHere = createRequire(import.meta.url);
 const pkg = requireFromHere("../package.json");
@@ -54,6 +55,7 @@ registerWebhookTools(server, client);
 registerAgentCreditTools(server, client);
 registerUsageTools(server, client);
 registerAutopilotTools(server, client);
+registerResponderTools(server, client);
 registerAudienceTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/campaigns.js

@@ -193,7 +193,7 @@ export function registerCampaignTools(server, client) {
             return formatMcpError(error);
         }
     });
-    server.tool("analyze_campaign", "trigger AI analysis of a campaign to generate target profiles and recommendations. requires write scope.", {
+    server.tool("analyze_campaign", "queue AI analysis of a campaign to generate its target profiles: from the product for product_promotion campaigns, from goal_description for any other campaign. runs asynchronously; poll get_campaign until analysis_status is completed, then search_campaign_contacts. requires write scope.", {
         id: z.string().uuid().describe("campaign ID"),
     }, async ({ id }) => {
         try {

package/dist/tools/responder.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { IrisClient } from "../client.js";
+export declare function registerResponderTools(server: McpServer, client: IrisClient): void;

package/dist/tools/responder.js

@@ -0,0 +1,219 @@
+import { z } from "zod";
+import { formatMcpError } from "../cli-utils.js";
+const MEDIA_ID_PATTERN = /^\d{5,40}$/;
+function messageByteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+export function registerResponderTools(server, client) {
+    server.tool("get_responder", "get responder status: whether it's configured, the current config, connection and pause status, and activity counts for the last 30 days. requires read scope.", {}, async () => {
+        try {
+            const result = await client.get("/responder");
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("configure_responder", "create or update the responder config (merge: only the fields you send change; the first call creates the config). with auto_reply on, replies are sent without review. Instagram only allows a reply within 24 hours of the person's last message, and only to someone who wrote first. requires write scope.", {
+        enabled: z
+            .boolean()
+            .optional()
+            .describe("thread Instagram DMs from anyone into the inbox. turning it off also turns auto_reply off. true clears any pause state."),
+        auto_reply: z
+            .boolean()
+            .optional()
+            .describe("let iris send replies itself, with no review. requires enabled, and either instructions or a profile background to answer from."),
+        instructions: z
+            .string()
+            .max(4000)
+            .nullable()
+            .optional()
+            .describe("what you offer, prices, answers to common questions, tone; null to unset"),
+        booking_url: z
+            .string()
+            .url()
+            .max(500)
+            .nullable()
+            .optional()
+            .refine((value) => value === undefined || value === null || value.startsWith("https://"), {
+            message: "booking_url must use HTTPS",
+        })
+            .describe("shared when someone asks to talk or book (https url); null to unset"),
+        qualifying_questions: z
+            .array(z.string().max(200))
+            .max(5)
+            .optional()
+            .describe("asked one per message, in order, before the booking link is shared (max 5 items)"),
+        disclosure: z
+            .string()
+            .min(10)
+            .max(200)
+            .nullable()
+            .optional()
+            .describe("the line that says the reply is automated, sent once per conversation with the first reply; null uses the default"),
+        max_replies_per_conversation: z
+            .number()
+            .int()
+            .min(1)
+            .max(30)
+            .optional()
+            .describe("after this many automatic replies the conversation is handed to you (default 8)"),
+    }, async (args) => {
+        try {
+            const body = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== undefined));
+            const result = await client.patch("/responder", body);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("list_responder_activity", "list the responder's activity log (replies sent, handoffs, skips, and failures), newest first. requires read scope.", {
+        page: z.number().int().positive().optional().describe("page number (default 1)"),
+        page_size: z.number().int().min(1).max(100).optional().describe("items per page (default 50, max 100)"),
+    }, async ({ page, page_size }) => {
+        try {
+            const params = {};
+            if (page !== undefined)
+                params.page = String(page);
+            if (page_size !== undefined)
+                params.page_size = String(page_size);
+            const result = await client.get("/responder/activity", params);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("get_conversation_responder", "get the responder's status for a single conversation: active, paused, handed off, or never seen, plus the reason and reply counts. requires read scope.", {
+        conversation_id: z.string().uuid().describe("conversation ID"),
+    }, async ({ conversation_id }) => {
+        try {
+            const result = await client.get(`/conversations/${conversation_id}/responder`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("set_conversation_responder", "pause or resume the responder for a single conversation. pausing works on any conversation; resuming is refused after the person asked iris to stop. requires write scope.", {
+        conversation_id: z.string().uuid().describe("conversation ID"),
+        status: z.enum(["active", "paused"]).describe("new responder status for this conversation"),
+    }, async ({ conversation_id, status }) => {
+        try {
+            const result = await client.patch(`/conversations/${conversation_id}/responder`, {
+                status,
+            });
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("list_responder_comment_triggers", "list the account's comment triggers. a comment trigger watches for a keyword in instagram comments and sends the commenter one automatic DM. requires read scope.", {}, async () => {
+        try {
+            const result = await client.get("/responder/comment-triggers");
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("create_responder_comment_trigger", "create a comment trigger. when someone comments the keyword on the account's instagram post, iris sends that person one direct message: the owner's message as written, followed by the notice that it is automated. instagram allows one such message per comment, within 7 days of the comment, and nothing more unless the person replies. it only sends while status.comment_triggers on get_responder is ready; needs_permission means the owner has to reconnect instagram from the responder settings page in the iris web app, unavailable means the feature isn't offered on the account yet. each message sent counts as a message against the plan. needs an API key and a connected instagram account; x402 and MPP identities cannot use it. at most 20 triggers per account, and a second trigger with the same keyword on the same post is refused. requires write scope.", {
+        keyword: z
+            .string()
+            .min(1)
+            .max(50)
+            .describe("matched as a whole word or phrase in the comment, case-insensitive (1-50 characters)"),
+        message: z
+            .string()
+            .min(1)
+            .max(900)
+            .refine((value) => messageByteLength(value) <= 700, {
+            message: "message must be at most 700 bytes (an emoji can cost up to 4 bytes)",
+        })
+            .describe("the DM sent to the commenter, before the automated notice (1-900 characters, and at most 700 bytes)"),
+        media_id: z
+            .union([z.string().regex(MEDIA_ID_PATTERN, "media_id must be 5 to 40 digits"), z.null()])
+            .optional()
+            .describe("the numeric instagram media id to limit the trigger to one post (5-40 digits; get it from list_responder_posts); omit or send null to match every post"),
+        enabled: z.boolean().optional().describe("whether the trigger is active (default true)"),
+    }, async (args) => {
+        try {
+            const result = await client.post("/responder/comment-triggers", args);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("update_responder_comment_trigger", "update a comment trigger's keyword, message, media_id, or enabled state. give at least one field besides id. someone else's trigger, or an id that isn't a comment trigger on this account, is a 404. requires write scope.", {
+        id: z.string().uuid().describe("comment trigger ID"),
+        keyword: z
+            .string()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("matched as a whole word or phrase in the comment, case-insensitive (1-50 characters)"),
+        message: z
+            .string()
+            .min(1)
+            .max(900)
+            .refine((value) => messageByteLength(value) <= 700, {
+            message: "message must be at most 700 bytes (an emoji can cost up to 4 bytes)",
+        })
+            .optional()
+            .describe("the DM sent to the commenter, before the automated notice (1-900 characters, and at most 700 bytes)"),
+        media_id: z
+            .union([z.string().regex(MEDIA_ID_PATTERN, "media_id must be 5 to 40 digits"), z.null()])
+            .optional()
+            .describe("the numeric instagram media id to limit the trigger to one post (5-40 digits; get it from list_responder_posts); null matches every post"),
+        enabled: z.boolean().optional().describe("whether the trigger is active"),
+    }, async ({ id, ...rest }) => {
+        const body = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
+        if (Object.keys(body).length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: {
+                                code: "VALIDATION_ERROR",
+                                message: "at least one field besides id is required",
+                            },
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const result = await client.patch(`/responder/comment-triggers/${id}`, body);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("delete_responder_comment_trigger", "delete a comment trigger. requires write scope.", {
+        id: z.string().uuid().describe("comment trigger ID"),
+    }, async ({ id }) => {
+        try {
+            await client.delete(`/responder/comment-triggers/${id}`);
+            return { content: [{ type: "text", text: `comment trigger ${id} deleted` }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("list_responder_posts", "list the account's recent instagram posts with their media ids, for limiting a comment trigger to one post. requires read scope.", {}, async () => {
+        try {
+            const result = await client.get("/responder/posts");
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+}

package/dist/tools/webhooks.js

@@ -19,6 +19,8 @@ const WEBHOOK_EVENTS = [
     "message.rejected",
     "discovery.completed",
     "discovery.failed",
+    "responder.reply_sent",
+    "responder.handoff",
 ];
 export function registerWebhookTools(server, client) {
     server.tool("list_webhooks", "list all configured webhooks. requires admin scope.", {

package/dist/types.d.ts

@@ -33,6 +33,9 @@ export interface Campaign {
     follow_up_enabled: boolean;
     follow_up_max_count: number;
     follow_up_delay_days: number;
+    goal_description?: string | null;
+    analysis_status?: "none" | "pending" | "analyzing" | "completed" | "failed";
+    analysis_error?: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -43,14 +46,15 @@ export interface CampaignWithStats extends Campaign {
     emails_opened?: number;
     emails_replied?: number;
 }
+/** `GET /campaigns/{id}/usage` */
 export interface CampaignUsage {
     campaign_id: string;
-    contacts_count: number;
-    contacts_limit: number;
-    emails_sent: number;
-    emails_limit: number;
-    discovery_runs: number;
-    discovery_limit: number;
+    status: string;
+    total_contacts: number;
+    total_conversations: number;
+    delivery_status: Record<string, number>;
+    /** id of a contact search running for the campaign right now; null when none is */
+    discovery_job_id: string | null;
 }
 /** `POST /campaigns/{id}/contacts` */
 export interface AddCampaignContactsResult {
@@ -323,3 +327,95 @@ export interface AudienceProfile {
     created_at: string;
     updated_at: string;
 }
+export interface ResponderConfig {
+    enabled: boolean;
+    auto_reply: boolean;
+    instructions: string | null;
+    booking_url: string | null;
+    qualifying_questions: string[];
+    disclosure: string | null;
+    max_replies_per_conversation: number;
+    paused: boolean;
+    pause_reason: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** `GET /responder` data shape. */
+export interface ResponderStatus {
+    configured: boolean;
+    config: ResponderConfig | null;
+    status: {
+        instagram_connected: boolean;
+        replying: boolean;
+        /** when false, iris only sees replies sent through iris: pause a conversation before answering it from the Instagram app */
+        sees_instagram_app_replies: boolean;
+        paused: boolean;
+        pause_reason: string | null;
+        kill_switch: boolean;
+        /** whether comment triggers can send DMs right now: ready, needs the owner to reconnect instagram, or not offered on this account */
+        comment_triggers: "ready" | "needs_permission" | "unavailable";
+    };
+    last_30_days: {
+        threads: number;
+        replies_sent: number;
+        handoffs: number;
+        booking_links_sent: number;
+        comment_dms_sent: number;
+    };
+}
+/**
+ * `GET /responder/comment-triggers`, `POST /responder/comment-triggers`,
+ * `PATCH /responder/comment-triggers/{id}`. A keyword that, when commented on
+ * an instagram post, sends the commenter one automatic DM.
+ */
+export interface ResponderCommentTrigger {
+    id: string;
+    keyword: string;
+    message: string;
+    media_id: string | null;
+    enabled: boolean;
+    sent_count: number;
+    last_sent_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * `GET /responder/posts` list item. Up to 25 of the account's most recent
+ * instagram posts, newest first. `id` is the numeric instagram media id — pass
+ * it as `media_id` on a comment trigger to limit that trigger to one post.
+ */
+export interface ResponderPost {
+    id: string;
+    caption: string | null;
+    permalink: string | null;
+    media_type: string | null;
+    posted_at: string | null;
+}
+/** `GET /responder/activity` list item. */
+export interface ResponderEvent {
+    id: string;
+    kind: "reply_sent" | "handoff" | "skipped" | "failed";
+    reason: string | null;
+    conversation_id: string | null;
+    contact_id: string | null;
+    message_id: string | null;
+    booking_link_sent: boolean;
+    created_at: string;
+}
+/**
+ * `GET /conversations/{id}/responder` and `PATCH /conversations/{id}/responder`.
+ * `status` is null for a conversation the responder has never seen. `reason`
+ * is one of: human_replied, user_paused, contact_asked_for_person, needs_answer,
+ * sensitive, opted_out, reply_cap, message_limit, send_failed, outside_window, attachment,
+ * unsafe_reply.
+ */
+export interface ResponderThread {
+    conversation_id: string;
+    status: "active" | "paused" | "handed_off" | null;
+    reason: string | null;
+    origin: "dm" | "comment" | null;
+    replies_sent: number;
+    last_inbound_at: string | null;
+    last_reply_at: string | null;
+    booking_link_sent_at: string | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/iris",
-	"version": "0.20.0",
+	"version": "0.22.1",
 	"description": "MCP server for the Iris API",
 	"repository": {
 		"type": "git",