WhatsApp FAQ Chatbot

A comprehensive WhatsApp chatbot solution for handling customer frequently asked questions (FAQs) with intelligent matching, conversation tracking, and admin interface.

Features

WhatsApp Integration: Uses Twilio WhatsApp API for seamless messaging
Intelligent FAQ Matching: TF-IDF vectorization and cosine similarity for accurate answers
Keyword Search: Fallback keyword matching for better coverage
Conversation History: Track all user interactions
User Sessions: Maintain conversation state and context
Admin Interface: REST API for managing FAQs and viewing analytics
Analytics Dashboard: Track bot performance and user engagement
Multi-language Support: Extensible for multiple languages
Human Agent Handoff: Escalate to human agents when needed

Project Structure

FAQ_Chat_Bot/
├── app.py                 # Main Flask application
├── config.py             # Configuration settings
├── models.py             # Database models
├── faq_manager.py        # FAQ search and matching logic
├── message_handler.py    # Message processing and response generation
├── admin.py              # Admin API endpoints
├── wsgi.py               # WSGI entry point
├── requirements.txt      # Python dependencies
├── .env.example         # Environment variables template
└── README.md            # This file

Setup Instructions

1. Prerequisites

Python 3.8 or higher
Twilio account with WhatsApp enabled
Web server (for production deployment)

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env file with your credentials:

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_account_sid_here
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=your_twilio_phone_number_here

# Flask Configuration
FLASK_ENV=development
SECRET_KEY=your_secret_key_here
DATABASE_URL=sqlite:///faq_bot.db

# WhatsApp Configuration
WEBHOOK_URL=https://your-domain.com/webhook/whatsapp

4. Twilio WhatsApp Setup

Create a Twilio Account: Sign up at twilio.com
Enable WhatsApp Sandbox:
- Go to Twilio Console → Messaging → Try it out → WhatsApp
- Follow the instructions to set up the WhatsApp sandbox
Get Your Credentials:
- Account SID and Auth Token from Twilio Console
- Phone number from WhatsApp sandbox settings

5. Database Initialization

The application will automatically create the database and tables on first run. Sample FAQs will be added automatically if the database is empty.

6. Run the Application

Development:

python app.py

Production:

gunicorn --workers 4 --bind 0.0.0.0:5000 wsgi:app

7. Configure Webhook

Deploy your application to a web server (Heroku, AWS, DigitalOcean, etc.)
Set the webhook URL in your Twilio WhatsApp settings:
- URL: https://your-domain.com/webhook/whatsapp
- Method: POST
Test the webhook by sending a message to your WhatsApp number

Usage

For Customers

Customers can interact with the bot by sending messages to your WhatsApp number:

Ask questions: "What are your business hours?"
Get help: Send "help" or "menu"
Browse categories: Send "categories" or "category:Shipping"
Human agent: Send "human" or "agent"

For Administrators

Use the admin API to manage FAQs and view analytics:

Add FAQ

curl -X POST http://localhost:5000/admin/faqs \
  -H "Content-Type: application/json" \
  -d '{"question": "What is your return policy?", "answer": "30-day return policy", "category": "Returns"}'

Get All FAQs

curl http://localhost:5000/admin/faqs

View Analytics

curl http://localhost:5000/admin/analytics/summary

View Conversations

curl http://localhost:5000/admin/conversations

API Endpoints

WhatsApp Webhook

POST /webhook/whatsapp - Receive WhatsApp messages

Admin API

GET /admin/faqs - List all FAQs
POST /admin/faqs - Add new FAQ
PUT /admin/faqs/{id} - Update FAQ
DELETE /admin/faqs/{id} - Delete FAQ
GET /admin/conversations - View conversation history
GET /admin/users - View user sessions
GET /admin/analytics - View analytics data
GET /admin/categories - List FAQ categories
GET /admin/search?q=query - Search FAQs and conversations

Deployment Guide

Heroku Deployment

Create Heroku App:

heroku create your-app-name

Set Environment Variables:

heroku config:set TWILIO_ACCOUNT_SID=your_sid
heroku config:set TWILIO_AUTH_TOKEN=your_token
heroku config:set TWILIO_PHONE_NUMBER=your_number
heroku config:set SECRET_KEY=your_secret

Deploy:

git add .
git commit -m "Initial deploy"
git push heroku main

Set Webhook: Update your Twilio webhook URL to: https://your-app-name.herokuapp.com/webhook/whatsapp

Docker Deployment

Create Dockerfile:

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 5000

CMD ["gunicorn", "--workers", "4", "--bind", "0.0.0.0:5000", "wsgi:app"]

Build and Run:

docker build -t whatsapp-faq-bot .
docker run -p 5000:5000 --env-file .env whatsapp-faq-bot

Customization

Adding New Languages

Update the preprocess_text method in faq_manager.py
Add language-specific stop words
Update welcome and help messages in message_handler.py

Custom Response Logic

Modify the generate_response method in message_handler.py to add:

New command handlers
Custom conversation flows
Integration with external APIs

Database Customization

For production, consider switching from SQLite to PostgreSQL:

DATABASE_URL=postgresql://user:password@localhost/faq_bot

Monitoring and Maintenance

Health Checks

GET /admin/health - Application health status
Monitor database connectivity and FAQ count

Analytics Tracking

The bot automatically tracks:

Daily conversation counts
Unique users
Response success rates
Human agent requests

Backup and Recovery

Regular database backups
FAQ export/import functionality
Conversation history retention policies

Security Considerations

Use HTTPS for webhook URLs
Validate incoming requests from Twilio
Secure admin endpoints with authentication
Rate limiting for API endpoints
Regular security updates for dependencies

Troubleshooting

Common Issues

Webhook Not Receiving Messages
- Check webhook URL is accessible
- Verify Twilio configuration
- Check server logs
FAQ Matching Not Working
- Ensure FAQs are loaded in database
- Check similarity threshold in config
- Review FAQ content and keywords
Database Connection Issues
- Verify DATABASE_URL configuration
- Check database permissions
- Ensure database server is running

Debug Mode

Enable debug logging:

FLASK_ENV=development
FLASK_DEBUG=1

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

Create an issue in the repository
Check the troubleshooting section
Review the API documentation

Note: This chatbot is designed to handle FAQs and basic customer inquiries. For complex customer service needs, consider integrating with a full customer service platform or human agent system.

Name		Name	Last commit message	Last commit date
FAQ_Chat_Bot		FAQ_Chat_Bot
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation