Troubleshooting Guide

This comprehensive troubleshooting guide helps you quickly resolve common issues with TextFlow.

Quick Diagnostics

System Health Check

If you’re experiencing issues, run through this quick checklist:

1. ✅ Can you access the login page? → Login Issues
2. ✅ Are you logged in but seeing errors? → Dashboard Issues
3. ✅ Messages not sending? → Message Sending Issues
4. ✅ Not receiving replies? → Inbound Message Issues
5. ✅ Import failed? → Contact Import Issues
6. ✅ Campaign not launching? → Campaign Issues

---

Login Issues

Cannot Access Login Page

Problem: Page won’t load or shows error

Solutions:

1. Check URL is correct: https://textflow.telair.net
2. Clear browser cache and cookies
3. Try incognito/private browsing mode
4. Try different browser (Chrome, Firefox, Safari, Edge)
5. Check your internet connection
6. Contact your system administrator

”Invalid email or password” Error

Problem: Credentials rejected even though they’re correct

Solutions:

1. Check email format: Must be lowercase (e.g., john@company.com not John@Company.com)
2. Check for spaces: No spaces before/after email or password
3. Caps Lock: Ensure Caps Lock is off for password
4. Copy/paste carefully: Pasting may include hidden characters
5. Request password reset: Use “Forgot Password?” link
6. Contact admin: Your account may be disabled

Account Locked After Failed Attempts

Problem: “Too many login attempts” error

Cause: 5 failed login attempts within 15 minutes triggers lockout

Solutions:

1. Wait 15 minutes before trying again
2. Use “Forgot Password?” to reset
3. Contact system administrator to unlock account manually

Password Reset Email Not Received

Problem: Reset code doesn’t arrive

Solutions:

1. Check spam/junk folder
2. Wait 2-3 minutes: Email delivery can be delayed
3. Verify email address: Ensure you entered correct email
4. Check email provider: Some providers block automated emails
5. Request again: Click “Resend Code” after 1 minute
6. Contact admin: Admin can manually reset your password

---

Dashboard Issues

Dashboard Loading Slowly

Problem: Dashboard takes forever to load

Solutions:

1. Check internet speed: Run speed test
2. Clear browser cache: Ctrl+Shift+Del (Chrome/Firefox)
3. Close other tabs: Too many open tabs slow performance
4. Update browser: Use latest version
5. Check system resources: Close unnecessary programs

Metrics Not Updating

Problem: Dashboard shows old/stale data

Solutions:

1. Refresh page: Press F5 or Ctrl+R
2. Hard refresh: Ctrl+Shift+R (clears cache)
3. Check filters: Date range may be set to past period
4. Wait a moment: Some metrics update every 30 seconds
5. Log out and back in: Clears cached data

”Permission Denied” on Dashboard Features

Problem: Cannot access certain features

Cause: Your user role doesn’t have permission

Solutions:

1. Check your role: Settings → Profile
2. Role permissions:
   • Staff: View-only access to most features
   • Manager: Can create campaigns and manage contacts
   • Admin: Full access except billing
   • Super Admin: Full system access
3. Request access: Contact your organization admin
4. Wrong organization: Verify you’re in correct org (top-left dropdown)

---

Message Sending Issues

”Usage limits exceeded” Error

Problem: Cannot send messages due to limits

Solutions:

1. Check daily limit: Dashboard shows usage
2. Check monthly limit: May have hit monthly cap
3. Purchase addon: Contact admin to buy more messages
4. Upgrade plan: Move to higher tier (Starter → Marketer)
5. Wait until tomorrow: Daily limit resets at midnight
6. Wait until next month: Monthly limit resets on 1st

Messages Stuck in “Sending” Status

Problem: Messages show as “Sending…” indefinitely

Solutions:

1. Wait 30 seconds: Normal delay for processing
2. Check Bandwidth status: Provider may be down
3. Refresh page: F5 to reload delivery status
4. Invalid phone number: Check recipient number format
5. Network issue: Check your internet connection
6. Contact support: If persists after 5 minutes

”Invalid phone number” Error

Problem: Cannot send to specific number

Cause: Phone number format or validation issue

Solutions:

1. Check format: Must be 10-11 digits (e.g., 4165551234 or 14165551234)
2. Remove formatting: No spaces, hyphens, or parentheses
3. Add country code: US/Canada numbers need +1 or 1 prefix
4. Check for typos: Verify all digits are correct
5. Number is opted out: Check opt-out list
6. Landline: TextFlow only supports mobile numbers

Messages Sending to Wrong Number

Problem: Messages delivered to incorrect recipient

Cause: Saved contact data is wrong

Solutions:

1. Verify contact: Open contact record and check phone number
2. Update contact: Edit phone number if incorrect
3. Check personalization: {{phone}} merge field may be wrong
4. Export and verify: Export contacts to CSV and check data

Campaign Sends Partial Messages

Problem: Only some contacts received campaign

Solutions:

1. Check campaign report: View delivery stats
2. Opted out contacts: Automatically skipped
3. Invalid numbers: Bad phone numbers skipped
4. Daily limit hit: Check usage dashboard
5. Monthly limit hit: Purchase addon or upgrade plan
6. Filter applied: Campaign may target specific tag/list

---

Inbound Message Issues

Not Receiving Replies

Problem: Expected reply doesn’t appear in Messages inbox

Solutions:

1. Check filter: Ensure “All Messages” is selected (not “Unread”)
2. Check phone number filter: Select correct number or “All”
3. Refresh inbox: Press F5 to reload
4. Contact replied to different number: Check all your phone numbers
5. Carrier delay: SMS can be delayed up to 5 minutes
6. Contact used different number: Check contact’s phone record

Notifications Not Appearing

Problem: No notification for new inbound message

Solutions:

1. Check notification settings: Settings → Notifications
2. Refresh page: Notifications appear in real-time via Socket.IO
3. Browser notifications blocked: Check browser permissions
4. PWA app: Notifications intentionally disabled to prevent overload during campaigns
5. Log out/in: Re-establishes real-time connection

Reply Not Attributed to Campaign

Problem: Reply doesn’t show under campaign statistics

Cause: Reply must come within 7 days of campaign send

Solutions:

1. Check timing: Replies after 7 days not attributed
2. Check contact: Verify they received campaign message
3. Manual attribution: Note in campaign comments if needed

Duplicate Messages Appearing

Problem: Same message shows twice in inbox

Solutions:

1. Refresh page: May be display glitch
2. Check conversation: Both messages may be different
3. Bandwidth duplicate: Rare webhook issue (now fixed in v1.1.64+)
4. Contact support: Report if persists

---

Contact Import Issues

”No valid contacts found”

Problem: CSV import fails with no contacts imported

Solutions:

1. Check CSV format: First column = phone, second column = first name
2. Remove header row: Or ensure it’s labeled correctly
3. Check phone numbers: Must be 10-11 digits, numbers only
4. Check for empty rows: Delete blank rows in CSV
5. Save as CSV: Not Excel (.xlsx) format

”All contacts skipped as duplicates”

Problem: Import reports 100% duplicates

Cause: Phone numbers already exist in system

Solutions:

1. Expected behavior: Duplicate detection prevents re-import
2. Export existing: Download contacts to compare
3. Check list assignment: Contacts may be in different list
4. Update instead: Edit existing contacts rather than re-import
5. Delete and re-import: Only if you need to replace data (careful!)

”File too large” Error

Problem: CSV exceeds 10 MB size limit

Solutions:

1. Split file: Import in batches of 10,000-25,000 contacts
2. Remove columns: Keep only required fields (phone, first_name)
3. Remove test data: Delete dummy/test rows
4. Compress in Excel: Remove extra formatting

Phone Numbers Import with Wrong Format

Problem: Numbers show as scientific notation or missing leading zeros

Solutions:

1. Format as Text in Excel before export:
   • Select phone column
   • Format Cells → Text
   • Re-enter phone numbers
2. Add single quote: Excel trick - type '4165551234 to force text
3. Save as CSV UTF-8: File → Save As → CSV UTF-8

Tags Not Applied During Import

Problem: CSV has tags column but tags not created

Solutions:

1. Check delimiter: Use semicolon (;) or comma (,) between tags
2. Check tag column position: Tags should be 6th column
3. Check spelling: Tag names case-insensitive but must match
4. Manually add tags: After import, bulk tag contacts

---

Campaign Issues

Cannot Create Campaign

Problem: “Create Campaign” button disabled or errors on save

Solutions:

1. Check permissions: Staff role cannot create campaigns
2. Fill required fields: Campaign name and phone number required
3. Select audience: Must choose at least one list or tag
4. Enter message: Message body required
5. Daily limit: Check if limits exceeded

”No contacts match criteria”

Problem: Campaign has 0 recipients

Solutions:

1. Check list/tag selection: Verify contacts exist in selected lists
2. All opted out: Check if all contacts in list are opted out
3. Filter conflict: Using AND logic with incompatible tags
4. Empty list: List may have no contacts
5. Switch to Tags view: May have tagged contacts instead of lists

Scheduled Campaign Didn’t Send

Problem: Campaign scheduled but never sent

Solutions:

1. Check status: View campaign details
2. Canceled accidentally: Someone may have canceled it
3. Past quiet hours: Campaign delayed to next day
4. System issue: Check audit log
5. Time zone confusion: Verify scheduled time was correct
6. Contact support: With campaign ID

Campaign Stuck in “Processing”

Problem: Campaign shows “Processing” for extended time

Solutions:

1. Large audience: Takes 1-2 minutes per 1,000 contacts
2. Rate limiting: Bandwidth enforces send rate
3. Refresh page: Status may be cached
4. Wait: Processing can take up to 30 minutes for large campaigns
5. Contact support: If over 1 hour with no progress

Wrong Message Sent to Contacts

Problem: Campaign sent incorrect message

Cause: Wrong template selected or message edited after review

Solutions:

1. Check campaign details: View exact message sent
2. Personalization error: {{merge_fields}} may have wrong data
3. Template confusion: May have selected wrong template
4. Prevention: Always send test message first
5. Send correction: Create new campaign with corrected message

---

Performance Issues

App Running Slowly

Problem: Entire app feels sluggish

Solutions:

1. Clear browser cache: Ctrl+Shift+Del
2. Close other tabs: Especially video/music sites
3. Restart browser: Full browser restart
4. Check RAM usage: Close memory-heavy programs
5. Update browser: Install latest version
6. Try different browser: Chrome, Firefox, Edge, Safari
7. Check internet speed: Run speed test (need 5+ Mbps)

Messages Inbox Slow to Load

Problem: Messages page takes long time to open

Cause: Large number of conversations (1,000+)

Solutions:

1. Archive old conversations: Keep inbox under 500 conversations
2. Use search: Instead of scrolling through all messages
3. Filter by phone number: Reduces displayed conversations
4. Clear browser cache: Removes stored data

Contact List Slow to Load

Problem: Contacts page lags when opening

Cause: Large contact list (10,000+)

Solutions:

1. Use search: Find specific contacts instead of browsing
2. Filter by tag/list: Reduces displayed contacts
3. Pagination: Navigate pages instead of loading all
4. Export to CSV: For bulk analysis outside app

---

Mobile App Issues (PWA)

Cannot Install App on iOS

Problem: “Add to Home Screen” option missing

Solutions:

1. Use Safari: PWA installation only works in Safari (not Chrome)
2. Tap Share button: Look for up-arrow icon at bottom of Safari
3. Scroll down: “Add to Home Screen” is mid-list
4. Update iOS: Requires iOS 14.5 or later
5. Clear Safari data: Settings → Safari → Clear History

Cannot Install App on Android

Problem: Install prompt doesn’t appear

Solutions:

1. Use Chrome: PWA works best in Chrome on Android
2. Look for install banner: May appear automatically
3. Menu → Install app: Three dots menu → Add to Home Screen
4. Clear Chrome data: Settings → Apps → Chrome → Clear Cache
5. Update Android: Requires Android 5.0 or later

App Icon Disappeared from Home Screen

Problem: Installed PWA icon vanished

Solutions:

1. Check app drawer: May have moved
2. Reinstall: Open site in browser and re-add to home screen
3. iOS update: Sometimes removes PWAs after OS update
4. Storage full: Free up space and reinstall

Push Notifications Not Working

Problem: Expected notifications not appearing

Note: This is INTENTIONAL behavior

Explanation:

• TextFlow PWA does NOT send device push notifications
• Reason: Campaigns can generate hundreds of replies, causing notification spam
• Instead: Check app regularly for new messages
• In-app notification badge shows unread count

---

Billing & Subscription Issues

”Payment method declined”

Problem: Cannot update credit card or purchase addon

Solutions:

1. Verify card details: Check number, expiry, CVV
2. Check billing address: Must match card on file
3. International cards: Some cards blocked for US purchases
4. Insufficient funds: Verify account balance
5. Card expired: Update with new card
6. Contact bank: They may have flagged transaction
7. Try different card: Use alternative payment method

Plan Upgrade Not Reflected

Problem: Upgraded plan but limits haven’t changed

Solutions:

1. Wait 5 minutes: Changes take time to propagate
2. Log out and back in: Refreshes session
3. Check confirmation email: Verify upgrade processed
4. Contact billing: Submit support ticket
5. Check invoice: Verify payment went through

Usage Counter Incorrect

Problem: Dashboard shows wrong usage numbers

Solutions:

1. Wait for sync: Counters update every 30 seconds
2. Refresh page: F5 to reload
3. Check time period: Ensure viewing correct month
4. Sent + Received: Usage includes BOTH outbound and inbound
5. Segments counted: Long messages (160+ chars) count as multiple
6. Export usage log: Download detailed report for verification

---

Technical Issues

”Session expired” Error

Problem: Constantly logged out

Cause: Session expires after 24 hours of inactivity

Solutions:

1. Log in again: Normal behavior after 24 hours
2. Check clock: System clock must be accurate
3. Clear cookies: Remove all textflow.telair.net cookies
4. Disable privacy blockers: Some extensions block session cookies
5. Try incognito: Test without browser extensions

”Network error” or “Failed to fetch”

Problem: API calls failing

Solutions:

1. Check internet: Verify connection is active
2. Firewall/VPN: May be blocking TextFlow servers
3. Try different network: Switch to mobile data or different WiFi
4. Clear browser cache: Remove cached API responses
5. Check browser console: F12 → Console tab for detailed errors
6. Contact support: Report if widespread issue

Page Stuck on Loading Screen

Problem: Infinite loading spinner

Solutions:

1. Wait 30 seconds: Some operations take time
2. Hard refresh: Ctrl+Shift+R
3. Clear cache: Ctrl+Shift+Del
4. Disable extensions: Ad blockers may interfere
5. Try incognito mode: Test without extensions
6. Check browser console: F12 → Console for errors

Real-Time Updates Not Working

Problem: New messages don’t appear without refresh

Cause: Socket.IO connection lost

Solutions:

1. Refresh page: Re-establishes WebSocket connection
2. Check firewall: May be blocking WebSocket protocol
3. VPN interference: Some VPNs block WebSockets
4. Corporate network: IT may restrict WebSockets
5. Use standard network: Test on home/mobile network

---

Data & Privacy Issues

Cannot Delete Contact

Problem: Delete button disabled or error on delete

Solutions:

1. Check permissions: Manager/Admin role required
2. Contact in active campaign: Cannot delete mid-campaign
3. Opted out contact: Must keep for compliance (CASL)
4. Mark inactive instead: Alternative to deletion
5. Contact admin: They can force-delete if needed

Exported CSV Has Wrong Data

Problem: Export doesn’t match what’s shown in UI

Solutions:

1. Check filters: Export respects current filters
2. Select correct list/tags: Verify selection before export
3. Wait for export: Large exports take 30-60 seconds
4. Re-export: Try export again
5. Contact support: With description of mismatch

Lost All My Contacts

Problem: Contact list is empty

Solutions:

1. Check filter: May have filter applied
2. Check list selection: Switch to “All Contacts”
3. Wrong organization: Verify org in top-left dropdown
4. Accidental delete: Contact admin immediately for restore
5. Database backup: Admin can restore from /tmp backup

---

Getting Additional Help

Before Contacting Support

1. ✅ Try solutions in this guide
2. ✅ Check FAQ
3. ✅ Search documentation
4. ✅ Note error messages (screenshot if possible)
5. ✅ Note what you were doing when error occurred
6. ✅ Try in different browser

How to Contact Support

Submit Support Request:

1. Go to /support
2. Provide:
   • Your email address
   • Organization name
   • Detailed description of issue
   • Steps to reproduce
   • Screenshots (if applicable)
   • Browser and OS version

Emergency Issues (System Down):

• Contact your organization administrator
• Admin will escalate to technical support

Information to Include

When reporting an issue, include:

• Error message: Exact wording or screenshot
• When it started: Date and time
• Frequency: Always, sometimes, once
• Browser: Chrome 119, Firefox 120, etc.
• OS: Windows 11, macOS 14, etc.
• Steps to reproduce: 1, 2, 3…
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Account email: For identification
• Organization: If multi-org user

---

Useful Resources

• FAQ - Quick answers to common questions
• Getting Started - Beginner’s guide
• Contact Import Guide - Detailed import instructions
• Campaign Creation - Step-by-step campaign guide
• Dashboard Overview - Understanding metrics

---

Remember: Most issues can be resolved quickly by clearing your browser cache, refreshing the page, or logging out and back in!