@wabery/cli 0.15.2 → 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,22 +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}`),
 };
 // 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, routing/human handoff, signed webhooks, hosted functions, and Meta Business Agent configuration.
-One hosted AI agent, two versions: Live is read-only customer traffic; Draft is the only editable version, tested in the shared Sandbox. Config apply, validate, and preview only create or change Draft — they never edit Live or publish. Publish Live in the Wabery AI builder after review.
-Keep sandbox and production readiness distinct: shared sandbox is for controlled Draft tests; production inbound, proactive templates, and broadcasts need an eligible dedicated WhatsApp channel. Enroll only controlled or opted-in contacts; keep the returned contact_id and channel_id.
-Read conversations and message history before replying. Apply never publishes a hosted agent or Flow; draft and validate Flows, then confirm publish or send separately.
-Broadcasts: approved templates, exactly one audience source, review recipients/exclusions, then confirm.
-Use routing and thread-control tools for automation ownership and human handoff. Hosted function test/invoke is side-effecting. Obtain explicit user confirmation before any external or irreversible action (send, publish, delete, rotate secrets, update providers, run functions). After send, call wabery_get_message, wabery_get_dispatch, or wabery_get_broadcast for provider status; acceptance is not delivery.`;
+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
@@ -212,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)
@@ -931,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(),
@@ -1467,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(),
         },
@@ -1485,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,
@@ -1492,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. type can be unsupported when WhatsApp Cloud API withheld the original content (official errors 131051 / 131060). type revoke/edit are official coexistence delete/edit events with original_message_id.",
+        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(),
@@ -1509,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()
@@ -1531,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. Inbound type unsupported means Cloud API delivered Meta's official unsupported envelope instead of the original body.",
+        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),
         },