Advanced Configuration

Basic Configuration

The minimum required configuration to initialize the client:

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

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

Complete Configuration Interface

Here’s the full configuration interface with all available options:

interface WhatsAppConfig {
  // Required
  accessToken: string;           // Meta access token
  phoneNumberId: string;         // WhatsApp Business phone number ID
  
  // Optional API Configuration
  baseUrl?: string;             // Default: 'https://graph.facebook.com'
  apiVersion?: string;          // Default: 'v23.0'
  timeout?: number;             // Default: 30000 (30 seconds)
  
  // Optional Business Configuration
  webhookVerifyToken?: string;  // For webhook verification
  businessId?: string;          // Business account ID
}

Configuration Examples

Production Configuration

const client = new WhatsAppClient({
  // Required credentials
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  
  // Production settings
  timeout: 60000,               // 60 second timeout for slower networks
  apiVersion: 'v23.0',          // Specific API version
  baseUrl: 'https://graph.facebook.com',
  
  // Webhook configuration
  webhookVerifyToken: process.env.WHATSAPP_WEBHOOK_TOKEN!,
  businessId: process.env.WHATSAPP_BUSINESS_ID,
});

Development Configuration

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  
  // Development settings
  timeout: 10000,               // Shorter timeout for quick feedback
  webhookVerifyToken: 'dev-webhook-token',
});

High-Volume Configuration

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  
  // High-volume settings
  timeout: 120000,              // 2 minute timeout for bulk operations
  apiVersion: 'v23.0',          // Latest stable version
  businessId: process.env.WHATSAPP_BUSINESS_ID!,
});

Storage Configuration

Configure message persistence and storage integration:

With Supabase Storage
Without Storage

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,

  // Storage configuration
  storage: {
    enabled: true,
    provider: 'supabase',
    options: {
      url: process.env.SUPABASE_URL!,
      apiKey: process.env.SUPABASE_KEY!,
      schema: 'public',
      tablePrefix: 'whatsapp_'
    },
    features: {
      persistIncoming: true,   // Save incoming messages
      persistOutgoing: true,   // Save outgoing messages
      persistStatus: true,     // Update message status
      autoConversations: true, // Auto-create conversations
      createThreads: true,     // Track message threads
      enableSearch: true,      // Enable full-text search
      retentionDays: 90       // Auto-delete after 90 days
    }
  }
});

// Initialize storage
await client.initializeStorage();

// Verify storage is enabled
console.log('Storage enabled:', client.isStorageEnabled());

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  // No storage configuration - messages are not persisted
});

Storage Integration Guide

Learn more about storage configuration and features

Configuration Options Explained

API Version

Latest Stable (Recommended)
Previous Version
Auto-detect (Default)

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  apiVersion: 'v23.0', // Latest stable version
});

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  apiVersion: 'v22.0', // Previous version
});

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  // apiVersion defaults to 'v23.0'
});

The SDK defaults to the latest stable API version. Only specify a different version if you need compatibility with older API features.

Timeout Configuration

Configure request timeouts based on your use case:

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  timeout: 10000, // 10 seconds - for quick operations
});

Base URL Configuration

Use different endpoints for testing or custom deployments:

Production (Default)
Beta Testing
Custom Proxy

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  baseUrl: 'https://graph.facebook.com', // Default
});

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  baseUrl: 'https://graph.beta.facebook.com',
});

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  baseUrl: 'https://your-proxy.example.com/graph',
});

Environment-Based Configuration

Set up different configurations for different environments:

export const developmentConfig = {
  accessToken: process.env.WHATSAPP_DEV_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_DEV_PHONE_NUMBER_ID!,
  timeout: 10000,
  webhookVerifyToken: 'dev-webhook-token',
  apiVersion: 'v23.0' as const,
};

Configuration Validation

The SDK automatically validates your configuration and provides helpful error messages:

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

try {
  const client = new WhatsAppClient({
    accessToken: '', // Invalid: empty string
    phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  });
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.error('Configuration error:', error.message);
    console.error('Missing fields:', error.missingFields);
    // Output: Missing fields: ['accessToken']
  }
}

Runtime Configuration Updates

Get and verify current configuration:

// Get current configuration (access token will be masked)
const config = client.getConfig();
console.log('Current config:', config);
// Output: { accessToken: '***', phoneNumberId: '123...', timeout: 30000, ... }

// Test connection with current configuration
const isConnected = await client.testConnection();
console.log('Connection status:', isConnected);

// Verify specific configuration
if (!config.webhookVerifyToken) {
  console.warn('Webhook verification not configured');
}

Configuration Best Practices

1. Environment Variables

# Development environment
NODE_ENV=development
WHATSAPP_ACCESS_TOKEN=your_dev_token
WHATSAPP_PHONE_NUMBER_ID=your_dev_phone_id
WHATSAPP_WEBHOOK_TOKEN=dev_webhook_token

2. Configuration Factory Pattern

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

class WhatsAppClientFactory {
  private static instance: WhatsAppClient;
  
  static createClient(environment: 'dev' | 'staging' | 'prod' = 'dev'): WhatsAppClient {
    if (this.instance) {
      return this.instance;
    }
    
    const config: WhatsAppConfig = {
      accessToken: process.env[`WHATSAPP_${environment.toUpperCase()}_ACCESS_TOKEN`]!,
      phoneNumberId: process.env[`WHATSAPP_${environment.toUpperCase()}_PHONE_NUMBER_ID`]!,
      timeout: environment === 'prod' ? 60000 : 30000,
      apiVersion: 'v23.0',
    };
    
    if (environment !== 'dev') {
      config.webhookVerifyToken = process.env[`WHATSAPP_${environment.toUpperCase()}_WEBHOOK_TOKEN`];
      config.businessId = process.env[`WHATSAPP_${environment.toUpperCase()}_BUSINESS_ID`];
    }
    
    this.instance = new WhatsAppClient(config);
    return this.instance;
  }
  
  static getInstance(): WhatsAppClient {
    if (!this.instance) {
      throw new Error('Client not initialized. Call createClient() first.');
    }
    return this.instance;
  }
}

// Usage
const client = WhatsAppClientFactory.createClient('prod');

3. Configuration with Secrets Management

import { WhatsAppClient } from 'whatsapp-client-sdk';
import { SecretsManager } from '@aws-sdk/client-secrets-manager';

async function createClientWithSecretsManager() {
  const secretsManager = new SecretsManager({ region: 'us-east-1' });
  
  const secret = await secretsManager.getSecretValue({
    SecretId: 'whatsapp-credentials'
  });
  
  const credentials = JSON.parse(secret.SecretString!);
  
  return new WhatsAppClient({
    accessToken: credentials.accessToken,
    phoneNumberId: credentials.phoneNumberId,
    webhookVerifyToken: credentials.webhookVerifyToken,
    businessId: credentials.businessId,
    timeout: 60000,
  });
}

Framework-Specific Configuration

Next.js Configuration

// lib/whatsapp.ts
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,
  timeout: 30000,
});

export default client;

// pages/api/whatsapp/send.ts
import client from '../../../lib/whatsapp';

export default async function handler(req, res) {
  try {
    const response = await client.sendText(req.body.to, req.body.message);
    res.status(200).json(response);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Express.js Configuration

// config/whatsapp.ts
import { WhatsAppClient } from 'whatsapp-client-sdk';

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

// app.ts
import express from 'express';
import { whatsappClient } from './config/whatsapp';

const app = express();

app.post('/api/send-message', async (req, res) => {
  try {
    const response = await whatsappClient.sendText(req.body.to, req.body.message);
    res.json(response);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

NestJS Configuration

// whatsapp/whatsapp.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { WhatsAppClient } from 'whatsapp-client-sdk';

@Module({
  imports: [ConfigModule],
  providers: [
    {
      provide: 'WHATSAPP_CLIENT',
      useFactory: (configService: ConfigService) => {
        return new WhatsAppClient({
          accessToken: configService.get('WHATSAPP_ACCESS_TOKEN')!,
          phoneNumberId: configService.get('WHATSAPP_PHONE_NUMBER_ID')!,
          webhookVerifyToken: configService.get('WHATSAPP_WEBHOOK_TOKEN'),
          timeout: 60000,
        });
      },
      inject: [ConfigService],
    },
  ],
  exports: ['WHATSAPP_CLIENT'],
})
export class WhatsAppModule {}

// whatsapp/whatsapp.service.ts
import { Injectable, Inject } from '@nestjs/common';
import { WhatsAppClient } from 'whatsapp-client-sdk';

@Injectable()
export class WhatsAppService {
  constructor(
    @Inject('WHATSAPP_CLIENT') private readonly client: WhatsAppClient
  ) {}

  async sendMessage(to: string, message: string) {
    return this.client.sendText(to, message);
  }
}

Troubleshooting Configuration Issues

ConfigurationError: Missing required fields

Ensure all required environment variables are set:

# Check if variables are loaded
echo $WHATSAPP_ACCESS_TOKEN
echo $WHATSAPP_PHONE_NUMBER_ID

Make sure you’re loading environment variables:

import 'dotenv/config'; // At the top of your main file

Connection timeout errors

Increase the timeout value based on your network conditions:

const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  timeout: 60000, // Increase from default 30000
});

Invalid API version

Use a supported API version:

// Supported versions: v23.0, v22.0, v21.0
const client = new WhatsAppClient({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
  apiVersion: 'v23.0', // Use latest stable
});

Webhook verification fails

Ensure webhook token matches Meta configuration:

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

Next Steps

Core Concepts

Learn about the SDK’s internal architecture and design

Error Handling

Understand error types and handling strategies

Webhook Setup

Configure webhooks for receiving messages

Production Guide

Deploy your configuration to production

Introduction

​Basic Configuration

​Complete Configuration Interface

​Configuration Examples

​Production Configuration

​Development Configuration

​High-Volume Configuration

​Storage Configuration

Storage Integration Guide

​Configuration Options Explained

​API Version

​Timeout Configuration

​Base URL Configuration

​Environment-Based Configuration

​Configuration Validation

​Runtime Configuration Updates

​Configuration Best Practices

​1. Environment Variables

​2. Configuration Factory Pattern

​3. Configuration with Secrets Management

​Framework-Specific Configuration

​Next.js Configuration

​Express.js Configuration

​NestJS Configuration

​Troubleshooting Configuration Issues

​Next Steps

Core Concepts

Error Handling

Webhook Setup

Production Guide

Basic Configuration

Complete Configuration Interface

Configuration Examples

Production Configuration

Development Configuration

High-Volume Configuration

Storage Configuration

Configuration Options Explained

API Version

Timeout Configuration

Base URL Configuration

Environment-Based Configuration

Configuration Validation

Runtime Configuration Updates

Configuration Best Practices

1. Environment Variables

2. Configuration Factory Pattern

3. Configuration with Secrets Management

Framework-Specific Configuration

Next.js Configuration

Express.js Configuration

NestJS Configuration

Troubleshooting Configuration Issues

Next Steps