WhatsApp Cloud API Client

A TypeScript client for the WhatsApp Cloud API with full type safety using Zod schemas.

Features

• 🔒 Type-safe - Built with TypeScript and Zod for runtime validation
• 📦 Lightweight - Minimal dependencies (only Zod)
• 🎯 Simple API - Intuitive and easy-to-use interface
• 🔌 Flexible - Custom HTTP adapter support
• ✅ Comprehensive - Supports messages, templates, media, and more
• 📝 Well-typed - Full TypeScript definitions included

Installation

npm install @goevery/whatsapp-cloud-api-client

pnpm add @goevery/whatsapp-cloud-api-client

yarn add @goevery/whatsapp-cloud-api-client

Quick Start

import { WhatsAppClient, FetchWhatsAppHttpAdapter } from "@goevery/whatsapp-cloud-api-client";

// Initialize the client
const client = new WhatsAppClient(new FetchWhatsAppHttpAdapter());

// Send a text message
const response = await client.sendMessage({
  phoneNumberId: "YOUR_PHONE_NUMBER_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    messaging_product: "whatsapp",
    to: "1234567890",
    type: "text",
    text: {
      body: "Hello from WhatsApp Cloud API!",
    },
  },
});

console.log(response);

Usage

Sending Messages

Text Message

await client.sendMessage({
  phoneNumberId: "YOUR_PHONE_NUMBER_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    messaging_product: "whatsapp",
    to: "1234567890",
    type: "text",
    text: {
      body: "Hello World!",
      preview_url: false,
    },
  },
});

Image Message

await client.sendMessage({
  phoneNumberId: "YOUR_PHONE_NUMBER_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    messaging_product: "whatsapp",
    to: "1234567890",
    type: "image",
    image: {
      link: "https://example.com/image.jpg",
      caption: "Check out this image!",
    },
  },
});

Template Message

await client.sendMessage({
  phoneNumberId: "YOUR_PHONE_NUMBER_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    messaging_product: "whatsapp",
    to: "1234567890",
    type: "template",
    template: {
      name: "hello_world",
      language: {
        code: "en_US",
        policy: "deterministic",
      },
    },
  },
});

Managing Templates

List Templates

const templates = await client.listTemplates({
  wabaId: "YOUR_WABA_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    status: "APPROVED",
  },
});

Create Template

const template = await client.createTemplate({
  wabaId: "YOUR_WABA_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    name: "my_template",
    language: "en_US",
    category: "MARKETING",
    components: [
      {
        type: "BODY",
        text: "Hello {{1}}, welcome to our service!",
      },
    ],
  },
});

Delete Template

const result = await client.deleteTemplate({
  wabaId: "YOUR_WABA_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  payload: {
    name: "my_template",
  },
});

Media Operations

Upload Media

const file = new File(["content"], "image.jpg", { type: "image/jpeg" });

const media = await client.uploadMedia({
  phoneNumberId: "YOUR_PHONE_NUMBER_ID",
  accessToken: "YOUR_ACCESS_TOKEN",
  file: file,
  payload: {
    messaging_product: "whatsapp",
    type: "image",
  },
});

console.log(media.id); // Use this ID to send the media

Get Media URL

const mediaUrl = await client.getMediaUrl(
  "MEDIA_ID",
  "YOUR_ACCESS_TOKEN"
);

console.log(mediaUrl.url);

Download Media

const media = await client.downloadMedia(
  "https://lookaside.fbsbx.com/...",
  "YOUR_ACCESS_TOKEN"
);

// media.data is a ReadableStream<Uint8Array>
// media.contentType contains the MIME type

Schema Exports

All Zod schemas are exported and can be imported separately:

import {
  sendMessageRequestSchema,
  sendMessageResponseSchema,
  type SendMessageRequest,
  type SendMessageResponse,
} from "@goevery/whatsapp-cloud-api-client/schemas";

// Validate your own data
const validatedMessage = sendMessageRequestSchema.parse(messageData);

Development

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Lint
pnpm lint

Example

See the example directory for a complete working example.

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Run the example
pnpm --filter example dev

Requirements

• Node.js 18 or higher
• WhatsApp Business Account
• WhatsApp Business App ID and Phone Number ID
• Access Token from Meta Developer Platform

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

Juan Marín - @goevery

Links

• GitHub Repository
• NPM Package
• WhatsApp Cloud API Documentation
• Issue Tracker