Unreadbox

Unreadbox — Installation & User Guide

Thank you for purchasing Unreadbox. This guide takes you from a blank server to your first WhatsApp message.

Time needed: ~20 minutes on a clean VPS.

1. Server Requirements

Component	Minimum
PHP	8.2 (extensions: `bcmath`, `ctype`, `curl`, `dom`, `fileinfo`, `json`, `mbstring`, `openssl`, `pdo_mysql`, `tokenizer`, `xml`, `sodium`)
Database	MySQL 8+ (production) or SQLite (local testing)
Web server	Nginx or Apache with HTTPS
Composer	2.x
Node.js	18+ (only for building assets)

An HTTPS certificate is required — Meta rejects plain-HTTP webhook URLs.

2. Installation

# 1. Upload the source to your web root, e.g. /var/www/Unreadbox
cd /var/www/Unreadbox

# 2. Install PHP dependencies
composer install --no-dev --optimize-autoloader

# 3. Build frontend assets
npm install && npm run build

# 4. Configure environment
cp .env.example .env
php artisan key:generate

Edit .env:

APP_URL=https://yourdomain.com
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=Unreadbox
DB_USERNAME=...
DB_PASSWORD=...

# Meta Cloud API driver: "graph" for production, "mock" for testing/demo
META_DRIVER=graph
META_GRAPH_VERSION=v21.0

# 32+ random chars, used to encrypt WhatsApp credentials (AES-256-GCM)
CREDENTIAL_ENCRYPTION_KEY=<generate with: php -r "echo bin2hex(random_bytes(32));">

# 5. Migrate + seed (seeder creates a demo tenant; remove --seed for production)
php artisan migrate --seed

# 6. Permissions & cache
chown -R www-data:www-data storage bootstrap/cache
php artisan config:cache && php artisan route:cache

# 7. Queue worker (required for webhook processing and message sending)
php artisan queue:work   # run under supervisor in production

Nginx pointer

root /var/www/Unreadbox/public;
index index.php;
location / { try_files $uri $uri/ /index.php?$query_string; }
location ~ \.php$ { fastcgi_pass unix:/run/php/php8.2-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $realpath_root/index.php; }

3. Create Your First Tenant & User

Seeded demo login: demo@wa-crm.test / password.

To create a real user manually:

php artisan tinker
>>> $tenant = \App\Models\Tenant::create(['name' => 'My Company', 'slug' => 'my-company']);
>>> $tenant->users()->create(['name' => 'Admin', 'email' => 'you@example.com', 'password' => bcrypt('secret')]);

4. Connect WhatsApp (Meta Cloud API)

In Meta for Developers, create an app and add the WhatsApp product.
Copy from the WhatsApp → API Setup page: Phone Number ID, WhatsApp Business Account ID, and a permanent Access Token (use a System User token, never a temporary one).
In Unreadbox: Settings → WhatsApp Accounts, paste the three values, save. Credentials are encrypted (AES-256-GCM) immediately; you will only ever see a fingerprint afterwards.

Webhook configuration

Your tenant-specific webhook URL is shown on the same settings page:

https://yourdomain.com/webhook/wa/{tenant-uuid}

Copy this URL and a verify_token (also shown there) into Meta's WhatsApp → Configuration page.
Meta sends a GET handshake; Unreadbox answers hub.challenge automatically.
Subscribe to the messages field.

5. Go Live Check

Open System Check in the sidebar. It verifies:

PHP extensions present, storage writable
Database reachable, migrations up to date
Queue worker running
Meta credentials decrypted correctly (fingerprint check)
Webhook endpoint publicly reachable over HTTPS

Fix anything red, then send a WhatsApp message from your phone to the connected number. It should appear in Inbox within seconds.

6. How Messaging Works

Inbound: customer → Meta webhook → Unreadbox → Inbox. Duplicate webhook deliveries are deduplicated by message ID; raw payloads are archived before processing.
Outbound replies: allowed inside the 24-hour customer service window (Meta rule) after the customer's last message. Outside the window, the reply is rejected by the system with a clear error.
Quota: each tenant has a monthly message quota (set on its plan). Sending pre-deducts atomically; at 110% of quota sending is blocked until the quota is raised or the month resets.

7. Testing Without Real Credentials

Set META_DRIVER=mock to run the complete send/receive flow against an in-app simulator — useful for development, demos, and CI.

8. Troubleshooting

Symptom	Likely cause / fix
Webhook handshake fails	URL not HTTPS, or wrong verify_token; check Meta's Configuration page
Messages not arriving	Queue worker not running; `php artisan queue:work` under supervisor
"Credentials could not be decrypted"	`CREDENTIAL_ENCRYPTION_KEY` changed after saving credentials — restore the original key
401 on webhook POST	Signature mismatch: confirm the App Secret is set correctly in `.env`
Send fails with window error	The 24h window has expired; customer must message you first

9. Support

Post in the item comments on CodeCanyon, or use the contact form on our author profile. Please include your System Check output (it contains no credentials).