WhatsApp Business MCP Server

Instructions

Implementation Reference

• src/whatsapp-client.ts:148-159 (handler)

  The actual implementation of sendMediaMessage which sends a POST request to the WhatsApp Business Cloud API.

  async sendMediaMessage(
    to: string,
    mediaType: "image" | "video" | "audio" | "document",
    media: { link?: string; id?: string; caption?: string; filename?: string }
  ) {
    return this.request(`/${this.config.phoneNumberId}/messages`, "POST", {
      messaging_product: "whatsapp",
      to,
      type: mediaType,
      [mediaType]: media,
    });
  }

• src/index.ts:162-186 (registration)

  Registration of the send_media_message MCP tool, including parameter validation using Zod and a wrapper for pre/post execution hooks.

    "send_media_message",
    "Send an image, video, audio, or document to a WhatsApp number.",
    {
      to: z.string().describe("Recipient phone number in international format"),
      media_type: z.enum(["image", "video", "audio", "document"]).describe("Type of media to send"),
      media_url: z.string().optional().describe("Public URL of the media file"),
      media_id: z.string().optional().describe("Media ID from a previous upload"),
      caption: z.string().optional().describe("Caption for the media (images and videos only)"),
      filename: z.string().optional().describe("Filename for documents"),
    },
    async ({ to, media_type, media_url, media_id, caption, filename }) => {
      const media: Record<string, string> = {};
      if (media_url) media.link = media_url;
      if (media_id) media.id = media_id;
      if (caption) media.caption = caption;
      if (filename) media.filename = filename;
  
      return executeWithHooks(
        "send_media_message",
        { to, media_type, media_url, media_id, caption, filename },
        config,
        () => wa.sendMediaMessage(to, media_type, media)
      );
    }
  );