Troubleshooting

Webhook issues

Meta webhook verification fails

Fix:

• Callback URL: https://yourdomain.com/api/webhook/whatsapp/{webhook_token}
• Verify token field: use verify_token from WhatsApp Settings (NOT webhook_token)
• Ensure your site is publicly accessible (not localhost)
• Check APP_URL in .env matches your public domain

Webhook verified but no messages arrive

• Confirm webhook subscribes to messages field in Meta
• Check WhatsApp account is active in portal settings
• Verify Phone Number ID in portal matches Meta
• Check core/storage/logs/laravel.log for errors
• Ensure app is installed (APP_INSTALLED=true)

Messages not sending

Symptom	Likely cause	Fix
Outbound fails immediately	Invalid access token	Regenerate permanent token in Meta, update WhatsApp Settings
Template rejected	Template not approved or wrong name	Sync templates, use exact name and language from Meta
Outside 24h window error	Trying to send free-form text	Use an approved template for re-engagement
Subscription error	Plan expired or message limit reached	Renew plan or upgrade at /plans

Bot flow issues

Flow does not trigger

• Check trigger type and keywords match exactly (exact vs contains)
• Ensure flow is saved (click Save Graph in builder)
• Another keyword flow may match first — check trigger priority
• Verify bot_enabled is on in WhatsApp Settings

Flow stops mid-way

• Check all button/list branches are connected to next nodes
• Condition node may not match customer's reply — add a default branch
• View conversation in Live Chat to see current bot state

AI not replying

Cause	Fix
AI not enabled in settings	Go to AI Settings → enable and save API key
Invalid or expired API key	Regenerate key at provider, update AI Settings, Test Connection
Deprecated model (e.g. gemini-1.5-pro)	Switch to current model like gemini-2.5-flash
Wrong trigger keyword	Send exact keyword configured on the flow (case may matter for exact match)
Provider outage or rate limit	Check provider status; AI node routes to Error branch

Live chat issues

Agent cannot see conversations

• Agent needs Can manage chats permission
• Regular agents only see chats assigned to them
• Enable Can view all chats for supervisor browse access
• Account owner must assign chats to the agent

Agent cannot reply

• Agent can only reply to own assigned chats (or unassigned if view-all)
• Conversation may be in bot status — hand off first

PWA not installing

• Use HTTPS (required for PWA)
• Open /app in Chrome or Safari on mobile
• Look for "Add to Home Screen" in browser menu

Campaign issues

• Stuck in processing — Cron not running. Set up /cron/scheduler
• All failed — Check template approval, phone number format, opt-out flags
• Not starting at scheduled time — Server timezone vs scheduled time; verify cron
• Queue backlog — Set QUEUE_CONNECTION=database and run queue worker

General fixes

Problem	Fix
CSS not loading / pages look unstyled	Re-upload public_html/.htaccess from the package. It must rewrite /css/ to core/public/css/. Test: open https://yourdomain.com/css/portal-ui.css — should show CSS text, not HTML.
Flow builder broken / missing styles	Ensure core/public/build/ is uploaded. Test: https://yourdomain.com/build/manifest.json
CSRF token mismatch on AJAX	Hard refresh browser; ensure logged in; clear cookies
Assets/CSS not loading	Run npm run build, clear view cache, check .htaccess
500 error after deploy	Check storage permissions, run php artisan config:clear
Redirect to /install	App not marked installed — complete installer or set APP_INSTALLED=true
Session/login issues	Ensure storage/framework/sessions is writable