whatsapp-cloud 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # whatzapp
 
+## 0.1.5
+
+### Patch Changes
+
+- 32573ff: add media download namespace
+
+## 0.1.4
+
+### Patch Changes
+
+- 0741aba: add sendMessage method
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -81,7 +81,7 @@ export async function POST(request: NextRequest) {
       console.log(`Image from ${context.contact?.name || message.from}`);
 
       // Download the image
-      const imageData = await client.webhooks.downloadMedia(message.image.id);
+      const imageData = await client.media.download(message.image.id);
 
       // Process the image (save to storage, analyze, etc.)
       // const buffer = Buffer.from(imageData);
@@ -107,4 +107,5 @@ export async function POST(request: NextRequest) {
 - `client.accounts` - Manage WhatsApp Business Accounts
 - `client.business` - Manage Business Portfolios
 - `client.templates` - Create, retrieve and send WhatsApp templates
+- `client.media` - Upload, download, and manage media files
 - ... more to come very soon. 🕒

package/dist/index.cjs

@@ -503,6 +503,24 @@ var MessagesService = class {
     const client = this.getClient(phoneNumberId);
     return sendReaction(client, input);
   }
+  /**
+   * Send any message type using the discriminated union
+   *
+   * @param message - Any outgoing message (text, image, location, reaction)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
+   */
+  async sendMessage(message, phoneNumberId) {
+    switch (message.type) {
+      case "text":
+        return this.sendText(message, phoneNumberId);
+      case "image":
+        return this.sendImage(message, phoneNumberId);
+      case "location":
+        return this.sendLocation(message, phoneNumberId);
+      case "reaction":
+        return this.sendReaction(message, phoneNumberId);
+    }
+  }
 };
 
 // src/services/accounts/AccountsClient.ts
@@ -1401,33 +1419,6 @@ var WebhooksService = class {
   extractStatuses(payload) {
     return extractStatuses(payload);
   }
-  /**
-   * Download media file by media ID
-   *
-   * Downloads media files (images, audio, video, documents) from WhatsApp servers.
-   * Uses the access token from the client configuration automatically.
-   *
-   * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
-   * @returns Promise resolving to ArrayBuffer containing the media file
-   * @throws Error if download fails or media ID is invalid
-   *
-   * @example
-   * ```typescript
-   * client.webhooks.handle(req.body, {
-   *   image: async (message, context) => {
-   *     const mediaData = await client.webhooks.downloadMedia(message.image.id);
-   *     // Upload to S3, save to disk, etc.
-   *     await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
-   *   },
-   * });
-   * ```
-   */
-  async downloadMedia(mediaId) {
-    if (!mediaId || mediaId.trim().length === 0) {
-      throw new Error("Media ID is required");
-    }
-    return this.httpClient.getBinary(`/${mediaId}`);
-  }
   /**
    * Validate webhook payload structure
    *
@@ -1543,6 +1534,57 @@ var WebhooksService = class {
   }
 };
 
+// src/services/media/MediaService.ts
+var MediaService = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * Download media file by media ID
+   *
+   * Downloads media files (images, audio, video, documents) from WhatsApp servers.
+   * Uses the access token from the client configuration automatically.
+   *
+   * According to WhatsApp API docs, you cannot download directly from the media ID endpoint.
+   * The flow is:
+   * 1. GET /MEDIA_ID → returns JSON metadata with a URL
+   * 2. GET /MEDIA_URL → returns the actual binary data
+   *
+   * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
+   * @returns Promise resolving to ArrayBuffer containing the media file
+   * @throws Error if download fails or media ID is invalid
+   *
+   * @example
+   * ```typescript
+   * const mediaData = await client.media.download(message.image.id);
+   * // Upload to S3, save to disk, etc.
+   * await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
+   * ```
+   */
+  async download(mediaId) {
+    if (!mediaId || mediaId.trim().length === 0) {
+      throw new Error("Media ID is required");
+    }
+    const metadata = await this.httpClient.get(`/${mediaId}`);
+    const response = await fetch(metadata.url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.httpClient.accessToken}`
+      }
+    });
+    if (!response.ok) {
+      let errorMessage = `API Error: ${response.statusText}`;
+      try {
+        const error = await response.json();
+        errorMessage = `API Error: ${error.error?.message || response.statusText} (${error.error?.code || response.status})`;
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.arrayBuffer();
+  }
+};
+
 // src/client/WhatsAppClient.ts
 var import_zod9 = require("zod");
 var WhatsAppClient = class {
@@ -1551,6 +1593,7 @@ var WhatsAppClient = class {
   business;
   templates;
   webhooks;
+  media;
   httpClient;
   constructor(config) {
     let validated;
@@ -1568,6 +1611,7 @@ var WhatsAppClient = class {
     this.business = new BusinessService(this.httpClient);
     this.templates = new TemplatesService(this.httpClient);
     this.webhooks = new WebhooksService(this.httpClient);
+    this.media = new MediaService(this.httpClient);
   }
   /**
    * Debug the current access token

package/dist/index.d.cts

@@ -279,6 +279,13 @@ declare class MessagesService {
      * @param phoneNumberId - Optional phone number ID (overrides client config)
      */
     sendReaction(input: SendReactionInput, phoneNumberId?: string): Promise<MessageResponse>;
+    /**
+     * Send any message type using the discriminated union
+     *
+     * @param message - Any outgoing message (text, image, location, reaction)
+     * @param phoneNumberId - Optional phone number ID (overrides client config)
+     */
+    sendMessage(message: OutgoingMessage, phoneNumberId?: string): Promise<MessageResponse>;
 }
 
 /**
@@ -1377,28 +1384,6 @@ declare class WebhooksService {
      * @returns Flat array of status updates
      */
     extractStatuses(payload: WebhookPayload): Status[];
-    /**
-     * Download media file by media ID
-     *
-     * Downloads media files (images, audio, video, documents) from WhatsApp servers.
-     * Uses the access token from the client configuration automatically.
-     *
-     * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
-     * @returns Promise resolving to ArrayBuffer containing the media file
-     * @throws Error if download fails or media ID is invalid
-     *
-     * @example
-     * ```typescript
-     * client.webhooks.handle(req.body, {
-     *   image: async (message, context) => {
-     *     const mediaData = await client.webhooks.downloadMedia(message.image.id);
-     *     // Upload to S3, save to disk, etc.
-     *     await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
-     *   },
-     * });
-     * ```
-     */
-    downloadMedia(mediaId: string): Promise<ArrayBuffer>;
     /**
      * Validate webhook payload structure
      *
@@ -1429,6 +1414,39 @@ declare class WebhooksService {
     handle<THandlers extends MessageHandlers<any>>(payload: unknown, handlers: THandlers, options?: HandleOptions): void;
 }
 
+/**
+ * Media service for downloading WhatsApp media files
+ *
+ * This service handles downloading media files from WhatsApp servers.
+ */
+declare class MediaService {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Download media file by media ID
+     *
+     * Downloads media files (images, audio, video, documents) from WhatsApp servers.
+     * Uses the access token from the client configuration automatically.
+     *
+     * According to WhatsApp API docs, you cannot download directly from the media ID endpoint.
+     * The flow is:
+     * 1. GET /MEDIA_ID → returns JSON metadata with a URL
+     * 2. GET /MEDIA_URL → returns the actual binary data
+     *
+     * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
+     * @returns Promise resolving to ArrayBuffer containing the media file
+     * @throws Error if download fails or media ID is invalid
+     *
+     * @example
+     * ```typescript
+     * const mediaData = await client.media.download(message.image.id);
+     * // Upload to S3, save to disk, etc.
+     * await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
+     * ```
+     */
+    download(mediaId: string): Promise<ArrayBuffer>;
+}
+
 /**
  * Schema for debug token response
  * Matches Graph API debug_token endpoint response structure
@@ -1465,6 +1483,7 @@ declare class WhatsAppClient {
     readonly business: BusinessService;
     readonly templates: TemplatesService;
     readonly webhooks: WebhooksService;
+    readonly media: MediaService;
     private readonly httpClient;
     constructor(config: ClientConfig);
     /**
@@ -1797,6 +1816,18 @@ type TemplateComponent = z.infer<typeof templateComponentSchema>;
  */
 type TemplateLanguage = z.infer<typeof templateLanguageSchema>;
 
+/**
+ * Media metadata response (from GET /MEDIA_ID)
+ */
+type MediaMetadata = {
+    messaging_product: "whatsapp";
+    url: string;
+    mime_type: string;
+    sha256: string;
+    file_size: string;
+    id: string;
+};
+
 /**
  * Base error class for WhatsApp API errors
  */
@@ -1836,4 +1867,4 @@ declare class WhatsAppRateLimitError extends WhatsAppAPIError {
     constructor(message: string, retryAfter?: number | undefined);
 }
 
-export { type BusinessAccountsListResponse, type ClientConfig, type DebugTokenResponse, type HandleOptions, type IncomingAudioMessage, type IncomingImageMessage, type IncomingMessage, type IncomingTextMessage, type MessageContext, type MessageHandlers, type MessageResponse, type OutgoingImageMessage, type OutgoingLocationMessage, type OutgoingMessage, type OutgoingReactionMessage, type OutgoingTextMessage, type PhoneNumberListResponse, type SendImageInput, type SendLocationInput, type SendReactionInput, type SendTextInput, type Status, type Template, type TemplateBodyComponent, type TemplateButton, type TemplateButtonsComponent, type TemplateComponent, type TemplateCopyCodeButton, type TemplateCreate, type TemplateCreateResponse, type TemplateDelete, type TemplateDeleteResponse, type TemplateFlowButton, type TemplateFooterComponent, type TemplateHeaderComponent, type TemplateLanguage, type TemplateList, type TemplateListResponse, type TemplatePhoneNumberButton, type TemplateQuickReplyButton, type TemplateUpdate, type TemplateUpdateResponse, type TemplateUrlButton, type WebhookContext, type WebhookPayload, WhatsAppAPIError, WhatsAppClient, WhatsAppError, WhatsAppRateLimitError, WhatsAppValidationError, businessAccountResponseSchema, businessAccountsListResponseSchema, clientConfigSchema, debugTokenResponseSchema, incomingAudioMessageSchema, incomingImageMessageSchema, incomingMessageSchema, incomingTextMessageSchema, messageResponseSchema, outgoingImageMessageSchema, outgoingLocationMessageSchema, outgoingMessageSchema, outgoingReactionMessageSchema, outgoingTextMessageSchema, phoneNumberListResponseSchema, phoneNumberResponseSchema, sendImageInputSchema, sendLocationInputSchema, sendReactionInputSchema, sendTextInputSchema, statusSchema, templateBodyComponentSchema, templateButtonSchema, templateButtonsComponentSchema, templateComponentSchema, templateCopyCodeButtonSchema, templateCreateResponseSchema, templateCreateSchema, templateDeleteResponseSchema, templateDeleteSchema, templateFlowButtonSchema, templateFooterComponentSchema, templateHeaderComponentSchema, templateLanguageSchema, templateListResponseSchema, templateListSchema, templatePhoneNumberButtonSchema, templateQuickReplyButtonSchema, templateSchema, templateUpdateResponseSchema, templateUpdateSchema, templateUrlButtonSchema, webhookPayloadSchema };
+export { type BusinessAccountsListResponse, type ClientConfig, type DebugTokenResponse, type HandleOptions, type IncomingAudioMessage, type IncomingImageMessage, type IncomingMessage, type IncomingTextMessage, type MediaMetadata, type MessageContext, type MessageHandlers, type MessageResponse, type OutgoingImageMessage, type OutgoingLocationMessage, type OutgoingMessage, type OutgoingReactionMessage, type OutgoingTextMessage, type PhoneNumberListResponse, type SendImageInput, type SendLocationInput, type SendReactionInput, type SendTextInput, type Status, type Template, type TemplateBodyComponent, type TemplateButton, type TemplateButtonsComponent, type TemplateComponent, type TemplateCopyCodeButton, type TemplateCreate, type TemplateCreateResponse, type TemplateDelete, type TemplateDeleteResponse, type TemplateFlowButton, type TemplateFooterComponent, type TemplateHeaderComponent, type TemplateLanguage, type TemplateList, type TemplateListResponse, type TemplatePhoneNumberButton, type TemplateQuickReplyButton, type TemplateUpdate, type TemplateUpdateResponse, type TemplateUrlButton, type WebhookContext, type WebhookPayload, WhatsAppAPIError, WhatsAppClient, WhatsAppError, WhatsAppRateLimitError, WhatsAppValidationError, businessAccountResponseSchema, businessAccountsListResponseSchema, clientConfigSchema, debugTokenResponseSchema, incomingAudioMessageSchema, incomingImageMessageSchema, incomingMessageSchema, incomingTextMessageSchema, messageResponseSchema, outgoingImageMessageSchema, outgoingLocationMessageSchema, outgoingMessageSchema, outgoingReactionMessageSchema, outgoingTextMessageSchema, phoneNumberListResponseSchema, phoneNumberResponseSchema, sendImageInputSchema, sendLocationInputSchema, sendReactionInputSchema, sendTextInputSchema, statusSchema, templateBodyComponentSchema, templateButtonSchema, templateButtonsComponentSchema, templateComponentSchema, templateCopyCodeButtonSchema, templateCreateResponseSchema, templateCreateSchema, templateDeleteResponseSchema, templateDeleteSchema, templateFlowButtonSchema, templateFooterComponentSchema, templateHeaderComponentSchema, templateLanguageSchema, templateListResponseSchema, templateListSchema, templatePhoneNumberButtonSchema, templateQuickReplyButtonSchema, templateSchema, templateUpdateResponseSchema, templateUpdateSchema, templateUrlButtonSchema, webhookPayloadSchema };

package/dist/index.d.ts

@@ -279,6 +279,13 @@ declare class MessagesService {
      * @param phoneNumberId - Optional phone number ID (overrides client config)
      */
     sendReaction(input: SendReactionInput, phoneNumberId?: string): Promise<MessageResponse>;
+    /**
+     * Send any message type using the discriminated union
+     *
+     * @param message - Any outgoing message (text, image, location, reaction)
+     * @param phoneNumberId - Optional phone number ID (overrides client config)
+     */
+    sendMessage(message: OutgoingMessage, phoneNumberId?: string): Promise<MessageResponse>;
 }
 
 /**
@@ -1377,28 +1384,6 @@ declare class WebhooksService {
      * @returns Flat array of status updates
      */
     extractStatuses(payload: WebhookPayload): Status[];
-    /**
-     * Download media file by media ID
-     *
-     * Downloads media files (images, audio, video, documents) from WhatsApp servers.
-     * Uses the access token from the client configuration automatically.
-     *
-     * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
-     * @returns Promise resolving to ArrayBuffer containing the media file
-     * @throws Error if download fails or media ID is invalid
-     *
-     * @example
-     * ```typescript
-     * client.webhooks.handle(req.body, {
-     *   image: async (message, context) => {
-     *     const mediaData = await client.webhooks.downloadMedia(message.image.id);
-     *     // Upload to S3, save to disk, etc.
-     *     await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
-     *   },
-     * });
-     * ```
-     */
-    downloadMedia(mediaId: string): Promise<ArrayBuffer>;
     /**
      * Validate webhook payload structure
      *
@@ -1429,6 +1414,39 @@ declare class WebhooksService {
     handle<THandlers extends MessageHandlers<any>>(payload: unknown, handlers: THandlers, options?: HandleOptions): void;
 }
 
+/**
+ * Media service for downloading WhatsApp media files
+ *
+ * This service handles downloading media files from WhatsApp servers.
+ */
+declare class MediaService {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Download media file by media ID
+     *
+     * Downloads media files (images, audio, video, documents) from WhatsApp servers.
+     * Uses the access token from the client configuration automatically.
+     *
+     * According to WhatsApp API docs, you cannot download directly from the media ID endpoint.
+     * The flow is:
+     * 1. GET /MEDIA_ID → returns JSON metadata with a URL
+     * 2. GET /MEDIA_URL → returns the actual binary data
+     *
+     * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
+     * @returns Promise resolving to ArrayBuffer containing the media file
+     * @throws Error if download fails or media ID is invalid
+     *
+     * @example
+     * ```typescript
+     * const mediaData = await client.media.download(message.image.id);
+     * // Upload to S3, save to disk, etc.
+     * await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
+     * ```
+     */
+    download(mediaId: string): Promise<ArrayBuffer>;
+}
+
 /**
  * Schema for debug token response
  * Matches Graph API debug_token endpoint response structure
@@ -1465,6 +1483,7 @@ declare class WhatsAppClient {
     readonly business: BusinessService;
     readonly templates: TemplatesService;
     readonly webhooks: WebhooksService;
+    readonly media: MediaService;
     private readonly httpClient;
     constructor(config: ClientConfig);
     /**
@@ -1797,6 +1816,18 @@ type TemplateComponent = z.infer<typeof templateComponentSchema>;
  */
 type TemplateLanguage = z.infer<typeof templateLanguageSchema>;
 
+/**
+ * Media metadata response (from GET /MEDIA_ID)
+ */
+type MediaMetadata = {
+    messaging_product: "whatsapp";
+    url: string;
+    mime_type: string;
+    sha256: string;
+    file_size: string;
+    id: string;
+};
+
 /**
  * Base error class for WhatsApp API errors
  */
@@ -1836,4 +1867,4 @@ declare class WhatsAppRateLimitError extends WhatsAppAPIError {
     constructor(message: string, retryAfter?: number | undefined);
 }
 
-export { type BusinessAccountsListResponse, type ClientConfig, type DebugTokenResponse, type HandleOptions, type IncomingAudioMessage, type IncomingImageMessage, type IncomingMessage, type IncomingTextMessage, type MessageContext, type MessageHandlers, type MessageResponse, type OutgoingImageMessage, type OutgoingLocationMessage, type OutgoingMessage, type OutgoingReactionMessage, type OutgoingTextMessage, type PhoneNumberListResponse, type SendImageInput, type SendLocationInput, type SendReactionInput, type SendTextInput, type Status, type Template, type TemplateBodyComponent, type TemplateButton, type TemplateButtonsComponent, type TemplateComponent, type TemplateCopyCodeButton, type TemplateCreate, type TemplateCreateResponse, type TemplateDelete, type TemplateDeleteResponse, type TemplateFlowButton, type TemplateFooterComponent, type TemplateHeaderComponent, type TemplateLanguage, type TemplateList, type TemplateListResponse, type TemplatePhoneNumberButton, type TemplateQuickReplyButton, type TemplateUpdate, type TemplateUpdateResponse, type TemplateUrlButton, type WebhookContext, type WebhookPayload, WhatsAppAPIError, WhatsAppClient, WhatsAppError, WhatsAppRateLimitError, WhatsAppValidationError, businessAccountResponseSchema, businessAccountsListResponseSchema, clientConfigSchema, debugTokenResponseSchema, incomingAudioMessageSchema, incomingImageMessageSchema, incomingMessageSchema, incomingTextMessageSchema, messageResponseSchema, outgoingImageMessageSchema, outgoingLocationMessageSchema, outgoingMessageSchema, outgoingReactionMessageSchema, outgoingTextMessageSchema, phoneNumberListResponseSchema, phoneNumberResponseSchema, sendImageInputSchema, sendLocationInputSchema, sendReactionInputSchema, sendTextInputSchema, statusSchema, templateBodyComponentSchema, templateButtonSchema, templateButtonsComponentSchema, templateComponentSchema, templateCopyCodeButtonSchema, templateCreateResponseSchema, templateCreateSchema, templateDeleteResponseSchema, templateDeleteSchema, templateFlowButtonSchema, templateFooterComponentSchema, templateHeaderComponentSchema, templateLanguageSchema, templateListResponseSchema, templateListSchema, templatePhoneNumberButtonSchema, templateQuickReplyButtonSchema, templateSchema, templateUpdateResponseSchema, templateUpdateSchema, templateUrlButtonSchema, webhookPayloadSchema };
+export { type BusinessAccountsListResponse, type ClientConfig, type DebugTokenResponse, type HandleOptions, type IncomingAudioMessage, type IncomingImageMessage, type IncomingMessage, type IncomingTextMessage, type MediaMetadata, type MessageContext, type MessageHandlers, type MessageResponse, type OutgoingImageMessage, type OutgoingLocationMessage, type OutgoingMessage, type OutgoingReactionMessage, type OutgoingTextMessage, type PhoneNumberListResponse, type SendImageInput, type SendLocationInput, type SendReactionInput, type SendTextInput, type Status, type Template, type TemplateBodyComponent, type TemplateButton, type TemplateButtonsComponent, type TemplateComponent, type TemplateCopyCodeButton, type TemplateCreate, type TemplateCreateResponse, type TemplateDelete, type TemplateDeleteResponse, type TemplateFlowButton, type TemplateFooterComponent, type TemplateHeaderComponent, type TemplateLanguage, type TemplateList, type TemplateListResponse, type TemplatePhoneNumberButton, type TemplateQuickReplyButton, type TemplateUpdate, type TemplateUpdateResponse, type TemplateUrlButton, type WebhookContext, type WebhookPayload, WhatsAppAPIError, WhatsAppClient, WhatsAppError, WhatsAppRateLimitError, WhatsAppValidationError, businessAccountResponseSchema, businessAccountsListResponseSchema, clientConfigSchema, debugTokenResponseSchema, incomingAudioMessageSchema, incomingImageMessageSchema, incomingMessageSchema, incomingTextMessageSchema, messageResponseSchema, outgoingImageMessageSchema, outgoingLocationMessageSchema, outgoingMessageSchema, outgoingReactionMessageSchema, outgoingTextMessageSchema, phoneNumberListResponseSchema, phoneNumberResponseSchema, sendImageInputSchema, sendLocationInputSchema, sendReactionInputSchema, sendTextInputSchema, statusSchema, templateBodyComponentSchema, templateButtonSchema, templateButtonsComponentSchema, templateComponentSchema, templateCopyCodeButtonSchema, templateCreateResponseSchema, templateCreateSchema, templateDeleteResponseSchema, templateDeleteSchema, templateFlowButtonSchema, templateFooterComponentSchema, templateHeaderComponentSchema, templateLanguageSchema, templateListResponseSchema, templateListSchema, templatePhoneNumberButtonSchema, templateQuickReplyButtonSchema, templateSchema, templateUpdateResponseSchema, templateUpdateSchema, templateUrlButtonSchema, webhookPayloadSchema };

package/dist/index.js

@@ -430,6 +430,24 @@ var MessagesService = class {
     const client = this.getClient(phoneNumberId);
     return sendReaction(client, input);
   }
+  /**
+   * Send any message type using the discriminated union
+   *
+   * @param message - Any outgoing message (text, image, location, reaction)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
+   */
+  async sendMessage(message, phoneNumberId) {
+    switch (message.type) {
+      case "text":
+        return this.sendText(message, phoneNumberId);
+      case "image":
+        return this.sendImage(message, phoneNumberId);
+      case "location":
+        return this.sendLocation(message, phoneNumberId);
+      case "reaction":
+        return this.sendReaction(message, phoneNumberId);
+    }
+  }
 };
 
 // src/services/accounts/AccountsClient.ts
@@ -1328,33 +1346,6 @@ var WebhooksService = class {
   extractStatuses(payload) {
     return extractStatuses(payload);
   }
-  /**
-   * Download media file by media ID
-   *
-   * Downloads media files (images, audio, video, documents) from WhatsApp servers.
-   * Uses the access token from the client configuration automatically.
-   *
-   * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
-   * @returns Promise resolving to ArrayBuffer containing the media file
-   * @throws Error if download fails or media ID is invalid
-   *
-   * @example
-   * ```typescript
-   * client.webhooks.handle(req.body, {
-   *   image: async (message, context) => {
-   *     const mediaData = await client.webhooks.downloadMedia(message.image.id);
-   *     // Upload to S3, save to disk, etc.
-   *     await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
-   *   },
-   * });
-   * ```
-   */
-  async downloadMedia(mediaId) {
-    if (!mediaId || mediaId.trim().length === 0) {
-      throw new Error("Media ID is required");
-    }
-    return this.httpClient.getBinary(`/${mediaId}`);
-  }
   /**
    * Validate webhook payload structure
    *
@@ -1470,6 +1461,57 @@ var WebhooksService = class {
   }
 };
 
+// src/services/media/MediaService.ts
+var MediaService = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * Download media file by media ID
+   *
+   * Downloads media files (images, audio, video, documents) from WhatsApp servers.
+   * Uses the access token from the client configuration automatically.
+   *
+   * According to WhatsApp API docs, you cannot download directly from the media ID endpoint.
+   * The flow is:
+   * 1. GET /MEDIA_ID → returns JSON metadata with a URL
+   * 2. GET /MEDIA_URL → returns the actual binary data
+   *
+   * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
+   * @returns Promise resolving to ArrayBuffer containing the media file
+   * @throws Error if download fails or media ID is invalid
+   *
+   * @example
+   * ```typescript
+   * const mediaData = await client.media.download(message.image.id);
+   * // Upload to S3, save to disk, etc.
+   * await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
+   * ```
+   */
+  async download(mediaId) {
+    if (!mediaId || mediaId.trim().length === 0) {
+      throw new Error("Media ID is required");
+    }
+    const metadata = await this.httpClient.get(`/${mediaId}`);
+    const response = await fetch(metadata.url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.httpClient.accessToken}`
+      }
+    });
+    if (!response.ok) {
+      let errorMessage = `API Error: ${response.statusText}`;
+      try {
+        const error = await response.json();
+        errorMessage = `API Error: ${error.error?.message || response.statusText} (${error.error?.code || response.status})`;
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.arrayBuffer();
+  }
+};
+
 // src/client/WhatsAppClient.ts
 import { ZodError as ZodError2 } from "zod";
 var WhatsAppClient = class {
@@ -1478,6 +1520,7 @@ var WhatsAppClient = class {
   business;
   templates;
   webhooks;
+  media;
   httpClient;
   constructor(config) {
     let validated;
@@ -1495,6 +1538,7 @@ var WhatsAppClient = class {
     this.business = new BusinessService(this.httpClient);
     this.templates = new TemplatesService(this.httpClient);
     this.webhooks = new WebhooksService(this.httpClient);
+    this.media = new MediaService(this.httpClient);
   }
   /**
    * Debug the current access token

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-cloud",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Work in progress. A WhatsApp client tailored for LLMs—built to actually work.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "zod": "^4.2.1"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "lint": "tsc",
     "example": "tsx src/examples/main.ts"
   }

package/src/client/WhatsAppClient.ts

@@ -6,6 +6,7 @@ import { AccountsService } from "../services/accounts/index";
 import { BusinessService } from "../services/business/index";
 import { TemplatesService } from "../services/templates/index";
 import { WebhooksService } from "../services/webhooks/index";
+import { MediaService } from "../services/media/index";
 import { ZodError } from "zod";
 import { transformZodError } from "../utils/zod-error";
 import type { DebugTokenResponse } from "../types/debug";
@@ -19,6 +20,7 @@ export class WhatsAppClient {
   public readonly business: BusinessService;
   public readonly templates: TemplatesService;
   public readonly webhooks: WebhooksService;
+  public readonly media: MediaService;
 
   private readonly httpClient: HttpClient;
 
@@ -43,6 +45,7 @@ export class WhatsAppClient {
     this.business = new BusinessService(this.httpClient);
     this.templates = new TemplatesService(this.httpClient);
     this.webhooks = new WebhooksService(this.httpClient);
+    this.media = new MediaService(this.httpClient);
   }
 
   /**

package/src/examples/media-download.ts

@@ -0,0 +1,65 @@
+import "dotenv/config";
+import { WhatsAppClient } from "../client";
+import { writeFileSync } from "fs";
+import { join } from "path";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+});
+
+async function testMediaDownload() {
+  try {
+    console.log("🧪 Testing Media Download API...\n");
+
+    // Media ID from the user's message
+    const mediaId = "768583052204368";
+
+    console.log(`📥 Downloading media with ID: ${mediaId}`);
+    console.log("   This should download the image from the message...\n");
+
+    // Download the media
+    const startTime = Date.now();
+    const mediaData = await client.media.download(mediaId);
+    const downloadTime = Date.now() - startTime;
+
+    console.log("✅ Download successful!");
+    console.log(`   Size: ${mediaData.byteLength} bytes (${(mediaData.byteLength / 1024).toFixed(2)} KB)`);
+    console.log(`   Time: ${downloadTime}ms\n`);
+
+    // Save to file for verification
+    const outputPath = join(process.cwd(), "downloaded-media.jpg");
+    const buffer = Buffer.from(mediaData);
+    writeFileSync(outputPath, buffer);
+
+    console.log(`💾 Saved to: ${outputPath}`);
+    console.log("   You can open this file to verify the download worked correctly.\n");
+
+    // Try to get metadata as well (if we had a getUrl method, but we can test the internal call)
+    console.log("📋 Testing metadata retrieval...");
+    try {
+      // We can test the internal get call by checking what we got
+      // Actually, let's just verify the download worked by checking file size
+      if (mediaData.byteLength > 0) {
+        console.log("✅ Media file is valid (non-empty)");
+      } else {
+        console.log("⚠️  Warning: Media file is empty");
+      }
+    } catch (error) {
+      console.error("❌ Error getting metadata:", error);
+    }
+
+    console.log("\n✨ Test completed successfully!");
+  } catch (error) {
+    console.error("\n❌ Test failed:");
+    if (error instanceof Error) {
+      console.error(`   Error: ${error.message}`);
+      console.error(`   Stack: ${error.stack}`);
+    } else {
+      console.error("   Unknown error:", error);
+    }
+    process.exit(1);
+  }
+}
+
+testMediaDownload();
+

package/src/services/index.ts

@@ -1,2 +1,3 @@
 export * from "./messages/index";
 export * from "./accounts/index";
+export * from "./media/index";

package/src/services/media/MediaService.ts

@@ -0,0 +1,71 @@
+import type { HttpClient } from "../../client/HttpClient";
+import type { MediaMetadata } from "../../types/media";
+
+/**
+ * Media service for downloading WhatsApp media files
+ *
+ * This service handles downloading media files from WhatsApp servers.
+ */
+export class MediaService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * Download media file by media ID
+   *
+   * Downloads media files (images, audio, video, documents) from WhatsApp servers.
+   * Uses the access token from the client configuration automatically.
+   *
+   * According to WhatsApp API docs, you cannot download directly from the media ID endpoint.
+   * The flow is:
+   * 1. GET /MEDIA_ID → returns JSON metadata with a URL
+   * 2. GET /MEDIA_URL → returns the actual binary data
+   *
+   * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
+   * @returns Promise resolving to ArrayBuffer containing the media file
+   * @throws Error if download fails or media ID is invalid
+   *
+   * @example
+   * ```typescript
+   * const mediaData = await client.media.download(message.image.id);
+   * // Upload to S3, save to disk, etc.
+   * await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
+   * ```
+   */
+  async download(mediaId: string): Promise<ArrayBuffer> {
+    if (!mediaId || mediaId.trim().length === 0) {
+      throw new Error("Media ID is required");
+    }
+
+    // Step 1: Get the media URL and metadata
+    // GET /MEDIA_ID returns JSON, not binary, so we use get() not getBinary()
+    // phone_number_id query param is optional per WhatsApp docs - we omit it
+    const metadata = await this.httpClient.get<MediaMetadata>(`/${mediaId}`);
+
+    // Step 2: Download the actual binary data from the URL
+    // The URL is a full URL (not a path), so we can't use httpClient.getBinary()
+    // which expects a path. We need to fetch the full URL directly.
+    const response = await fetch(metadata.url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.httpClient.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      let errorMessage = `API Error: ${response.statusText}`;
+      try {
+        const error = (await response.json()) as {
+          error?: { message?: string; code?: number };
+        };
+        errorMessage = `API Error: ${
+          error.error?.message || response.statusText
+        } (${error.error?.code || response.status})`;
+      } catch {
+        // If JSON parsing fails, use default message
+      }
+      throw new Error(errorMessage);
+    }
+
+    return response.arrayBuffer();
+  }
+}

package/src/services/media/index.ts

@@ -0,0 +1 @@
+export { MediaService } from "./MediaService";

package/src/services/messages/MessagesService.ts

@@ -10,6 +10,7 @@ import type {
   SendImageInput,
   SendLocationInput,
   SendReactionInput,
+  OutgoingMessage,
 } from "../../types/messages/outgoing";
 import type { MessageResponse } from "../../types/messages/response";
 
@@ -94,4 +95,26 @@ export class MessagesService {
     const client = this.getClient(phoneNumberId);
     return sendReaction(client, input);
   }
+
+  /**
+   * Send any message type using the discriminated union
+   *
+   * @param message - Any outgoing message (text, image, location, reaction)
+   * @param phoneNumberId - Optional phone number ID (overrides client config)
+   */
+  async sendMessage(
+    message: OutgoingMessage,
+    phoneNumberId?: string
+  ): Promise<MessageResponse> {
+    switch (message.type) {
+      case "text":
+        return this.sendText(message, phoneNumberId);
+      case "image":
+        return this.sendImage(message, phoneNumberId);
+      case "location":
+        return this.sendLocation(message, phoneNumberId);
+      case "reaction":
+        return this.sendReaction(message, phoneNumberId);
+    }
+  }
 }

package/src/services/webhooks/WebhooksService.ts

@@ -168,37 +168,6 @@ export class WebhooksService {
     return extractStatuses(payload);
   }
 
-  /**
-   * Download media file by media ID
-   *
-   * Downloads media files (images, audio, video, documents) from WhatsApp servers.
-   * Uses the access token from the client configuration automatically.
-   *
-   * @param mediaId - Media ID from incoming message (e.g., message.image.id, message.audio.id)
-   * @returns Promise resolving to ArrayBuffer containing the media file
-   * @throws Error if download fails or media ID is invalid
-   *
-   * @example
-   * ```typescript
-   * client.webhooks.handle(req.body, {
-   *   image: async (message, context) => {
-   *     const mediaData = await client.webhooks.downloadMedia(message.image.id);
-   *     // Upload to S3, save to disk, etc.
-   *     await s3.upload({ key: message.image.id, body: Buffer.from(mediaData) });
-   *   },
-   * });
-   * ```
-   */
-  async downloadMedia(mediaId: string): Promise<ArrayBuffer> {
-    if (!mediaId || mediaId.trim().length === 0) {
-      throw new Error("Media ID is required");
-    }
-
-    // WhatsApp API endpoint: GET /{version}/{media-id}
-    // Use HttpClient's getBinary method which handles baseURL, apiVersion, and auth automatically
-    return this.httpClient.getBinary(`/${mediaId}`);
-  }
-
   /**
    * Validate webhook payload structure
    *

package/src/services/webhooks/utils/extract-messages.ts

@@ -1,5 +1,5 @@
 import type { WebhookPayload } from "../../../types/webhooks";
-import type { IncomingMessage } from "../../../types/webhooks/incoming-message";
+import type { IncomingMessage } from "../../../types/messages/incoming";
 
 /**
  * Extract all incoming messages from webhook payload

package/src/types/index.ts

@@ -4,4 +4,5 @@ export type * from "./accounts/index";
 export type * from "./business/index";
 export type * from "./templates/index";
 export type * from "./webhooks/index";
+export type * from "./media/index";
 export type * from "./debug";

package/src/types/media/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Media metadata response (from GET /MEDIA_ID)
+ */
+export type MediaMetadata = {
+  messaging_product: "whatsapp";
+  url: string;
+  mime_type: string;
+  sha256: string;
+  file_size: string;
+  id: string;
+};
+