​
Installation & Setup Issues

Error: ECONNREFUSED or Connection timeoutSolutions:
  1. Verify DATABASE_URL is correct
  2. Check database is running
  3. Ensure firewall allows connections
  4. Test connection manually: 
    psql $DATABASE_URL
Full troubleshooting →
Common causes:
  • HTTPS certificate invalid
  • Webhook URL not accessible
  • Wrong verify token
  • Webhook not subscribed to message events
Solutions:
  1. Test webhook manually
  2. Check Meta Developer Console logs
  3. Verify HTTPS is working
  4. Ensure message field is subscribed
WhatsApp setup guide →
Check these:
  • All environment variables set?
  • Dependencies installed? (npm install)
  • Database migrations run? (npm run db:migrate)
  • Port 3000 available?
View logs:
pm2 logs team-inbox
# or
tail -f logs/error.log

​
Message Delivery Issues

Possible causes:
  1. Rate limits exceeded - Check Meta Business Suite
  2. Invalid access token - Regenerate token
  3. 24-hour window expired - Use template message
  4. Low quality score - Improve message quality
Quick test:
curl -X POST "https://graph.facebook.com/v18.0/PHONE_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","to":"RECIPIENT","type":"template","template":{"name":"hello_world","language":{"code":"en"}}}'
Expected delivery:
  • Outbound: 1-3 seconds
  • Inbound to inbox: <2 seconds
If slower:
  1. Check server CPU/memory usage
  2. Review database query performance
  3. Check WhatsApp API status
  4. Verify webhook processing time
Performance monitoring →

​
Performance Issues

Diagnose:
-- Find slow queries
SELECT query, mean_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;
Solutions:
  1. Add database indexes
  2. Enable Redis caching
  3. Optimize queries
  4. Scale server resources
Optimization guide →
Check for:
  • Memory leaks (event listeners not removed)
  • Unbound cache growth
  • Too many concurrent connections
Monitor:
pm2 monit
Solutions:
  1. Restart application
  2. Increase server RAM
  3. Fix memory leaks in code
  4. Set cache size limits

​
Email Issues

SendGrid:
  • Verify API key is valid
  • Check sender is verified
  • Review SendGrid activity log
AWS SES:
  • Ensure out of sandbox mode
  • Verify sender email
  • Check AWS credentials
SMTP:
  • Test SMTP credentials
  • Check port (587 for TLS)
  • Verify firewall allows outbound SMTP
Improve deliverability:
  1. Set up SPF record
  2. Configure DKIM
  3. Add DMARC policy
  4. Use business domain (not Gmail)
  5. Avoid spam trigger words
Email setup guide →

​
Authentication Issues

Reset password:
npm run user:reset-password email@example.com
Check:
  • Email is verified
  • Account is not deactivated
  • 2FA codes are correct
  • Browser cookies enabled
Solutions:
  1. Ensure time sync is correct on device
  2. Try backup codes
  3. Admin can disable 2FA: 
    npm run user:disable-2fa email@example.com

​
Integration Issues

Check:
  • OAuth token not expired
  • Field mappings are correct
  • API limits not exceeded
  • Required permissions granted
Re-authenticate: Settings → Integrations → Salesforce → Reconnect
Verify:
  1. Endpoint URL is accessible
  2. Returning 200 OK within 5 seconds
  3. Signature verification passing
  4. Events are subscribed
Test webhook:
curl -X POST https://your-app.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: test" \
  -d '{"type":"test","data":{}}'

​
Data & Privacy

Process:
  1. Contact → Actions → Export Data
  2. Verify identity
  3. Generate export (JSON/CSV)
  4. Provide to customer within 30 days
Includes:
  • Profile information
  • All conversation history
  • Custom fields
  • Notes (optional)
Right to be forgotten:
  1. Contact → Actions → Delete
  2. Choose: Delete or Anonymize
  3. Confirm action
  4. Data removed immediately
Legal holds: Retain for 30 days in case of mistakes

​
Getting More Help

If your issue isn’t listed here:

Troubleshooting Guide

Detailed technical troubleshooting

FAQ

Frequently asked questions

Contact Support

Get personalized help

GitHub Issues

Report bugs or request features