Skip to main content

​
Overview

This guide walks you through setting up the WhatsApp RAG Bot for local development. You’ll use PHP’s built-in server and ngrok for webhook testing.

​
Prerequisites

Before starting, ensure you have:

PHP 7.4+

With required extensions installed

Composer

For dependency management

MySQL 5.7+

Or MariaDB 10.2+

ngrok

For webhook testing (optional)

​
Installation Steps

​
Step 1: Clone the Repository

# Clone the project
git clone <repository-url> whatsapp-rag-bot
cd whatsapp-rag-bot

​
Step 2: Install Dependencies

1

Install Composer packages

composer install
This installs:
  • guzzlehttp/guzzle - HTTP client
  • phpoffice/phpword - DOCX processing
  • smalot/pdfparser - PDF processing
  • PSR interfaces and dependencies
2

Verify installation

# Check if vendor directory exists
ls -la vendor/autoload.php

# Verify PHP can load autoloader
php -r "require 'vendor/autoload.php'; echo 'OK';">

​
Step 3: Database Setup

1

Create the database

# Connect to MySQL
mysql -u root -p

-- Create database
CREATE DATABASE whatsapp_rag_bot 
  DEFAULT CHARACTER SET utf8mb4 
  COLLATE utf8mb4_unicode_ci;

-- Create user (optional)
CREATE USER 'whatsapp_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON whatsapp_rag_bot.* TO 'whatsapp_user'@'localhost';
FLUSH PRIVILEGES;

EXIT;
2

Import the schema

# Import database schema
mysql -u root -p whatsapp_rag_bot < database/schema.sql
The schema includes:
  • documents - Uploaded files for RAG
  • vectors - Embeddings for semantic search
  • conversations - Chat sessions
  • messages - Message history
  • settings - Bot configuration
  • bot_credentials - API credentials (encrypted)
  • flow_nodes - Classic bot flows
  • calendar_flow_state - Calendar booking sessions
  • And more…
3

Verify database

# Check tables were created
mysql -u root -p whatsapp_rag_bot -e "SHOW TABLES;"
You should see 15+ tables listed.

​
Step 4: Environment Configuration

1

Create .env file

Create a .env file in the project root:
.env
# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_NAME=whatsapp_rag_bot
DB_USER=root
DB_PASSWORD=your_password

# WhatsApp Business API (get from Meta Developer Console)
WHATSAPP_ACCESS_TOKEN=your_access_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_VERIFY_TOKEN=my_custom_verify_token_123
WHATSAPP_APP_SECRET=your_app_secret

# OpenAI API
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_EMBEDDING_MODEL=text-embedding-ada-002

# Application
APP_BASE_URL=http://localhost:8080
APP_TIMEZONE=America/Bogota
APP_DEBUG=true
2

Secure the .env file

# Set proper permissions
chmod 600 .env
Never commit .env to version control. Add it to .gitignore.

​
Step 5: Create Required Directories

# Create directories for logs and uploads
mkdir -p logs
mkdir -p uploads/audios

# Set permissions
chmod 755 logs uploads uploads/audios

# Create .gitkeep files
touch logs/.gitkeep
touch uploads/.gitkeep

​
Step 6: Start the Development Server

The project includes router.php for use with PHP’s built-in server during development.
# Start PHP built-in server on port 8080
php -S localhost:8080 router.php
You should see: 
PHP 7.4.x Development Server (http://localhost:8080) started
From router.php:
/**
 * Router para PHP Built-in Server (solo desarrollo local)
 * Uso: php -S localhost:8080 router.php
 * 
 * NO subir a producción - solo para desarrollo local
 */
It serves static files directly and routes all other requests to index.php.

​
Step 7: Access the Admin Panel

Open your browser and navigate to: 
http://localhost:8080
You should see the admin panel login/dashboard.

​
Webhook Setup for Local Testing

Meta requires a public HTTPS URL for webhooks. Use ngrok to expose your local server.

​
Install and Configure ngrok

1

Install ngrok

Download from ngrok.com or install via package manager:
# macOS
brew install ngrok

# Linux
snap install ngrok

# Windows
choco install ngrok
2

Start ngrok tunnel

In a new terminal window:
ngrok http 8080
You’ll see output like:
Forwarding  https://abc123.ngrok.io -> http://localhost:8080
Keep this terminal window open. Closing it will stop the tunnel.
3

Note your webhook URL

Your webhook URL will be:
https://abc123.ngrok.io/webhook
Copy this URL - you’ll need it for Meta configuration.

​
Configure Meta Webhook

1

Open Meta Developer Console

Go to developers.facebook.com and open your WhatsApp app.
2

Configure webhook

Navigate to WhatsApp > Configuration > WebhookSet:
  • Callback URL: https://abc123.ngrok.io/webhook
  • Verify Token: Same as WHATSAPP_VERIFY_TOKEN in your .env file
3

Subscribe to webhook fields

Subscribe to:
  • ✅ messages
  • ✅ message_status (optional)
4

Test verification

Click Verify and Save. Meta will send a GET request to verify your webhook.Check your PHP server logs:
# In your PHP server terminal, you should see:
[200]: GET /webhook?hub.mode=subscribe&hub.verify_token=...

​
Testing the Bot

​
Send a Test Message

1

Send message from WhatsApp

Use your personal WhatsApp to send a message to your bot’s phone number.Example: “Hello, can you help me?”
2

Check logs

Monitor the PHP server terminal and check logs/ directory:
# Watch logs in real-time
tail -f logs/$(date +%Y-%m-%d).log
3

Verify response

You should receive a response from the bot based on your configured settings and available documents.

​
Test Webhook Locally

# Test webhook verification (GET)
curl "http://localhost:8080/webhook?hub.mode=subscribe&hub.verify_token=my_custom_verify_token_123&hub.challenge=test_challenge"

# Should return: test_challenge

​
Development Tips

​
Hot Reload

PHP’s built-in server doesn’t support auto-reload. Restart the server after code changes:
# Stop: Ctrl+C
# Restart:
php -S localhost:8080 router.php

​
Debug Mode

Enable detailed logging:
.env
APP_DEBUG=true
Check logs: 
# View all logs
ls -lh logs/

# View today's log
cat logs/$(date +%Y-%m-%d).log

# Follow logs in real-time
tail -f logs/$(date +%Y-%m-%d).log

​
Database Inspection

# Connect to database
mysql -u root -p whatsapp_rag_bot

-- View recent messages
SELECT * FROM messages ORDER BY created_at DESC LIMIT 10;

-- View conversations
SELECT * FROM conversations;

-- View settings
SELECT * FROM settings;

-- View document count
SELECT COUNT(*) FROM documents WHERE is_active = 1;

​
Upload Test Documents

  1. Navigate to admin panel: http://localhost:8080
  2. Go to Documents section
  3. Upload PDF or DOCX files
  4. Bot will process them for RAG

​
Common Issues

Problem: Can’t connect to databaseSolution:
# Check MySQL is running
sudo systemctl status mysql
# or
mysqladmin ping

# Verify credentials in .env match your MySQL setup
Problem: Meta can’t verify webhookSolution:
  • Ensure ngrok is running
  • Verify token matches exactly (case-sensitive)
  • Check PHP server is running
  • Review webhook.php:84-103 for verification logic
Problem: vendor/autoload.php not foundSolution:
composer install
Problem: Can’t write to logs directorySolution:
chmod 755 logs/
# or if running as different user:
sudo chown -R $USER:$USER logs/

​
Next Steps

Production Deployment

Deploy to production server

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us