Skip to content

Troubleshooting Guide

Common Issues and Solutions

Authentication Issues

Issue: Cannot log in

Symptoms: - Login fails with error message - "Invalid credentials" error - Account locked

Solutions: 1. Verify email and password are correct 2. Check if email is verified 3. Try password reset 4. Check for account lockout 5. Clear browser cache and cookies 6. Try incognito/private mode 7. Contact support if issue persists

Issue: Session expired

Symptoms: - "Session expired" error - Unexpected logout - Token refresh fails

Solutions: 1. Log in again 2. Check token expiration settings 3. Verify system time is correct 4. Clear browser storage 5. Check network connectivity

Channel Connection Issues

Issue: WhatsApp not connecting

Symptoms: - Connection status shows "Disconnected" - Cannot send/receive messages - Webhook errors

Solutions:

For WhatsApp Lite: 1. Verify Suit ID is correct 2. Check AppGain account status 3. Verify Suit ID is active 4. Test Suit ID in AppGain dashboard 5. Reconnect channel

For WhatsApp Cloud: 1. Verify access token is valid 2. Check phone number ID 3. Verify webhook URL configured 4. Check webhook verification 5. Review Meta Developer Console logs 6. Reconnect channel

Issue: Messages not receiving

Symptoms: - Messages sent but not appearing in inbox - Webhook not triggering - Delivery status unknown

Solutions: 1. Check channel connection status 2. Verify webhook URL is correct 3. Check webhook logs 4. Verify webhook signature (if configured) 5. Test webhook endpoint manually 6. Check Supabase Edge Function logs 7. Verify message filters not hiding messages

Issue: Messages not sending

Symptoms: - Message stuck in "Sending" status - "Failed to send" error - Rate limit errors

Solutions: 1. Check channel connection 2. Verify message format is valid 3. Check rate limits 4. Review error messages 5. Test channel separately 6. Check message length limits 7. Verify recipient number format 8. Check channel-specific restrictions

Data Issues

Issue: Contacts not importing

Symptoms: - Import fails - Partial import - Data validation errors

Solutions: 1. Check CSV format 2. Verify required fields present 3. Check data validation errors 4. Review import logs 5. Fix data issues in CSV 6. Try smaller batch import 7. Verify organization ID correct

Issue: Search not finding contacts

Symptoms: - Known contacts not appearing - Search returns no results - Partial matches not working

Solutions: 1. Check search term spelling 2. Verify phone number format 3. Check organization filter 4. Try different search terms 5. Check contact data accuracy 6. Verify search index updated 7. Clear search cache

Issue: Duplicate contacts

Symptoms: - Multiple entries for same contact - Import creates duplicates - Manual duplicates

Solutions: 1. Use duplicate detection tool 2. Merge duplicates manually 3. Review import process 4. Use unique identifiers 5. Standardize data format 6. Set up duplicate prevention rules

Performance Issues

Issue: Dashboard loads slowly

Symptoms: - Long load times - Widgets loading slowly - Timeout errors

Solutions: 1. Reduce number of widgets 2. Use date range filtering 3. Optimize custom widget queries 4. Check database performance 5. Clear browser cache 6. Check network connectivity 7. Review database indexes

Issue: Real-time updates not working

Symptoms: - Updates not appearing automatically - Need to refresh page - Connection errors

Solutions: 1. Check browser WebSocket support 2. Verify real-time connection status 3. Check network connectivity 4. Review firewall settings 5. Refresh page 6. Check Supabase real-time status 7. Review browser console for errors

Issue: API requests timing out

Symptoms: - API calls fail - Timeout errors - Slow responses

Solutions: 1. Check network connectivity 2. Verify API endpoint is accessible 3. Check rate limits 4. Review request size 5. Optimize queries 6. Check Supabase status 7. Retry with exponential backoff

Feature-Specific Issues

Issue: Deals not moving in kanban

Symptoms: - Cannot drag deals - Deals stuck in stage - Stage changes not saving

Solutions: 1. Check browser compatibility 2. Verify pipeline configuration 3. Refresh page 4. Check permissions 5. Verify deal data integrity 6. Try different browser 7. Clear browser cache

Issue: Automation not triggering

Symptoms: - Rules not executing - Actions not performed - No automation logs

Solutions: 1. Verify automation is active 2. Check trigger conditions 3. Review automation logs 4. Test trigger manually 5. Verify permissions 6. Check data matches conditions 7. Review automation configuration

Issue: Campaign not sending

Symptoms: - Campaign stuck in "DRAFT" - Messages not delivered - Delivery errors

Solutions: 1. Check campaign status 2. Verify target contacts exist 3. Check channel connections 4. Review delivery logs 5. Verify message content 6. Check rate limits 7. Review error messages

Issue: Bot flow not executing

Symptoms: - Bot not responding - Flow not triggered - Session errors

Solutions: 1. Verify flow is published 2. Check flow configuration 3. Review bot session logs 4. Test flow manually 5. Verify trigger conditions 6. Check conversation status 7. Review flow nodes

Integration Issues

Issue: Webhook not receiving events

Symptoms: - No webhook calls - Events not triggering - 404 errors

Solutions: 1. Verify webhook URL is correct 2. Check webhook is active 3. Test webhook endpoint manually 4. Verify webhook signature 5. Check firewall settings 6. Review webhook logs 7. Verify event subscriptions

Issue: API key not working

Symptoms: - 401 Unauthorized errors - API calls rejected - Invalid key errors

Solutions: 1. Verify API key is correct 2. Check API key is active 3. Verify key hasn't expired 4. Check key permissions 5. Verify organization matches 6. Review API key logs 7. Regenerate key if needed

Issue: External system integration failing

Symptoms: - Integration errors - Data not syncing - Connection timeouts

Solutions: 1. Verify API credentials 2. Check API endpoint URLs 3. Review integration logs 4. Test API endpoints separately 5. Verify data format 6. Check rate limits 7. Review error messages

Browser & Device Issues

Issue: Features not working in browser

Symptoms: - Buttons not clicking - Forms not submitting - JavaScript errors

Solutions: 1. Check browser compatibility 2. Update browser 3. Clear browser cache 4. Disable browser extensions 5. Try different browser 6. Check JavaScript console 7. Verify browser settings

Issue: Mobile app issues

Symptoms: - Features not working - Layout issues - Performance problems

Solutions: 1. Check mobile browser compatibility 2. Clear mobile browser cache 3. Update mobile browser 4. Check network connectivity 5. Verify responsive design 6. Test on different devices 7. Review mobile-specific issues

Data Loss Prevention

Issue: Accidentally deleted data

Symptoms: - Contact deleted - Deal removed - Conversation lost

Solutions: 1. Check if cascade deletion occurred 2. Review deletion logs 3. Check database backups 4. Contact support for restoration 5. Verify backup availability 6. Implement deletion confirmations 7. Set up data retention policies

Issue: Data not saving

Symptoms: - Changes not persisting - Data reverts - Save errors

Solutions: 1. Check network connectivity 2. Verify save button clicked 3. Review validation errors 4. Check permissions 5. Verify data format 6. Review error messages 7. Try saving again

Getting Help

When to Contact Support

Contact support when: - Issue persists after troubleshooting - Data loss occurred - Security concerns - Billing issues - Feature requests - Bug reports

Information to Provide

When contacting support, provide: 1. Description of issue 2. Steps to reproduce 3. Expected vs actual behavior 4. Error messages 5. Screenshots/videos 6. Browser/device information 7. Account information (if safe)

Self-Service Resources

Before contacting support: 1. Check this troubleshooting guide 2. Review FAQ 3. Search documentation 4. Check status page 5. Review error logs 6. Test in different browser 7. Clear cache and retry

Prevention Best Practices

Regular Maintenance

  1. Monitor Channels
  2. Check connection status daily
  3. Review webhook logs weekly

  4. Test message sending regularly

  5. Data Quality

  6. Regular duplicate cleanup
  7. Data validation

  8. Backup important data

  9. Performance

  10. Monitor dashboard load times
  11. Review API response times

  12. Optimize queries regularly

  13. Security

  14. Review API keys regularly
  15. Update passwords periodically

  16. Monitor access logs

  17. Updates

  18. Keep browser updated
  19. Review release notes
  20. Test new features

Last Updated: January 2025