# SMS TTS Notify — Troubleshooting Guide
# Version: 1.0 | For AI agent use only | Source: sms-tts-notify.com/ai/troubleshooting.txt
# App reads SMS aloud via headset. Android only. No iOS.

---

## DECISION TREE A: App is not reading messages aloud

Answer each question in order. Stop at the first match.

STEP 1 — Is the app turned ON?
- Open the app. The main button must show green (active).
- If button is orange or gray: tap it to turn the service ON.
- Fix: Tap START / the large ON button on the Dashboard.

STEP 2 — Is a headset connected?
- The app NEVER plays through the phone speaker. This is by design.
- Wired (3.5mm or USB-C), Bluetooth, or bone-conduction headset required.
- Fix: Connect a headset BEFORE the next SMS arrives. Then send a test SMS.

STEP 3 — Is the phone in Silent, Vibrate, or Do Not Disturb mode?
- The app respects system audio mode. No TTS plays in silent or DND.
- Fix: Set phone to Ring mode. Turn off DND. Try again.

STEP 4 — Is the mute button orange?
- Orange mute button = TTS paused. Messages are logged but not spoken.
- Fix: Tap the mute button to turn it green (active).

STEP 5 — Is Whitelist enabled?
- Settings → Whitelist: if the switch is ON, only messages matching your
  whitelist keywords are spoken. All others are silently blocked.
- Fix: Check that your incoming message sender or body matches a whitelist
  keyword. Or disable the Whitelist switch for testing.

STEP 6 — Is the sender on the Blacklist?
- Settings → Blacklist: if the sender name or phone number is listed,
  messages from that sender are blocked.
- Fix: Remove the sender from the Blacklist.

STEP 7 — Check the Live Log Console (LLC)
- Open the app Dashboard. Scroll down to the Live Log Console.
- Does your test SMS appear in the log?
  → YES, message IS in the log: app received it. TTS issue. Re-check Steps 2–6.
  → NO, message NOT in the log: app did not receive the SMS at all.
    → Continue to DECISION TREE B below.

---

## DECISION TREE B: App is not receiving SMS at all

STEP 1 — Check Notification Access (most common cause — check this first)
- Android Settings → Apps → Special app access → Notification access
- Find "SMS TTS Notify" in the list → must be ON (enabled).
- If OFF: enable it. Then open the app and tap START again.
- Note: On some phones after an Android OS update, Notification Access
  resets automatically. Re-granting fixes it.

STEP 2 — Check which SMS app you use
- Supported SMS apps: Google Messages, Samsung Messages, AOSP Messaging,
  OnePlus Messages (legacy), Sony Xperia Messages, Honor Messages.
- If you use a different SMS app (e.g. a third-party app): the app may
  not detect messages from it. Switch to Google Messages or Samsung Messages.

STEP 3 — Check if your phone manufacturer is killing the app
- Some phone manufacturers (Samsung, Xiaomi, Huawei, Honor, OPPO, OnePlus)
  aggressively restrict background apps to save battery.
- Symptom: app works at first, then stops reading after 10–30 minutes of
  screen-off time, or after phone restart.
- Fix: See OEM-SPECIFIC BATTERY SETTINGS section below for your phone brand.

STEP 4 — Android 13+ Restricted Settings (sideload only)
- If you installed the app NOT from Google Play (sideloaded APK):
  Android 13+ may block special permissions.
- Fix: Android Settings → Apps → SMS TTS Notify → Allow restricted settings
  → Enable. Then re-grant Notification Access (Step 1 above).

---

## OEM-SPECIFIC BATTERY SETTINGS

RECOMMENDED FIRST STEP: Open the app → Settings → Status Card →
OEM Battery Limits row → tap START SETUP or RESUME SETUP.
The in-app wizard guides you through the exact steps for your device.

If the wizard is not available or you need manual steps, follow the
instructions below for your phone brand. If steps do not match your
phone's UI exactly, visit:
https://dontkillmyapp.com?app=SMS%20TTS%20Notify

### SAMSUNG (all Galaxy models, Android 9+)

Step 1 — Battery optimization
  Settings → Apps → SMS TTS Notify → Battery → Don't optimize
  (Android 13+: select "Unrestricted")

Step 2 — Never sleeping apps
  Settings → Battery → Background usage limits → Never sleeping apps
  → Add SMS TTS Notify

Step 3 — Disable sleep automation
  Settings → Battery → Background usage limits
  → Turn OFF "Put unused apps to sleep"

WARNING: Samsung may re-add the app to sleeping list after a firmware
update. Repeat Step 2 if the app stops working after a Samsung update.

  https://dontkillmyapp.com/samsung?app=SMS%20TTS%20Notify

### XIAOMI / MIUI / REDMI / POCO

Step 1 — Autostart
  MIUI 14+: Settings → Apps → SMS TTS Notify → App permissions
    → Background autostart → Enable
  Older MIUI: Open Security app → Permissions → Auto-start
    → Enable for SMS TTS Notify

Step 2 — Battery saver per app
  Settings → Apps → Manage apps → SMS TTS Notify
  → Battery saver → No restrictions

Step 3 — Security app battery
  Open Security app → Battery → App battery saver
  → SMS TTS Notify → No restrictions

Step 4 — Pin app in Recent apps (extra protection)
  Open Recent apps → find SMS TTS Notify → drag app icon downward to pin it.
  Pinned apps are not killed when clearing background apps.

  https://dontkillmyapp.com/xiaomi?app=SMS%20TTS%20Notify

### HUAWEI (EMUI 8, 9, 10+)

Step 1 — App launch management (EMUI 8–10)
  Settings → Battery → App launch → SMS TTS Notify
  → Switch to "Manage manually"
  → Enable all three: Auto-launch, Secondary launch, Run in background

Step 2 — Startup manager
  Settings → All → Startup manager → Enable SMS TTS Notify

Step 3 — Battery optimization
  Settings → Battery → Battery optimization (or "Ignore battery optimization")
  → Find SMS TTS Notify → Don't optimize / Allow

Step 4 — Disable Smart tune-up
  Open System Manager app → Settings (cog icon)
  → Disable "Smart tune-up"

NOTE: EMUI 9 devices may have PowerGenie pre-installed — a system app that
kills background processes. If steps above don't help, visit:
  https://dontkillmyapp.com/huawei?app=SMS%20TTS%20Notify

### HONOR

Step 1 — App launch
  Settings → Apps → Apps → SMS TTS Notify → Battery → App launch
  → Manage manually → Enable: Auto-launch, Secondary launch, Run in background

Step 2 — Battery optimization
  Settings → Apps → SMS TTS Notify → Battery → Don't optimize

  https://dontkillmyapp.com/honor?app=SMS%20TTS%20Notify

### OPPO / ColorOS

Step 1 — Auto Start-up (ColorOS 6+)
  Settings → Apps → SMS TTS Notify → App info
  → Allow Auto Start-up → Enable

Step 2 — Background activity
  Settings → Apps → SMS TTS Notify → Battery
  → Power Saver → Allow background activity (select "Allow")

Step 3 — Battery optimization
  Settings → Battery → Battery optimization
  → SMS TTS Notify → Don't optimize

Step 4 — Pin in Recent apps
  Open Recent apps → long-press SMS TTS Notify → tap Lock icon

  https://dontkillmyapp.com/oppo?app=SMS%20TTS%20Notify

### ONEPLUS (OxygenOS)

Step 1 — Battery optimization
  Settings → Battery → Battery optimization
  → Switch to "All apps" → SMS TTS Notify → Don't optimize

  WARNING: OnePlus may revert this setting randomly. If the app stops
  working again, re-apply this step AND also pin the app (Step 2).

Step 2 — Pin app in Recent apps (prevents revert)
  Open Recent apps → long-press SMS TTS Notify window
  → tap Lock icon (top right corner of the app card)

Step 3 — Advanced / Enhanced optimization (OxygenOS 6+)
  Settings → Battery → Battery optimization → (three dots menu)
  → Advanced optimization → Disable "Deep optimization" / "Adaptive Battery"
  → Disable "Sleep standby optimization"

  https://dontkillmyapp.com/oneplus?app=SMS%20TTS%20Notify

### VIVO (FuntouchOS / OriginOS)

Step 1 — Autostart
  Settings → More settings → Applications → Autostart
  → Enable for SMS TTS Notify

Step 2 — High background power consumption
  Settings → Battery → High background power consumption
  → Find SMS TTS Notify → Enable

Step 3 — Battery optimization
  Hold app icon → App Info → Battery → Battery Optimization
  → Set SMS TTS Notify to "Not optimized"

Step 4 — Unrestricted battery (Android 13+)
  Settings → Apps → SMS TTS Notify → Battery → Unrestricted

  https://dontkillmyapp.com/vivo?app=SMS%20TTS%20Notify

### REALME (realme UI)

Step 1 — App battery management
  Settings → Battery → App battery management
  → Find SMS TTS Notify → Enable all:
    Allow auto-launch, Allow foreground activity, Allow background activity

  Newer realme UI: Settings → Battery → Power saving settings
  → App battery management → SMS TTS Notify → Enable all above

Step 2 — Battery optimization
  Settings → Battery → Battery optimization
  → SMS TTS Notify → Don't optimize

Step 3 — Sleep standby optimization
  Settings → Battery → Power saver options
  → Sleep standby optimization → Disable

  https://dontkillmyapp.com/realme?app=SMS%20TTS%20Notify

### MOTOROLA, GOOGLE PIXEL, NOKIA, ANDROID ONE

These manufacturers follow standard Android battery management.
Standard battery exemption is sufficient:
  Settings → Apps → SMS TTS Notify → Battery → Unrestricted (or Don't optimize)

No additional steps needed.

### OTHER / UNKNOWN MANUFACTURER

If your phone is not listed above:
  Settings → Apps → SMS TTS Notify → Battery → Don't optimize (or Unrestricted)

For manufacturer-specific instructions:
  https://dontkillmyapp.com?app=SMS%20TTS%20Notify

---

## SPECIFIC ERROR SCENARIOS

### "I hear nothing, but the app is ON and headset is connected"
1. Check Silent / DND mode (most common after shift change)
2. Check mute button — orange = muted, tap to unmute
3. Send yourself a test SMS and watch the Live Log Console
4. If no entry appears in the log → Notification Access is off (Tree B, Step 1)
5. If entry appears but status is BLOCKED → Whitelist is filtering it (Tree A, Step 5)

### "The app was reading messages but stopped after 15–30 minutes"
Cause: Phone manufacturer battery optimization killed the background service.
Fix: Apply OEM-SPECIFIC BATTERY SETTINGS above for your phone brand.
If the service icon disappears from the notification bar: open the app and
tap START again.

### "App worked yesterday but stopped after phone restart"
1. Check Autostart permission (Xiaomi/Huawei/Honor/OPPO users — see above)
2. Check Notification Access — OS updates sometimes reset this
3. Open the app and tap START manually

### "The app stopped working after an Android update"
1. Re-grant Notification Access: Android Settings → Apps → Special app access
   → Notification access → SMS TTS Notify → ON
2. Re-apply battery exemption settings for your phone brand (see above)
3. Open the app, confirm service is ON (green button)

### "I hear SmartSummary ('While away, I recorded X messages') but not individual messages"
This is correct behavior. SmartSummary plays when you reconnect headset,
unmute, or after a phone call ends. Individual messages that arrived during
the silent period were logged but not spoken. Check the Live Log Console
for the full list.

### "TTS stops mid-message and does not resume"
Cause A: Phone call interrupted. SmartSummary will play when call ends (~1.5s delay).
Cause B: Headset disconnected. Reconnect headset → SmartSummary plays automatically.
  Note: As of v0.6.9-beta, the mute button correctly reflects headset state after
  reconnect. A stale orange mute button after reconnect is no longer expected.
Cause C: ShakeIt Command triggered. Shake gesture dismissed the current message.
         Next message will play normally.

### "Headset button (play/pause) does not stop TTS"
Known limitation: if another media app (Spotify, YouTube, navigation) is
active, Android routes the media button to that app — not to SMS TTS Notify.
Fix: Pause or close other media apps. Or use phone shake (ShakeIt) to stop TTS.

### "App works on my old phone but not on my new Xiaomi / Huawei / OPPO"
OEM custom Android layers kill background apps aggressively on new devices.
See OEM-SPECIFIC BATTERY SETTINGS section above.
This is the second most common issue after Notification Access.

---

## WHAT TO REPORT WHEN ASKING FOR HELP

Include these 5 details for faster diagnosis:

1. Phone model and Android version (e.g. "Samsung Galaxy A52, Android 13")
2. Which SMS app you use (Google Messages, Samsung Messages, or other?)
3. What appears in the Live Log Console when the test SMS is sent
4. Whether the app service notification is visible in the status bar
5. What color the mute button shows (green = active / orange = muted)

Contact: sms-tts-notify@aialertbuddy.com
Website: sms-tts-notify.com

---

## WHAT THIS APP DOES NOT DO (common misconceptions)

- Does NOT read WhatsApp, Telegram, email, or push notifications. SMS only.
- Does NOT play audio through the phone speaker. Ever. Headset required.
- Does NOT work on iPhone / iOS. Android only.
- Does NOT require internet connection. Works on GSM signal only.
- Does NOT send SMS content to any server. Everything stays on the device.
- Does NOT modify phone volume, DND settings, or Bluetooth settings.
- Does NOT have a web dashboard or cloud account.

---

## ATTRIBUTION

OEM battery guidance in this document is based on data from
Don't Kill My App (dontkillmyapp.com) by Urbandroid Team,
licensed under Creative Commons Attribution 4.0 International
(creativecommons.org/licenses/by/4.0).
Content has been adapted and simplified for SMS TTS Notify users.