WhatsApp Client API

constructor(config: WhatsAppConfig)

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

async sendText(
  to: string, 
  text: string, 
  options?: TextOptions
): Promise<MessageResponse>

interface TextOptions {
  previewUrl?: boolean;      // Enable URL preview
  replyToMessageId?: string; // Reply to specific message
}

const response = await client.sendText(
  '+1234567890',
  'Hello! Check out https://example.com',
  { previewUrl: true }
);

async sendImage(
  to: string,
  image: ImageMedia,
  options?: MessageOptions
): Promise<MessageResponse>

interface ImageMedia {
  id?: string;        // Media ID from upload
  link?: string;      // Direct URL to image
  caption?: string;   // Image caption (max 1,024 chars)
}

// Send from URL
await client.sendImage('+1234567890', {
  link: 'https://example.com/image.jpg',
  caption: 'Beautiful sunset!'
});

// Send uploaded media
const media = await client.uploadMedia(imageBuffer, 'image');
await client.sendImage('+1234567890', {
  id: media.id,
  caption: 'Uploaded image'
});

async sendVideo(
  to: string,
  video: VideoMedia,
  options?: MessageOptions
): Promise<MessageResponse>

interface VideoMedia {
  id?: string;
  link?: string;
  caption?: string;
}

async sendAudio(
  to: string,
  audio: AudioMedia,
  options?: MessageOptions
): Promise<MessageResponse>

interface AudioMedia {
  id?: string;
  link?: string;
}

async sendDocument(
  to: string,
  document: DocumentMedia,
  options?: MessageOptions
): Promise<MessageResponse>

interface DocumentMedia {
  id?: string;
  link?: string;
  filename?: string;  // Display filename
  caption?: string;
}

async sendButtons(
  to: string,
  text: string,
  buttons: Button[],
  options?: InteractiveOptions
): Promise<MessageResponse>

interface Button {
  id: string;     // Button ID (max 256 chars)
  title: string;  // Button text (max 20 chars)
}

await client.sendButtons(
  '+1234567890',
  'Choose an option:',
  [
    { id: 'yes', title: 'Yes' },
    { id: 'no', title: 'No' },
    { id: 'maybe', title: 'Maybe' }
  ],
  {
    header: { type: 'text', text: 'Confirmation' },
    footer: 'Please select one'
  }
);

async sendList(
  to: string,
  text: string,
  buttonText: string,
  sections: ListSection[],
  options?: InteractiveOptions
): Promise<MessageResponse>

interface ListSection {
  title: string;      // Section title (max 24 chars)
  rows: ListRow[];    // Section rows
}

interface ListRow {
  id: string;           // Row ID (max 200 chars)
  title: string;        // Row title (max 24 chars)
  description?: string; // Row description (max 72 chars)
}

async sendTemplate(
  to: string,
  templateName: string,
  languageCode: string,
  components?: TemplateComponent[]
): Promise<MessageResponse>

async sendLocation(
  to: string,
  latitude: number,
  longitude: number,
  options?: LocationOptions
): Promise<MessageResponse>

interface LocationOptions {
  name?: string;     // Location name
  address?: string;  // Location address
}

async sendContacts(
  to: string,
  contacts: Contact[],
  options?: MessageOptions
): Promise<MessageResponse>

async sendSticker(
  to: string,
  sticker: StickerMedia,
  options?: MessageOptions
): Promise<MessageResponse>

async uploadMedia(
  file: Buffer | string,
  type: 'image' | 'video' | 'audio' | 'document'
): Promise<MediaResponse>

interface MediaResponse {
  id: string; // Media ID for reuse
}

const fileBuffer = fs.readFileSync('./image.jpg');
const media = await client.uploadMedia(fileBuffer, 'image');
console.log('Media ID:', media.id);

async getMediaInfo(mediaId: string): Promise<MediaInfo>

interface MediaInfo {
  url: string;        // Download URL (temporary)
  mime_type: string;  // File MIME type
  sha256: string;     // File hash
  file_size: number;  // Size in bytes
  id: string;         // Media ID
}

async downloadMedia(mediaId: string): Promise<Buffer>

const mediaInfo = await client.getMediaInfo('media_id');
const buffer = await client.downloadMedia('media_id');
fs.writeFileSync('./downloaded_file.ext', buffer);

verifyWebhook(
  mode: string,
  token: string,
  challenge: string
): string | null

parseWebhook(payload: any): ProcessedIncomingMessage[]

createWebhookProcessor(handlers: WebhookHandlers): WebhookProcessor

const processor = client.createWebhookProcessor({
  onTextMessage: async (message) => {
    console.log('Text:', message.text);
  },
  onError: async (error) => {
    console.error('Error:', error.message);
  }
});

async testConnection(): Promise<boolean>

const isConnected = await client.testConnection();
if (isConnected) {
  console.log('✅ WhatsApp API is accessible');
} else {
  console.log('❌ Cannot connect to WhatsApp API');
}

getConfig(): Partial<WhatsAppConfig>

const config = client.getConfig();
console.log(config);
// Output: { accessToken: '***', phoneNumberId: '123...', timeout: 30000 }

interface MessageResponse {
  messaging_product: 'whatsapp';
  contacts: Array<{
    input: string;   // Phone number sent to
    wa_id: string;   // WhatsApp ID
  }>;
  messages: Array<{
    id: string;                    // Unique message ID
    message_status?: MessageStatus; // Message status
  }>;
}

type MessageStatus = 'accepted' | 'queued' | 'sent' | 'delivered' | 'read' | 'failed';

interface ProcessedIncomingMessage {
  id: string;               // Message ID
  from: string;             // Sender phone number
  timestamp: string;        // ISO timestamp
  type: WhatsAppMessageType; // Message type
  
  // Type-specific content
  text?: string;
  media?: MediaInfo;
  location?: LocationInfo;
  interactive?: InteractiveInfo;
  contacts?: Contact[];
}

import { 
  WhatsAppApiError, 
  MessageValidationError,
  RateLimitError 
} from 'whatsapp-client-sdk';

try {
  await client.sendText('+1234567890', 'Hello!');
} catch (error) {
  if (error instanceof WhatsAppApiError) {
    console.error('API Error:', error.details);
  } else if (error instanceof MessageValidationError) {
    console.error('Validation Error:', error.field);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  }
}

// Upload and send in sequence
const media = await client.uploadMedia(fileBuffer, 'image');
const response = await client.sendImage('+1234567890', { 
  id: media.id, 
  caption: 'Uploaded image' 
});

// Reuse media for multiple recipients
await Promise.all([
  client.sendImage('+1111111111', { id: media.id }),
  client.sendImage('+2222222222', { id: media.id }),
  client.sendImage('+3333333333', { id: media.id })
]);

interface WhatsAppConfig {
  // Required
  accessToken: string;           // Meta access token
  phoneNumberId: string;         // WhatsApp Business phone number ID
  
  // Optional
  baseUrl?: string;             // API base URL (default: graph.facebook.com)
  apiVersion?: string;          // API version (default: v23.0)
  timeout?: number;             // Request timeout in ms (default: 30000)
  webhookVerifyToken?: string;  // Webhook verification token
  businessId?: string;          // Business account ID
}