whatsapp-cloud 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # whatzapp
 
+## 0.0.7
+
+### Patch Changes
+
+- 2024d31: add audio and image handler
+- f2501c2: add template types
+
+## 0.0.6
+
+### Patch Changes
+
+- a46c084: export types
+- 175d774: add webhooks namespace
+
 ## 0.0.5
 
 ### Patch Changes

package/docs/DEVELOPMENT.md

@@ -0,0 +1,154 @@
+# Development Guide
+
+## Local Development with npm/pnpm link
+
+To test the SDK in your own project without publishing to npm:
+
+### Step 1: Link the package (in whatsapp-cloud directory)
+
+```bash
+cd /Users/lukas/Developer/whatsapp-cloud
+pnpm build  # Build the package first
+pnpm link --global  # Creates a global symlink
+```
+
+Or with npm:
+
+```bash
+npm link
+```
+
+### Step 2: Link in your project
+
+```bash
+cd /path/to/your/project
+pnpm link whatsapp-cloud
+```
+
+Or with npm:
+
+```bash
+npm link whatsapp-cloud
+```
+
+**What this does:** Creates a symlink in your project's `node_modules` pointing to your local package. You don't need to:
+
+- Add it to `package.json` (link handles it)
+- Run `pnpm install` (link is enough)
+- Publish to npm
+
+### Step 3: Use it in your project
+
+```typescript
+import { WhatsAppClient, type IncomingTextMessage } from "whatsapp-cloud";
+
+const client = new WhatsAppClient({
+  accessToken: "...",
+});
+```
+
+### Important Notes
+
+- **Rebuild after changes**: After making changes to whatsapp-cloud, run `pnpm build` in the whatsapp-cloud directory
+- **Hot reload**: Some bundlers (like Next.js) may need a restart to pick up changes
+- **Unlink**: When done, unlink with `pnpm unlink whatsapp-cloud` in your project
+
+## Production / CI/CD
+
+For production builds and CI/CD, you have a few options:
+
+### Option 1: Publish to npm (Recommended)
+
+Once ready, publish the package:
+
+```bash
+cd /Users/lukas/Developer/whatsapp-cloud
+pnpm publish
+```
+
+Then in your project's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": "^0.0.5"
+  }
+}
+```
+
+### Option 2: Git dependency (For private repos)
+
+If your repo is private, use git dependency:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": "git+https://github.com/your-username/whatsapp-cloud.git"
+  }
+}
+```
+
+### Option 3: Local file path (For monorepos)
+
+If both projects are in the same repo/monorepo:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": "file:../whatsapp-cloud"
+  }
+}
+```
+
+### Option 4: Conditional linking (Dev vs Prod)
+
+Use environment detection:
+
+```json
+{
+  "dependencies": {
+    "whatsapp-cloud": process.env.NODE_ENV === "development"
+      ? "link:../whatsapp-cloud"
+      : "^0.0.5"
+  }
+}
+```
+
+**Note:** For CI/CD, you'll need Option 1 (npm publish) or Option 2 (git dependency). `pnpm link` only works locally.
+
+## Type Exports
+
+All types are properly exported and can be imported in React/Next.js projects:
+
+```typescript
+// Import client
+import { WhatsAppClient } from "whatsapp-cloud";
+
+// Import types
+import type {
+  IncomingTextMessage,
+  IncomingMessage,
+  WebhookPayload,
+  MessageContext,
+  CreateTemplateRequest,
+  // ... all other types
+} from "whatsapp-cloud";
+
+// Import schemas (for validation)
+import {
+  incomingTextMessageSchema,
+  webhookPayloadSchema,
+  // ... all other schemas
+} from "whatsapp-cloud";
+```
+
+## Verifying Exports
+
+To verify all types are exported correctly:
+
+```bash
+# In your project
+pnpm exec tsc --noEmit --skipLibCheck
+```
+
+This will check that all imported types are available.

package/docs/webhooks.md

@@ -0,0 +1,104 @@
+# Webhooks
+
+Handle incoming WhatsApp messages and status updates via webhooks.
+
+## Quick Start
+
+```typescript
+import { WhatsAppClient } from "@whatsapp-cloud/sdk";
+
+const client = new WhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+});
+
+// In your webhook endpoint
+app.post("/webhook", async (req, res) => {
+  // handle() returns IMMEDIATELY - handlers run in background
+  client.webhooks.handle(req.body, {
+    text: async (message, context) => {
+      // This can take as long as needed (20s, 1min, etc.)
+      // Webhook already returned 200, so Meta is happy
+
+      // Process text message
+      console.log(`Received: ${message.text.body} from ${message.from}`);
+
+      // Store in database
+      await db.messages.create({
+        id: message.id,
+        from: message.from,
+        body: message.text.body,
+        phoneNumberId: context.metadata.phoneNumberId,
+      });
+
+      // Send response
+      await client.messages.sendText({
+        to: `+${message.from}`,
+        text: { body: "Got it!" },
+      });
+    },
+  });
+
+  // Returns 200 IMMEDIATELY (handlers continue in background)
+  res.json({ success: true });
+});
+```
+
+## Webhook Verification
+
+Meta sends GET requests to verify your webhook endpoint:
+
+```typescript
+app.get("/webhook", (req, res) => {
+  const challenge = client.webhooks.verify(req.query, process.env.VERIFY_TOKEN);
+  if (challenge) {
+    return res.send(challenge);
+  }
+  return res.status(403).send("Forbidden");
+});
+```
+
+## Low-Level API
+
+For more control, extract messages manually:
+
+```typescript
+const messages = client.webhooks.extractMessages(payload);
+for (const message of messages) {
+  // Custom processing
+}
+```
+
+## Media Downloads
+
+Download media files (images, audio, video, documents) from incoming messages:
+
+```typescript
+client.webhooks.handle(req.body, {
+  image: async (message, context) => {
+    // Download the image
+    const imageData = await client.webhooks.downloadMedia(message.image.id);
+
+    // Upload to your storage (S3, Cloudinary, etc.)
+    await s3.upload({
+      key: `images/${message.image.id}`,
+      body: Buffer.from(imageData),
+      contentType: message.image.mime_type || "image/jpeg",
+    });
+  },
+
+  audio: async (message, context) => {
+    const audioData = await client.webhooks.downloadMedia(message.audio.id);
+    // Process audio file...
+  },
+});
+```
+
+**Note:** Media files are only available for a limited time. Download them as soon as possible after receiving the webhook.
+
+## API Reference
+
+- `client.webhooks.verify(query, token)` - Verify GET request, returns challenge or null
+- `client.webhooks.extractMessages(payload)` - Extract messages from payload
+- `client.webhooks.extractStatuses(payload)` - Extract status updates
+- `client.webhooks.handle(payload, handlers, options?)` - Handle with type-safe callbacks
+- `client.webhooks.downloadMedia(mediaId)` - Download media file by ID, returns ArrayBuffer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-cloud",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Work in progress. A WhatsApp client tailored for LLMs—built to actually work.",
   "type": "module",
   "main": "dist/index.js",

package/src/client/HttpClient.ts

@@ -11,7 +11,7 @@ interface APIErrorResponse {
  * HTTP client for making requests to the WhatsApp Cloud API
  */
 export class HttpClient {
-  private readonly baseURL: string;
+  public readonly baseURL: string;
   public readonly accessToken: string;
   public readonly phoneNumberId?: string;
   public readonly businessAccountId?: string;
@@ -95,6 +95,37 @@ export class HttpClient {
     return response.json() as Promise<T>;
   }
 
+  /**
+   * Make a GET request and return binary data (ArrayBuffer)
+   * Useful for downloading media files
+   */
+  async getBinary(path: string): Promise<ArrayBuffer> {
+    const url = `${this.baseURL}/${this.apiVersion}${path}`;
+
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      // Try to parse error response
+      let errorMessage = `API Error: ${response.statusText}`;
+      try {
+        const error = (await response.json()) as APIErrorResponse;
+        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();
+  }
+
   /**
    * Make a PATCH request
    */

package/src/client/WhatsAppClient.ts

@@ -5,6 +5,7 @@ import { MessagesService } from "../services/messages/index";
 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 { ZodError } from "zod";
 import { transformZodError } from "../utils/zod-error";
 import type { DebugTokenResponse } from "../types/debug";
@@ -17,6 +18,7 @@ export class WhatsAppClient {
   public readonly accounts: AccountsService;
   public readonly business: BusinessService;
   public readonly templates: TemplatesService;
+  public readonly webhooks: WebhooksService;
 
   private readonly httpClient: HttpClient;
 
@@ -40,6 +42,7 @@ export class WhatsAppClient {
     this.accounts = new AccountsService(this.httpClient);
     this.business = new BusinessService(this.httpClient);
     this.templates = new TemplatesService(this.httpClient);
+    this.webhooks = new WebhooksService(this.httpClient);
   }
 
   /**

package/src/index.ts

@@ -7,6 +7,13 @@ export * from "./schemas/index";
 // Export types (primary export point)
 export type * from "./types/index";
 
+// Export webhook handler types (convenience exports)
+export type {
+  MessageContext,
+  MessageHandlers,
+  HandleOptions,
+} from "./services/webhooks/index";
+
 // Export errors for error handling
 export {
   WhatsAppError,

package/src/schemas/index.ts

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

package/src/schemas/templates/request.ts

@@ -5,7 +5,7 @@ import { componentSchema } from "./component";
  * Schema for creating a template
  * Simplified - no variables/examples for now
  */
-export const createTemplateRequestSchema = z.object({
+export const templateCreateSchema = z.object({
   name: z.string().min(1).max(512, "Template name must be 512 characters or less"),
   language: z.string().min(2).max(5, "Language code must be 2-5 characters (e.g., 'en' or 'en_US')"),
   category: z.enum(["AUTHENTICATION", "MARKETING", "UTILITY"]),
@@ -49,7 +49,7 @@ export const createTemplateRequestSchema = z.object({
  * Schema for updating a template
  * All fields optional - only update what's provided
  */
-export const updateTemplateRequestSchema = z.object({
+export const templateUpdateSchema = z.object({
   category: z.enum(["AUTHENTICATION", "MARKETING", "UTILITY"]).optional(),
   components: z.array(componentSchema).optional(),
   language: z.string().min(2).max(5).optional(),

package/src/schemas/templates/response.ts

@@ -2,9 +2,9 @@ import { z } from "zod";
 import { componentSchema } from "./component";
 
 /**
- * Schema for template response (single template)
+ * Schema for template (the base/select model - what you get from API)
  */
-export const templateResponseSchema = z.object({
+export const templateSchema = z.object({
   id: z.string(),
   name: z.string(),
   language: z.string(),

package/src/schemas/webhooks/incoming-message.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+
+/**
+ * Base fields present in ALL incoming messages
+ */
+const baseIncomingMessageSchema = z.object({
+  from: z.string(), // WhatsApp ID (phone number without +)
+  id: z.string(), // Message ID (wamid.*)
+  timestamp: z.string(), // Unix timestamp as string
+  type: z.string(), // Message type discriminator
+});
+
+/**
+ * Text content in incoming text messages
+ * Note: Incoming messages don't have preview_url like outgoing
+ */
+const incomingTextContentSchema = z.object({
+  body: z.string(),
+});
+
+/**
+ * Audio content in incoming audio messages
+ */
+const incomingAudioContentSchema = z.object({
+  id: z.string(), // Media ID for downloading
+  mime_type: z.string().optional(), // e.g., "audio/ogg; codecs=opus"
+});
+
+/**
+ * Image content in incoming image messages
+ */
+const incomingImageContentSchema = z.object({
+  id: z.string(), // Media ID for downloading
+  mime_type: z.string().optional(), // e.g., "image/jpeg"
+  caption: z.string().optional(), // Optional caption text
+});
+
+/**
+ * Incoming text message schema
+ * Uses discriminated union pattern (type: "text")
+ */
+export const incomingTextMessageSchema = baseIncomingMessageSchema.extend({
+  type: z.literal("text"),
+  text: incomingTextContentSchema,
+});
+
+/**
+ * Incoming audio message schema
+ * Uses discriminated union pattern (type: "audio")
+ */
+export const incomingAudioMessageSchema = baseIncomingMessageSchema.extend({
+  type: z.literal("audio"),
+  audio: incomingAudioContentSchema,
+});
+
+/**
+ * Incoming image message schema
+ * Uses discriminated union pattern (type: "image")
+ */
+export const incomingImageMessageSchema = baseIncomingMessageSchema.extend({
+  type: z.literal("image"),
+  image: incomingImageContentSchema,
+});
+
+/**
+ * Union of all incoming message types
+ */
+export const incomingMessageSchema = z.discriminatedUnion("type", [
+  incomingTextMessageSchema,
+  incomingAudioMessageSchema,
+  incomingImageMessageSchema,
+]);

package/src/schemas/webhooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./incoming-message";
+export * from "./payload";
+

package/src/schemas/webhooks/payload.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { incomingMessageSchema } from "./incoming-message";
+
+/**
+ * Contact information in webhook
+ */
+const contactSchema = z.object({
+  profile: z.object({
+    name: z.string(),
+  }),
+  wa_id: z.string(),
+});
+
+/**
+ * Metadata in webhook value
+ */
+const webhookMetadataSchema = z.object({
+  display_phone_number: z.string(),
+  phone_number_id: z.string(),
+});
+
+/**
+ * Webhook value (the actual data)
+ */
+const webhookValueSchema = z.object({
+  messaging_product: z.literal("whatsapp"),
+  metadata: webhookMetadataSchema,
+  contacts: z.array(contactSchema).optional(),
+  messages: z.array(incomingMessageSchema).optional(), // Incoming messages
+  statuses: z.array(z.any()).optional(), // Status updates (for later)
+});
+
+/**
+ * Webhook change entry
+ */
+const webhookChangeSchema = z.object({
+  value: webhookValueSchema,
+  field: z.literal("messages"), // For now: only messages field
+});
+
+/**
+ * Webhook entry
+ */
+const webhookEntrySchema = z.object({
+  id: z.string(), // WABA ID
+  changes: z.array(webhookChangeSchema),
+});
+
+/**
+ * Full webhook payload schema
+ */
+export const webhookPayloadSchema = z.object({
+  object: z.literal("whatsapp_business_account"),
+  entry: z.array(webhookEntrySchema),
+});
+

package/src/services/templates/TemplatesService.ts

@@ -7,15 +7,15 @@ import { updateTemplate } from "./methods/update";
 import { deleteTemplate } from "./methods/delete";
 import { WhatsAppValidationError } from "../../errors";
 import type {
-  CreateTemplateRequest,
-  UpdateTemplateRequest,
+  TemplateCreate,
+  TemplateUpdate,
   ListTemplatesRequest,
   DeleteTemplateRequest,
 } from "../../types/templates/request";
 import type {
   CreateTemplateResponse,
   ListTemplatesResponse,
-  TemplateResponse,
+  Template,
   UpdateTemplateResponse,
   DeleteTemplateResponse,
 } from "../../types/templates/response";
@@ -54,7 +54,7 @@ export class TemplatesService {
    * @param businessAccountId - Optional WABA ID (overrides client config)
    */
   async create(
-    request: CreateTemplateRequest,
+    request: TemplateCreate,
     businessAccountId?: string
   ): Promise<CreateTemplateResponse> {
     const client = this.getClient(businessAccountId);
@@ -82,7 +82,7 @@ export class TemplatesService {
    *
    * @param templateId - Template ID
    */
-  async get(templateId: string): Promise<TemplateResponse> {
+  async get(templateId: string): Promise<Template> {
     return getTemplate(this.httpClient, templateId);
   }
 
@@ -96,7 +96,7 @@ export class TemplatesService {
    */
   async update(
     templateId: string,
-    request: UpdateTemplateRequest
+    request: TemplateUpdate
   ): Promise<UpdateTemplateResponse> {
     return updateTemplate(this.httpClient, templateId, request);
   }

package/src/services/templates/methods/create.ts

@@ -1,6 +1,6 @@
 import type { TemplatesClient } from "../TemplatesClient";
-import { createTemplateRequestSchema } from "../../../schemas/templates/request";
-import type { CreateTemplateRequest } from "../../../types/templates/request";
+import { templateCreateSchema } from "../../../schemas/templates/request";
+import type { TemplateCreate } from "../../../types/templates/request";
 import type { CreateTemplateResponse } from "../../../types/templates/response";
 import { transformZodError } from "../../../utils/zod-error";
 
@@ -12,16 +12,18 @@ import { transformZodError } from "../../../utils/zod-error";
  */
 export async function createTemplate(
   templatesClient: TemplatesClient,
-  request: CreateTemplateRequest
+  request: TemplateCreate
 ): Promise<CreateTemplateResponse> {
   // Validate request with schema - throws WhatsAppValidationError if invalid
-  const result = createTemplateRequestSchema.safeParse(request);
+  const result = templateCreateSchema.safeParse(request);
   if (!result.success) {
     throw transformZodError(result.error);
   }
   const data = result.data;
 
   // Make API request - templatesClient handles the WABA ID prefix automatically
-  return templatesClient.post<CreateTemplateResponse>("/message_templates", data);
+  return templatesClient.post<CreateTemplateResponse>(
+    "/message_templates",
+    data
+  );
 }
-

package/src/services/templates/methods/get.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from "../../../client/HttpClient";
-import type { TemplateResponse } from "../../../types/templates/response";
+import type { Template } from "../../../types/templates/response";
 
 /**
  * Get a template by ID
@@ -12,12 +12,12 @@ import type { TemplateResponse } from "../../../types/templates/response";
 export async function getTemplate(
   httpClient: HttpClient,
   templateId: string
-): Promise<TemplateResponse> {
+): Promise<Template> {
   if (!templateId || templateId.trim().length === 0) {
     throw new Error("Template ID is required");
   }
 
   // Make API request - template ID is used directly, no WABA prefix
-  return httpClient.get<TemplateResponse>(`/${templateId}`);
+  return httpClient.get<Template>(`/${templateId}`);
 }
 

package/src/services/templates/methods/update.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from "../../../client/HttpClient";
-import { updateTemplateRequestSchema } from "../../../schemas/templates/request";
-import type { UpdateTemplateRequest } from "../../../types/templates/request";
+import { templateUpdateSchema } from "../../../schemas/templates/request";
+import type { TemplateUpdate } from "../../../types/templates/request";
 import type { UpdateTemplateResponse } from "../../../types/templates/response";
 import { transformZodError } from "../../../utils/zod-error";
 
@@ -16,14 +16,14 @@ import { transformZodError } from "../../../utils/zod-error";
 export async function updateTemplate(
   httpClient: HttpClient,
   templateId: string,
-  request: UpdateTemplateRequest
+  request: TemplateUpdate
 ): Promise<UpdateTemplateResponse> {
   if (!templateId || templateId.trim().length === 0) {
     throw new Error("Template ID is required");
   }
 
   // Validate request with schema - throws WhatsAppValidationError if invalid
-  const result = updateTemplateRequestSchema.safeParse(request);
+  const result = templateUpdateSchema.safeParse(request);
   if (!result.success) {
     throw transformZodError(result.error);
   }

package/src/services/webhooks/WebhooksService.ts

@@ -0,0 +1,265 @@
+import type { HttpClient } from "../../client/HttpClient";
+import { extractMessages } from "./utils/extract-messages";
+import { extractStatuses } from "./utils/extract-statuses";
+import { verifyWebhook } from "./utils/verify";
+import { webhookPayloadSchema } from "../../schemas/webhooks/payload";
+import type {
+  WebhookPayload,
+  IncomingTextMessage,
+  IncomingAudioMessage,
+  IncomingImageMessage,
+  IncomingMessage,
+} from "../../types/webhooks";
+
+/**
+ * Context provided to message handlers
+ * Contains metadata and contact info (message is passed separately)
+ */
+export type MessageContext = {
+  metadata: {
+    phoneNumberId: string;
+    displayPhoneNumber: string;
+    wabaId: string;
+  };
+  contact?: {
+    name: string;
+    waId: string;
+  };
+};
+
+/**
+ * Handler functions for different message types
+ * Receives message and context separately - message is the focus, context is optional metadata
+ */
+export type MessageHandlers = {
+  text?: (
+    message: IncomingTextMessage,
+    context: MessageContext
+  ) => Promise<void> | void;
+  audio?: (
+    message: IncomingAudioMessage,
+    context: MessageContext
+  ) => Promise<void> | void;
+  image?: (
+    message: IncomingImageMessage,
+    context: MessageContext
+  ) => Promise<void> | void;
+};
+
+/**
+ * Options for handle() method
+ */
+export type HandleOptions = {
+  /**
+   * Error handler called when a message handler throws an error
+   * If not provided, errors are logged and processing continues
+   */
+  onError?: (error: Error, message: IncomingMessage) => void;
+};
+
+/**
+ * Webhooks service for handling incoming webhook payloads
+ *
+ * Provides utilities for extracting messages and a convenience handler
+ * for type-safe message processing.
+ */
+export class WebhooksService {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  /**
+   * Verify webhook GET request from Meta
+   *
+   * Meta sends GET requests to verify webhook endpoints during setup.
+   * Returns the challenge string if valid, null if invalid.
+   *
+   * @param query - Query parameters from GET request
+   * @param verifyToken - Your verification token (stored on your server)
+   * @returns Challenge string if valid, null if invalid
+   */
+  verify(
+    query: {
+      "hub.mode"?: string;
+      "hub.verify_token"?: string;
+      "hub.challenge"?: string;
+    },
+    verifyToken: string
+  ): string | null {
+    return verifyWebhook(query, verifyToken);
+  }
+
+  /**
+   * Extract all incoming messages from webhook payload
+   *
+   * Low-level utility that flattens the nested webhook structure
+   * and returns messages directly.
+   *
+   * @param payload - Webhook payload from Meta
+   * @returns Flat array of incoming messages
+   */
+  extractMessages(payload: WebhookPayload): IncomingMessage[] {
+    return extractMessages(payload);
+  }
+
+  /**
+   * Extract status updates from webhook payload
+   *
+   * Low-level utility for extracting status updates for outgoing messages.
+   *
+   * @param payload - Webhook payload from Meta
+   * @returns Flat array of status updates
+   */
+  extractStatuses(payload: WebhookPayload): unknown[] {
+    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
+   *
+   * Validates the payload against the schema. Logs errors if malformed
+   * but doesn't throw, allowing processing to continue.
+   *
+   * @param payload - Raw payload to validate
+   * @returns Validated payload if valid, original payload if invalid (with logged error)
+   */
+  private validatePayload(payload: unknown): WebhookPayload {
+    const result = webhookPayloadSchema.safeParse(payload);
+    if (!result.success) {
+      console.error(
+        "Webhook payload validation failed:",
+        result.error.format()
+      );
+      // Return as-is (TypeScript will treat it as WebhookPayload, but it's actually invalid)
+      // This allows processing to continue, but handlers should be defensive
+      return payload as WebhookPayload;
+    }
+    return result.data;
+  }
+
+  /**
+   * Handle webhook payload with type-safe callbacks
+   *
+   * High-level convenience method that extracts messages and dispatches
+   * them to appropriate handlers based on message type.
+   *
+   * **Important**: This method returns quickly to allow fast webhook responses.
+   * Handlers are processed asynchronously. If you need to await handler completion,
+   * use the low-level `extractMessages()` method instead.
+   *
+   * @param payload - Webhook payload from Meta (will be validated)
+   * @param handlers - Object with handler functions for each message type
+   * @param options - Optional error handling configuration
+   */
+  handle(
+    payload: unknown,
+    handlers: MessageHandlers,
+    options?: HandleOptions
+  ): void {
+    // Validate payload (logs error if malformed, but continues)
+    const validatedPayload = this.validatePayload(payload);
+
+    // Extract metadata and contacts from payload for context
+    for (const entry of validatedPayload.entry) {
+      for (const change of entry.changes) {
+        if (change.field === "messages" && change.value.messages) {
+          const metadata = {
+            phoneNumberId: change.value.metadata.phone_number_id,
+            displayPhoneNumber: change.value.metadata.display_phone_number,
+            wabaId: entry.id,
+          };
+
+          const contacts = change.value.contacts || [];
+
+          // Process each message with its context
+          for (const message of change.value.messages) {
+            // Find contact for this message (match by wa_id)
+            const contact = contacts.find((c) => c.wa_id === message.from);
+
+            // Build context (metadata + contact, no message duplication)
+            const context: MessageContext = {
+              metadata,
+              ...(contact && {
+                contact: {
+                  name: contact.profile.name,
+                  waId: contact.wa_id,
+                },
+              }),
+            };
+
+            // Process handler asynchronously (don't await)
+            // This allows long-running handlers without blocking webhook response
+            Promise.resolve()
+              .then(async () => {
+                // Type-safe dispatch based on message type
+                switch (message.type) {
+                  case "text":
+                    if (handlers.text) {
+                      await handlers.text(message, context);
+                    }
+                    break;
+
+                  case "audio":
+                    if (handlers.audio) {
+                      await handlers.audio(message, context);
+                    }
+                    break;
+
+                  case "image":
+                    if (handlers.image) {
+                      await handlers.image(message, context);
+                    }
+                    break;
+
+                  default:
+                    // Unhandled message type - silently continue
+                    break;
+                }
+              })
+              .catch((error) => {
+                // Handle errors in handler execution
+                if (options?.onError) {
+                  options.onError(error as Error, message);
+                } else {
+                  // Default: log and continue (don't break webhook response)
+                  console.error(
+                    `Error handling ${message.type} message ${message.id}:`,
+                    error
+                  );
+                }
+              });
+          }
+        }
+      }
+    }
+  }
+}

package/src/services/webhooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./WebhooksService";
+export type { MessageContext, MessageHandlers, HandleOptions } from "./WebhooksService";
+

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

@@ -0,0 +1,25 @@
+import type { WebhookPayload } from "../../../types/webhooks";
+import type { IncomingMessage } from "../../../types/webhooks/incoming-message";
+
+/**
+ * Extract all incoming messages from webhook payload
+ *
+ * Flattens the nested structure: entry[].changes[].value.messages[]
+ * Returns a flat array of messages directly
+ *
+ * @param payload - Webhook payload from Meta
+ * @returns Flat array of incoming messages
+ */
+export function extractMessages(payload: WebhookPayload): IncomingMessage[] {
+  const messages: IncomingMessage[] = [];
+
+  for (const entry of payload.entry) {
+    for (const change of entry.changes) {
+      if (change.field === "messages" && change.value.messages) {
+        messages.push(...change.value.messages);
+      }
+    }
+  }
+
+  return messages;
+}

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

@@ -0,0 +1,25 @@
+import type { WebhookPayload } from "../../../types/webhooks";
+
+/**
+ * Extract status updates from webhook payload
+ *
+ * Flattens the nested structure: entry[].changes[].value.statuses[]
+ * Returns a flat array of status updates
+ *
+ * @param payload - Webhook payload from Meta
+ * @returns Flat array of status updates
+ */
+export function extractStatuses(payload: WebhookPayload): unknown[] {
+  const statuses: unknown[] = [];
+
+  for (const entry of payload.entry) {
+    for (const change of entry.changes) {
+      if (change.field === "messages" && change.value.statuses) {
+        statuses.push(...change.value.statuses);
+      }
+    }
+  }
+
+  return statuses;
+}
+

package/src/services/webhooks/utils/verify.ts

@@ -0,0 +1,29 @@
+/**
+ * Verify webhook GET request from Meta
+ *
+ * Meta sends GET requests to verify webhook endpoints:
+ * GET /webhook?hub.mode=subscribe&hub.challenge=<CHALLENGE>&hub.verify_token=<TOKEN>
+ *
+ * @param query - Query parameters from GET request
+ * @param verifyToken - Your verification token (stored on your server)
+ * @returns Challenge string if valid, null if invalid
+ */
+export function verifyWebhook(
+  query: {
+    "hub.mode"?: string;
+    "hub.verify_token"?: string;
+    "hub.challenge"?: string;
+  },
+  verifyToken: string
+): string | null {
+  const mode = query["hub.mode"];
+  const token = query["hub.verify_token"];
+  const challenge = query["hub.challenge"];
+
+  // Verify mode is "subscribe" and token matches
+  if (mode === "subscribe" && token === verifyToken && challenge) {
+    return challenge;
+  }
+
+  return null;
+}

package/src/types/index.ts

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

package/src/types/templates/request.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import {
-  createTemplateRequestSchema,
-  updateTemplateRequestSchema,
+  templateCreateSchema,
+  templateUpdateSchema,
   listTemplatesRequestSchema,
   deleteTemplateRequestSchema,
 } from "../../schemas/templates/request";
@@ -9,12 +9,12 @@ import {
 /**
  * Type for creating a template
  */
-export type CreateTemplateRequest = z.infer<typeof createTemplateRequestSchema>;
+export type TemplateCreate = z.infer<typeof templateCreateSchema>;
 
 /**
  * Type for updating a template
  */
-export type UpdateTemplateRequest = z.infer<typeof updateTemplateRequestSchema>;
+export type TemplateUpdate = z.infer<typeof templateUpdateSchema>;
 
 /**
  * Type for listing templates

package/src/types/templates/response.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import {
-  templateResponseSchema,
+  templateSchema,
   createTemplateResponseSchema,
   listTemplatesResponseSchema,
   updateTemplateResponseSchema,
@@ -8,9 +8,9 @@ import {
 } from "../../schemas/templates/response";
 
 /**
- * Type for a single template
+ * Type for a template (the base/select model - what you get from API)
  */
-export type TemplateResponse = z.infer<typeof templateResponseSchema>;
+export type Template = z.infer<typeof templateSchema>;
 
 /**
  * Type for create template response

package/src/types/webhooks/incoming-message.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import {
+  incomingTextMessageSchema,
+  incomingAudioMessageSchema,
+  incomingImageMessageSchema,
+  incomingMessageSchema,
+} from "../../schemas/webhooks/incoming-message";
+
+/**
+ * Type for incoming text message
+ */
+export type IncomingTextMessage = z.infer<typeof incomingTextMessageSchema>;
+
+/**
+ * Type for incoming audio message
+ */
+export type IncomingAudioMessage = z.infer<typeof incomingAudioMessageSchema>;
+
+/**
+ * Type for incoming image message
+ */
+export type IncomingImageMessage = z.infer<typeof incomingImageMessageSchema>;
+
+/**
+ * Union type for all incoming message types
+ */
+export type IncomingMessage = z.infer<typeof incomingMessageSchema>;

package/src/types/webhooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./incoming-message";
+export * from "./payload";
+

package/src/types/webhooks/payload.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { webhookPayloadSchema } from "../../schemas/webhooks/payload";
+
+/**
+ * Type for webhook payload
+ */
+export type WebhookPayload = z.infer<typeof webhookPayloadSchema>;
+