@wabery/cli 0.15.0 → 0.16.0

package/dist/mcp-server.js

@@ -5,6 +5,76 @@ import { createExampleConfig } from "./config-example.js";
 import { checkWaberyConnection } from "./diagnostics.js";
 const configSchema = z.record(z.string(), z.unknown());
 const metadataSchema = z.record(z.string(), z.unknown()).optional();
+const groupIdSchema = z
+    .string()
+    .min(1)
+    .describe("Opaque WhatsApp group_id; never use a phone number here.");
+const groupJoinRequestIdsSchema = z
+    .array(z.string().min(1))
+    .min(1)
+    .max(8)
+    .describe("Bulk join-request IDs from wabery_list_group_join_requests.");
+const groupParticipantSchema = z.object({
+    user: z
+        .string()
+        .min(1)
+        .describe("WhatsApp user ID, encoded in Meta's required { user } shape."),
+});
+const groupMessageBodySchema = z
+    .object({
+    text: z.string().min(1).max(4096).optional(),
+    media: z
+        .object({
+        type: z.enum(["image", "document", "video", "audio"]),
+        id: z.string().min(1).optional(),
+        link: z.string().url().optional(),
+        caption: z.string().max(1024).optional(),
+        filename: z.string().max(255).optional(),
+    })
+        .refine((media) => Boolean(media.id) !== Boolean(media.link), {
+        message: "Provide exactly one of media.id or media.link",
+    })
+        .optional(),
+    sticker: z
+        .object({
+        id: z.string().min(1).optional(),
+        link: z.string().url().optional(),
+    })
+        .refine((sticker) => Boolean(sticker.id) !== Boolean(sticker.link), {
+        message: "Provide exactly one of sticker.id or sticker.link",
+    })
+        .optional(),
+    template: z
+        .object({
+        id: z.string().min(1).optional(),
+        name: z.string().min(1).optional(),
+        language: z.string().min(2).max(10).optional(),
+        components: z.array(z.record(z.string(), z.unknown())).optional(),
+    })
+        .refine((template) => Boolean(template.id) || Boolean(template.name && template.language), {
+        message: "Provide template.id or both template.name and template.language",
+    })
+        .optional(),
+    pin: z
+        .discriminatedUnion("type", [
+        z.object({
+            type: z.literal("pin"),
+            message_id: z.string().min(1),
+            expiration_days: z.number().int().min(1).max(30),
+        }),
+        z.object({
+            type: z.literal("unpin"),
+            message_id: z.string().min(1),
+        }),
+    ])
+        .optional(),
+    reply_to: z.string().min(1).max(200).optional(),
+    idempotency_key: z.string().min(1).max(200),
+})
+    .strict()
+    .refine((body) => [body.text, body.media, body.sticker, body.template, body.pin].filter(Boolean).length === 1, {
+    message: "Provide exactly one of text, media, sticker, template, or pin",
+});
 const readinessRequirementSchema = z.enum([
     "sandbox_test",
     "production_inbound",
@@ -80,18 +150,21 @@ const broadcastAudienceFilterSchema = z.object({
     created_after: z.string().datetime().optional(),
     created_before: z.string().datetime().optional(),
 });
+const MESSAGE_MUTATION_GUIDANCE = 'Inbound WhatsApp messages can use outer type "unsupported" when Cloud API does not provide the original body. Inspect unsupported.type: "revoke" and "edit" are message mutations, not unavailable media; never answer them or call wabery_send_message in response. Other unsupported subtypes are unavailable content and may be handled as such.';
 const toolOutputSchema = {
     result: z
         .record(z.string(), z.unknown())
-        .describe("The structured Wabery API result object. Its operation-specific fields are described by the tool and Wabery API documentation."),
+        .describe(`The structured Wabery API result object. Its operation-specific fields are described by the tool and Wabery API documentation. ${MESSAGE_MUTATION_GUIDANCE}`),
 };
-const SERVER_INSTRUCTIONS = `Wabery is a developer platform for building and operating WhatsApp AI agents. Start discovery with wabery_list_projects, select the intended project, then call wabery_get_project_readiness; use channel readiness only for phone-number/provider detail.
-Use Wabery for WhatsApp contacts, opt-in, conversations and message history, approved templates, Flows, broadcasts, routing/human handoff, signed webhooks, hosted functions, and Meta Business Agent configuration.
-Keep sandbox and production readiness distinct: the shared sandbox supports controlled tests; production inbound, proactive templates, and broadcasts require an eligible dedicated WhatsApp channel. Enroll only controlled or explicitly opted-in contacts and retain the returned contact_id and channel_id.
-Read conversations and message history before replying. Validate and preview config before apply; config apply may replace resources but never publishes a Flow. Draft and validate Flows before separately confirming publish or send.
-For broadcasts, create a draft with approved templates, prepare exactly one audience source, poll until ready, review recipients/exclusions, then obtain explicit confirmation before send or schedule. Preparation freezes the audience.
-Use routing and thread-control tools for automation ownership and human handoff. Treat hosted function test/invoke as potentially side-effecting code.
-Obtain explicit user confirmation immediately before any external or irreversible action, including sends, publishes, deletions, secret rotation, provider updates, or function execution. After sending, call wabery_get_message, wabery_get_dispatch, or wabery_get_broadcast to report provider status; acceptance is not delivery.`;
+// Claude Code caps MCP server instructions at 2KB and silently truncates from
+// the end (worse with multiple servers). Keep this text + WRITE_NOTE under
+// 1900 UTF-8 bytes as a buffer, and put invariants first. Per-tool playbooks
+// belong on tool descriptions, not in this handshake.
+const SERVER_INSTRUCTIONS = `Wabery is a developer platform for building and operating WhatsApp AI agents. Start discovery with wabery_list_projects, select the project, then wabery_get_project_readiness; use channel readiness only for phone-number/provider detail.
+Use Wabery for WhatsApp contacts, opted-in messaging, conversations and message history, approved templates, Flows, broadcasts, Groups, routing/human handoff, signed webhooks, hosted functions, and Business Agent configuration.
+Sandbox is for controlled Draft tests; production inbound, proactive templates, and broadcasts need an eligible dedicated channel. Enroll only controlled or opted-in contacts and retain contact_id/channel_id. Live hosted-agent traffic is read-only; only Draft is editable. Config apply, validate, and preview never publish; publish in the Wabery AI builder.
+Before replying, inspect message history. For inbound type unsupported, inspect unsupported.type: revoke/edit are mutations and must not be answered; other subtypes are unavailable content. Draft and validate Flows, then confirm publish or send separately. Broadcasts require approved templates, one reviewed audience source, and confirmation.
+Use routing and thread-control tools for human handoff. Groups require an Official Business Account and Cloud API number; max 8 participants, 10k groups per number, one Cloud API business per group. Group commerce, interactive, calls, ephemeral, view-once, auth, edit, and delete messages are unsupported. Obtain explicit user confirmation before external or irreversible actions, including group sends/mutations, send, publish, delete, rotate, provider updates, and function runs. After a send, inspect provider status with wabery_get_message, wabery_get_dispatch, or wabery_get_broadcast; acceptance is not delivery.`;
 // The write gate differs by transport, and the model has to be told the truth
 // about the session it is actually in: a hosted OAuth client (ChatGPT, Claude)
 // cannot set an env var, so advertising the env gate there makes it refuse to
@@ -208,6 +281,12 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         outputSchema: toolOutputSchema,
         ...config,
     }, callback);
+    const groupPath = (channelId, groupId) => {
+        const base = `/channels/${encodeURIComponent(channelId)}/whatsapp-groups`;
+        return groupId === undefined
+            ? base
+            : `${base}/${encodeURIComponent(groupId)}`;
+    };
     const requireWrite = async (action, token, expectedToken) => {
         const modeBlocked = checkWriteMode(action, undefined, undefined, writePolicy);
         if (modeBlocked)
@@ -401,7 +480,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async () => jsonResult(await client.get("/config")));
     registerTool("wabery_validate_config", {
         title: "Validate Wabery config",
-        description: "Use this when you need to validate a complete declarative config without changing resources. Use wabery_preview_config_diff next to inspect effects.",
+        description: "Use this when you need to validate a complete declarative config without changing resources. Hosted-agent fields are Draft-only; Live cannot be edited here. Use wabery_preview_config_diff next to inspect effects.",
         inputSchema: {
             config: configSchema.describe("The full wabery.config.json object."),
         },
@@ -414,7 +493,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ config }) => apiResult(client.post("/config/validate", config)));
     registerTool("wabery_preview_config_diff", {
         title: "Preview Wabery config diff",
-        description: "Use this when you need to preview what a complete config would create, update, delete, or leave unchanged without applying it. Use wabery_apply_config only after reviewing this diff.",
+        description: "Use this when you need to preview what a complete config would create, update, delete, or leave unchanged without applying it. Hosted-agent changes land on Draft only; Live stays unchanged until someone uses Review & publish in Wabery. Use wabery_apply_config only after reviewing this diff.",
         inputSchema: {
             config: configSchema.describe("The full wabery.config.json object."),
         },
@@ -427,7 +506,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ config }) => apiResult(client.post("/config/diff", config)));
     registerTool("wabery_apply_config", {
         title: "Apply Wabery config",
-        description: "Use this when you need to apply a reviewed complete config, creating, overwriting, or removing Wabery Flows, automations, webhooks, and eligible Business Agent resources. Do not use it for one resource update when a narrow update tool fits. It never publishes Flows; use wabery_publish_flow separately.",
+        description: "Use this when you need to apply a reviewed complete config, creating or updating the hosted-agent Draft plus Flows, automations, webhooks, and eligible Business Agent resources. It cannot edit Live or publish the hosted agent to customers. Do not use it for one resource update when a narrow update tool fits. It never publishes Flows; use wabery_publish_flow separately. Hosted-agent publish happens in the Wabery AI builder after Sandbox testing.",
         inputSchema: {
             config: configSchema.describe("The full wabery.config.json object."),
             confirmation_token: z
@@ -927,13 +1006,17 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
     }, async ({ project_id }) => jsonResult(await client.get(`/projects/${encodeURIComponent(project_id)}`)));
     registerTool("wabery_update_project", {
         title: "Update a Wabery project",
-        description: "Use this when you need to overwrite project name, description, routing_mode, require_opt_in, or signed-webhook settings for a project_id from wabery_list_projects. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
+        description: "Use this when you need to overwrite project name, description, routing_mode, require_opt_in, group management webhook opt-in, or signed-webhook settings for a project_id from wabery_list_projects. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
         inputSchema: {
             project_id: z.string().min(1),
             name: z.string().min(1).max(100).optional(),
             description: z.string().max(500).nullable().optional(),
             routing_mode: z.enum(["NONE", "FLOWS", "EXTERNAL"]).optional(),
             require_opt_in: z.boolean().optional(),
+            group_webhook_events_enabled: z
+                .boolean()
+                .optional()
+                .describe("Explicitly opt into the four new WhatsApp group management event names; defaults false."),
             webhook_url: z.string().url().nullable().optional(),
             webhook_signing_enabled: z.boolean().optional(),
             webhook_secret: z.string().min(16).max(256).optional(),
@@ -1463,6 +1546,10 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         inputSchema: {
             contact_id: z.string().optional(),
             active: z.boolean().optional(),
+            recipient_type: z
+                .enum(["individual", "group", "all"])
+                .optional()
+                .describe("Defaults to individual for backward compatibility; use group or all explicitly."),
             limit: z.number().int().min(1).max(100).optional(),
             starting_after: z.string().optional(),
         },
@@ -1481,6 +1568,7 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         description: "Use this when you need one organization-scoped WhatsApp conversation by conversation_id from wabery_list_conversations.",
         inputSchema: {
             conversation_id: z.string().min(1),
+            recipient_type: z.enum(["individual", "group"]).optional(),
         },
         annotations: {
             readOnlyHint: true,
@@ -1488,12 +1576,13 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ conversation_id }) => jsonResult(await client.get(`/conversations/${conversation_id}`)));
+    }, async ({ conversation_id, ...query }) => jsonResult(await client.get(`/conversations/${conversation_id}`, query)));
     registerTool("wabery_list_conversation_messages", {
         title: "List Wabery conversation messages",
-        description: "Use this when you need message history for a conversation_id from wabery_list_conversations. Retained inbound media may include short-lived signed URLs; expires_at is the retention deadline.",
+        description: `Use this when you need message history for a conversation_id from wabery_list_conversations. Retained inbound media may include short-lived signed URLs; expires_at is the retention deadline. ${MESSAGE_MUTATION_GUIDANCE} Direct type revoke/edit are also official coexistence delete/edit events; inspect original_message_id when present.`,
         inputSchema: {
             conversation_id: z.string().min(1),
+            recipient_type: z.enum(["individual", "group"]).optional(),
             limit: z.number().int().min(1).max(100).optional(),
             starting_after: z.string().optional(),
             order: z.enum(["asc", "desc"]).optional(),
@@ -1505,13 +1594,298 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
             openWorldHint: false,
         },
     }, async ({ conversation_id, ...query }) => jsonResult(await client.get(`/conversations/${conversation_id}/messages`, query)));
+    registerTool("wabery_list_groups", {
+        title: "List WhatsApp groups",
+        description: "Use this when you need organization-scoped WhatsApp group_id values. A group_id is an opaque Meta ID, not a phone number or the messages.send to field. Groups require an eligible Official Business Account Cloud API channel. limit defaults to 25 and accepts 1–1024; starting_after/ending_before (or after/before) are opaque cursors.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            limit: z.number().int().min(1).max(1024).optional(),
+            starting_after: z.string().optional(),
+            ending_before: z.string().optional(),
+            after: z.string().optional(),
+            before: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ channel_id, ...query }) => jsonResult(await client.get(groupPath(channel_id), query)));
+    registerTool("wabery_get_group", {
+        title: "Get WhatsApp group",
+        description: "Use this when you need group settings, suspension state, participant count, or participant data for one opaque group_id from wabery_list_groups. The participant count excludes the business account.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ channel_id, group_id }) => jsonResult(await client.get(groupPath(channel_id, group_id))));
+    registerTool("wabery_create_group", {
+        title: "Create WhatsApp group",
+        description: "Use this when you need to create a WhatsApp group on an eligible Official Business Account Cloud API channel. Supply a caller-generated stable idempotency_key and reuse it for every retry. Meta limits groups to 8 participants and 10,000 groups per business number; explicit confirmation is required.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            subject: z.string().min(1).max(128),
+            description: z.string().max(2048).optional(),
+            join_approval_mode: z
+                .enum(["auto_approve", "approval_required"])
+                .optional(),
+            idempotency_key: z
+                .string()
+                .trim()
+                .min(1)
+                .max(200)
+                .describe("Stable caller-generated key reused for every retry of this group creation."),
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, confirmation_token, idempotency_key, ...body }) => {
+        const blocked = await requireWrite("wabery_create_group", confirmation_token, "create_group");
+        if (blocked)
+            return blocked;
+        return apiResult(client.post(groupPath(channel_id), body, idempotency_key));
+    });
+    registerTool("wabery_update_group_settings", {
+        title: "Update WhatsApp group settings",
+        description: "Use this when you need to change a group's subject or description. Meta reports the final result asynchronously through group.settings; explicit confirmation is required.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            subject: z.string().min(1).max(128).optional(),
+            description: z.string().max(2048).optional(),
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, confirmation_token, ...body }) => {
+        const blocked = await requireWrite("wabery_update_group_settings", confirmation_token, "update_group_settings");
+        if (blocked)
+            return blocked;
+        return apiResult(client.post(groupPath(channel_id, group_id), body));
+    });
+    registerTool("wabery_update_group_profile_picture", {
+        title: "Update WhatsApp group profile picture",
+        description: "Use this when you need to upload a JPEG group profile picture as base64. Meta validates square aspect ratio and minimum dimensions and reports the final result asynchronously through group.settings. Explicit confirmation is required.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            jpeg_base64: z.string().min(4).max(8_000_000),
+            filename: z.string().min(1).max(240).optional(),
+            subject: z.string().min(1).max(128).optional(),
+            description: z.string().max(2048).optional(),
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, jpeg_base64, filename, subject, description, confirmation_token, }) => {
+        const blocked = await requireWrite("wabery_update_group_profile_picture", confirmation_token, "update_group_profile_picture");
+        if (blocked)
+            return blocked;
+        const bytes = Buffer.from(jpeg_base64, "base64");
+        if (bytes.length < 3 ||
+            bytes[0] !== 0xff ||
+            bytes[1] !== 0xd8 ||
+            bytes[2] !== 0xff) {
+            throw new Error("jpeg_base64 must decode to a JPEG file");
+        }
+        const form = new FormData();
+        form.set("profile_picture_file", new Blob([bytes], { type: "image/jpeg" }), filename ?? "profile.jpg");
+        if (subject !== undefined)
+            form.set("subject", subject);
+        if (description !== undefined)
+            form.set("description", description);
+        return apiResult(client.postForm(groupPath(channel_id, group_id), form));
+    });
+    registerTool("wabery_get_group_invite_link", {
+        title: "Get WhatsApp group invite link",
+        description: "Use this when you need the current chat.whatsapp.com invite link for a group_id. Reading the link is safe; share it only with the intended audience.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ channel_id, group_id }) => jsonResult(await client.get(`${groupPath(channel_id, group_id)}/invite-link`)));
+    registerTool("wabery_reset_group_invite_link", {
+        title: "Reset WhatsApp group invite link",
+        description: "Use this when you need Meta to invalidate the current group invite link and issue a new one. Existing links stop working; explicit confirmation is required.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_reset_group_invite_link", confirmation_token, "reset_group_invite_link");
+        if (blocked)
+            return blocked;
+        return apiResult(client.post(`${groupPath(channel_id, group_id)}/invite-link`));
+    });
+    registerTool("wabery_list_group_join_requests", {
+        title: "List WhatsApp group join requests",
+        description: "Use this when you need pending join-request IDs before approving or rejecting requests in bulk. limit defaults to 25 and accepts 1–1024; starting_after/ending_before (or after/before) are opaque cursors. Pass the returned opaque IDs to the corresponding mutation tool.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            limit: z.number().int().min(1).max(1024).optional(),
+            starting_after: z.string().optional(),
+            ending_before: z.string().optional(),
+            after: z.string().optional(),
+            before: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ channel_id, group_id, ...query }) => jsonResult(await client.get(`${groupPath(channel_id, group_id)}/join-requests`, query)));
+    registerTool("wabery_approve_group_join_requests", {
+        title: "Approve WhatsApp group join requests",
+        description: "Use this when you need to approve one or more pending group join-request IDs. This uses Meta's bulk join_requests contract and requires explicit confirmation.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            join_request_ids: groupJoinRequestIdsSchema,
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, join_request_ids, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_approve_group_join_requests", confirmation_token, "approve_group_join_requests");
+        if (blocked)
+            return blocked;
+        return apiResult(client.post(`${groupPath(channel_id, group_id)}/join-requests`, {
+            join_requests: join_request_ids,
+        }));
+    });
+    registerTool("wabery_reject_group_join_requests", {
+        title: "Reject WhatsApp group join requests",
+        description: "Use this when you need to reject one or more pending group join-request IDs. This uses Meta's bulk join_requests contract and requires explicit confirmation.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            join_request_ids: groupJoinRequestIdsSchema,
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, join_request_ids, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_reject_group_join_requests", confirmation_token, "reject_group_join_requests");
+        if (blocked)
+            return blocked;
+        return apiResult(client.delete(`${groupPath(channel_id, group_id)}/join-requests`, {
+            join_requests: join_request_ids,
+        }));
+    });
+    registerTool("wabery_remove_group_participants", {
+        title: "Remove WhatsApp group participants",
+        description: "Use this when you need to remove WhatsApp users from a group. Pass participant user IDs in Meta's required participants:[{user}] shape; partial failures are returned per participant. Explicit confirmation is required.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            participants: z.array(groupParticipantSchema).min(1).max(8),
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, participants, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_remove_group_participants", confirmation_token, "remove_group_participants");
+        if (blocked)
+            return blocked;
+        return apiResult(client.delete(`${groupPath(channel_id, group_id)}/participants`, {
+            participants: participants.map(({ user }) => user),
+        }));
+    });
+    registerTool("wabery_delete_group", {
+        title: "Delete WhatsApp group",
+        description: "Use this when you need to permanently delete a Wabery-managed WhatsApp group. This is irreversible at the provider and requires explicit confirmation.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_delete_group", confirmation_token, "delete_group");
+        if (blocked)
+            return blocked;
+        return apiResult(client.delete(groupPath(channel_id, group_id)));
+    });
+    registerTool("wabery_send_group_message", {
+        title: "Send WhatsApp group message",
+        description: "Use this when you need to send a supported WhatsApp message to a group_id through POST /messages. group_id is an opaque Meta ID and is mutually exclusive with conversation_id/to. Groups support text, media, and text/media templates, but not commerce or interactive messages. Explicit confirmation is required.",
+        inputSchema: {
+            channel_id: z.string().min(1),
+            group_id: groupIdSchema,
+            body: groupMessageBodySchema.describe("Exactly one supported group content field plus a stable idempotency_key that must be reused for retries. reply_to is optional."),
+            confirmation_token: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ channel_id, group_id, body, confirmation_token }) => {
+        const blocked = await requireWrite("wabery_send_group_message", confirmation_token, "send_group_message");
+        if (blocked)
+            return blocked;
+        const idempotencyKey = body.idempotency_key;
+        return apiResult(client.post("/messages", { ...body, channel_id, group_id, idempotency_key: idempotencyKey }, idempotencyKey));
+    });
     registerTool("wabery_send_message", {
         title: "Send WhatsApp message",
-        description: "Use this when you need to send one real WhatsApp text, approved template, media, or interactive message. Do not use it to send a Flow; use wabery_send_flow. The body must identify channel and recipient using ids from list tools and should include idempotency_key; explicit confirmation is required.",
+        description: "Use this when you need to send one real WhatsApp text, approved template, media, or interactive message. Do not use it to send a Flow; use wabery_send_flow. The body must identify channel and exactly one recipient: conversation_id, to, or opaque group_id. group_id is not a phone number; use wabery_send_group_message for the dedicated group-safe path. Include idempotency_key; explicit confirmation is required.",
         inputSchema: {
             body: z
                 .record(z.string(), z.unknown())
-                .describe("POST /messages body. Include channel_id plus contact_id, conversation_id, or to; include type-specific content and an idempotency_key for safe retries."),
+                .describe("POST /messages body. Include channel_id plus exactly one of conversation_id, to, or group_id; include type-specific content and an idempotency_key for safe retries."),
             confirmation_token: z
                 .string()
                 .optional()
@@ -1527,11 +1901,21 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         const blocked = await requireWrite("wabery_send_message", confirmation_token, "send_message");
         if (blocked)
             return blocked;
-        return apiResult(client.post("/messages", body));
+        const groupIdempotencyKey = typeof body.group_id === "string"
+            ? typeof body.idempotency_key === "string" && body.idempotency_key
+                ? body.idempotency_key
+                : null
+            : undefined;
+        if (groupIdempotencyKey === null) {
+            throw new Error("WhatsApp group sends require a stable idempotency_key that is reused for retries.");
+        }
+        return apiResult(client.post("/messages", groupIdempotencyKey
+            ? { ...body, idempotency_key: groupIdempotencyKey }
+            : body, groupIdempotencyKey));
     });
     registerTool("wabery_get_message", {
         title: "Get Wabery message",
-        description: "Use this when you need queued, provider, delivery, or failure status for a message_id returned by wabery_send_message or message history. An accepted send is not proof of delivery.",
+        description: `Use this when you need queued, provider, delivery, or failure status for a message_id returned by wabery_send_message or message history. An accepted send is not proof of delivery. ${MESSAGE_MUTATION_GUIDANCE}`,
         inputSchema: {
             message_id: z.string().min(1),
         },