Skip to main content

​
Getting Started with WhatsApp SDK

This guide will help you create your first application using the WhatsApp SDK. You’ll learn how to set up the SDK, authenticate with WhatsApp, and send your first message.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 20 or higher installed
  • npm or yarn package manager
  • Basic knowledge of TypeScript/JavaScript
  • Chromium or Chrome browser (used by Puppeteer for WhatsApp Web)

​
Quick Start Example

Here’s a simple example to get you started with the WhatsApp SDK: 
import { WhatsAppSDK } from '@deco-cx/whatsapp-sdk';
import { LocalAuthStrategy } from '@deco-cx/whatsapp-sdk/whatsapp/sdk/auth/strategies/local.js';
import path from 'path';

// Initialize the SDK with local authentication
const sdk = new WhatsAppSDK({
  auth: {
    type: 'local',
    // Store session data in the local filesystem
    dataPath: path.resolve(process.cwd(), 'sessions')
  },
  // Enable debug mode for detailed logs
  debug: true
});

// Create a WhatsApp client
const client = sdk.createClient({
  name: 'my-whatsapp-client'
});

// Listen for the QR code event to authenticate
client.on('qr', (qrCode) => {
  console.log('Scan this QR code to log in:');
  console.log(qrCode);
});

// Listen for ready event
client.on('ready', () => {
  console.log('Client is ready!');
  
  // Send a message once the client is ready
  client.sendTextMessage({
    to: '[email protected]', // Phone number + @c.us
    text: 'Hello from WhatsApp SDK!'
  })
  .then(response => {
    console.log('Message sent:', response);
  })
  .catch(error => {
    console.error('Failed to send message:', error);
  });
});

// Initialize the client
client.initialize()
  .then(() => {
    console.log('Initialization started');
  })
  .catch(error => {
    console.error('Initialization failed:', error);
  });

​
Using the REST API

The WhatsApp SDK also provides a REST API that you can use to integrate with web applications: 
import { WhatsAppSDK } from '@deco-cx/whatsapp-sdk';
import path from 'path';

// Initialize the SDK with API enabled
const sdk = new WhatsAppSDK({
  auth: {
    type: 'local',
    dataPath: path.resolve(process.cwd(), 'sessions')
  },
  debug: true,
  api: {
    enabled: true,
    port: 3000,
    host: 'localhost'
  }
});

// Start the API server
sdk.startApiServer()
  .then(() => {
    console.log('API server started on http://localhost:3000/api');
    console.log('API docs available at http://localhost:3000/api/docs');
    
    // The API server will automatically handle client initialization
  })
  .catch(error => {
    console.error('Failed to start API server:', error);
  });
After starting the API server, you can:
  1. Access the Swagger documentation at http://localhost:3000/api/docs
  2. Scan the QR code via the /api/v1/client/qr endpoint
  3. Send messages via the /api/v1/messages/send endpoint

​
Next Steps

Now that you’ve created your first WhatsApp SDK application, you can:

Authentication

Learn about different authentication strategies.

Sending Messages

Explore advanced messaging capabilities.

Working with Chats

Learn how to manage chats and conversations.
For a complete reference of all available features, check out the API Reference.