Skip to main content

​
Prerequisites

Before installing the SDK, make sure you have:
1

Node.js 16 or higher

The SDK requires Node.js version 16 or higher. Check your version:
node --version
2

WhatsApp Business Account

A verified WhatsApp Business account with API access through Meta Business.
3

Meta Developer Account

Access to Meta for Developers to create an app and get API credentials.

​
Package Installation

Install the SDK using your preferred package manager:
  • npm
  • yarn
  • pnpm
  • bun
npm install whatsapp-client-sdk

​
TypeScript Support

The SDK is built with TypeScript and includes complete type definitions out of the box. No additional @types packages are needed.
TypeScript 4.5+ is recommended for the best experience with the SDK’s advanced type features.

​
Getting API Credentials

To use the WhatsApp Business API, you need to obtain credentials from Meta:

​
1. Create a Meta Developer Account

  1. Go to Meta for Developers
  2. Create an account or log in with your existing Facebook account
  3. Complete the developer verification process

​
2. Create a New App

  1. Navigate to My Apps in the developer console
  2. Click Create App
  3. Choose Business as the app type
  4. Fill in your app details and create the app

​
3. Add WhatsApp Product

  1. In your app dashboard, click Add Product
  2. Find WhatsApp and click Set up
  3. Choose WhatsApp Business API

​
4. Get Your Credentials

After setting up WhatsApp, you’ll need these credentials:
Found in the WhatsApp > Getting Started section of your app dashboard. This token authenticates your requests to the WhatsApp API.
Found in the WhatsApp > API Setup section. This identifies your WhatsApp Business phone number.
You create this token when setting up webhooks. Used to verify webhook endpoints during setup.
Found in the WhatsApp > API Setup section. Optional, but useful for advanced business features.

​
Environment Variables

Set up your environment variables to securely store your credentials: 
# Required credentials
WHATSAPP_ACCESS_TOKEN=your_access_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id_here

# Optional but recommended
WHATSAPP_WEBHOOK_TOKEN=your_webhook_verify_token_here
WHATSAPP_BUSINESS_ID=your_business_account_id_here

# Optional API configuration
WHATSAPP_API_VERSION=v23.0
WHATSAPP_BASE_URL=https://graph.facebook.com
Never commit your actual credentials to version control. Always use environment variables and add .env to your .gitignore file.

​
Basic Initialization

Create your first WhatsApp client instance: 
import { WhatsAppClient } from 'whatsapp-client-sdk';

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  webhookVerifyToken: process.env.WHATSAPP_WEBHOOK_TOKEN,
});

// Test the connection
const isConnected = await client.testConnection();
console.log('WhatsApp API connected:', isConnected);

​
Verification Steps

After installation, verify everything is working correctly:

​
1. Test API Connection

import { WhatsAppClient } from 'whatsapp-client-sdk';

async function verifySetup() {
  try {
    const client = new WhatsAppClient({
      accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
      phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
    });

    // Test API connectivity
    const isConnected = await client.testConnection();
    
    if (isConnected) {
      console.log('✅ WhatsApp API connection successful');
      
      // Get client configuration (access token will be masked)
      const config = client.getConfig();
      console.log('📋 Configuration:', config);
      
    } else {
      console.log('❌ WhatsApp API connection failed');
    }
  } catch (error) {
    console.error('🚨 Setup error:', error.message);
  }
}

verifySetup();

​
2. Send a Test Message

async function sendTestMessage() {
  try {
    const client = new WhatsAppClient({
      accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
      phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
    });

    // Replace with your WhatsApp number (include country code)
    const testNumber = '+1234567890';
    
    const response = await client.sendText(
      testNumber,
      '🎉 Hello from WhatsApp Client SDK!'
    );
    
    console.log('✅ Test message sent:', response.messages[0].id);
  } catch (error) {
    console.error('❌ Failed to send test message:', error.message);
  }
}

// sendTestMessage();
Uncomment the sendTestMessage() call only after you’ve added your test phone number to the WhatsApp Business account’s recipients list.

​
Common Installation Issues

Make sure you’re using the correct import syntax for your environment:
  • ES6 modules: import { WhatsAppClient } from 'whatsapp-client-sdk'
  • CommonJS: const { WhatsAppClient } = require('whatsapp-client-sdk')
Ensure your tsconfig.json includes:
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}
For Node.js projects, install and configure dotenv:
npm install dotenv
Then in your main file:
require('dotenv').config();
// or for ES6:
import 'dotenv/config';
Check that:
  • Your access token is valid and not expired
  • Your phone number ID is correct
  • You have proper internet connectivity
  • Your Meta Developer account is in good standing

​
Next Steps

Quick Start Guide

Send your first message in under 5 minutes

Configuration Options

Explore advanced configuration options

Message Types

Learn about all supported message types

Webhook Setup

Set up webhooks to receive messages

​
Need Help?

Join our community

Get help from the community or reach out for support
⌘I