Troubleshoot

The connection test fails

Symptom

The setup window shows a red error after you click Test connection.

Cause

The 3CX FQDN, Client ID, Client Secret, edition, or service-principal role may not allow Configuration API access.

Fix

1. Confirm the FQDN has no path after the host name.
2. Confirm the Client ID matches the 3CX API client.
3. Paste the API key again if you just created it.
4. Confirm 3CX Configuration API Access is enabled for the client.
5. Confirm the 3CX edition and role support the requested API access.

When to contact support

Contact support if the same client details work in 3CX tooling but fail in TracsConnect.

Caller lookup does not find customers

Symptom

3CX receives a call, but no matching TRACS customer appears.

Cause

The CRM template may be using the wrong lookup value, the CRM secret may be wrong, or the local TRACS connection may be offline.

Fix

1. Confirm CRM lookup is enabled in the TracsConnect setup window.
2. Confirm the shop-specific 3CX CRM template was downloaded from Settings > Telephony and uploaded in 3CX Settings > CRM > Server side.
3. Confirm the CRM secret matches the one generated by TracsConnect.
4. Test with a phone number that exists on a TRACS customer record.
5. Confirm the shop connection to TRACS is online.

When to contact support

Contact support with the shop name, call time, and the number used for the lookup test. Do not send secrets.

Dashboard popup or Windows toast is missing

Symptom

3CX shows the caller, but the TracsConnect dashboard popup or workstation toast does not appear.

Cause

The shop-level surface may be off, the workstation may not be registered, or the incoming call may not be reaching TracsConnect after the 3CX CRM lookup.

Fix

1. In TracsConnect Settings > Telephony, confirm Caller ID Popup is on for dashboard notifications.
2. Confirm Windows Toasts is on only if the shop wants workstation toasts; it defaults off.
3. Confirm the Client Monitor is running and registered on the workstation that should receive the toast.
4. Run a controlled inbound call from a known TRACS customer number.
5. Turn Windows Toasts off again if the shop only wants the dashboard popup.

When to contact support

Contact support with the shop name, workstation name, and test call time. Do not send CRM secrets.

Call or chat journal records are missing

Symptom

Lookup works, but call or chat activity does not appear in TracsConnect.

Cause

The 3CX CRM template may not be sending the journal action, or the generated journal value may not be configured.

Fix

1. Confirm the generated journal value is configured in the 3CX CRM template.
2. Confirm the CRM secret is included with the journal action.
3. Run a new controlled call after saving the template.
4. Check whether the 3CX template test succeeds before retrying live calls.

When to contact support

Contact support with the shop name and test call time.

CDR records do not appear

Symptom

The 3CX connection is saved, but CDR records are missing.

Cause

3CX native CDR output is file or socket based, so a compatible receiver or bridge must send records to TracsConnect.

Fix

1. Confirm CDR ingest is enabled in TracsConnect.
2. Confirm the CDR receiver or bridge is running.
3. Confirm the receiver or bridge uses the generated CDR value and CDR secret.
4. Confirm 3CX is producing CDR records for completed calls.

When to contact support

Contact support with the shop name, receiver or bridge owner, and a test call time.

When to contact support

Send support the shop name, the time of the failed test or call, and the visible 3CX or TracsConnect error. Do not send Client Secrets, API keys, CRM secrets, or CDR secrets.