Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/green-api/whatsapp-chatgpt-js

This is a library for creating WhatsApp bot with OpenAI GPT integration, built on GREEN-API.
https://github.com/green-api/whatsapp-chatgpt-js

openai openai-chatgpt whatsapp whatsapp-api whatsapp-bot whatsapp-chat whatsapp-chatbot whatsapp-js

Last synced: 6 days ago
JSON representation

This is a library for creating WhatsApp bot with OpenAI GPT integration, built on GREEN-API.

Awesome Lists containing this project

README 

        
# WhatsApp GPT Bot Library



A modern, state-based WhatsApp bot library with OpenAI GPT integration, built on top of GREEN-API and

@green-api/whatsapp-chatbot-js-v2.



## Features



- OpenAI GPT model integration for intelligent responses

- Support for multiple GPT models (GPT-3.5, GPT-4, GPT-4o)

- Multimodal capabilities with image processing support

- Voice message transcription

- Comprehensive message handling for various WhatsApp media types

- Middleware architecture for customizing message and response processing

- Built-in conversation history management

- State-based conversation flow inherited from base library

- TypeScript support



## Installation



```bash

npm install @green-api/whatsapp-chatgpt

```



The dependencies (`openai` and `@green-api/whatsapp-chatbot-js-v2`) will be installed automatically.



## Quick Start



```typescript

import { WhatsappGptBot } from '@green-api/whatsapp-chatgpt';



// Initialize the bot

const bot = new WhatsappGptBot({

    idInstance: "your-instance-id",

    apiTokenInstance: "your-token",

    openaiApiKey: "your-openai-api-key",

    model: "gpt-4o",

    systemMessage: "You are a helpful assistant."

});



// Start the bot

bot.start();

```



# Usage Patterns



This library supports two distinct usage patterns depending on your needs:



## 1. Standalone Bot



You can run the bot as a standalone service that listens for and processes WhatsApp messages automatically:



```typescript

const bot = new WhatsappGptBot({

    idInstance: "your-instance-id",

    apiTokenInstance: "your-token",

    openaiApiKey: "your-openai-api-key",

    model: "gpt-4o",

    systemMessage: "You are a helpful assistant."

});



// Start listening for webhooks and processing messages

bot.start();

```



## 2. Message Processor



Alternatively, you can use the bot as a message processing utility within your own bot or application:



```typescript

const gptBot = new WhatsappGptBot({

    idInstance: "your-instance-id",

    apiTokenInstance: "your-token",

    openaiApiKey: "your-openai-api-key",

    model: "gpt-4o",

    systemMessage: "You are a helpful assistant."

});



// No need to call start() - just use processMessage when needed

const {response, updatedData} = await gptBot.processMessage(message, sessionData);



// Handle the response in your own way

await yourBot.sendText(message.chatId, response);



// Store the updated session data in your own state system

yourSessionData.gptSession = updatedData;

```



### Integration Example



Here's how to integrate the GPT bot into your own state-based bot:



```typescript

interface CustomSessionData {

    lang?: string;

    gptSession?: GPTSessionData;  // Store GPT session data

}



const gptState: State = {

    name: "gpt_state",

    async onEnter(message, data) {

        // Initialize GPT session

        data.gptSession = {

            messages: [{role: "system", content: gptBot.systemMessage}],

            lastActivity: Date.now()

        };

        await bot.sendText(message.chatId, "Chat with GPT started!");

    },

    async onMessage(message, data) {

        // Process messages using GPT bot

        const {response, updatedData} = await gptBot.processMessage(

                message,

                data.gptSession

        );



        await bot.sendText(message.chatId, response);

        data.gptSession = updatedData;



        return undefined;  // Stay in current state

    }

};

```



This flexibility allows you to either run the bot independently or integrate its GPT capabilities into a larger system

while maintaining full control over the conversation flow and state management.



Key points about these patterns:



1. **Standalone Bot**

    - Uses internal state management

    - Handles webhooks automatically

    - Better for simple, single-purpose GPT chatbots

    - Requires calling `bot.start()`



2. **Message Processor**

    - No internal state management needed

    - No webhook handling

    - Perfect for integration into existing bots

    - Uses only the GPT processing capabilities

    - More flexible and controllable

    - Never call `start()` - just use `processMessage()`



## Core Components



### Bot Configuration



Complete configuration options for the WhatsappGptBot:



```typescript

interface GPTBotConfig extends BotConfig {

    /** OpenAI API key */

    openaiApiKey: string;



    /** Model to use for chat completion (default: gpt-4o) */

    model?: OpenAIModel;



    /** Maximum number of messages to keep in conversation history (default: 10) */

    maxHistoryLength?: number;



    /** System message to set assistant behavior */

    systemMessage?: string;



    /** Temperature for response generation (default: 0.5) */

    temperature?: number;



    /** Default reply when an error occurs */

    errorMessage?: string;



    // All configuration options from the base WhatsAppBot are also available

    // See @green-api/whatsapp-chatbot-js-v2 for additional options

}

```



### WhatsappGptBot



Main class for creating and managing your OpenAI-powered WhatsApp bot:



```typescript

const bot = new WhatsappGptBot({

    // Required parameters

    idInstance: "your-instance-id",

    apiTokenInstance: "your-token",

    openaiApiKey: "your-openai-api-key",



    // Optional GPT-specific parameters

    model: "gpt-4o",

    maxHistoryLength: 15,

    systemMessage: "You are a helpful assistant specializing in customer support.",

    temperature: 0.7,

    errorMessage: "Sorry, I couldn't process your request. Please try again.",



    // Optional parameters from base bot

    defaultState: "greeting",

    sessionTimeout: 300,

    // See base library documentation for more options

});

```



## Message Handling



The bot automatically handles different types of WhatsApp messages and converts them into a format understood by

OpenAI's models.



### Supported Message Types



- **Text**: Regular text messages

- **Image**: Photos with optional captions (supported in vision-capable models)

- **Audio**: Voice messages with automatic transcription

- **Video**: Video messages with captions

- **Document**: File attachments

- **Poll**: Poll messages and poll updates

- **Location**: Location sharing

- **Contact**: Contact sharing



### Message Handler Registry



The bot uses a registry of message handlers to process different message types:



```typescript

// Access the registry

const registry = bot.messageHandlers;



// Create a custom message handler

class CustomMessageHandler implements MessageHandler {

    canHandle(message: Message): boolean {

        return message.type === "custom-type";

    }



    async processMessage(message: Message): Promise {

        // Process the message

        return "Processed content";

    }

}



// Register the custom handler

bot.registerMessageHandler(new CustomMessageHandler());



// Replace an existing handler

bot.replaceHandler(TextMessageHandler, new CustomTextHandler());

```



## Middleware System



The middleware system allows for customizing message processing before sending to GPT and response processing before

sending back to the user.



### Adding Message Middleware



```typescript

// Process messages before sending to GPT

bot.addMessageMiddleware(async (message, messageContent, messages, sessionData) => {

    // Add custom context to the conversation

    if (message.type === "text" && message.chatId.endsWith("@c.us")) {

        // Add user information from a database

        const userInfo = await getUserInfo(message.chatId);



        // Modify the current message content

        const enhancedContent = `[User: ${userInfo.name}] ${messageContent}`;



        return {

            messageContent: enhancedContent,

            messages

        };

    }



    return {

        messageContent,

        messages

    };

});

```



### Adding Response Middleware



```typescript

// Process GPT responses before sending to user

bot.addResponseMiddleware(async (response, messages, sessionData) => {

    // Format or modify the response

    const formattedResponse = response

            .replace(/\bGPT\b/g, "Assistant")

            .trim();



    // You can also modify the messages that will be saved in history

    return {

        response: formattedResponse,

        messages

    };

});

```



## Session Data



The GPT bot extends the base session data with conversation-specific information:



```typescript

interface GPTSessionData {

    /** Conversation history */

    messages: ChatCompletionMessageParam[];



    /** Timestamp of last activity */

    lastActivity: number;



    /** Custom user state data */

    userData?: Record;



    /** Context for the current conversation */

    context?: {

        /** Tags or metadata for the conversation */

        tags?: string[];



        /** Custom context variables */

        variables?: Record;

    };

}

```



You can access and modify this data in your middleware:



```typescript

bot.addMessageMiddleware(async (message, content, messages, sessionData) => {

    // Set context variables

    if (!sessionData.context) {

        sessionData.context = {variables: {}};

    }



    sessionData.context.variables.lastInteraction = new Date().toISOString();



    return {messageContent: content, messages};

});

```



## Utilities



The library provides several utility functions for common tasks:



### Media Handling



```typescript

import { Utils } from '@green-api/whatsapp-chatgpt';



// Download media from a URL

const tempFile = await Utils.downloadMedia("https://example.com/image.jpg");



// Transcribe audio

const openai = new OpenAI({apiKey: "your-openai-api-key"});

const transcript = await Utils.transcribeAudio("/path/to/audio.ogg", openai);



// Clean up after processing

fs.unlinkSync(tempFile);

```



### Conversation Management



```typescript

import { Utils } from 'whatsapp-gpt-bot';



// Trim conversation history

const trimmedMessages = Utils.trimConversationHistory(

        messages,

        10,  // max messages

        true  // preserve system message

);



// Estimate token usage

const estimatedTokens = Utils.estimateTokens(messages);

```



## Supported OpenAI Models



The library supports a variety of OpenAI models:



### GPT-4 Models



- gpt-4

- gpt-4-turbo

- gpt-4-turbo-preview

- gpt-4-1106-preview

- gpt-4-0125-preview

- gpt-4-32k



### GPT-4o Models



- gpt-4o (default)

- gpt-4o-mini

- gpt-4o-2024-05-13



### GPT-3.5 Models



- gpt-3.5-turbo

- gpt-3.5-turbo-16k

- gpt-3.5-turbo-1106

- gpt-3.5-turbo-0125



### o1 Models



- o1

- o1-mini

- o1-preview



### Image-Capable Models



The following models can process images:



- gpt-4o

- gpt-4o-mini

- gpt-4-vision-preview

- gpt-4-turbo

- gpt-4-turbo-preview



## Advanced Configuration



### Custom State Handling



Since the library is built on @green-api/whatsapp-chatbot-js-v2, you can use all the state features of the base library:



```typescript

// Add custom state

bot.addState({

    name: "collect_info",

    async onEnter(message) {

        await bot.sendText(message.chatId, "Please provide your name.");

    },

    async onMessage(message, data = {}) {

        // Store the name and process with GPT

        const openai = bot.getOpenAI();

        const completion = await openai.chat.completions.create({

            model: "gpt-3.5-turbo",

            messages: [

                {role: "system", content: "Generate a personalized greeting."},

                {role: "user", content: `My name is ${message.text}`}

            ]

        });



        await bot.sendText(message.chatId, completion.choices[0]?.message.content || "Hello!");

        return "main_chat"; // Transition to main chat state

    }

});

```



### Advanced Message Processing



```typescript

// Get OpenAI client for custom API calls

const openai = bot.getOpenAI();



// Check if current model supports images

if (bot.supportsImages()) {

    // Handle image-based workflow

}

```



## Demo Bot Example



See [our demo chatbot](https://github.com/green-api/whatsapp-demo-chatgpt-js) for a comprehensive demo chatbot, which

showcases many features:



```typescript

import {

    GPTSessionData,

    ImageMessageHandler,

    ProcessMessageMiddleware,

    ProcessResponseMiddleware,

    WhatsappGptBot,

    OpenAIModel,

} from "@green-api/whatsapp-chatgpt";

import * as dotenv from "dotenv";

import { Message } from "@green-api/whatsapp-chatbot-js-v2";

import { ChatCompletionMessageParam } from "openai/resources/chat/completions";

import OpenAI from "openai";



dotenv.config();



// Custom image handler that provides enhanced descriptions

class EnhancedImageHandler extends ImageMessageHandler {

    async processMessage(message: Message, openai: OpenAI, model: OpenAIModel): Promise {

        const result = await super.processMessage(message, openai, model);



        if (typeof result === "string") {

            return result.replace(

                    "[The user sent an image",

                    "[The user sent an image. Tell them that you are not the model they should be using"

            );

        }



        return result;

    }

}



// Middleware examples



// Logging middleware

const loggingMessageMiddleware: ProcessMessageMiddleware = async (

        message, messageContent, messages, _

) => {

    console.log(`[${new Date().toISOString()}] User (${message.chatId}): `,

            typeof messageContent === "string"

                    ? messageContent

                    : JSON.stringify(messageContent));



    return {messageContent, messages};

};



// Initialize the bot

const bot = new WhatsappGptBot({

    idInstance: process.env.INSTANCE_ID || "",

    apiTokenInstance: process.env.INSTANCE_TOKEN || "",

    openaiApiKey: process.env.OPENAI_API_KEY || "",

    model: "gpt-4o",

    systemMessage: "You are a helpful WhatsApp assistant created by GREEN-API",

    maxHistoryLength: 15,

    temperature: 0.5,

    handlersFirst: true,

    clearWebhookQueueOnStart: true,

});



// Command handlers

bot.onText("/help", async (message, _) => {

    const helpText = `*WhatsAppGPT Demo Bot*\n\nAvailable commands:\n- /help - Show this help message\n- /clear - Clear conversation history`;

    await bot.sendText(message.chatId, helpText);

});



// Register middleware

bot.addMessageMiddleware(loggingMessageMiddleware);



// Replace default handlers

bot.replaceHandler(ImageMessageHandler, new EnhancedImageHandler());



// Start the bot

bot.start();

```



This demo bot includes:



- Custom message handlers

- Various middleware implementations

- Command handlers

- Custom type handlers

- Error handling



## Additional Examples



### Multi-Language Support Bot



```typescript

import { WhatsappGptBot } from '@green-api/whatsapp-chatgpt';

import { detectLanguage } from './language-detector';



const bot = new WhatsappGptBot({

    idInstance: "your-instance-id",

    apiTokenInstance: "your-token",

    openaiApiKey: "your-openai-api-key",

    model: "gpt-4o"

});



// Add language detection middleware

bot.addMessageMiddleware(async (message, content, messages, sessionData) => {

    // Only process text messages

    if (message.type !== 'text' || !message.text) {

        return {messageContent: content, messages};

    }



    // Detect language

    const language = await detectLanguage(message.text);



    // Store language in session

    if (!sessionData.context) {

        sessionData.context = {variables: {}};

    }

    sessionData.context.variables.language = language;



    // Update system message with language instruction

    const languageInstruction = `User is writing in ${language}. Reply in the same language.`;



    // Find system message

    const systemIndex = messages.findIndex(m => m.role === 'system');



    if (systemIndex >= 0) {

        // Update existing system message

        const updatedMessages = [...messages];

        const currentContent = updatedMessages[systemIndex].content;

        if (typeof currentContent === 'string' && !currentContent.includes('User is writing in')) {

            updatedMessages[systemIndex].content = `${currentContent} ${languageInstruction}`;

        }

        return {messageContent: content, messages: updatedMessages};

    } else {

        // Add new system message

        return {

            messageContent: content,

            messages: [

                {role: 'system', content: languageInstruction},

                ...messages

            ]

        };

    }

});



// Start the bot

bot.start();

```



## License



MIT