WhatsApp Chatbot library for SDKWA based on Telegraf

This project extends Telegraf to support WhatsApp using the SDKWA WhatsApp API. It provides a seamless way to use the familiar Telegraf API with WhatsApp, including support for scenes, sessions, middleware, and all other Telegraf features.

📦 Available on npm as @sdkwa/whatsapp-chatbot

Features

✅ Full Telegraf API Compatibility - Use your existing Telegraf code with WhatsApp and Telegram
✅ Multi-Messenger Support - Works with both WhatsApp and Telegram using identical API
✅ Clean WhatsAppBot Constructor - Intuitive new WhatsAppBot(config, options) syntax
✅ Scenes Support - Create complex conversation flows
✅ Sessions & Middleware - Maintain state and add custom functionality
✅ Command Handling - Handle /start, /help, and custom commands
✅ Text Messages - Send and receive text messages seamlessly
✅ Messenger Selection - Simply specify messenger: 'whatsapp' or 'telegram'

Installation

npm install @sdkwa/whatsapp-chatbot

That's it! The package includes all necessary dependencies.

Quick Start

1. Install the package:

   npm install @sdkwa/whatsapp-chatbot

2. Get credentials:

   • Sign up at SDKWA
   • Create a new WhatsApp instance
   • Get your idInstance and apiTokenInstance

3. Create your bot:

   WhatsApp Bot:

   const { WhatsAppBot } = require('@sdkwa/whatsapp-chatbot');
      
   const bot = new WhatsAppBot({
     idInstance: 'your-instance-id',
     apiTokenInstance: 'your-api-token'
   }, {
     messenger: 'whatsapp' // Optional, 'whatsapp' is default
   });
      
   bot.start((ctx) => ctx.reply('Hello WhatsApp!'));
   bot.launch();

   Telegram Bot:

   const { WhatsAppBot } = require('@sdkwa/whatsapp-chatbot');
      
   const bot = new WhatsAppBot({
     idInstance: 'your-telegram-instance-id',
     apiTokenInstance: 'your-telegram-api-token'
   }, {
     messenger: 'telegram'
   });
      
   bot.start((ctx) => ctx.reply('Hello Telegram!'));
   bot.launch();

Usage

Basic WhatsApp Bot

const { WhatsAppBot } = require('@sdkwa/whatsapp-chatbot');

// WhatsApp configuration
const bot = new WhatsAppBot({
  idInstance: 'your-instance-id',
  apiTokenInstance: 'your-api-token',
  apiUrl: 'https://api.sdkwa.pro' // Optional
}, {
  messenger: 'whatsapp' // Optional, 'whatsapp' is default
});

// Use familiar Telegraf API
bot.start((ctx) => {
  ctx.reply('Hello from WhatsApp bot!');
});

bot.on('text', (ctx) => {
  ctx.reply(`You said: ${ctx.message.text}`);
});

bot.launch();

Advanced Example with Scenes

const { WhatsAppBot, Scenes, session } = require('@sdkwa/whatsapp-chatbot');

// WhatsApp configuration
const whatsappConfig = {
  idInstance: 'your-instance-id',
  apiTokenInstance: 'your-whatsapp-token',
};

// Create a scene
const greetingScene = new Scenes.BaseScene('greeting');
greetingScene.enter((ctx) => ctx.reply('What\'s your name?'));
greetingScene.on('text', (ctx) => {
  ctx.reply(`Nice to meet you, ${ctx.message.text}!`);
  ctx.scene.leave();
});

// Set up bot with scenes
const stage = new Scenes.Stage([greetingScene]);
const bot = new WhatsAppBot(whatsappConfig);

bot.use(session());
bot.use(stage.middleware());

bot.command('greet', (ctx) => ctx.scene.enter('greeting'));

bot.launch();

Configuration

Multi-Messenger Support (New in v1.0.18+)

The bot now supports both WhatsApp and Telegram! You can choose which messenger to use when creating your bot.

WhatsApp Configuration

// WhatsApp bot (default messenger)
const whatsappBot = new WhatsAppBot({
  idInstance: "your-whatsapp-instance-id",
  apiTokenInstance: "your-whatsapp-api-token", 
  host: "https://api.sdkwa.pro"  // Optional
}, {
  messenger: 'whatsapp' // Optional, 'whatsapp' is default
});

Telegram Configuration

// Telegram bot (same credentials format, different messenger)
const telegramBot = new WhatsAppBot({
  idInstance: "your-telegram-instance-id",
  apiTokenInstance: "your-telegram-api-token", 
  host: "https://api.sdkwa.pro"  // Optional
}, {
  messenger: 'telegram'
});

Choosing Messenger Type at Runtime

const messengerType = process.env.MESSENGER_TYPE || 'whatsapp'; // 'whatsapp' or 'telegram'

const bot = new WhatsAppBot({
  idInstance: process.env.ID_INSTANCE,
  apiTokenInstance: process.env.API_TOKEN_INSTANCE
}, {
  messenger: messengerType
});

Alternative: Legacy JSON string format (still supported):

const { Telegraf } = require('@sdkwa/whatsapp-chatbot');

const bot = new Telegraf(JSON.stringify({
  idInstance: "your-instance-id",
  apiTokenInstance: "your-api-token"
}));

Getting SDKWA Credentials

Both WhatsApp and Telegram use the same SDKWA API credentials format:

1. Sign up at SDKWA
2. Create a new instance (choose WhatsApp or Telegram when creating)
3. Get your idInstance and apiTokenInstance from the dashboard
4. Use these credentials with the appropriate messenger option in your bot configuration

API Compatibility

| Feature | Telegram | WhatsApp | Notes | |---------|----------|----------|-------| | Text Messages | ✅ | ✅ | Full support on both platforms | | Commands | ✅ | ✅ | /start, /help, custom commands | | Scenes | ✅ | ✅ | Complete scene support | | Sessions | ✅ | ✅ | Memory and custom stores | | Middleware | ✅ | ✅ | All middleware types | | Inline Keyboards | ✅ | ⚠️ | Full Telegram, Limited WhatsApp | | Media Files | ✅ | ✅ | Photos, documents, audio, video | | Groups | ✅ | ✅ | Group chat support | | Stickers | ✅ | ⚠️ | Telegram native, WhatsApp limited |

Examples

See the examples/ directory for more examples:

Basic Examples

• hello-bot.js - Basic WhatsApp bot
• echo-bot.js - Echo messages back
• command-bot.js - Command handling
• messenger-type-example.js - Using both WhatsApp and Telegram

Advanced Examples

• scene-bot.js - Conversation flows with scenes
• media-bot.js - Media file handling
• custom-context-bot.js - Custom context usage

Limitations

• WhatsApp has different capabilities than Telegram (inline keyboards, different file handling, etc.)
• Rate limiting may apply based on your SDKWA plan
• Some advanced Telegram features may not have WhatsApp equivalents

Troubleshooting

Common Issues

Bot not detecting WhatsApp config:

• Ensure the token is a valid JSON string
• Check that idInstance and apiTokenInstance properties are present

API errors:

• Verify your SDKWA credentials are correct
• Check that your instance is active and verified
• Ensure you have sufficient API quota

Installation errors:

• Try using npm install @sdkwa/whatsapp-chatbot --legacy-peer-deps if there are peer dependency conflicts
• Make sure you're using Node.js version 16 or higher

Import errors:

• Make sure you're importing from @sdkwa/whatsapp-chatbot not telegraf
• Check that the package is properly installed in your node_modules

License

Same as Telegraf - MIT License