Mobile troubleshooting#

Work through the problem that matches your symptom. Almost every mobile issue has exactly one of three causes: a permission, the server address, or a connection/sync delay. Device health is where the evidence lives — start there when in doubt.

Who this is for#

• Agents fixing their own phone.
• Admins and support staff walking a user through a fix.

Difficulty: Easy · Time: about 10 minutes per problem · Prerequisites: the app installed (Installation).

Quick map#

Cannot log in#

Quick fix: check the Server: line at the bottom of the login screen. If it is wrong, Advanced → Server URL → correct URL (must end with /) → SAVE SERVER URL → try again. On a local server, use the PC's LAN IP, not localhost.

Then: confirm the login method is enabled by the workspace admin (email/phone, password or OTP), and that 5 failed attempts haven't locked the account for 15 minutes — while locked, the API answers 429 ACCOUNT_LOCKED with a retry-time message (wait, or ask an admin to reset).

Escalate when: the server line is correct, no lockout, and the server returns an error you don't recognize — send the exact message. See Login & workspace selection and Cannot log in.

No leads appear#

Quick fix: pull the latest data with More → Device health → SYNC NOW, then reopen Home. Check the Background sync row for "Last sync".

Then: confirm in the CRM (web) that the lead is assigned to this agent and not archived. Leads are per-user in the app — an agent sees their assignments, not the whole business.

Escalate when: the web CRM shows the lead assigned to the agent but it never appears on the phone after a successful sync.

Calls are not syncing to the CRM#

Quick fix: More → Device health →

1. Call tracking row must be green; if not, tap ALLOW and grant phone/call-log permissions.
2. Battery optimization → ALLOW UNRESTRICTED.
3. Tap SYNC NOW, or Settings → Sync → SCAN CALL LOG NOW.

Then: check Settings → Call tracking → Monitored SIMs — a call made on a SIM that isn't monitored is not synced. Check Excluded numbers too; excluded numbers never sync, by design.

Escalate when: permissions and battery are green, the SIM is monitored, but yesterday's calls still don't appear. Include a Device health support report. See Calling from the CRM.

Push notifications do not arrive#

Quick fix: More → Device health → Push notifications (FCM):

Escalate when: state is Registered, test-push runs without error, and nothing shows on the phone.

Recording is unavailable#

Quick fix: none exists — read the Recording: … row in Device health. If it says Metadata only, this phone cannot produce recordings the CRM can read; that is the phone/OS talking, not a setting. Calls still sync.

If your phone records on its own: set the folder in More → Settings → Call tracking → SAVE RECORDINGS FOLDER, then SYNC NOW, and re-check Device health.

Escalate when: Device health says Native/Importable and shows a readable folder, but recordings never appear in the CRM after a sync. See Call recording & what your phone supports.

The app is slow or stuck#

Quick fix: give it a minute — after a long offline period the app drains a call-log backlog (up to 500 rows per scan) and discovery may scan recent recordings (up to 500 files). Then RE-CHECK DEVICE.

Then: force-restart the app once; check free storage on the phone; confirm the phone isn't in severe battery-saver mode.

Escalate when: slowness persists with a healthy connection and free storage.

Before you escalate: generate a support report#

1. More → Device health.
2. Scroll to Diagnostics → GENERATE SUPPORT REPORT.
3. Send the report plus a one-line description of the symptom to your admin or support.

The report is redacted: no access tokens, phone numbers, message contents or recordings are included — it is safe to share.

Technical details#

• Diagnostics build their rows in DeviceHealthScreen.kt (buildDiagnostics, shareSupportReport); recording state from CallCapabilityEngine, push state from PushRegistration.state().
• Call-log scan runs as WorkManager unique work leadhub_calllog_scan; queue upload as leadhub_sync (SyncWorker).
• CRM-side per-device evidence: Super Admin → Android App → Devices (latest device_capability_snapshots).

Related guides#

• Mobile not syncing / push not arriving
• Calls & recording issues
• Device health
• Permissions